# tanvir-hannan-anik/foodbridge architecture

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

- Interactive diagram: https://gitdiagram.com/tanvir-hannan-anik/foodbridge
- Repository: https://github.com/tanvir-hannan-anik/foodbridge

## Overview

FoodBridge is a Dhaka surplus-food platform connecting donors, NGOs, volunteers, and administrators. Its central workflow posts a donation, allocates it to an NGO through direct requests or system matching, dispatches a volunteer for pickup and delivery, and lets the NGO record meals served. The graph also preserves administration, maps and live location, notifications, chat integrations, reporting, and the AI assistant. The main workflow is documented in the README; several service relationships are visible in excerpts or SOURCE INDEX references. Unsampled routes and service wiring are not inferred.

Main entry points: [`src/db/index.ts`](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/db/index.ts) (Postgres Data), [`src/lib/donations/service.ts`](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/donations/service.ts) (Donation Lifecycle), [`src/app/(app)`](https://github.com/tanvir-hannan-anik/foodbridge/tree/main/src/app/(app)) (Role Portals), [`src/lib/requests/service.ts`](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/requests/service.ts) (Requests And Needs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portals["Role Portals"]
  node_role_portals["Role Portals"]
  node_admin_ops["Admin Controls<br/>[service.ts]"]
end

subgraph group_allocation["Food Allocation"]
  node_donation_ops["Donation Lifecycle<br/>[service.ts]"]
  node_requests["Requests And Needs<br/>[service.ts]"]
  node_matching["Matching Allocation<br/>[service.ts]"]
  node_safety["Food Safety<br/>[service.ts]"]
end

subgraph group_delivery["Pickup Delivery"]
  node_dispatch["Volunteer Dispatch<br/>[service.ts]"]
  node_volunteer_ops["Volunteer Tasks<br/>[service.ts]"]
  node_location["Live Location<br/>[service.ts]"]
  node_maps["Maps"]
end

subgraph group_platform["Platform Services"]
  node_auth["Session Authorization<br/>[dal.ts]"]
  node_database[("Postgres Data<br/>[index.ts]")]
  node_schema["Domain Schema<br/>[schema.ts]"]
end

subgraph group_engagement["Communication Insights"]
  node_notifications["Notifications<br/>[service.ts]"]
  node_integrations["Chat Integrations<br/>[service.ts]"]
  node_assistant_api["Assistant API<br/>[route.ts]"]
  node_assistant_graph["Assistant Workflow<br/>[graph.ts]"]
  node_ai_provider["AI Providers<br/>[provider.ts]"]
  node_reports["Reports And Export"]
end

node_donor(("Donor"))
node_ngo(("NGO"))
node_volunteer(("Volunteer"))
node_admin(("Admin"))
node_external_channels{{"Messaging Channels"}}

node_donor -->|"posts food"| node_role_portals
node_ngo -->|"requests food"| node_role_portals
node_volunteer -->|"accepts tasks"| node_role_portals
node_admin -->|"manages platform"| node_role_portals
node_role_portals -.->|"checks identity"| node_auth
node_role_portals -.->|"uses donation workflow"| node_donation_ops
node_donation_ops -->|"reads writes"| node_database
node_donation_ops -->|"releases tasks"| node_dispatch
node_donation_ops -->|"sends updates"| node_notifications
node_requests -->|"allocates requests"| node_matching
node_requests -->|"notifies donors"| node_donation_ops
node_requests -->|"reads writes"| node_database
node_matching -->|"transitions donation"| node_donation_ops
node_matching -->|"reads writes"| node_database
node_safety -.->|"checks food"| node_database
node_dispatch -->|"offers tasks"| node_database
node_dispatch -->|"alerts admins"| node_notifications
node_volunteer_ops -->|"manages offers"| node_dispatch
node_volunteer_ops -->|"updates donation"| node_donation_ops
node_location -.->|"records positions"| node_database
node_maps -.->|"shows live position"| node_location
node_admin_ops -->|"transitions records"| node_donation_ops
node_admin_ops -->|"reads writes"| node_database
node_database -->|"uses tables"| node_schema
node_auth -->|"checks account"| node_database
node_notifications -.->|"delivers optionally"| node_external_channels
node_integrations -->|"creates donations"| node_donation_ops
node_integrations -->|"matches needs"| node_requests
node_integrations -->|"receives chat events"| node_external_channels
node_assistant_api -->|"checks user"| node_auth
node_assistant_api -->|"runs assistant"| node_assistant_graph
node_assistant_graph -->|"selects provider"| node_ai_provider
node_assistant_api -.->|"stores conversation"| node_database
node_reports -.->|"queries reports"| node_database
node_admin -->|"reviews exports"| node_reports

click node_role_portals "https://github.com/tanvir-hannan-anik/foodbridge/tree/main/src/app/(app)"
click node_donation_ops "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/donations/service.ts"
click node_requests "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/requests/service.ts"
click node_matching "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/matching/service.ts"
click node_safety "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/safety/service.ts"
click node_dispatch "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/dispatch/service.ts"
click node_volunteer_ops "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/volunteer/service.ts"
click node_location "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/location/service.ts"
click node_maps "https://github.com/tanvir-hannan-anik/foodbridge/tree/main/src/components/map"
click node_admin_ops "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/admin/service.ts"
click node_auth "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/auth/dal.ts"
click node_database "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/db/index.ts"
click node_schema "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/db/schema.ts"
click node_notifications "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/notifications/service.ts"
click node_integrations "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/integrations/service.ts"
click node_assistant_api "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/app/api/assistant/route.ts"
click node_assistant_graph "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/ai/graph.ts"
click node_ai_provider "https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/ai/provider.ts"
click node_reports "https://github.com/tanvir-hannan-anik/foodbridge/tree/main/src/lib/reports"

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_role_portals,node_admin_ops toneBlue
class node_donation_ops,node_requests,node_matching,node_safety toneAmber
class node_dispatch,node_volunteer_ops,node_location,node_maps toneMint
class node_auth,node_database,node_schema toneRose
class node_notifications,node_integrations,node_assistant_api,node_assistant_graph,node_ai_provider,node_reports,node_donor,node_ngo,node_volunteer,node_admin,node_external_channels toneIndigo
```

## Components

### Role Portals

- [Role Portals](https://github.com/tanvir-hannan-anik/foodbridge/tree/main/src/app/(app)): `src/app/(app)`
- [Admin Controls](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/admin/service.ts): `src/lib/admin/service.ts`

### Food Allocation

- [Donation Lifecycle](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/donations/service.ts): `src/lib/donations/service.ts`
- [Requests And Needs](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/requests/service.ts): `src/lib/requests/service.ts`
- [Matching Allocation](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/matching/service.ts): `src/lib/matching/service.ts`
- [Food Safety](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/safety/service.ts): `src/lib/safety/service.ts`

### Pickup Delivery

- [Volunteer Dispatch](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/dispatch/service.ts): `src/lib/dispatch/service.ts`
- [Volunteer Tasks](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/volunteer/service.ts): `src/lib/volunteer/service.ts`
- [Live Location](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/location/service.ts): `src/lib/location/service.ts`
- [Maps](https://github.com/tanvir-hannan-anik/foodbridge/tree/main/src/components/map): `src/components/map`

### Platform Services

- [Session Authorization](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/auth/dal.ts): `src/lib/auth/dal.ts`
- [Postgres Data](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/db/index.ts): `src/db/index.ts`
- [Domain Schema](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/db/schema.ts): `src/db/schema.ts`

### Communication Insights

- [Notifications](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/notifications/service.ts): `src/lib/notifications/service.ts`
- [Chat Integrations](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/integrations/service.ts): `src/lib/integrations/service.ts`
- [Assistant API](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/app/api/assistant/route.ts): `src/app/api/assistant/route.ts`
- [Assistant Workflow](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/ai/graph.ts): `src/lib/ai/graph.ts`
- [AI Providers](https://github.com/tanvir-hannan-anik/foodbridge/blob/main/src/lib/ai/provider.ts): `src/lib/ai/provider.ts`
- [Reports And Export](https://github.com/tanvir-hannan-anik/foodbridge/tree/main/src/lib/reports): `src/lib/reports`

### Other components

- **Donor**
- **NGO**
- **Volunteer**
- **Admin**
- **Messaging Channels**

## Connections

- Donor → Role Portals: posts food
- NGO → Role Portals: requests food
- Volunteer → Role Portals: accepts tasks
- Admin → Role Portals: manages platform
- Role Portals → Session Authorization: checks identity (evidence: `src/app/(app)/volunteer/tasks/[id]/image/route.ts`)
- Role Portals → Donation Lifecycle: uses donation workflow (evidence: `src/app/(app)/volunteer/tasks/[id]/image/route.ts`)
- Donation Lifecycle → Postgres Data: reads writes (evidence: `src/lib/donations/service.ts`)
- Donation Lifecycle → Volunteer Dispatch: releases tasks (evidence: `src/lib/donations/service.ts`)
- Donation Lifecycle → Notifications: sends updates (evidence: `src/lib/donations/service.ts`)
- Requests And Needs → Matching Allocation: allocates requests (evidence: `src/lib/requests/service.ts`)
- Requests And Needs → Donation Lifecycle: notifies donors (evidence: `src/lib/requests/service.ts`)
- Requests And Needs → Postgres Data: reads writes (evidence: `src/lib/requests/service.ts`)
- Matching Allocation → Donation Lifecycle: transitions donation (evidence: `src/lib/matching/service.ts`)
- Matching Allocation → Postgres Data: reads writes (evidence: `src/lib/matching/service.ts`)
- Food Safety → Postgres Data: checks food
- Volunteer Dispatch → Postgres Data: offers tasks (evidence: `src/lib/dispatch/service.ts`)
- Volunteer Dispatch → Notifications: alerts admins (evidence: `src/lib/dispatch/service.ts`)
- Volunteer Tasks → Volunteer Dispatch: manages offers (evidence: `src/lib/volunteer/service.ts`)
- Volunteer Tasks → Donation Lifecycle: updates donation (evidence: `src/lib/volunteer/service.ts`)
- Live Location → Postgres Data: records positions
- Maps → Live Location: shows live position
- Admin Controls → Donation Lifecycle: transitions records (evidence: `src/lib/admin/service.ts`)
- Admin Controls → Postgres Data: reads writes (evidence: `src/lib/admin/service.ts`)
- Postgres Data → Domain Schema: uses tables (evidence: `src/db/index.ts`)
- Session Authorization → Postgres Data: checks account (evidence: `src/lib/auth/dal.ts`)
- Notifications → Messaging Channels: delivers optionally
- Chat Integrations → Donation Lifecycle: creates donations (evidence: `src/lib/integrations/service.ts`)
- Chat Integrations → Requests And Needs: matches needs (evidence: `src/lib/integrations/service.ts`)
- Chat Integrations → Messaging Channels: receives chat events
- Assistant API → Session Authorization: checks user (evidence: `src/app/api/assistant/route.ts`)
- Assistant API → Assistant Workflow: runs assistant (evidence: `src/app/api/assistant/route.ts`)
- Assistant Workflow → AI Providers: selects provider (evidence: `src/lib/ai/graph.ts`)
- Assistant API → Postgres Data: stores conversation
- Reports And Export → Postgres Data: queries reports
- Admin → Reports And Export: reviews exports