TAEDS Architecture & Design
Reference Documentation

Client layer

• Field officers use an installable PWA (React 19 + TanStack Start) that works offline.
• Command, analytics and administration use the same app in a desktop browser.
• The PWA renders server side (Nitro node) in production behind the same gateway.

Edge & application

• An nginx gateway terminates TLS, proxies /api and /sanctum and fronts the PWA.
• Laravel (PHP 8.5) exposes the REST API and owns every business rule.
• Thirteen modules share one codebase with enforced boundaries.

Data services

• PostgreSQL 18 + PostGIS 3.6: authoritative store, relational + spatial.
• Redis 7: sessions, cache and the queue broker.
• PostgreSQL FTS: full text search built into the source of truth; MinIO/S3: evidence objects.
• Workers (Redis queue:work + scheduler; Horizon bundled) drain the outbox.

Module ownership

• Each module owns its tables, Actions, API surface and tests.
• Cross-module access happens only through public contracts, never internals.
• Architecture tests fail CI if a module reaches into a neighbour's internals.

Why a modular monolith

• Whole case transactions are easy: no distributed saga for one accident file.
• One build, one deploy, simple operations and rollbacks.
• Module discipline keeps it clean as volume grows.

Controllers are thin

• Controller → Form Request → Authorization → Action → Domain → DB → Outbox → Resource.
• Side effects exit through the durable outbox, never inside the request tail.
• Domain code never imports HTTP, cloud SDKs or browser APIs.

The rule in one sentence

• No module reaches into another module's internal tables or classes.
• Dependencies point toward the platform core: authentication, administration, audit, notifications, synchronisation and integrations.
• Domain modules (accidents, evidence, enforcement, GIS) relate to each other only through public contracts, read endpoints or events, never through internal code.

Events keep modules decoupled

• One module publishes a fact through the outbox (for example an accident was approved); the modules that care subscribe and react.
• There are no synchronous calls from one module into another over the network or the class loader.
• Reporting and analytics read across several domains through scoped read models, so a live dashboard never depends on another module's internals.

Schema by module

• 96 tables today, every one owned by exactly one of the thirteen modules; ownership is enforced by tests, not convention.
• Location hierarchy (region → county → sub-county), traffic bases, officer ranks/transfers and onboarding live under Administration.
• Human case numbers TAEDS-ACC-2026-000123; ULIDs for internal keys.
• Migrate expand/contract; destructive changes require approval.

Spatial (PostGIS)

• Accident point geometry, road network, county/station boundaries.
• Black-spot clustering and heat-mapping run against geometry.
• GIS basemap tiles are proxied server side (credentials never reach devices).

Evidence objects

• Files stored in MinIO (S3); rows in Postgres reference them by SHA-256.
• Metadata, hashes and custody live in the database, never only in the bucket.
• Backups cover both the database and the object store.

Stack

• React 19 · TypeScript strict (incl. noUncheckedIndexedAccess) · TanStack Start/Router/Query · Vite 8 · Tailwind 4 + shadcn/ui.
• react-hook-form + Zod for typed forms; Recharts for dashboards; MapLibre GL for maps (OpenFreeMap tiles, keyless).
• PWA via Workbox (vite-plugin-pwa): installable and offline-capable.
• API client is generated by Orval from the backend OpenAPI contract into shared/api/generated.

State strategy

• TanStack Query: server state cache of API truth.
• Dexie/IndexedDB: durable offline working copy + outbox.
• UI state stays in React; auth has a dedicated boundary.

Rules that hold

• Never hand-edit the generated OpenAPI client (shared/api/generated) or the route tree.
• No raw fetch in components: one central HTTP client (lib/taeds/http-client.ts).
• Every screen models all states: loading · empty · offline · syncing · error · conflict.

Capture first

• Every field autosaves to IndexedDB as a local draft.
• A visible status shows ONLINE / OFFLINE / SYNCING / SYNC ERROR.
• The officer never waits on a signal to do their job.

Replay, don't guess

