# abdullahalsahaf/bonnabondhu architecture

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

- Interactive diagram: https://gitdiagram.com/abdullahalsahaf/bonnabondhu
- Repository: https://github.com/abdullahalsahaf/bonnabondhu

## Overview

1. **System shape**
   - This repository is a two-tier full-stack app: a React/Vite frontend in `client/` and an Express/Node backend in `server/`.
   - The backend exposes REST endpoints, while the frontend is a single-page application that consumes those endpoints through Axios.

2. **Primary runtime boundaries**
   - `server/server.js` is the backend entry point and mounts domain routes plus middleware.
   - `client/src/main.jsx` boots the React app, and `client/src/App.jsx` coordinates page-level routing/layout.
   - The app is deployed as a Render web service, with `render.yaml` defining the deployment path.

3. **Frontend shell and navigation**
   - The UI is organized around a shared application frame in `client/src/components/`:
     - `Layout.jsx` for overall page structure
     - `Navbar.jsx` and `Sidebar.jsx` for navigation
     - `Modal.jsx`, `Toast.jsx`, and `StatCard.jsx` for common interaction and display patterns
   - These components wrap the functional pages so the app behaves like a dashboard rather than a collection of isolated screens.

4. **Frontend feature pages**
   - `client/src/pages/` contains the main functional areas:
     - `Dashboard.jsx` for summary status
     - `Analytics.jsx` for chart-based reporting
     - `Areas.jsx` for affected-area CRUD/search
     - `Priority.jsx` for urgency-driven relief handling
     - `Trucks.jsx` for queue-based truck dispatch
     - `RouteOptimizer.jsx` for map-based shortest-path planning
     - `Login.jsx` for authentication
   - These pages represent the main user workflows and map directly to backend domains.

5. **Client-side state and API access**
   - `client/src/context/AuthContext.jsx` manages login state and role/session persistence on the frontend.
   - `client/src/services/api.js` is the shared HTTP boundary for all backend calls, centralizing API access from the pages.
   - This creates a clean separation between presentation, user session state, and server communication.

6. **Authentication boundary**
   - Authentication is handled on the backend by `server/routes/auth.js` and protected by `server/middleware/auth.js`.
   - The README indicates JWT-based auth with role separation for admin and volunteer users.
   - This means the architecture has a clear trust boundary: the frontend can initiate login, but authorization is enforced server-side.

7. **Domain API modules**
   - The backend is split into route modules by domain:
     - `routes/areas.js`
     - `routes/trucks.js`
     - `routes/dispatch.js`
     - `routes/routeOptimizer.js`
     - `routes/analytics.js`
   - This keeps each feature area isolated and makes the API surface align with the business concepts in the UI.

8. **Core in-memory data structures**
   - The most important architectural characteristic is that the backend stores and processes operational data in memory using custom services in `server/services/`:
     - `GraphService.js`
     - `BSTService.js`
     - `MaxHeapService.js`
     - `TruckQueueService.js`
   - This mirrors the original C++ project’s data-structure-focused design rather than using a database.

9. **Operational data flows**
   - Flood/area records flow through the BST service, which supports sorted traversal, search, add, and delete operations.
   - Relief dispatch flow uses the max-heap service to prioritize requests by urgency-related criteria.
   - Truck operations use the queue service to preserve FIFO ordering.
   - Route planning uses the graph service for weighted shortest-path calculation.

10. **Route optimization subsystem**
    - `routes/routeOptimizer.js` exposes shortest-path lookup between locations.
    - `GraphService.js` backs this with a weighted graph and Dijkstra-style pathfinding.
    - The frontend `RouteOptimizer.jsx` pairs this with the map UI, so the user sees geographic routing results rather than just raw distances.

11. **Analytics and dashboard aggregation**
    - `routes/analytics.js` provides backend summaries for charts and dashboard metrics.
    - The dashboard and analytics pages consume these aggregates to render operational status, urgency breakdowns, and regional statistics.
    - This layer is read-oriented and sits above the underlying data-structure services.

12. **Seeded, ephemeral backend state**
    - `server/data/seedData.js` provides initial application data.
    - Because the project is intentionally in-memory, the backend state is lightweight and resets with process restart unless re-seeded.
    - That makes the application architecture simple to run, but also means the server process is the primary state container.

