How bhavikostwal/disaster-alert-05 works
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: alerts.py Alert routes · main.py API entry · models.py Data models · types.ts UI types
Components 29
Backend
Python FastAPI service, domain logic, persistence, auth, and notification side effects.
- API entry · Bootstraps the backend service and wires routes and shared services.
backend/main.py - Auth routes · Login, registration, and session-related HTTP endpoints.
backend/routes/auth.py - Alert routes · Alert creation, retrieval, and workflow endpoints.
backend/routes/alerts.py - Admin routes · Privileged operator and admin actions exposed over HTTP.
backend/routes/admin.py - Auth core · Token or session security and role-aware authentication helpers.
backend/auth.py - Validation · Shared input and business-rule validation before persistence or side effects.
backend/validation.py - API schemas · Request and response shapes at the API boundary.
backend/schemas.py - Data models · Database-facing entities and record structure definitions.
backend/models.py - Database · Central persistence integration for reading and writing system records.
backend/database.py - Notifications · Delivery and notification logic triggered by alert activity.
backend/notifications.py - Background tasks · 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 · Shared application shell and global styling for the Next.js app.
frontend/app/layout.tsx - Login page · Authentication entry screen for users.
frontend/app/login/page.tsx - Operator page · Operational control surface for composing and managing alerts.
frontend/app/operator/page.tsx - Map page · Map-centric view for geospatial interaction and location work.
frontend/app/map/page.tsx - Alert detail · Per-alert detail page under the alert route.
frontend/app/alerts/[id]/page.tsx - Reverse geocode · Frontend API route used to resolve coordinates into readable locations.
frontend/app/api/reverse-geocode/route.ts - Session context · Cross-page session and login state management.
frontend/context/session-context.tsx - Alerts context · Shared alert data and client-side alert state coordination.
frontend/context/alerts-context.tsx - API client · Frontend abstraction for calling the backend API.
frontend/lib/api.ts - UI types · Frontend type definitions for API and state data.
frontend/lib/types.ts - Client data · Frontend data abstractions for alerts, users, config, and operator logs.
frontend/db/alerts.ts - Login UI · Forms and flows for sign-in, registration, and location input.
frontend/components/login/login-form.tsx - Operator UI · Alert composition, active alert management, map picking, and operator stats.
frontend/components/operator/alert-composer.tsx - Alert UI · Alert detail, severity, delivery, and map presentation components.
frontend/components/alerts/alert-details-panel.tsx - Dashboard UI · 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 · High-level system architecture and design assumptions.
docs/architecture.md - API docs · API reference and usage documentation.
docs/api-reference.md - Validation reports · QA, integration, and final project validation artifacts.
reports/QA_REPORT_1.md
Connections 32
- 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.