• Local mutations carry idempotency keys.
• The server writes the change and its outbox event in one transaction.
• Horizon / queue workers fan out to search, notifications and integrations.

Guarantees (tested)

• Durable: a crash never loses a queued draft.
• Idempotent: replaying never duplicates a record.
• Deterministic conflicts: server resolution wins, always.

Backend is the lock

• Every sensitive Action checks permission and data scope.
• Self/station scope closes off accidental or malicious cross record access.
• Audit + status history written in the same transaction as the change.

Roles & scopes

• Officers = self · investigators/commanders = station · county/regional command = county/region · HQ/DIG/analyst/ICT = national.
• Ten canonical roles; the RBAC matrix is one tested source of truth (seeded in Administration and locked by an automated RBAC conformance suite).
• The PWA mirrors the same matrix (traffic_officer … system_administrator) for UX only; the backend stays the real boundary.
• Segregation of duties: you cannot approve a case you recorded.

Hygiene

• Sanctum sessions + CSRF; persisted sessions are verified against /auth/me and are revocable from /auth/sessions.
• Login throttling tracks failed attempts (login_attempts) and rate-limits the password endpoints.
• No secrets in code or env files; TLS in transit; no demo account fallback in production.

Capture & hash

• Client computes SHA-256 of the real bytes; server re-hashes and compares on verify.
• Status lifecycle: pending → uploaded → verified → approved.
• Storage keys derive from hashes: corruption is detectable.

Chain of custody

• Append-only events: captured · reviewed · downloaded · transferred · approved.
• Each event records who, when, from where (IP) and any details.
• Nothing is silently overwritten: change is a new event.

Governance

• Public share links carry random capability tokens and expiry.
• Medical (P3), parade and specimen sub forms follow the same integrity rules.
• Defined by a dedicated design record and enforced with security tests.

Officer track

• Draft → submitted on completion (owner-only); role-gated commands (submit/assign/etc.).
• Completeness meter before submit: no half-finished cases.
• Returned cases come back with the commander's comment.

Investigator track

• Cases act as one state machine: draft → submitted → assigned → under_review → approved → closed, with rejected, returned and escalated paths.
• Diary, statements, sketches, conclusion, CRF; evidence validated and approved into the file.
• Conclusion is submitted, then approved or returned for correction.

Command & beyond

• Approve / return / escalate: each with comment and audit.
• Approved cases feed dashboards, exports and national statistics.
• Status transitions are legal only via backend Actions.

Connected providers

• NTSA: vehicle & driver verification.
• IPRS: identity screening.
• eCitizen / payments and email/SMS: notification & court outputs.

Failure contract

• Timeouts and exponential backoff; circuit breakers stop hammering dead providers.
• Feature flags and cached fallbacks keep the app usable.
• Every integration call is audited.

GIS tiles

• Basemap tiles are proxied by the backend so provider keys never reach a device.
• Public CARTO fallback keeps maps working with no provider configured.

Three repositories, one contract

• TAEDS-Platform: docs, constitution, decisions.
• TAEDS-Backend: Laravel + OpenAPI contract.
• TAEDS-Frontend: React PWA; client generated from the contract.

Quality gates

• Backend CI (backend.yml): migrate & seed against a fresh Postgres service, then pest tests, phpstan and pint.
• Frontend CI (frontend.yml): typecheck · lint · format:check · vitest then production build.
• Playwright E2E specs live in the repo but run locally, not in CI, until the runner is provisioned.
• Every gate must pass before a change can ship.

Delivery

• Pushing to main (or manual workflow_dispatch) publishes ghcr.io/odhiamboatieno/taeds-backend and taeds-frontend as :latest + :sha images.
• Production stack (docker-compose.prod.yml) pulls those images behind an nginx gateway; dev stack (docker-compose.yml) hot-reloads via bind mounts.
• Environment-specific config comes from env/secret management, never the repo.

What runs

