Backend API for Damm route/catalog data. Local database is JSON at data/app_db.json.

• Python 3.11+ (3.13 recommended; tested on 3.14).
• macOS or Windows. Linux works the same as macOS.

If you don't already have Python on macOS, install it with Homebrew:

brew install python@3.13

From the project root:

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

After this, python and pytest will resolve to the venv. Reactivate later with source .venv/bin/activate.

To leave the venv:

deactivate

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

With the venv activated:

uvicorn main:app --reload

Or without activating the venv:

.venv/bin/uvicorn main:app --reload

Open:

http://127.0.0.1:8000/docs

The bare host (http://127.0.0.1:8000/) redirects to /docs. The user-facing UI lives in the damm-frontend repo.

If port 8000 is busy:

uvicorn main:app --reload --port 8001

.\.venv\Scripts\python.exe -m uvicorn main:app --reload

The repo has no installable package, so tests need the project root on PYTHONPATH:

PYTHONPATH=. .venv/bin/pytest --basetemp .pytest_tmp

Or, with the venv activated:

PYTHONPATH=. pytest --basetemp .pytest_tmp

Run a single file:

PYTHONPATH=. .venv/bin/pytest tests/test_orders_import.py -q

.\.venv\Scripts\python.exe -m pytest --basetemp .pytest_tmp

Generic DB endpoints read schema from local JSON data and allow dynamic rows/tables.

GET    /api/v1/db/tables
GET    /api/v1/db/{table}/schema
GET    /api/v1/db/{table}?limit=100
GET    /api/v1/db/{table}/{row_id}
POST   /api/v1/db/{table}
PATCH  /api/v1/db/{table}/{row_id}
DELETE /api/v1/db/{table}/{row_id}

macOS examples:

curl 'http://127.0.0.1:8000/api/v1/db/warehouses?limit=1'
curl -X POST http://127.0.0.1:8000/api/v1/db/notes \
  -H 'Content-Type: application/json' \
  -d '{"title":"test"}'
curl -X PATCH http://127.0.0.1:8000/api/v1/db/notes/<row_id> \
  -H 'Content-Type: application/json' \
  -d '{"done":true}'

Three endpoints under /api/v1/optimize/. They drive the planner: generate suggestions cheaply with preview, then commit the chosen one with persist.

POST /api/v1/optimize/full          → async; runs solver in background, persists, returns job_id + ws_url
POST /api/v1/optimize/full/preview  → sync; runs solver and returns the route(s) without saving anything
POST /api/v1/optimize/persist       → commits a precomputed RouteResult as a transport + delivery_stops

persist skips the solver entirely. It takes a RouteResult (typically the one you just got back from preview) and writes it as a new transport. Driver is matched by name, truck by capacity (scoped to warehouse_id when given), and the route row is auto-created if route_code doesn't already exist — so the persisted transport renders with its optimizer label in the read endpoints.

Generate a preview:

curl -X POST http://127.0.0.1:8000/api/v1/optimize/full/preview \
  -H 'Content-Type: application/json' \
  -d '{
    "date": "2026-01-30",
    "warehouse_id": "<warehouse-uuid>",
    "max_orders": 30,
    "solver_time_limit_s": 10
  }'

That returns {result: {route, routes, load, viz, ...}}. Take the route object and post it back to commit:

curl -X POST http://127.0.0.1:8000/api/v1/optimize/persist \
  -H 'Content-Type: application/json' \
  -d '{
    "route": <RouteResult from preview>,
    "warehouse_id": "<warehouse-uuid>"
  }'

Response:

{
  "status": "ok",
  "transport_id": "...",
  "stops_inserted": 3,
  "resolved_driver_id": null,
  "resolved_truck_id": "...",
  "resolved_route_id": "..."
}

The new transport is queryable via /api/v1/data/transport/{transport_id} and shows up in /api/v1/data/transports.

Upload a CSV of new orders. The CSV must have a header row and use ; or , as the delimiter. Required columns: customer_id, material_id, quantity, sales_unit. Optional column: due_date.

customer_id and material_id are the UUIDs from the customers and materials tables (browse them via GET /api/v1/db/customers and GET /api/v1/db/materials). The importer is strict: rows are inserted only when both UUIDs already exist. Unknown customers and materials are skipped, never created. A ready-to-use sample for the seeded demo DB lives at data/sample_orders.csv.

curl -X POST http://127.0.0.1:8000/api/v1/data/orders/import \
  -F "file=@data/sample_orders.csv" \
  -F "due_date=2026-05-09"

The response includes received, inserted, skipped, the list of unknown_customers, the list of unknown_materials, and the first 200 per-row errors.

Every imported order is tagged with imported_via_csv: true. To wipe everything created by past CSV imports — without touching the seeded baseline — call:

curl -X DELETE http://127.0.0.1:8000/api/v1/data/orders/imported

Response: {"status":"ok","deleted_orders":<n>,"deleted_delivery_lines":<n>}.

Use CLI for quick local reads/writes without running the API.

macOS / Linux:

.venv/bin/python db_cli.py tables
.venv/bin/python db_cli.py schema warehouses
.venv/bin/python db_cli.py list warehouses --limit 5
.venv/bin/python db_cli.py insert notes --data '{"title":"test"}'
.venv/bin/python db_cli.py update notes <row_id> --data '{"done":true}'
.venv/bin/python db_cli.py delete notes <row_id>

Windows PowerShell:

.\.venv\Scripts\python.exe db_cli.py tables
.\.venv\Scripts\python.exe db_cli.py schema warehouses
.\.venv\Scripts\python.exe db_cli.py list warehouses --limit 5
.\.venv\Scripts\python.exe db_cli.py insert notes --data "{\"title\":\"test\"}"
.\.venv\Scripts\python.exe db_cli.py update notes <row_id> --data "{\"done\":true}"
.\.venv\Scripts\python.exe db_cli.py delete notes <row_id>

The app runs from data/app_db.json. Raw Excel workbooks and processed snapshots are not part of the runtime anymore. To seed new orders for testing the optimizer, use the CSV import endpoint above or db_cli.py insert orders ....