TrafficGrid — Implementation Tracker¶

Last audited: 2026-08-26
Sources: TrafficGrid.md, TrafficGrid System Design.md, Data Model.md, API Contracts.md, codebase scan

Use this to see where the project stands and what to pick up next. Status is relative to Phase 1 scope in the architecture docs (not the future backlog).

Status	Meaning
Done	Present and usable for its intended Phase 1 role
Partial	Module/entity exists but APIs, wiring, or behaviour are incomplete
Missing	Not in the repo / not started
Deferred	Explicitly out of Phase 1 (future backlog)

1. Snapshot — Where you left off¶

Platform scaffolding is largely in place. Domain work progressed furthest on auth, system-parameters, and audit. Vehicle is a thin create-only scaffold. Fines, payments, and notifications services do not exist yet.

You appear to have stopped mid–message-broker migration: root docker-compose.yaml runs Kafka, but Java code still publishes/consumes RabbitMQ for audit events.

Suggested next focus (in order):

Finish the RabbitMQ → Kafka cutover (auth publisher, audit listener, deps, config-server).
Complete vehicle-service (read/search, citizen link, documents, JWT security).
Create fines-service (core Phase 1 product loop).
Create payments-service, then notifications-service.
Wire OpenFeign + domain Kafka topics between those services.

2. Services inventory¶

Service	Port	Status	Notes
discovery (`discovery/`)	8761	Done	Eureka registry
config-server	8888	Done	Native classpath configs; no fines/payments/notifications configs yet
api-gateway	8080	Partial	JWT validate + routes for auth/audit/system-parameters/vehicle; no rate limiting yet; no routes for missing services
auth-service	8081	Partial	Register/login/refresh/logout/validate + user admin; Redis token blocklist incomplete; Flyway path broken
audit-service	8082	Partial	Consume + query APIs; empty Flyway; method security may not enforce
system-parameters-service	8083	Done	Strongest domain module — orgs, currencies, fine categories, payment methods, notification channels + seeds
vehicle-service	8084	Done	Full CRUD, search/filtering, citizen vehicles link/unlink, vehicle documents, JWT + Gateway security
fines-service	8085	Missing	No module
payments-service	8086	Missing	No module
notifications-service	8088	Missing	No module
core-service (shared JAR)	—	Done	`core-common` + `core-web`: JWT helpers, envelopes, exceptions, OpenAPI, Kafka topology

3. Infrastructure¶

Component	Planned	Status	Notes
PostgreSQL	Yes	Done	Root + init-scripts compose; schemas created in init SQL
Redis	Yes	Partial	Running; used for auth Redis config, but JWT blocklist code commented out
Message broker	Kafka (KRaft)	Done	Root + init-scripts compose: Kafka KRaft; auth-service & audit-service use Spring Kafka
Docker Compose (infra)	Yes	Done	Postgres + Redis + Kafka
Per-service Docker images	Production future	Missing	Services run as local Java processes
Kubernetes	Production future	Deferred
CI/CD (GitHub Actions)	Production future	Deferred	Docs mention it; not wired for the monorepo services
Schema naming consistency	—	Partial	init-scripts: `auth_service`; auth config: `user_service`. Vehicle: Hibernate `vehicle_service` vs migration/entity schema `vehicles`

4. Data model vs code¶

Entity	Owner (docs)	Status	Notes
`users`	auth-service	Done	Entity + APIs; Flyway file under typo folder `db.migation` (not applied) — relies on `ddl-auto`
`organisations`	system-parameters	Done	CRUD + activate/deactivate + seeds
`currencies`	system-parameters	Done
`fine_categories`	system-parameters	Done
`payment_methods`	system-parameters	Done	Reference data only (not payment processing)
`notification_channels`	system-parameters	Done	Reference data only
`vehicles`	vehicle-service	Partial	Create API only; no get/search/update
`citizen_vehicles`	vehicle-service	Partial	Flyway table exists; no JPA entity / no API
`vehicle_documents`	vehicle-service	Missing	`DocumentType` enum only
`fines`	fines-service	Missing
`parking_tickets`	fines-service	Deferred / Missing	Docs mark Planned — City Parking API
`payments`	payments-service	Missing
`payment_items`	payments-service	Missing	Docs mark Planned with payments feature
`notifications`	notifications-service	Missing
`notification_preferences`	notifications-service	Missing
`audit_logs`	audit-service	Partial	Entity + listen/query; no Flyway; missing some doc fields (`ip_address`, `user_agent`)

