fleet-platform

Greenfield rebuild of the Rahamafresh fleet telematics platform.

One FastAPI codebase, one Docker image, three container roles (gateway / worker / cron) from the same image. Event-sourced ingest into TimescaleDB + PostGIS. JWT-mandatory reads. Image-tag deploys via Coolify from a self-hosted Forgejo registry.

See:

• 260522_fleet_platform_prd_final.md — product spec (P1–P4)
• 260522_fleet_platform_architecture_final.md — engineering design (phases A–G)
• ~/.claude/plans/you-are-an-experienced-majestic-planet.md — approved Phase 1 plan

Quick start (dev)

cp .env.example .env
# edit .env: at minimum set POSTGRES_PASSWORD, JWT_SECRET, TRACKSOLID_PUSH_TOKEN
docker compose -f docker-compose.dev.yml up

Health checks:

curl http://localhost:8001/health/gateway
curl http://localhost:8001/health/worker   # via worker container's exposed port
curl http://localhost:8001/health/cron

Layout

app/                   one FastAPI codebase
  entrypoints/         three role entrypoints from the same image
    gateway.py         /push/jimi/*, /api/views/*, /api/auth/token
    worker.py          LISTEN parser + projectors
    cron.py            polling + SLO + contract checker
  models/              Pydantic models (Jimi contracts, view shapes)
  parsers/             one function per msg_type / poll endpoint
  projectors/          single-writer projectors per state table
db/migrations/         dbmate forward-only SQL
scripts/               operational utilities (parity_check, entrypoint.sh)
tests/                 pytest
web/                   fleet-core.js + index-live.html + login.html

Container roles

The same image runs in three roles, selected by APP_ROLE:

Role	Workload
gateway	HTTP: Tracksolid push receivers + dashboard read API + JWT issuance
worker	LISTEN events_raw_new / events_parsed_new → parser → projectors
cron	APScheduler: polled ingest (60s/10m), SLO measurement, contract checker

Failure isolation is the point: a heavy report in worker does not stall gateway.

Deploy

CI (Forgejo Actions) builds on push to main, tags <registry>/fleet-platform:<sha> and :latest. Coolify deploys by tag. Rollback is coolify deploy :<prev-sha>.

dbmate up runs on platform-worker startup before the worker serves traffic; gateway and cron wait on a startup probe that confirms migration completion.