# bhavikostwal/disaster-alert-05 architecture

> Architecture diagram of the GitHub repository bhavikostwal/disaster-alert-05, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhavikostwal/disaster-alert-05
- Repository: https://github.com/bhavikostwal/disaster-alert-05

## Overview

1. **System shape**
   - This repository is a two-tier disaster alert platform:
     - a **Python backend** that exposes the core API, persistence, authentication, alert logic, and notification side effects
     - a **Next.js frontend** that provides the operator/admin UI, login flow, map-based interaction, and alert dashboards
   - The main architectural boundary is the **HTTP API** between `frontend/` and `backend/`.

2. **Backend runtime and API layer**
   - The backend is organized as a **FastAPI-style service** centered on `backend/main.py`.
   - Route modules under `backend/routes/` split the API by domain:
     - `auth.py` for login/register/session-related endpoints
     - `alerts.py` for alert creation, retrieval, and alert workflows
     - `admin.py` for privileged/operator/admin actions
   - This separation suggests the backend is the authoritative source for business rules and access control.

3. **Backend domain model and data contract**
   - `backend/models.py` defines the persistence-facing entities.
   - `backend/schemas.py` defines request/response shapes used by the API boundary.
   - `backend/validation.py` and `backend/utils.py` contain shared domain checks and helper logic, indicating validation is treated as a first-class concern before data is accepted or acted on.

4. **Backend persistence boundary**
   - `backend/database.py` is the central database integration point.
   - The structure implies a conventional service-to-database flow:
     - API route receives request
     - schema validation and auth checks run
     - domain logic executes
     - models/database layer persists or reads records
   - Tests in `backend/tests/` cover auth, alerts, users, and core behavior, reinforcing that the backend is the system of record.

5. **Authentication and authorization**
   - `backend/auth.py` and `backend/routes/auth.py` handle identity and session/token-related concerns.
   - The README mentions a `SECRET_KEY`, which implies signed tokens or session security.
   - The presence of separate `admin.py` routes and a default operator account indicates role-based access is part of the architecture, with operator/admin capabilities gated server-side.

6. **Alert processing and notification pipeline**
   - `backend/notifications.py` and `backend/background_tasks.py` indicate alerts are not only stored but also propagated through asynchronous or deferred work.
   - The architecture likely has a split between:
     - synchronous API handling for creating/managing alerts
     - background processing for delivery/notification effects
   - This supports the README’s emphasis on “crash resistant notifications” and suggests the system is designed to survive transient failures in delivery channels.

7. **Frontend application structure**
   - The frontend is a **Next.js app router** project under `frontend/app/`.
   - Routes are organized by user task:
     - `/login` for authentication
     - `/operator` for operational control
     - `/map` for map-centric views
     - `/alerts/[id]` for alert detail pages
     - root page as the landing/dashboard entry
   - `frontend/app/layout.tsx` and `globals.css` provide shared shell and styling across the app.

8. **Frontend state and API boundary**
   - `frontend/context/session-context.tsx` and `frontend/context/alerts-context.tsx` hold cross-page client state for session and alert data.
   - `frontend/lib/api.ts` and `frontend/lib/types.ts` define the frontend’s interaction layer with the backend API.
   - This shows a clear client-side separation:
     - UI components render state
     - contexts coordinate app-wide state
     - a dedicated API module mediates backend calls

9. **Frontend feature modules**
   - Components are grouped by workflow:
     - `components/login/*` for authentication and registration UX
     - `components/operator/*` for composing and managing alerts, map picking, delivery status, and operational stats
     - `components/alerts/*` and `components/dashboard/*` for alert viewing and analysis
   - This organization indicates the frontend is not a generic UI shell; it is built around distinct operational workflows for responders/operators.

10. **Geospatial and mapping concerns**
    - The frontend includes map-oriented screens and components (`map`, `alert-map`, `map-canvas`, `map-picker`, `location-picker`).
    - `frontend/app/api/reverse-geocode/route.ts` is a frontend-side API route, likely used to translate coordinates into human-readable locations without exposing that logic directly to the browser.
    - Geographic input and validation are therefore part of the product’s core data flow, not a cosmetic feature.