• Dev/prod compose: gateway (nginx) · backend (PHP-FPM + nginx :8080) · backend-worker (queue:work) · backend-scheduler (schedule:work) · frontend (Nitro node :3000) · pgsql (PostGIS) · redis · minio + minio-init · mailpit (dev / prod mail profile).
• Planned, not yet deployed: Prometheus (metrics), Grafana (dashboards), Alertmanager (alerts), Loki (log shipping and storage).
• Queue workers drain the outbox; scheduler runs housekeeping (backups, aggregation, sync reconciliation).

Backup ladder

• Daily (and periodic weekly/monthly) PostgreSQL dumps + volume snapshots; evidence objects replicate to an offsite/cold tier (MinIO).
• Proposed recovery targets (under development): recovery point objective 24 hours, recovery time objective 4 hours.
• A backup freshness alert pages operations if the latest dump is older than the objective; restore drills follow the runbook (docs/runbooks) on a fixed schedule.

Observability

• Planned stack: Prometheus scrapes a metrics endpoint and exporters; Grafana renders service and business dashboards.
• Alertmanager turns rule breaches into pages with severity and an escalation path (pending).
• Requests already carry a request_id end to end; structured logs are shipped today and will flow to Loki for correlation once monitoring lands.
• Full details and proposed service targets in § 16 Observability and monitoring.

One application, not microservices

• We gave up per-service scaling for a single codebase that is simpler to secure, test, deploy and run.
• The payoff: one accident is processed in one transaction, so a case file can never be left half written across services. If a module ever needs to split out, the API contract already gives us the seam to do it without a rewrite.

Self hosted everywhere

• We gave up the convenience of managed cloud services for the right to keep records and telemetry inside police infrastructure.
• The payoff: no per-user SaaS fees, no foreign data storage, and no vendor that can change terms or disappear. The same open source tools (PostgreSQL, Redis, MinIO, Prometheus, Grafana) are supported across the market if we ever need a second opinion.

PostgreSQL full text search, not a search engine

• We accepted that extreme scale "smart search" is beyond the database, for now.
• The payoff: one less system to run, secure and keep consistent. Ranked, typo tolerant search lives with the data it searches, so search results can never disagree with the source of truth.

Browser sessions, not long lived tokens

• We gave up the statelessness of bearer tokens for server managed sessions.
• The payoff: a session can be revoked the moment an officer reports a lost device, and there is no token file sitting on a phone that a thief can replay.

A web app, not native phone apps

• We gave up a few phone-only device capabilities for one codebase that installs and updates instantly on any phone.
• The payoff: field devices never wait for an app store, and there is no fleet of out-of-date native apps with different behaviour; if a specific hardware feature is ever needed, a native shell can be added later without changing the core.

Convention over configuration

• We accepted framework conventions instead of bespoke plumbing in every area.
• The payoff: predictable, auditable behaviour that a new engineer can understand quickly, and a system the Service is not locked to one individual to maintain.

Keys & identity rules

• Internal keys are ULIDs (globally unique, sortable, unguessable): required for offline creation.
• Human-facing identifiers: TAEDS-ACC-2026-000123 generated server side from a per year sequence.
• Every row that is "owned" records created_by / updated_by for accountability.

Normalization stance

• Targets 3NF: facts live once; vehicles aren't repeated inside casualty rows.
• Example: accident → vehicles → drivers(1:1 to vehicle); accident → casualties; accident → witnesses.
• Small lookup lists (road surface, weather, lighting, offence) are reference data, referenced by FK, not free text.

Intentional denormalization

• Read-optimised aggregate snapshots (analytics_snapshots, forecast_data) computed on a schedule from the source of truth.
• Counts shown on cards are computed in queries (with eager-loading), not stored and allowed to drift.
• JSONB used only for genuinely flexible payloads (form extras), never for core relations.

Constraints

• NOT NULL on mandatory fields; CHECK/enum-like constraints for statuses, severities, injury classes.
• Foreign keys everywhere relations exist (no orphaned children); deletions are restricted, not cascaded, for case data.
• Unique indexes: case_number, per year sequence, share tokens, citation references.

Integrity by workflow

