The source of truth for technical detail is the code itself. This section captures the high-level architecture; the low-level database schema, API models, and endpoint contracts are generated from — and kept in sync by — the code:
<aside> 📚
Technical reference (authoritative, always current):
/docs and ReDoc at /redoc, generated from the FastAPI routes. Every route has a summary, a description, and documents the error responses a client can realistically trigger.*_entity.py files (one per table) and the Pydantic *_model.py DTOs under backend/src/modules/.AGENTS.md (root, backend, frontend) and the backend/ and frontend/ READMEs.
</aside>The codebase follows a strict, one-directional layering — a layer never skips the one below it (for example, a React component never calls a service directly; it goes through a query hook).
flowchart TB
subgraph Backend
direction TB
E["persistence — *_entity.py"] --> S["service — *_service.py"] --> R["router — *_router.py"]
end
subgraph Frontend
direction TB
FS["FE service — *.service.ts"] --> Q["query layer — *.queries.ts"] --> P["presentational — components / pages"]
end
R -->|HTTP / JSON| FS
*_entity.py) — SQLAlchemy ORM models; one per database table. No business logic.*_service.py) — business logic and validation; owns the DB session; raises typed exceptions.*_router.py) — thin HTTP layer: authentication, request/response shapes, status codes, OpenAPI metadata.*.service.ts) — typed Axios client; maps backend responses to frontend types.*.queries.ts) — React Query hooks: caching, invalidation, optimistic updates.A suffix tells you the layer and shape at a glance:
| Suffix / file | Layer | Meaning |
|---|---|---|
FooEntity / foo_entity.py |
persistence | SQLAlchemy model — one DB table |
FooDto / foo_model.py |
API contract | Pydantic request/response schema |
FooService / foo_service.py |
service | Business logic for a domain |
foo_router.py |
router | FastAPI endpoints for a domain |
foo.service.ts |
FE service | Typed Axios client for a domain |
foo.queries.ts |
query layer | React Query hooks for a domain |
foo.types.ts |
FE types | Frontend DTOs + convertFoo mappers |
Each backend domain under backend/src/modules/<name>/ follows the same four-file pattern (_entity / _model / _service / _router): account, auth, party, student, police, incident, location, notification. Each frontend domain mirrors it with a *.service.ts / *.queries.ts / *.types.ts trio under frontend/src/lib/api/<domain>/.