13. **External libraries that materially affect architecture**
    - The frontend uses React + Vite for the SPA shell, Tailwind CSS for styling, Leaflet for map interactions, and Chart.js for analytics visualization.
    - The backend is built on Node.js + Express with JWT for auth.
    - Axios is the client-to-server transport layer.

14. **Diagramming takeaway**
    - The cleanest architecture diagram is: browser SPA on the left, Express API in the middle, and four in-memory domain services underneath the API.
    - The main cross-cutting flow is auth/token issuance, then role-aware requests from the frontend into domain-specific routes, which delegate to the appropriate data-structure service and return operational views back to the UI.

Main entry points: [`client/src/App.jsx`](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/App.jsx) (App Shell), [`server/server.js`](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/server.js) (Server), [`client/src/components/Layout.jsx`](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/components/Layout.jsx) (Layout), [`server/routes/analytics.js`](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/analytics.js) (Analytics Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client SPA"]
  node_client_main(("Main<br/>entry<br/>[main.jsx]"))
  node_client_app["App Shell<br/>spa shell<br/>[App.jsx]"]
  node_client_layout["Layout<br/>frame<br/>[Layout.jsx]"]
  node_client_nav["Navbar<br/>navigation<br/>[Navbar.jsx]"]
  node_client_side["Sidebar<br/>navigation<br/>[Sidebar.jsx]"]
  node_client_state["Auth State<br/>context<br/>[AuthContext.jsx]"]
  node_client_api["API Client<br/>http client<br/>[api.js]"]
  node_page_dash["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_page_analytics["Analytics<br/>page<br/>[Analytics.jsx]"]
  node_page_areas["Areas<br/>page<br/>[Areas.jsx]"]
  node_page_priority["Priority<br/>page<br/>[Priority.jsx]"]
  node_page_trucks["Trucks<br/>page<br/>[Trucks.jsx]"]
  node_page_route["Route Optimizer<br/>page<br/>[RouteOptimizer.jsx]"]
  node_page_login["Login<br/>page<br/>[Login.jsx]"]
end

subgraph group_server["API Server"]
  node_server_entry(("Server<br/>entry<br/>[server.js]"))
  node_server_auth_route["Auth Routes<br/>route module<br/>[auth.js]"]
  node_server_auth_mw["Auth Middleware<br/>[auth.js]"]
  node_server_areas_route["Areas Routes<br/>route module<br/>[areas.js]"]
  node_server_trucks_route["Trucks Routes<br/>route module<br/>[trucks.js]"]
  node_server_dispatch_route["Dispatch Routes<br/>route module<br/>[dispatch.js]"]
  node_server_route_route["Route API<br/>route module<br/>[routeOptimizer.js]"]
  node_server_analytics_route["Analytics Routes<br/>route module<br/>[analytics.js]"]
  node_svc_bst[("BST Service<br/>in-memory store<br/>[BSTService.js]")]
  node_svc_heap["Max Heap<br/>priority queue<br/>[MaxHeapService.js]"]
  node_svc_queue["Truck Queue<br/>fifo queue"]
  node_svc_graph{{"Graph Service<br/>weighted graph<br/>[GraphService.js]"}}
  node_seed_data["Seed Data<br/>bootstrap data<br/>[seedData.js]"]
end

subgraph group_deploy["Deployment"]
  node_render_cfg["Render Config<br/>deployment<br/>[render.yaml]"]
end

node_client_main -->|"boots"| node_client_app
node_client_app -->|"wraps"| node_client_layout
node_client_layout -->|"includes"| node_client_nav
node_client_layout -->|"includes"| node_client_side
node_client_app -->|"uses"| node_client_state
node_client_app -->|"calls"| node_client_api
node_client_app -->|"routes to"| node_page_login
node_client_app -->|"routes to"| node_page_dash
node_client_app -->|"routes to"| node_page_analytics
node_client_app -->|"routes to"| node_page_areas
node_client_app -->|"routes to"| node_page_priority
node_client_app -->|"routes to"| node_page_trucks
node_client_app -->|"routes to"| node_page_route
node_client_api -->|"http"| node_server_entry
node_page_login -->|"auth"| node_server_auth_route
node_server_entry -->|"mounts"| node_server_auth_route
node_server_entry -->|"mounts"| node_server_areas_route
node_server_entry -->|"mounts"| node_server_trucks_route
node_server_entry -->|"mounts"| node_server_dispatch_route
node_server_entry -->|"mounts"| node_server_route_route
node_server_entry -->|"mounts"| node_server_analytics_route
node_server_auth_route -->|"guards"| node_server_auth_mw
node_server_areas_route -->|"delegates"| node_svc_bst
node_server_dispatch_route -->|"delegates"| node_svc_heap
node_server_trucks_route -->|"delegates"| node_svc_queue
node_server_route_route -->|"delegates"| node_svc_graph
node_server_analytics_route -->|"reads"| node_svc_bst
node_server_analytics_route -->|"reads"| node_svc_heap
node_server_entry -->|"loads"| node_seed_data
node_render_cfg -->|"deploys"| node_server_entry

click node_client_main "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/main.jsx"
click node_client_app "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/App.jsx"
click node_client_layout "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/components/Layout.jsx"
click node_client_nav "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/components/Navbar.jsx"
click node_client_side "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/components/Sidebar.jsx"
click node_client_state "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/context/AuthContext.jsx"
click node_client_api "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/services/api.js"
click node_page_dash "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Dashboard.jsx"
click node_page_analytics "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Analytics.jsx"
click node_page_areas "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Areas.jsx"
click node_page_priority "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Priority.jsx"
click node_page_trucks "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Trucks.jsx"
click node_page_route "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/RouteOptimizer.jsx"
click node_page_login "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Login.jsx"
click node_server_entry "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/server.js"
click node_server_auth_route "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/auth.js"
click node_server_auth_mw "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/middleware/auth.js"
click node_server_areas_route "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/areas.js"
click node_server_trucks_route "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/trucks.js"
click node_server_dispatch_route "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/dispatch.js"
click node_server_route_route "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/routeOptimizer.js"
click node_server_analytics_route "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/analytics.js"
click node_svc_bst "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/BSTService.js"
click node_svc_heap "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/MaxHeapService.js"
click node_svc_queue "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/TruckQueueService.js"
click node_svc_graph "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/GraphService.js"
click node_seed_data "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/data/seedData.js"
click node_render_cfg "https://github.com/abdullahalsahaf/bonnabondhu/blob/main/render.yaml"

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_client_main,node_client_app,node_client_layout,node_client_nav,node_client_side,node_client_state,node_client_api,node_page_dash,node_page_analytics,node_page_areas,node_page_priority,node_page_trucks,node_page_route,node_page_login toneBlue
class node_server_entry,node_server_auth_route,node_server_auth_mw,node_server_areas_route,node_server_trucks_route,node_server_dispatch_route,node_server_route_route,node_server_analytics_route,node_svc_bst,node_svc_heap,node_svc_queue,node_svc_graph,node_seed_data toneAmber
class node_render_cfg toneMint
```

## Components

### Client SPA

React/Vite frontend and user-facing workflows

- [Main](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/main.jsx): entry · Bootstraps the React application · `client/src/main.jsx`
- [App Shell](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/App.jsx): spa shell · Top-level app composition and routing · `client/src/App.jsx`
- [Layout](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/components/Layout.jsx): frame · Shared page structure and navigation frame · `client/src/components/Layout.jsx`
- [Navbar](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/components/Navbar.jsx): navigation · Top navigation controls · `client/src/components/Navbar.jsx`
- [Sidebar](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/components/Sidebar.jsx): navigation · Primary dashboard navigation · `client/src/components/Sidebar.jsx`
- [Auth State](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/context/AuthContext.jsx): context · Login state and role/session persistence · `client/src/context/AuthContext.jsx`
- [API Client](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/services/api.js): http client · Shared Axios boundary for backend calls · `client/src/services/api.js`
- [Dashboard](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Dashboard.jsx): page · Operational summary and status overview · `client/src/pages/Dashboard.jsx`
- [Analytics](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Analytics.jsx): page · Charts and reporting view · `client/src/pages/Analytics.jsx`
- [Areas](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Areas.jsx): page · Affected-area CRUD and search · `client/src/pages/Areas.jsx`
- [Priority](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Priority.jsx): page · Urgency-driven relief handling · `client/src/pages/Priority.jsx`
- [Trucks](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Trucks.jsx): page · Queue-based truck dispatch view · `client/src/pages/Trucks.jsx`
- [Route Optimizer](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/RouteOptimizer.jsx): page · Map-based shortest-path planning · `client/src/pages/RouteOptimizer.jsx`
- [Login](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/client/src/pages/Login.jsx): page · Authentication entry screen · `client/src/pages/Login.jsx`

### API Server

Express backend, auth, routes, and in-memory services

- [Server](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/server.js): entry · Express application bootstrap and route mounting · `server/server.js`
- [Auth Routes](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/auth.js): route module · Login and token issuance endpoints · `server/routes/auth.js`
- [Auth Middleware](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/middleware/auth.js): middleware · Protected-route and role enforcement · `server/middleware/auth.js`
- [Areas Routes](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/areas.js): route module · Area management API · `server/routes/areas.js`
- [Trucks Routes](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/trucks.js): route module · Truck workflow API · `server/routes/trucks.js`
- [Dispatch Routes](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/dispatch.js): route module · Priority dispatch API · `server/routes/dispatch.js`
- [Route API](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/routeOptimizer.js): route module · Shortest-path lookup API · `server/routes/routeOptimizer.js`
- [Analytics Routes](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/routes/analytics.js): route module · Summary and dashboard metrics API · `server/routes/analytics.js`
- [BST Service](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/BSTService.js): in-memory store · Sorted area records and search operations · `server/services/BSTService.js`
- [Max Heap](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/MaxHeapService.js): priority queue · Urgency-prioritized relief requests · `server/services/MaxHeapService.js`
- [Truck Queue](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/TruckQueueService.js): fifo queue · FIFO truck dispatch ordering · `server/services/TruckQueueService.js`
- [Graph Service](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/services/GraphService.js): weighted graph · Weighted shortest-path planning · `server/services/GraphService.js`
- [Seed Data](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/server/data/seedData.js): bootstrap data · Initial in-memory application records · `server/data/seedData.js`

### Deployment

Render deployment configuration

- [Render Config](https://github.com/abdullahalsahaf/bonnabondhu/blob/main/render.yaml): deployment · Web service deployment definition · `render.yaml`

## Connections

- Main → App Shell: boots · Initializes the SPA
- App Shell → Layout: wraps · Composes the shared dashboard frame
- Layout → Navbar: includes · Renders top navigation
- Layout → Sidebar: includes · Renders sidebar navigation
- App Shell → Auth State: uses · Provides session state to pages
- App Shell → API Client: calls · Uses shared HTTP client for server access
- App Shell → Login: routes to · Authentication entry view
- App Shell → Dashboard: routes to · Dashboard workflow
- App Shell → Analytics: routes to · Analytics workflow
- App Shell → Areas: routes to · Area management workflow
- App Shell → Priority: routes to · Priority relief workflow
- App Shell → Trucks: routes to · Truck dispatch workflow
- App Shell → Route Optimizer: routes to · Route planning workflow
- API Client → Server: http · Frontend API requests reach the backend
- Login → Auth Routes: auth · Submits credentials and receives token
- Server → Auth Routes: mounts · Registers authentication endpoints
- Server → Areas Routes: mounts · Registers area endpoints
- Server → Trucks Routes: mounts · Registers truck endpoints
- Server → Dispatch Routes: mounts · Registers dispatch endpoints
- Server → Route API: mounts · Registers route-optimization endpoints
- Server → Analytics Routes: mounts · Registers analytics endpoints
- Auth Routes → Auth Middleware: guards · Authorization checks protect server operations
- Areas Routes → BST Service: delegates · Area CRUD/search uses the BST service
- Dispatch Routes → Max Heap: delegates · Priority relief requests use the heap service
- Trucks Routes → Truck Queue: delegates · Truck dispatch uses FIFO queue ordering
- Route API → Graph Service: delegates · Route lookup uses weighted graph pathfinding
- Analytics Routes → BST Service: reads · Analytics summarize area records
- Analytics Routes → Max Heap: reads · Analytics summarize priority demand
- Server → Seed Data: loads · Bootstraps in-memory state from seed records
- Render Config → Server: deploys · Render starts the backend service