• State transitions are legal only through backend Actions, not raw SQL or free-form edits.
• Status history + audit write in the same transaction as the change.
• Evidence rows cannot be overwritten silently; changes are new chain events.

Indexing policy

• PKs/FKs indexed; covering indexes on list filters (status, severity, station, date).
• GiST spatial indexes on geometry; GIN tsvector indexes power full text search; GIN trigram indexes add prefix/typo tolerance.
• Queries eager-load relations to avoid N+1; lists paginate server side with stable ordering.

Migrations & evolution

• Expand / contract phases; destructive steps require explicit approval.
• Migrations are versioned and run forward only in pipelines (rollback = deploy old app + forward fix).
• Dates stored in UTC; human formatting happens at the edge.

Accident case file · 11

accidents · accident_casualties · accident_damage_reports · accident_drivers · accident_inquests · accident_locations · accident_road_conditions · accident_status_history · accident_vehicles · accident_weather · accident_witnesses

Accident forms, reports and files · 12

accused_statements · crime_incident_reports · crf_records · initial_reports · investigation_conclusions · investigation_diaries · investigation_reports · official_forms · persons · road_condition_records · situation_reports · sketches

Evidence and integrity · 15

descriptive_forms · drink_drunk_examinations · evidence · evidence_chain_of_custody · exhibit_memos · exhibits · fingerprints · identification_parades · medical_reports · parade_members · parade_results · parade_witnesses · personal_effects · post_mortems · specimens

Enforcement and prosecution · 11

bonds · cash_bail_receipts · charge_sheets · court_cases · driver_verification_requests · enforcement_actions · notices_of_prosecution · notices_to_attend_court · offences · traffic_citations · vehicle_inspections

Administration, identity and RBAC · 22

auth_events · counties · devices · login_attempts · officer_onboarding_requests · officer_transfers · organizations · password_reset_tokens · permissions · personal_access_tokens · police_stations · ranks · reference_data · regions · role_permission · roles · sessions · sub_counties · system_configurations · traffic_bases · user_role · users

GIS and analytics · 5

analytics_snapshots · blackspots · forecast_data · gis_locations · safety_recommendations

Reporting and correspondence · 5

correspondence_memos · export_jobs · report_schedules · reports · scheduled_reports

Workflow, platform plumbing and framework · 15

audit_logs · cache · cache_locks · failed_jobs · integration_circuit_state · integration_requests · job_batches · jobs · notifications · outbox_events · sync_conflicts · sync_cursors · workflow_comments · workflow_instances · workflow_transitions

CI: integration

• Triggers: every pull request, push to main, and manual workflow_dispatch.
• Backend job (backend.yml): boots a fresh PostGIS 16 service → composer install → migrate & seed the full schema → php artisan test (Pest) → phpstan → pint --test.
• Frontend job (frontend.yml): npm ci → typecheck (Strict TypeScript) → ESLint → Prettier format check → Vitest → production build.
• Playwright E2E spec files live in the repo but run locally, not in CI, until a E2E runner is provisioned.
• A red gate blocks the merge. CI never lies to you.

CD: delivery

• Publishing runs only on main or an explicit manual trigger (workflow_dispatch).
• Docker images built from the same commit with BuildKit caches and pushed to GHCR: ghcr.io/odhiamboatieno/taeds-backend and taeds-frontend, tagged latest + short sha.
• Production (docker-compose.prod.yml) pulls the new image, runs forward migrations, restarts app + workers, then health-checks.
• Rollback = point compose at the previous sha tag and redeploy.
• Healthchecks gate restarts (/health/live); target metrics like outbox age are watched once monitoring lands (§ 16).

Contract-first seam

• The OpenAPI spec is the contract between backend and frontend.
• Frontend regenerates its typed client from the contract; never hand-edits generated code.
• Both sides validate the contract in CI so an API change can't silently break the UI.

Collect: Prometheus

• The application exposes a metrics endpoint; Prometheus pulls it on a short interval.
• Exporters add metrics for PostgreSQL, Redis, MinIO, the web server and the host itself.
• Metrics are labelled (route, status, station, device) so dashboards can slice by scope.