5. API contracts vs implementation¶

Gateway path prefix: /auth-service, /audit-service, etc. Service paths use /api/v1/....

Auth — Partial¶

Contract area	Status
Register / login / refresh	Done
Logout	Done (path secured; Redis revoke incomplete)
Validate (gateway)	Done
Admin create user / activate / deactivate / list / get	Done

Vehicles — Partial¶

Contract area	Status
Create vehicle	Done (`POST api/v1/vehicles`)
Get / search / update vehicle	Missing
Vehicle documents CRUD	Missing
Citizen link / unlink / list	Missing

Fine categories — Done (in system-parameters)¶

Owned by system-parameters (not fines-service), matching current design.

Organisations / currencies / payment methods / notification channels — Done¶

CRUD (or activate/deactivate) under system-parameters.

Fines — Missing¶

Entire module and APIs (issue, get, list by vehicle, status changes, dispute, clear, cancel).

Parking tickets — Missing / Deferred¶

Payments — Missing¶

Initiate, idempotency, cash recording, receipts, multi-item settlement.

Notifications — Missing¶

History + preferences REST; event-driven send.

Audit logs — Partial¶

Contract area	Status
Query by actor / organisation / entity	Done
Immutable ingest via events	Partial (auth audit events only)

Admin users — Done (auth-service)¶

6. Functional requirements (Phase 1)¶

Requirement	Status	Evidence / gap
Citizen self-register + login	Done	auth-service
Officer/admin account creation (RBAC)	Partial	User create + roles exist; org scoping / creation rules may need hardening
Vehicle create / register	Partial	Create only
Citizen link vehicle by plate	Missing
Vehicle dashboard (docs, fines, renewals)	Missing	Needs vehicle + fines + notifications
Officer issue fine	Missing	fines-service
Fine statuses PENDING/PAID/CLEARED/DISPUTED/CANCELLED	Missing
Cash payment recorded by officer	Missing	payments-service
EcoCash / bank transfer	Missing	External integrations Deferred for real providers
Payment idempotency	Missing
Parking tickets	Deferred
Notifications on fine / payment / expiry	Missing
Audit every write	Partial	Auth actions via aspect + Rabbit; other services not emitting
OpenAPI / Swagger	Partial	springdoc on services + gateway aggregation for existing services
Offline officer sync	Deferred	Client concern

7. Cross-cutting platform features¶

Feature	Status	Notes
JWT auth	Partial	Issued/validated; gateway forwards `X-User-Id`, `X-User-Role`
RBAC	Partial	Method security on auth + system-parameters; vehicle open; audit annotation may be inert
Gateway routing	Partial	Existing services only
Rate limiting	Missing	Documented NFR; not implemented on gateway
OpenFeign inter-service calls	Missing	Config defaults exist; zero `@FeignClient`s
Async domain events (fine/payment/vehicle)	Missing	Only `audit.exchange` / `audit.queue`
Kafka adoption	Partial	Infra only; code still AMQP
Distributed locks (payment races)	Missing
Circuit breakers / timeouts	Partial	Feign CB config present; unused without Feign clients
Actuator health (liveness/readiness)	Unknown / likely Missing	Not verified as a deliberate setup
Dead letter queues	Missing
Automated tests	Missing	Smoke/context stubs only
Citizen / officer mobile apps	Missing	No clients in repo
Authority / super-admin web portals	Missing

8. Messaging topology¶

Designed (System Design v2 — RabbitMQ topic exchanges)¶