11. **Client-side data storage and operational logs**
    - The `frontend/db/` directory contains `alerts.ts`, `users.ts`, `op-logs.ts`, and `config.tsx`.
    - This suggests a client-side data abstraction layer for alert/user/operator log state, likely used to structure local data access or mock/persist operational records in the UI.
    - Even if the backend remains authoritative, the frontend is clearly treating these entities as first-class UI data domains.

12. **Testing, docs, and operational readiness**
    - The backend has a focused automated test suite in `backend/tests/`, covering the major domain boundaries.
    - The `docs/` directory contains architecture, API reference, environment, troubleshooting, and risk documentation, which means the system has explicit operational guidance and design assumptions.
    - The `reports/` folder shows project validation artifacts, implying the repository was built with integration and QA checkpoints in mind.

13. **End-to-end data flow**
    - Typical flow is:
      - user logs in through the Next.js frontend
      - frontend stores session state in context
      - UI actions such as composing or reviewing alerts call backend endpoints
      - backend validates request, enforces role checks, persists data, and triggers notification/background work
      - frontend rehydrates views from backend responses and presents dashboard/map/status updates
    - The system is therefore centered on a **server-authoritative alert lifecycle** with a rich client UX layered on top.

14. **Key architectural boundaries to draw**
    - **Browser/UI boundary:** Next.js pages and components vs. shared client context/API helpers
    - **Frontend/backend boundary:** HTTP requests from Next.js to the Python API
    - **Backend domain boundary:** routes vs. auth/validation/models/database/notifications
    - **Async side-effect boundary:** request handling vs. background notification work
    - **Data boundary:** persistent system records vs. frontend presentation/state management