Visualize: Grafana

• One dashboard per audience: service health, API latency and errors, queue and outbox depth, sync success by device, storage and backup freshness, evidence store growth.
• Anonymised read access for analysts who need business trends only.

Logs: Promtail + Loki

• Promtail ships container logs with the same request_id used across services.
• Loki stores logs cheaply and pairs with the metrics timeline for root cause analysis.
• Log rotation and retention are set so evidence and audit logs are never truncated silently.

Alert: Alertmanager

• Rules fire at three severities: warning (inform), critical (page), and incident (escalate).
• Routing goes to the right runbook owner, with a fallback channel when no one acknowledges.
• Silencing is time boxed and audited; false alerts are tuned, not deleted.

Service level indicators and objectives

• A service level indicator (SLI) is the measured number; a service level objective (SLO) is the target it must meet.
• Proposed objectives: API availability at least 99.5% per month, 95th percentile latency under 1 second, outbox drained within 5 minutes, sync success at least 99%.
• Objectives are reported honestly on dashboards; missing one starts a review, not a hidden incident.

Recovery point and time

• Recovery point objective (RPO) is how recent data must be after a restore; proposed 24 hours with daily dumps and volume snapshots.
• Recovery time objective (RTO) is how fast service must return; proposed 4 hours for the pilot deployment.
• Restore drills run on a schedule and the measured times are compared against these targets.

Backend layout principles

• Shared application code lives in app; every feature lives in its own folder under Modules.
• A module owns its routes, controllers, requests, actions, models, migrations and tests, so a feature team touches one folder.
• Business rules sit in Domain/Actions; controllers stay thin; a module cannot reach into another module's internals.
• Migrations, seeders and factories sit beside the code that uses them, versioned with the module.

Frontend layout principles

• One folder per domain under features, mirroring the API modules, so a screen change and its tests change together.
• Generated code (API client, route tree) is separated from hand written code and updated by tooling only.
• Shared types, permissions and the offline store live under lib; base UI under components/ui; product UI under components/taeds.
• Routes are file based and guarded by role, mirroring the backend permissions for good usability.

Digitised forms (A to J)

• Forms A–I are digitised (B was not supplied); A accident package · C medical & damage · D statements & parade.
• E accused statement · F diary · G prosecution package.
• H evidence/admin · I summary/findings · misc records.
• Each form maps to structured rows: fill / view / approve by role.

Key endpoints (contract-first)

• POST /auth/login · GET /auth/me · POST /auth/logout · /auth/sessions · /auth/password/*
• GET|POST /accidents · GET|PATCH /accidents/{id} with /assign-investigator · /submit · /approve · /reject · /return-for-correction · /escalate and /investigation-conclusion/{action}
• /cases/{id}/evidence … /upload-session · /verify · /approve · /chain · /share-link
• /enforcement/* incl. cash-bail/bond forfeit & return · /sync/pull · /sync/reconcile · /gis/roads · /dashboard/* · /admin/* incl. system health

Glossary

• P41, P3, P81A, P32, P2020A: police/medical form codes digitised.
• OB occurrence book · CR crime register · CRF case record file.
• Case file A to J: the bundle one accident generates.
• Outbox: durable, idempotent side-effect queue.
• RBAC / SoD: role based access · segregation of duties.
• PWA / Dexie: installable app · offline IndexedDB.
• TanStack Start / Router: React SSR framework and type-safe routing.
• Orval: generates the typed API client from the OpenAPI contract.
• MapLibre GL / OpenFreeMap: open source WebGL map renderer and its free, keyless basemap tiles.
• Prometheus / Grafana: metrics collector and dashboard tool (planned).
• Promtail / Loki: log shipper and log store.
• Alertmanager: routes alerts to their owners.
• Exporter: turns component stats into metrics for Prometheus.
• Service level indicator (SLI) / service level objective (SLO): measured number vs target.
• Recovery point objective (RPO) / recovery time objective (RTO): data loss and restore time targets.