Files
celtic-life-science/README.md
T
Shubhankar45 0d30c58bf0 Server backup 2026-11-07 of uncommitted work in projects/pharma-web-celtic
Snapshot of the working tree on srv1071960 (branch main), taken during
server cleanup. .env files, node_modules, builds, logs and media were excluded.
2026-11-07 05:43:12 +00:00

471 lines
27 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Pharma Field-Force Reporting
> **Deploying to a server?** Use [PRODUCTION.md](PRODUCTION.md) — the operator's guide (first deployment, real users, backups, updates, runbook). This README is for development.
Field-force reporting for a pharmaceutical sales team (Celtic Life Science Pvt Ltd): Medical Representatives (MRs) file **Daily Call Reports**, Area Business Managers (ABMs) review and approve them (the Assistant General Manager (AGM) has a read-only overview), and approved reports are locked and rendered as PDFs. Alongside the DCR, the system manages the company's paper forms — tour plans, fare charts, stock statements and more — and prints each one on its own PDF layout.
- **Backend:** FastAPI · SQLAlchemy 2 (async) · PostgreSQL 16 · Alembic
- **PDFs:** Jinja2 templates rendered by WeasyPrint
- **Web app:** React 18 + TypeScript (Vite), Celtic-branded, served by Caddy
- **Deployment:** Docker Compose on a single VPS, automatic HTTPS via Caddy
Deliberately **not** in scope: HR, payroll, attendance, distributor management, GPS, offline mode.
## Contents
1. [Features](#features)
2. [Quick start with Docker](#quick-start-with-docker) — incl. VPS over SSH, ports, operations
3. [Local development](#local-development)
4. [Configuration](#configuration)
5. [Roles and permissions](#roles-and-permissions)
6. [The approval workflow](#the-approval-workflow)
7. [Company forms and PDFs](#company-forms-and-pdfs)
8. [API overview](#api-overview)
9. [Project layout](#project-layout)
10. [Design decisions](#design-decisions)
11. [Testing](#testing)
12. [Production checklist](#production-checklist)
13. [Known limitations](#known-limitations)
14. [Troubleshooting](#troubleshooting)
---
## Features
| Area | What it does |
|---|---|
| Daily Call Reports | MR records doctor and chemist calls per day; one report per MR per date |
| Approval workflow | `DRAFT → PENDING_ABM → APPROVED`, with a return-for-correction loop (the Area Business Manager is the final approver); approved reports are immutable |
| Audit trail | Append-only log of every state change; approval history is a view over it |
| PDFs | Approved DCRs are stored as PDFs; company forms download as PDFs on demand |
| Company forms | Ten form tables (tour plan, fare chart, stock statement, …) with per-form PDF layouts |
| Masters | Users, headquarters, ABM↔HQ mapping, doctors, chemists, products, with MR assignments |
| Security | JWT with refresh-token rotation, argon2 password hashing, role **and** scope checks |
---
## Quick start with Docker
Requires Docker with the Compose plugin. On any machine — laptop, or a VPS over SSH:
```bash
git clone <repo-url> pharma-web-celtic && cd pharma-web-celtic
make deploy # = ./scripts/setup.sh + docker compose up -d --build + wait until healthy
```
`make deploy` is safe to re-run; it is also how you update after `git pull`. The setup step (`scripts/setup.sh`) prepares `.env` for you:
- creates `.env` from `.env.example` if it is missing;
- generates a strong `SECRET_KEY` (if missing or a placeholder), and sets `ENVIRONMENT=production`, `DEBUG=false`;
- generates `POSTGRES_PASSWORD` for a **new** database (an existing database keeps its password — see [Rotating the database password](#rotating-the-database-password));
- **picks free ports**: if 80/443 are free, Caddy serves your `DOMAIN` with automatic HTTPS; if another service already owns them, it switches to plain HTTP on the first free host port from 2000 (HTTPS side from 2443) and tells you which.
Then load the demo data once (skip this if the database already has users):
```bash
docker compose exec api python -m scripts.seed
```
Check it:
```bash
make status # containers, ports and the site URL
curl http://localhost:<HTTP_PORT>/health # {"status":"ok", ... "pdf_engine":"weasyprint"}
```
### Deploying on a VPS over SSH
```bash
ssh user@your-vps
sudo apt-get install -y docker.io docker-compose-v2 git # or Docker's official install script
git clone <repo-url> pharma-web-celtic && cd pharma-web-celtic
DOMAIN=app.example.com make deploy # omit DOMAIN if you only have an IP address
```
Which case applies is decided by what is listening on the server:
| Situation | What `setup.sh` does | How users reach it |
|---|---|---|
| Ports 80/443 free, real `DOMAIN` (DNS already points at the server) | Caddy takes 80/443 | `https://app.example.com` — certificate is automatic |
| Ports 80/443 free, no domain | `DOMAIN=localhost` | `https://<ip>` with a self-signed certificate warning |
| **80/443 already used** by another service | `DOMAIN=:80`, next free `HTTP_PORT` (e.g. `2000`) | `http://<ip>:2000`, or put your existing proxy in front (below) |
Open the chosen port in the firewall only if you want direct access (`sudo ufw allow 2000/tcp`); if a proxy on the same host fronts it, block it instead (`sudo ufw deny 2000/tcp` — the proxy still reaches it on `127.0.0.1`).
**Existing nginx in front** (terminating TLS on 80/443):
```nginx
server {
server_name app.example.com;
listen 443 ssl; # + your certificate directives
location / {
proxy_pass http://127.0.0.1:2000; # the HTTP_PORT chosen by setup.sh
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $remote_addr;
}
}
```
**Choosing ports yourself:** edit `.env` (`HTTP_PORT`, `HTTPS_PORT`, `DOMAIN`) and run `docker compose up -d`. `setup.sh` keeps ports your own containers already use and only moves them when something else holds them.
### Day-to-day operations
```bash
docker compose logs -f api # API logs (also: web, caddy, db)
docker compose ps # status
make deploy # after git pull: rebuild and restart
docker compose down # stop (data volumes are kept)
docker compose down -v # stop AND DELETE the database and PDFs — never on a live system
docker compose exec db pg_dump -U pharma pharma > backup-$(date +%F).sql # database backup
```
### Rotating the database password
The database keeps the password it was created with; changing `POSTGRES_PASSWORD` in `.env` alone would lock the API out. To rotate (needed if `setup.sh` warned about a default password):
```bash
NEW=$(python3 -c "import secrets;print(secrets.token_urlsafe(24))")
docker compose exec db psql -U pharma -d pharma -c "ALTER USER pharma PASSWORD '$NEW';"
sed -i "s|^POSTGRES_PASSWORD=.*|POSTGRES_PASSWORD=$NEW|" .env
docker compose up -d
```
### What the stack contains
| Service | Image | Notes |
|---|---|---|
| `caddy` | `caddy:2-alpine` | The only service publishing ports; routes `/api`, `/docs`, `/health` to the API and everything else to the web app |
| `api` | built from `Dockerfile` | Non-root, read-only filesystem, runs `alembic upgrade head` on start |
| `web` | built from `web/Dockerfile` | Static React build served by Caddy |
| `db` | `postgres:16-alpine` | Internal network only; data in the `pgdata` volume |
Things worth knowing:
- Compose refuses to start without `POSTGRES_PASSWORD` and `SECRET_KEY` (`make setup` fills them in).
- In `ENVIRONMENT=production` the API refuses to boot if WeasyPrint's system libraries are missing or `SECRET_KEY` is a placeholder / under 32 characters. `GET /health` reports `"pdf_engine": "weasyprint"`.
- Set `RUN_MIGRATIONS=0` on the `api` service to skip the start-up migration.
- The database and API are **not** published to the host. To reach the database from the host (tests, `psql`) use the development overlay: `DB_PORT=5433 make dev-db` publishes it on `127.0.0.1:5433` only.
- Volumes to back up: `pgdata` (use `pg_dump`) and `pdfstore` (approved DCR PDFs).
- The seed creates demo accounts that share one well-known password (see `scripts/seed.py`). **Change every password before real use.**
---
## Local development
Prerequisites: Python 3.11+, Node.js 20+, Docker (for PostgreSQL).
```bash
# 1. Python environment
python -m venv .venv && source .venv/bin/activate # Windows: .\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
# 2. Settings
cp .env.example .env # development defaults; DATABASE_URL already points at localhost:5432
# 3. PostgreSQL on localhost:5432 (also creates the pharma_test database)
make dev-db # port taken? DB_PORT=5433 make dev-db, and use 5433 in DATABASE_URL
# 4. Schema and demo data
alembic upgrade head
python -m scripts.seed
# 5. API (http://localhost:8000, docs at /docs)
uvicorn app.main:app --reload
# 6. Web app (http://localhost:5173, proxies /api to port 8000)
cd web && npm install && npm run dev
```
`make dev-up` starts the whole stack in containers with the database (`DB_PORT`, default 5432) and API (`API_PORT`, default 8000) published on `127.0.0.1` only. Run `make help` for all targets.
**PDF rendering on a dev machine:** WeasyPrint needs Pango and HarfBuzz (`apt install libpango-1.0-0 libpangoft2-1.0-0 libharfbuzz0b fonts-dejavu-core fonts-liberation fonts-crosextra-carlito` on Debian/Ubuntu). Without them the app still runs but produces plain-text PDFs and logs a warning; use the Docker image to see the real layout.
Seeded accounts (`scripts/seed.py`): `adm001@acmepharma.in` (System Admin), `gm001@acmepharma.in` (AGM), `am001@acmepharma.in` (ABM), `mr001@acmepharma.in` (MR) — one company, one headquarters (BBSR), 15 doctors (3 core) and 5 chemists assigned to the MR.
---
## Configuration
All settings come from environment variables (or `.env`); nothing secret lives in code. See `app/config/settings.py`.
**Deployment (read by Docker Compose)**
| Variable | Default | Purpose |
|---|---|---|
| `POSTGRES_USER` / `POSTGRES_DB` | `pharma` | Database credentials and name |
| `POSTGRES_PASSWORD` | *required* | Database password |
| `SECRET_KEY` | *required* | JWT signing key — 64+ random characters |
| `DOMAIN` | `localhost` | Host name Caddy serves and obtains a certificate for (`:80` = plain HTTP, see below) |
| `HTTP_PORT` / `HTTPS_PORT` | `80` / `443` | Host ports Caddy publishes (`setup.sh` picks free ones) |
| `ENVIRONMENT` | `production` | `production` enables the start-up safety checks |
| `WEB_CONCURRENCY` | `2` | Uvicorn worker processes |
**Application**
| Variable | Default | Purpose |
|---|---|---|
| `DATABASE_URL` | local Postgres | `postgresql+asyncpg://…` (Alembic derives a `psycopg` URL from it) |
| `PDF_STORAGE_PATH` | `./storage/pdf` | Where approved DCR PDFs are written |
| `CORS_ORIGINS` | localhost dev origins | Allowed browser origins |
| `DEBUG` / `DB_ECHO` | `false` | Verbose logging / SQL echo |
| `PDF_COMPANY_NAME`, `_ADDRESS`, `_WEBSITE`, `_EMAIL`, `_PHONE` | Celtic details | Letterhead on every PDF |
**Business rules** — settings rather than constants, so they change without a code change:
| Variable | Default | Rule |
|---|---|---|
| `BACKDATING_WINDOW_DAYS` | `7` | How many days back an MR may file |
| `SUBMISSION_DEADLINE_DAYS` | `1` | Report for date D must be submitted by end of D+N |
| `MIN_RETURN_REASON_LENGTH` | `10` | Minimum length of a manager's return reason |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `15` | Access-token life |
| `REFRESH_TOKEN_EXPIRE_DAYS` | `7` | Refresh-token life |
| `LOGIN_MAX_FAILED_ATTEMPTS` | `10` | Failed logins before lockout |
---
## Web application
A React 18 + TypeScript (Vite) single-page app in `web/`, styled as a minimal SaaS console: sidebar navigation with the Celtic logo, a top bar with the user menu, cards, tables with search and filters, side drawers for forms, toast notifications, and loading / empty / error states on every screen. It works down to phone width (the sidebar becomes a slide-in menu) and remembers whether the sidebar is collapsed.
```
web/src/
├── main.tsx, App.tsx Entry point; role-aware route table and sign-in gate
├── api/ client.ts (fetch, token refresh, downloads) · index.ts (all endpoints)
├── lib/ router (hash-based), session (auth context), navigation, formatting
├── hooks/useAsync.ts Data loading with loading / error / reload state
├── components/
│ ├── ui/ Button, Card, Badge, Field, DataTable, Tabs, Modal/drawer, Toast, Icon, …
│ ├── layout/ AppShell, Sidebar, Topbar
│ └── reports/ StatusBadge, WorkflowTracker, ApprovalTimeline, VisitList, AddVisitForm, ReviewPanel
├── pages/ Login, Dashboard, Directory, Products, Profile
│ ├── reports/ list, new, detail (with review actions)
│ ├── forms/ company forms: table, row drawer, approval state
│ └── admin/ Setup (tabs) and Users
└── styles/ tokens.css · base.css · layout.css · components.css
```
Screens are role-aware: MR / ABM / AGM get a dashboard with counts and a "waiting on you" queue; the Administrator gets an organisation overview. Routes use hash URLs (`#/reports/<id>`), so every screen is linkable and the back button works behind any static file server. To add a page, create it under `pages/`, add a route in `App.tsx` and a menu entry in `lib/navigation.ts`.
### Branding and theme
The UI uses the Celtic logo and the colours taken from it.
| Token | Value | Used for |
|---|---|---|
| Brand blue | `#285AA8` (dark `#23509A`) | Primary buttons, links, active navigation, sign-in panel |
| Brand orange | `#E95C00` | Small accents (sign-in panel highlight, logo star) |
| Brand grey | `#808080` | The logo's dot; text and borders use a neutral grey scale |
- The logo is `web/public/celtic-logo.svg`; it is shown in the sidebar, on the sign-in page and as the browser-tab icon. Replace that one file to change it everywhere in the web app.
- All colours, radii, shadows and sizes are CSS variables in `web/src/styles/tokens.css` — change `--brand-*` there to re-theme the whole app. Status colours (green approved, amber in review, red returned) are semantic and intentionally not brand-coloured.
- The PDF letterhead is text (company details from the `PDF_COMPANY_*` settings) and shares its own stylesheet in `app/pdf/templates/base.html`.
---
## Roles and permissions
| Role | Can do |
|---|---|
| **MR** | File and edit own DCRs while `DRAFT`/`RETURNED`; submit; edit company forms |
| **ABM** | Review DCRs of own headquarters: approve or return; sees only the approval forms (Tour Plan, Standard Tour Plan, Fare Chart) |
| **AGM** | Read-only: view reports, users and headquarters across the company; no approval step |
| **ADMIN** | Provision users, headquarters and masters; monitor and read Daily Call Reports across the company. **Cannot approve reports** |
Permissions are checked in two separate layers, because most RBAC bugs live in the gap between them:
```python
# Layer 1 — WHAT may this role do?
current_user: User = Depends(require_role(Role.MR))
# Layer 2 — WHOSE data may this specific user touch?
await assert_can_view_dcr(db, current_user, dcr)
```
"ABM" is the stored role code for an ABM; "ABM *of this headquarters*" is a scope. Both are mandatory on scoped endpoints, and each has a negative test asserting **403** — not 404 or an empty 200 — so a scope bug cannot hide behind an ambiguous response.
The System Administrator can never approve: `ADMIN` matches no transition in the state machine, so the audit trail stays evidence that a manager made the decision.
---
## The approval workflow
```
DRAFT ──submit(MR)──► PENDING_ABM ──approve(ABM)──► APPROVED (terminal, immutable)
▲ │
│ └──return(ABM)──┐
└──────submit(MR)───── RETURNED ◄───────┘
```
- `RETURNED` records who returned it in the `returned_by_role` column. There is no AGM stage; the AGM is a read-only role.
- `APPROVED` is both "finally approved" and "locked": immutability is a property of the state, enforced in one guard, so there is no window where a report is approved but still editable.
- Managers change state and add comments; they never edit another person's call rows.
- Returning a report requires a reason (`MIN_RETURN_REASON_LENGTH`).
The whole workflow is `app/approvals/state_machine.py`, a table of transitions with the role allowed to make each one.
---
## Company forms and PDFs
The `csv_data` module exposes the company's paper forms as editable tables, importable from the CSV files in the repository root.
| Form | Table | Layout highlights |
|---|---|---|
| Standard Tour Plan ¹ | `standard_tour_plan` | Route places, place count |
| Tour Plan ¹ | `tour_plan` | Date/from/to, POB total, stockist-visit count |
| Fare Chart ¹ | `fare_chart` | Travel log with total kilometers |
| Area Covered | `area_covered` | Area coverage and sale objectives |
| Core Doctor Call Conversion | `core_dr_call_conversion` | Doctor follow-up with status summary |
| Field Activity Report | `field_activity_report` | Daily activity, totals and call averages |
| Sales and Stock Statement | `sales_and_stock_statement` | Opening/receipt/sale/closing with value totals |
| Sales Projection | `sales_projection` | Landscape, product-wise projection |
| Weekly Report | `weekly_report` | One page per saved report |
| Daily Call Report (CSV) | `daily_call_report_csv` | Doctor and chemist sections (not exposed in the UI) |
¹ *Approval forms* — the ABM can only see these, and their PDF carries the ABM approval signature line.
**Approval forms are per MR.** Tour Plan, Standard Tour Plan and Fare Chart rows belong to the MR who entered them (`owner_user_id`), each MR sees and numbers only their own, and the approval (`form_approval`) is kept per form *and* MR. A request goes only to the Area Business Manager who currently manages that MR's headquarters: any other Area Business Manager gets a 403 and never sees it in their list, and an MR whose headquarters has no Area Business Manager cannot send a form. Editing an MR's rows withdraws only that MR's approval. An admin fills a form in on behalf of one chosen MR and can never approve.
**Monthly download.** Forms with a month (Sales Projection, Weekly Report, Field Activity Report, Core Doctor Call Conversion, Area Covered, Sales and Stock Statement) get a Month selector. The table and the PDF (`GET /csv-data/{form}/pdf?month=November`) then cover that month only; a month with no rows is refused rather than printed blank.
**How PDFs are built.** The DCR (`dcr.html`) extends the stylesheet `app/pdf/templates/base.html`. The company forms do **not**: each is a copy of the company's printed form — same letterhead, title, column headings, column proportions, number of ruled lines and signature block — built from `app/pdf/templates/forms/_form_base.html` plus one small template per form. `app/pdf/forms.py` decides what each form prints (headings, widths, how many blank lines); stored rows fill the lines from the top, and rows beyond the printed length continue on the next page with the header repeated. Fonts: Liberation Sans/Serif and Carlito (the Arial / Times / Calibri look-alikes of the printed forms), with DejaVu as fallback.
- `GET /api/v1/csv-data/{table}/pdf` prints **every stored row**; `…/rows/{id}/pdf` prints one row.
- Blank numbered lines pad each form to its printed length; longer data is never truncated.
- Identity fields (name, headquarter, month) are gathered from all rows, and for an MR always reflect the logged-in account.
**Importing data.** `python -m scripts.import_csv_data` loads the CSV files from the repo root. It **replaces** the contents of every form table — never run it against a database holding real data — use `python -m scripts.import_csv_data --only-empty` instead, which loads only tables that have no rows (e.g. the product lists) and never deletes anything. It is deliberately not part of container start-up, and the CSVs are not in the Docker image.
---
## API overview
Base path `/api/v1`; interactive documentation at `/docs` and `/redoc`, schema at `/openapi.json`.
| Module | Prefix | Purpose |
|---|---|---|
| auth | `/auth` | Login, refresh (rotating tokens), logout, current user |
| users | `/users` | User administration and the MR profile |
| organization | `/headquarters` | Headquarters and ABM↔HQ mapping |
| doctors, chemists | `/doctors`, `/chemists` | Masters and MR assignment |
| products | `/products` | Product master and stock inventory list |
| reports | `/dcr` | DCR CRUD, calls, submit / return / approve, PDF |
| audit | `/audit` | Read access to the audit log |
| csv_data | `/csv-data` | Company form tables, rows and PDFs |
Errors use one envelope: `{"error": {"code": "…", "message": "…", "details": {…}}}`.
---
## Project layout
```
app/
├── main.py App factory, error envelope, CORS, production preflight
├── config/ Pydantic settings
├── database/ Engine, session, declarative base, model registry
├── common/ Enums, exceptions, base repository, helpers
├── auth/ JWT, argon2, refresh rotation, permission dependencies
├── users/ organization/ doctors/ chemists/ products/ Masters
├── reports/ DailyCallReport, DoctorCall, ChemistCall ← core domain
├── approvals/ The state machine ← the rules live here
├── audit/ Append-only log
├── csv_data/ Company form tables and their endpoints
├── pdf/ service.py, forms.py, templates/ (base, dcr, forms/*)
└── api/v1/ Router mount point
alembic/ Migrations
scripts/ seed, CSV import, audit hardening SQL, container entrypoint
web/ React application (its own Dockerfile) — see "Web application"
tests/ unit/, integration/, e2e/
```
Domain modules share the same file set, so a new module is a copy of a folder: `models.py` (ORM), `schemas.py` (Pydantic), `service.py` (business rules, transactions, audit calls) and `router.py` (HTTP only).
---
## Design decisions
**Database-enforced constraints.** Under concurrency only the database can guarantee these, so they are constraints, not just service checks:
```sql
-- One report per MR per calendar day
ALTER TABLE daily_call_report ADD CONSTRAINT uq_dcr_mr_date UNIQUE (mr_user_id, report_date);
-- No duplicate doctor call within one report
ALTER TABLE doctor_call ADD CONSTRAINT uq_call_dcr_doctor UNIQUE (dcr_id, doctor_id);
-- Exactly one active Area Business Manager per headquarters
CREATE UNIQUE INDEX uq_active_am_per_hq ON am_headquarters (headquarters_id)
WHERE effective_to IS NULL;
```
`tests/integration/test_db_constraints.py` proves each rejects the bad case *and* permits the good one.
**Tables deliberately not created.** The original brief listed 28 tables; the core domain uses far fewer:
| Not created | Instead |
|---|---|
| `role` | `user.role` enum — four fixed roles; a lookup table adds a join to every request |
| `mr_profile`, `area_manager_profile` | Merged into `user` |
| `area_territory` | Merged into `headquarters` — the HQ *is* the territory |
| `mr_assignment` | `user.headquarters_id` — an MR has exactly one HQ |
| `core_doctor_conversion` | `doctor.is_core_doctor` + `doctor_call.conversion_status` |
| `comments` | `audit_log.comment` — every comment attaches to a state change |
| `approval_history` | A filtered query over `audit_log` — one source of truth |
**Single-VPS deployment.** No Kubernetes, message broker or microservices: one company and a handful of MRs do not need them, and each extra piece is something to operate.
---
## Testing
Tests run against a real PostgreSQL database — never SQLite. The system relies on partial unique indexes, composite uniques and `jsonb`, which SQLite does not implement the same way.
```bash
make dev-db # starts Postgres and creates pharma_test
export TEST_DATABASE_URL=postgresql+asyncpg://pharma:<password>@localhost:5432/pharma_test
pytest -q # everything
pytest tests/unit -q # state machine, PDF layouts — see note below
```
`tests/unit` is mostly pure logic (state machine, form PDF view-models and rendering), but a couple of tests there use the database. `make lint` runs ruff.
---
## Production checklist
1. **Set a real `SECRET_KEY`** (64 random characters) and `POSTGRES_PASSWORD`, from a secrets manager — never in the repo.
2. **Run `scripts/harden_audit.sql`** once as a superuser to make `audit_log` genuinely append-only (revokes UPDATE/DELETE from the app role, plus a trigger as a backstop). Then connect the API as the `pharma_app` role it creates.
3. **Change every seeded password**, or do not seed at all and create real users.
4. **Set `DOMAIN`** to the real host name and, once HTTPS is confirmed, enable the commented HSTS header in `Caddyfile`.
5. **Confirm the blocking business rules** marked in code as `A1`–`A16` / `Q1`–`Q9`; the shipped defaults are assumptions, not decisions.
6. **Back up** `pgdata` and `pdfstore`, and **test a restore** — an untested backup is not a backup.
7. **Point an error tracker (e.g. Sentry) at the app** so production 500s surface as errors.
---
## Known limitations
- **Company-form approval is per form, not per row.** The tour plan, standard tour plan and fare chart each have one server-stored approval state (`draft → pending → approved`). The MR sends a form that has rows, the Area Business Manager approves it, and the PDF signature is decided by the server. Any change to the rows withdraws the approval.
- **`web/node_modules` and `web/dist` are committed** to the repository (with stale build output) and should be untracked; Docker builds the app from source.
- The test suite needs a reachable PostgreSQL; some tests under `tests/unit` also need it.
---
## Troubleshooting
| Symptom | Fix |
|---|---|
| `required variable POSTGRES_PASSWORD is missing` | Create `.env` from `.env.example` and fill it in |
| API exits with `SECRET_KEY must be a random value…` | Set a `SECRET_KEY` of 32+ random characters |
| API exits with `WeasyPrint system libraries are required` | Use the provided image, or install Pango/HarfBuzz and DejaVu fonts |
| PDFs are plain text | WeasyPrint is unavailable (`/health` shows `"pdf_engine": "fallback"`) |
| `no pq wrapper available` from Alembic | `pip install --upgrade --force-reinstall "psycopg[binary]"` |
| Web build in Docker fails on `esbuild` | A host `node_modules` leaked in; check `web/.dockerignore` |
| `npm run build` fails with `tsc: Permission denied` | The committed `web/node_modules` has lost its executable bits. Delete it and run `npm ci` (or build through Docker, which does this) |
| `failed to bind host port 0.0.0.0:80 … address already in use` | Another service owns 80/443. Run `make setup` (or `make deploy`): it switches to free ports. Manually: `DOMAIN=:80`, `HTTP_PORT=2000`, `HTTPS_PORT=2443` in `.env` |
| `password authentication failed` after editing `POSTGRES_PASSWORD` | The database keeps its original password — see *Rotating the database password* |
| API container unhealthy / restarting | `docker compose logs api`: a weak `SECRET_KEY` or missing WeasyPrint stops a production start on purpose |
| Port 5432 in use during `make dev-db` | Set `DB_PORT` (e.g. `DB_PORT=5433`) and adjust `TEST_DATABASE_URL` |