Main entry points: [`backend/routes/alerts.py`](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/routes/alerts.py) (Alert routes), [`backend/main.py`](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/main.py) (API entry), [`backend/models.py`](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/models.py) (Data models), [`frontend/lib/types.ts`](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/lib/types.ts) (UI types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["API entry<br/>fastapi app<br/>[main.py]"]
  node_backend_routes_auth["Auth routes<br/>api routes<br/>[auth.py]"]
  node_backend_routes_alerts["Alert routes<br/>api routes<br/>[alerts.py]"]
  node_backend_routes_admin["Admin routes<br/>api routes<br/>[admin.py]"]
  node_backend_auth["Auth core<br/>identity/session<br/>[auth.py]"]
  node_backend_validation["Validation<br/>domain checks<br/>[validation.py]"]
  node_backend_schemas["API schemas<br/>contracts<br/>[schemas.py]"]
  node_backend_models[("Data models<br/>persistence models<br/>[models.py]")]
  node_backend_database[("Database<br/>storage layer<br/>[database.py]")]
  node_backend_notifications["Notifications<br/>side effects<br/>[notifications.py]"]
  node_backend_background["Background tasks<br/>async work"]
end

subgraph group_frontend["Frontend"]
  node_frontend_layout["App shell<br/>next layout<br/>[layout.tsx]"]
  node_frontend_login_page["Login page<br/>ui route<br/>[page.tsx]"]
  node_frontend_operator_page["Operator page<br/>ui route<br/>[page.tsx]"]
  node_frontend_map_page["Map page<br/>ui route<br/>[page.tsx]"]
  node_frontend_alert_page["Alert detail<br/>ui route<br/>[page.tsx]"]
  node_frontend_api_route["Reverse geocode<br/>edge api<br/>[route.ts]"]
  node_frontend_session_ctx["Session context<br/>client state"]
  node_frontend_alerts_ctx["Alerts context<br/>client state<br/>[alerts-context.tsx]"]
  node_frontend_api_lib["API client<br/>http client<br/>[api.ts]"]
  node_frontend_types["UI types<br/>client contracts<br/>[types.ts]"]
  node_frontend_db[("Client data<br/>ui data layer<br/>[alerts.ts]")]
  node_frontend_components_login["Login UI<br/>components<br/>[login-form.tsx]"]
  node_frontend_components_operator["Operator UI<br/>components<br/>[alert-composer.tsx]"]
  node_frontend_components_alerts["Alert UI<br/>components"]
  node_frontend_components_dashboard["Dashboard UI<br/>components<br/>[alert-card.tsx]"]
end

subgraph group_docs["Docs & reports"]
  node_docs_architecture["Architecture docs<br/>documentation<br/>[architecture.md]"]
  node_docs_api["API docs<br/>documentation<br/>[api-reference.md]"]
  node_reports_validation["Validation reports<br/>[QA_REPORT_1.md]"]
end

node_backend_main -->|"mounts"| node_backend_routes_auth
node_backend_main -->|"mounts"| node_backend_routes_alerts
node_backend_main -->|"mounts"| node_backend_routes_admin
node_backend_routes_auth -->|"uses"| node_backend_auth
node_backend_routes_auth -->|"checks"| node_backend_validation
node_backend_routes_alerts -->|"checks"| node_backend_validation
node_backend_routes_alerts -->|"serializes"| node_backend_schemas
node_backend_routes_alerts -->|"writes"| node_backend_models
node_backend_routes_admin -->|"guards"| node_backend_auth
node_backend_routes_admin -->|"reads/writes"| node_backend_database
node_backend_validation -->|"constrains"| node_backend_models
node_backend_schemas -->|"maps to"| node_backend_models
node_backend_models -->|"persists via"| node_backend_database
node_backend_routes_alerts -->|"triggers"| node_backend_notifications
node_backend_notifications -->|"defers to"| node_backend_background
node_frontend_login_page -->|"renders"| node_frontend_components_login
node_frontend_operator_page -->|"renders"| node_frontend_components_operator
node_frontend_alert_page -->|"renders"| node_frontend_components_alerts
node_frontend_map_page -->|"renders"| node_frontend_components_dashboard
node_frontend_layout -->|"wraps"| node_frontend_session_ctx
node_frontend_layout -->|"wraps"| node_frontend_alerts_ctx
node_frontend_session_ctx -->|"calls"| node_frontend_api_lib
node_frontend_alerts_ctx -->|"calls"| node_frontend_api_lib
node_frontend_api_lib -->|"requests"| node_backend_main
node_frontend_api_route -->|"supports"| node_frontend_map_page
node_frontend_components_login -->|"uses"| node_frontend_types
node_frontend_components_operator -->|"uses"| node_frontend_types
node_frontend_components_alerts -->|"uses"| node_frontend_types
node_frontend_db -->|"structures"| node_frontend_types
node_docs_architecture -.->|"describes"| node_backend_main
node_docs_api -.->|"describes"| node_backend_routes_alerts
node_reports_validation -.->|"validates"| node_backend_main

click node_backend_main "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/main.py"
click node_backend_routes_auth "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/routes/auth.py"
click node_backend_routes_alerts "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/routes/alerts.py"
click node_backend_routes_admin "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/routes/admin.py"
click node_backend_auth "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/auth.py"
click node_backend_validation "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/validation.py"
click node_backend_schemas "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/schemas.py"
click node_backend_models "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/models.py"
click node_backend_database "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/database.py"
click node_backend_notifications "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/notifications.py"
click node_backend_background "https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/background_tasks.py"
click node_frontend_layout "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/layout.tsx"
click node_frontend_login_page "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/login/page.tsx"
click node_frontend_operator_page "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/operator/page.tsx"
click node_frontend_map_page "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/map/page.tsx"
click node_frontend_alert_page "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/alerts/[id]/page.tsx"
click node_frontend_api_route "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/api/reverse-geocode/route.ts"
click node_frontend_session_ctx "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/context/session-context.tsx"
click node_frontend_alerts_ctx "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/context/alerts-context.tsx"
click node_frontend_api_lib "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/lib/api.ts"
click node_frontend_types "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/lib/types.ts"
click node_frontend_db "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/db/alerts.ts"
click node_frontend_components_login "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/login/login-form.tsx"
click node_frontend_components_operator "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/operator/alert-composer.tsx"
click node_frontend_components_alerts "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/alerts/alert-details-panel.tsx"
click node_frontend_components_dashboard "https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/dashboard/alert-card.tsx"
click node_docs_architecture "https://github.com/bhavikostwal/disaster-alert-05/blob/main/docs/architecture.md"
click node_docs_api "https://github.com/bhavikostwal/disaster-alert-05/blob/main/docs/api-reference.md"
click node_reports_validation "https://github.com/bhavikostwal/disaster-alert-05/blob/main/reports/QA_REPORT_1.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_main,node_backend_routes_auth,node_backend_routes_alerts,node_backend_routes_admin,node_backend_auth,node_backend_validation,node_backend_schemas,node_backend_models,node_backend_database,node_backend_notifications,node_backend_background toneBlue
class node_frontend_layout,node_frontend_login_page,node_frontend_operator_page,node_frontend_map_page,node_frontend_alert_page,node_frontend_api_route,node_frontend_session_ctx,node_frontend_alerts_ctx,node_frontend_api_lib,node_frontend_types,node_frontend_db,node_frontend_components_login,node_frontend_components_operator,node_frontend_components_alerts,node_frontend_components_dashboard toneAmber
class node_docs_architecture,node_docs_api,node_reports_validation toneMint
```

## Components

### Backend

Python FastAPI service, domain logic, persistence, auth, and notification side effects.

- [API entry](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/main.py): fastapi app · Bootstraps the backend service and wires routes and shared services. · `backend/main.py`
- [Auth routes](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/routes/auth.py): api routes · Login, registration, and session-related HTTP endpoints. · `backend/routes/auth.py`
- [Alert routes](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/routes/alerts.py): api routes · Alert creation, retrieval, and workflow endpoints. · `backend/routes/alerts.py`
- [Admin routes](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/routes/admin.py): api routes · Privileged operator and admin actions exposed over HTTP. · `backend/routes/admin.py`
- [Auth core](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/auth.py): identity/session · Token or session security and role-aware authentication helpers. · `backend/auth.py`
- [Validation](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/validation.py): domain checks · Shared input and business-rule validation before persistence or side effects. · `backend/validation.py`
- [API schemas](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/schemas.py): contracts · Request and response shapes at the API boundary. · `backend/schemas.py`
- [Data models](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/models.py): persistence models · Database-facing entities and record structure definitions. · `backend/models.py`
- [Database](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/database.py): storage layer · Central persistence integration for reading and writing system records. · `backend/database.py`
- [Notifications](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/notifications.py): side effects · Delivery and notification logic triggered by alert activity. · `backend/notifications.py`
- [Background tasks](https://github.com/bhavikostwal/disaster-alert-05/blob/main/backend/background_tasks.py): async work · Deferred or asynchronous processing for notifications and related work. · `backend/background_tasks.py`

### Frontend

Next.js app router UI, client state, and browser-facing workflows.

- [App shell](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/layout.tsx): next layout · Shared application shell and global styling for the Next.js app. · `frontend/app/layout.tsx`
- [Login page](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/login/page.tsx): ui route · Authentication entry screen for users. · `frontend/app/login/page.tsx`
- [Operator page](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/operator/page.tsx): ui route · Operational control surface for composing and managing alerts. · `frontend/app/operator/page.tsx`
- [Map page](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/map/page.tsx): ui route · Map-centric view for geospatial interaction and location work. · `frontend/app/map/page.tsx`
- [Alert detail](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/alerts/[id]/page.tsx): ui route · Per-alert detail page under the alert route. · `frontend/app/alerts/[id]/page.tsx`
- [Reverse geocode](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/app/api/reverse-geocode/route.ts): edge api · Frontend API route used to resolve coordinates into readable locations. · `frontend/app/api/reverse-geocode/route.ts`
- [Session context](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/context/session-context.tsx): client state · Cross-page session and login state management. · `frontend/context/session-context.tsx`
- [Alerts context](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/context/alerts-context.tsx): client state · Shared alert data and client-side alert state coordination. · `frontend/context/alerts-context.tsx`
- [API client](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/lib/api.ts): http client · Frontend abstraction for calling the backend API. · `frontend/lib/api.ts`
- [UI types](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/lib/types.ts): client contracts · Frontend type definitions for API and state data. · `frontend/lib/types.ts`
- [Client data](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/db/alerts.ts): ui data layer · Frontend data abstractions for alerts, users, config, and operator logs. · `frontend/db/alerts.ts`
- [Login UI](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/login/login-form.tsx): components · Forms and flows for sign-in, registration, and location input. · `frontend/components/login/login-form.tsx`
- [Operator UI](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/operator/alert-composer.tsx): components · Alert composition, active alert management, map picking, and operator stats. · `frontend/components/operator/alert-composer.tsx`
- [Alert UI](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/alerts/alert-details-panel.tsx): components · Alert detail, severity, delivery, and map presentation components. · `frontend/components/alerts/alert-details-panel.tsx`
- [Dashboard UI](https://github.com/bhavikostwal/disaster-alert-05/blob/main/frontend/components/dashboard/alert-card.tsx): components · Dashboard cards, map canvas, and summary widgets for alert overview. · `frontend/components/dashboard/alert-card.tsx`

### Docs & reports

Project documentation and validation artifacts.

- [Architecture docs](https://github.com/bhavikostwal/disaster-alert-05/blob/main/docs/architecture.md): documentation · High-level system architecture and design assumptions. · `docs/architecture.md`
- [API docs](https://github.com/bhavikostwal/disaster-alert-05/blob/main/docs/api-reference.md): documentation · API reference and usage documentation. · `docs/api-reference.md`
- [Validation reports](https://github.com/bhavikostwal/disaster-alert-05/blob/main/reports/QA_REPORT_1.md): reports · QA, integration, and final project validation artifacts. · `reports/QA_REPORT_1.md`

## Connections

- API entry → Auth routes: mounts · Registers authentication endpoints in the service.
- API entry → Alert routes: mounts · Registers alert endpoints in the service.
- API entry → Admin routes: mounts · Registers privileged admin endpoints in the service.
- Auth routes → Auth core: uses · Delegates identity and session handling to auth core.
- Auth routes → Validation: checks · Validates login and registration inputs.
- Alert routes → Validation: checks · Validates alert payloads and workflow actions.
- Alert routes → API schemas: serializes · Uses API contracts for request and response data.
- Alert routes → Data models: writes · Persists alert domain records through models.
- Admin routes → Auth core: guards · Applies role-aware access control.
- Admin routes → Database: reads/writes · Performs privileged data operations.
- Validation → Data models: constrains · Enforces domain rules before records are stored.
- API schemas → Data models: maps to · Shapes the API boundary around persistence entities.
- Data models → Database: persists via · Routes data access through the central database layer.
- Alert routes → Notifications: triggers · Starts alert delivery side effects after core handling.
- Notifications → Background tasks: defers to · Hands off delivery work to asynchronous processing.
- Login page → Login UI: renders · Login page is composed from login feature components.
- Operator page → Operator UI: renders · Operator page is composed from operator feature components.
- Alert detail → Alert UI: renders · Alert detail page is composed from alert feature components.
- Map page → Dashboard UI: renders · Map page reuses dashboard/map presentation components.
- App shell → Session context: wraps · Provides app-wide session state to pages and components.
- App shell → Alerts context: wraps · Provides shared alert state to the app.
- Session context → API client: calls · Uses the API client to authenticate and refresh session state.
- Alerts context → API client: calls · Uses the API client to fetch and update alert data.
- API client → API entry: requests · Frontend communicates with the Python backend over HTTP.
- Reverse geocode → Map page: supports · Provides a server-side helper for location lookup.
- Login UI → UI types: uses · Relies on shared frontend data shapes.
- Operator UI → UI types: uses · Relies on shared frontend data shapes.
- Alert UI → UI types: uses · Relies on shared frontend data shapes.
- Client data → UI types: structures · Organizes client-side records using shared types.
- Architecture docs → API entry: describes · Documents the backend and system architecture.
- API docs → Alert routes: describes · Documents API behavior and endpoints.
- Validation reports → API entry: validates · Captures validation and QA results for the system.