Axiom Urban v4.0

Axiom Urban is a traffic-corridor analysis platform that combines FastAPI workflows, a gRPC physics engine, and report generation into a single operator-facing system.

Repository Layout

• backend/ - FastAPI API, worker, orchestration, migrations, tests
• physics/ - gRPC simulation services
• frontend/ - React/Vite UI
• nginx/ - ingress configuration
• scripts/ - startup, deployment, monitoring, smoke scripts
• docs/ - architecture, deployment, developer and testing documentation
• docker-compose*.yml - dev/prod/test compose files

Quick Start (Docker)

docker compose -f docker-compose.yml up -d --build
docker compose -f docker-compose.yml ps

Expected dev services:

• postgres
• redis
• physics
• migrate (one-shot, exits 0)
• api
• worker
• frontend
• nginx

Health Checks

curl -f http://localhost:3080/api/v1/health/live
curl -f http://localhost:3080/api/v1/health

Note (Windows PowerShell): use curl.exe to avoid the curl alias to Invoke-WebRequest.

End-to-End Smoke

Use the built-in smoke runner:

bash scripts/compose_smoke_test.sh

The smoke flow waits for health, creates an analysis job, polls until terminal status, then verifies results and PDF endpoints.

Production smoke (local TLS, self-signed cert is OK):

COMPOSE_FILE=docker-compose.prod.yml \
COMPOSE_PROFILES=local-redis \
BASE_URL=https://localhost \
CURL_INSECURE=1 \
bash scripts/compose_smoke_test.sh

Local Dev (without Docker)

• Backend: cd backend && uvicorn app.main:app --reload
• Physics: cd physics && python -m app.server
• Frontend: cd frontend && npm run dev

Core Architecture

• Ingress: nginx
• API and async worker split: api + worker
• Queue/cache: Redis
• Primary DB: PostgreSQL/PostGIS
• Simulation: gRPC calls to physics
• Migrations: one-shot migrate
• Production ingress behavior: nginx proxies /api/* to api and / to frontend.
• Frontend assets are served by frontend container behind nginx.

Frontend Entry Flow

• / shows the branded landing page.
• Landing page DASHBOARD button navigates to /dashboard.
• /301 is maintained as a compatibility path and is resolved to dashboard routing.

Production Compose (Deterministic Local Profile)

docker compose -f docker-compose.prod.yml --profile local-redis up -d --build
docker compose -f docker-compose.prod.yml --profile local-redis ps

Health (local TLS uses self-signed fallback cert by default):

curl -k -f https://localhost/api/v1/health/live
curl -k -f https://localhost/api/v1/health

Note (Windows PowerShell): use curl.exe (and keep -k for self-signed local TLS).

URL behavior:

• https://localhost/ loads the frontend app
• https://localhost/301 is treated as an SPA path and should return app HTML (200)
• http://localhost/* redirects to HTTPS (301)

Canonical architecture doc: docs/ARCHITECTURE.md

Testing

pytest backend/tests/deployment -q
pytest backend/tests/smoke/test_startup.py -q
docker compose -f docker-compose.test.yml run --rm api-test python -m pytest -q /app/backend/tests

Documentation

• Architecture: docs/ARCHITECTURE.md
• Deployment: docs/DEPLOYMENT.md
• Developer Guide: docs/DEVELOPER.md
• Testing Guide: docs/TESTING.md
• Oracle Cloud (override): docker-compose.oracle.yml and scripts/deploy-oracle.sh (archived guide: docs/archive/root_ORACLE_CLOUD_DEPLOYMENT_GUIDE.md)