62 lines
2.4 KiB
Markdown
62 lines
2.4 KiB
Markdown
|
# 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)
|
|||
|
|
|
|||
|
|
```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.
|