Exchange	Events	Status
`trafficgrid.fines`	`fine.created`, `fine.status.updated`	Missing
`trafficgrid.payments`	`payment.success`, `payment.failed`	Missing
`trafficgrid.vehicles`	`vehicle.document.expiry`	Missing
`trafficgrid.notifications`	internal dispatch	Missing

Implemented today¶

Piece	Status
`audit.exchange` + `audit.queue` + routing key	Done (RabbitMQ in `RabbitConfig`)
Auth `AuditEventPublisher`	Done (RabbitTemplate)
Audit `AuditEventListener`	Done (`@RabbitListener`)
Kafka producers/consumers	Missing

9. External integrations¶

Integration	Status
ZINARA API	Deferred (mock later)
VTS API	Deferred
City Parking API	Deferred
EcoCash	Deferred
Bank transfer webhooks	Deferred
SMS / email / push providers	Deferred

10. Known debt / blockers (fix before new domains)¶

Broker mismatch — Kafka in compose, RabbitMQ in code and config-server YAML.
Auth Flyway — db.migation typo; config expects db/migration.
Schema name drift — auth_service vs user_service; vehicle_service vs vehicles.
Vehicle security — permitAll until JWT filter is wired.
Auth Redis JWT blocklist — commented out; logout/revoke incomplete.
Audit Flyway empty + confirm @EnableMethodSecurity.
init-scripts compose / README — still document RabbitMQ; out of sync with root compose.
API Contracts vs System Design — contracts sometimes assume modular/monolith paths; system design is microservices. Tracker follows the running microservices layout.

11. Suggested implementation checklist¶

Use as a working backlog. Check off as you complete.

Platform hygiene¶

[x] Migrate auth → audit messaging from RabbitMQ to Kafka
[x] Remove RabbitMQ deps/config; align config-server + init-scripts
[x] Fix auth Flyway path and schema name
[x] Align vehicle schema names (config vs migrations)
[x] Enable vehicle JWT / gateway-header security
[ ] Restore Redis-backed token blocklist on logout
[ ] Add gateway rate limiting (at least public auth endpoints)

Vehicle (complete before fines)¶

[x] GET vehicle by id / by number plate
[x] List/search vehicles
[x] Citizen vehicles entity + link/unlink/list APIs
[x] Vehicle documents entity + CRUD + expiry fields
[ ] Emit document-expiry events (when notifications exist)

Fines-service (new)¶

[ ] Service scaffold + Eureka + config + gateway route
[ ] fines schema + Flyway
[ ] Issue fine (Feign: vehicle exists, fine category from system-parameters)
[ ] Get / list by vehicle / status transitions
[ ] Publish fine.created / fine.status.updated

Payments-service (new)¶

[ ] Service scaffold + gateway route
[ ] payments + payment_items
[ ] Idempotent pay flow (stub provider OK for Phase 1)
[ ] Cash recording by officer
[ ] Publish payment.success / payment.failed; fines consume → mark PAID

Notifications-service (new)¶

[ ] Service scaffold + gateway route
[ ] Consume fine/payment/document events
[ ] Preferences + notification history APIs
[ ] Stub channel adapters (log-only) until SMS/email providers

Hardening¶

[ ] Real unit/integration tests for auth, payments idempotency, fine issue
[ ] Audit events from all write paths
[ ] DLQ + retry policy on consumers
[ ] Actuator liveness/readiness

Clients (after core APIs stabilize)¶

[ ] Citizen mobile
[ ] Officer mobile (offline later)
[ ] Authority / admin web

Explicitly later (do not block Phase 1)¶

[ ] Parking tickets + City Parking sync
[ ] ZINARA / VTS / EcoCash real integrations
[ ] USSD / WhatsApp / ZIMRA / national expansion
[ ] K8s + production CI/CD

12. Rough completion estimate (Phase 1 backend)¶

Area	Approx. done
Platform (discovery, config, gateway, core)	~75%
Auth	~70%
System parameters	~90%
Audit	~50%
Vehicle	~25%
Fines / payments / notifications	~0%
Clients	~0%
Overall Phase 1 backend	~35–40%

Update this file whenever a service lands or a checklist item finishes. Prefer status changes over rewriting narrative.