# mohitt-0805/surplus-to-shelter architecture

> Architecture diagram of the GitHub repository mohitt-0805/surplus-to-shelter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mohitt-0805/surplus-to-shelter
- Repository: https://github.com/mohitt-0805/surplus-to-shelter

## Overview

FoodRescue connects surplus-food donors, shelters, and couriers through role-based portals, geospatial offer matching, and live dispatch. The main flow is donor posting → shelter offer and decision → courier assignment → delivery and impact reporting. The graph includes auth, persistence, and public impact alongside the three user portals. Some portal and route implementations are unsampled; those branches are shown at their documented or exact tree paths, and only evidenced relationships are linked.

Main entry points: [`backend/server.js`](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/server.js) (HTTP and socket server), [`backend/services/matching.js`](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/services/matching.js) (Spatial matching), [`frontend/src/App.jsx`](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/App.jsx) (Role routing), [`backend/db.js`](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/db.js) (PostgreSQL and PostGIS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web portals"]
  node_donor["Donor portal<br/>[DonorDashboard.jsx]"]
  node_recipient["Shelter portal"]
  node_driver["Courier portal"]
  node_public["Impact portal"]
  node_login["Login<br/>[Login.jsx]"]
  node_router["Role routing<br/>[App.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_socket_client["Live client<br/>[socket.js]"]
end

subgraph group_api["API and identity"]
  node_server["HTTP and socket server<br/>[server.js]"]
  node_auth_routes["Authentication routes<br/>[auth.js]"]
  node_auth_middleware["Token and role checks<br/>[auth.js]"]
  node_donation_routes["Donation routes<br/>[donations.js]"]
  node_recipient_routes["Recipient routes<br/>[recipients.js]"]
  node_driver_routes["Driver routes<br/>[drivers.js]"]
  node_impact_routes["Impact routes<br/>[impact.js]"]
end

subgraph group_allocation["Matching and dispatch"]
  node_matching["Spatial matching<br/>[matching.js]"]
  node_dispatch["Courier dispatch<br/>[dispatch.js]"]
  node_notifications["Live notifications<br/>[notifications.js]"]
end

subgraph group_data["Persistence and impact"]
  node_db[("PostgreSQL and PostGIS<br/>[db.js]")]
end

node_actor(("Portal users"))

node_actor -->|"uses portals"| node_router
node_router -->|"routes to"| node_login
node_router -->|"routes to"| node_donor
node_router -->|"routes to"| node_recipient
node_router -->|"routes to"| node_driver
node_router -->|"routes to"| node_public
node_login -->|"requests"| node_api_client
node_donor -->|"requests"| node_api_client
node_recipient -->|"requests"| node_api_client
node_driver -->|"requests"| node_api_client
node_public -->|"requests"| node_api_client
node_donor -->|"uses live events"| node_socket_client
node_recipient -->|"uses live events"| node_socket_client
node_driver -->|"uses live events"| node_socket_client
node_public -->|"uses live events"| node_socket_client
node_api_client -.->|"HTTP requests"| node_server
node_socket_client -.->|"opens socket"| node_server
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_impact_routes
node_server -->|"mounts"| node_donation_routes
node_server -->|"mounts"| node_recipient_routes
node_server -->|"mounts"| node_driver_routes
node_server -->|"starts timeout cascade"| node_matching
node_server -->|"sets socket"| node_matching
node_server -->|"sets socket"| node_dispatch
node_auth_routes -->|"reads and writes"| node_db
node_auth_routes -->|"uses secret"| node_auth_middleware
node_donation_routes -->|"reads and writes"| node_db
node_donation_routes -->|"invokes matching"| node_matching
node_recipient_routes -->|"reads and writes"| node_db
node_recipient_routes -->|"invokes matching"| node_matching
node_driver_routes -->|"reads and writes"| node_db
node_driver_routes -->|"invokes dispatch"| node_dispatch
node_impact_routes -->|"reads metrics"| node_db
node_matching -->|"reads and updates"| node_db
node_matching -->|"notifies recipient"| node_notifications
node_matching -->|"assigns after acceptance"| node_dispatch
node_dispatch -->|"assigns and records"| node_db
node_dispatch -->|"notifies driver"| node_notifications
node_dispatch -.->|"feeds delivery metrics"| node_impact_routes

click node_donor "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/DonorDashboard.jsx"
click node_recipient "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/RecipientDashboard.jsx"
click node_driver "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/DriverDashboard.jsx"
click node_public "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/ImpactDashboard.jsx"
click node_login "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/Login.jsx"
click node_router "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/api.js"
click node_socket_client "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/socket.js"
click node_server "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/server.js"
click node_auth_routes "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/auth.js"
click node_auth_middleware "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/middleware/auth.js"
click node_donation_routes "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/donations.js"
click node_recipient_routes "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/recipients.js"
click node_driver_routes "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/drivers.js"
click node_impact_routes "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/impact.js"
click node_matching "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/services/matching.js"
click node_dispatch "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/services/dispatch.js"
click node_notifications "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/services/notifications.js"
click node_db "https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/db.js"

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_donor,node_recipient,node_driver,node_public,node_login,node_router,node_api_client,node_socket_client,node_actor toneBlue
class node_server,node_auth_routes,node_auth_middleware,node_donation_routes,node_recipient_routes,node_driver_routes,node_impact_routes toneAmber
class node_matching,node_dispatch,node_notifications toneMint
class node_db toneRose
```

## Components

### Web portals

- [Donor portal](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/DonorDashboard.jsx): `frontend/src/pages/DonorDashboard.jsx`
- [Shelter portal](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/RecipientDashboard.jsx): `frontend/src/pages/RecipientDashboard.jsx`
- [Courier portal](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/DriverDashboard.jsx): `frontend/src/pages/DriverDashboard.jsx`
- [Impact portal](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/ImpactDashboard.jsx): `frontend/src/pages/ImpactDashboard.jsx`
- [Login](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/pages/Login.jsx): `frontend/src/pages/Login.jsx`
- [Role routing](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API client](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Live client](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/frontend/src/socket.js): `frontend/src/socket.js`

### API and identity

- [HTTP and socket server](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/server.js): `backend/server.js`
- [Authentication routes](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Token and role checks](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/middleware/auth.js): `backend/middleware/auth.js`
- [Donation routes](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/donations.js): `backend/routes/donations.js`
- [Recipient routes](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/recipients.js): `backend/routes/recipients.js`
- [Driver routes](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/drivers.js): `backend/routes/drivers.js`
- [Impact routes](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/routes/impact.js): `backend/routes/impact.js`

### Matching and dispatch

- [Spatial matching](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/services/matching.js): `backend/services/matching.js`
- [Courier dispatch](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/services/dispatch.js): `backend/services/dispatch.js`
- [Live notifications](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/services/notifications.js): `backend/services/notifications.js`

### Persistence and impact

- [PostgreSQL and PostGIS](https://github.com/mohitt-0805/surplus-to-shelter/blob/main/backend/db.js): `backend/db.js`

### Other components

- **Portal users**

## Connections

- Portal users → Role routing: uses portals (evidence: `frontend/src/App.jsx`)
- Role routing → Login: routes to (evidence: `frontend/src/App.jsx`)
- Role routing → Donor portal: routes to (evidence: `frontend/src/App.jsx`)
- Role routing → Shelter portal: routes to (evidence: `frontend/src/App.jsx`)
- Role routing → Courier portal: routes to (evidence: `frontend/src/App.jsx`)
- Role routing → Impact portal: routes to (evidence: `frontend/src/App.jsx`)
- Login → API client: requests (evidence: `frontend/src/pages/Login.jsx`)
- Donor portal → API client: requests (evidence: `frontend/src/pages/DonorDashboard.jsx`)
- Shelter portal → API client: requests (evidence: `frontend/src/pages/RecipientDashboard.jsx`)
- Courier portal → API client: requests (evidence: `frontend/src/pages/DriverDashboard.jsx`)
- Impact portal → API client: requests (evidence: `frontend/src/pages/ImpactDashboard.jsx`)
- Donor portal → Live client: uses live events (evidence: `frontend/src/pages/DonorDashboard.jsx`)
- Shelter portal → Live client: uses live events (evidence: `frontend/src/pages/RecipientDashboard.jsx`)
- Courier portal → Live client: uses live events (evidence: `frontend/src/pages/DriverDashboard.jsx`)
- Impact portal → Live client: uses live events (evidence: `frontend/src/pages/ImpactDashboard.jsx`)
- API client → HTTP and socket server: HTTP requests
- Live client → HTTP and socket server: opens socket
- HTTP and socket server → Authentication routes: mounts (evidence: `backend/server.js`)
- HTTP and socket server → Impact routes: mounts (evidence: `backend/server.js`)
- HTTP and socket server → Donation routes: mounts (evidence: `backend/server.js`)
- HTTP and socket server → Recipient routes: mounts (evidence: `backend/server.js`)
- HTTP and socket server → Driver routes: mounts (evidence: `backend/server.js`)
- HTTP and socket server → Spatial matching: starts timeout cascade (evidence: `backend/server.js`)
- HTTP and socket server → Spatial matching: sets socket (evidence: `backend/server.js`)
- HTTP and socket server → Courier dispatch: sets socket (evidence: `backend/server.js`)
- Authentication routes → PostgreSQL and PostGIS: reads and writes (evidence: `backend/routes/auth.js`)
- Authentication routes → Token and role checks: uses secret (evidence: `backend/routes/auth.js`)
- Donation routes → PostgreSQL and PostGIS: reads and writes (evidence: `backend/routes/donations.js`)
- Donation routes → Spatial matching: invokes matching (evidence: `backend/routes/donations.js`)
- Recipient routes → PostgreSQL and PostGIS: reads and writes (evidence: `backend/routes/recipients.js`)
- Recipient routes → Spatial matching: invokes matching (evidence: `backend/routes/recipients.js`)
- Driver routes → PostgreSQL and PostGIS: reads and writes (evidence: `backend/routes/drivers.js`)
- Driver routes → Courier dispatch: invokes dispatch (evidence: `backend/routes/drivers.js`)
- Impact routes → PostgreSQL and PostGIS: reads metrics (evidence: `backend/routes/impact.js`)
- Spatial matching → PostgreSQL and PostGIS: reads and updates (evidence: `backend/services/matching.js`)
- Spatial matching → Live notifications: notifies recipient (evidence: `backend/services/matching.js`)
- Spatial matching → Courier dispatch: assigns after acceptance (evidence: `backend/services/matching.js`)
- Courier dispatch → PostgreSQL and PostGIS: assigns and records (evidence: `backend/services/dispatch.js`)
- Courier dispatch → Live notifications: notifies driver (evidence: `backend/services/dispatch.js`)
- Courier dispatch → Impact routes: feeds delivery metrics