fleet-platform/README.md

# fleet-platform

Greenfield rebuild of the Rahamafresh fleet telematics platform — CI is live on Forgejo Actions.

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)

```sh
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:

```sh
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.