61 lines
2.4 KiB
Markdown
61 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.
|