# nikhil-4404/surplus2serve architecture

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

- Interactive diagram: https://gitdiagram.com/nikhil-4404/surplus2serve
- Repository: https://github.com/nikhil-4404/surplus2serve

## Overview

Surplus2Serve is a community food-redistribution web app: restaurants submit time-limited surplus offers, then volunteers browse and claim offers for pickup. The main browser workflow uses the localStorage store in `app.js` to persist alerts and statistics and render dashboard, activity, partner, and impact views. Firebase and Google Sheets are documented alternatives, not shown wired into the main app. The Sheets script includes backend alert, claim, reporting, and notification logic; email and WhatsApp delivery are optional. Some UI and integration details are unsampled, so uncertain connections are omitted.

Main entry points: [`surplus2serve/app.js`](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js) (Web App), [`surplus2serve/google-sheets-integration.js`](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/google-sheets-integration.js) (Alert & Claim Logic), [`surplus2serve/firebase-setup.js`](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/firebase-setup.js) (Firebase Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Redistribution Workflow"]
  node_alert_ui["Alert Dashboard<br/>[app.js]"]
  node_claim_ui["Claim Flow<br/>[app.js]"]
  node_impact_ui["Impact Views<br/>[app.js]"]
  node_activity_ui["Activity &amp; Partners<br/>[app.js]"]
end

subgraph group_browser["Browser Application"]
  node_app["Web App<br/>[app.js]"]
end

subgraph group_persistence["Data Stores"]
  node_local_store["Local Store<br/>[app.js]"]
  node_local_storage[("Browser Storage")]
end

subgraph group_integrations["Optional Integrations"]
  node_firebase_store["Firebase Store<br/>[firebase-setup.js]"]
  node_firebase_db[("Firebase Database")]
  node_sheets_api["Sheets Web API"]
  node_sheets_handlers["Alert &amp; Claim Logic"]
  node_sheets_data[("Sheets Data")]
  node_notifications["Email &amp; WhatsApp"]
end

node_restaurant(("Restaurant"))
node_volunteer(("Volunteer"))

node_restaurant -->|"submits offer"| node_app
node_volunteer -->|"browses and claims"| node_app
node_app -->|"handles alert actions"| node_local_store
node_app -->|"renders alerts"| node_alert_ui
node_app -->|"handles claims"| node_claim_ui
node_app -->|"renders impact"| node_impact_ui
node_app -->|"renders activity"| node_activity_ui
node_alert_ui -->|"reads alerts"| node_local_store
node_claim_ui -->|"claims alert"| node_local_store
node_impact_ui -->|"reads statistics"| node_local_store
node_activity_ui -->|"reads alerts"| node_local_store
node_local_store -->|"reads and writes"| node_local_storage
node_firebase_store -.->|"reads and writes"| node_firebase_db
node_sheets_api -.->|"dispatches actions"| node_sheets_handlers
node_sheets_handlers -.->|"reads and writes"| node_sheets_data
node_sheets_handlers -.->|"sends alerts"| node_notifications

click node_app "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js"
click node_alert_ui "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js"
click node_claim_ui "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js"
click node_impact_ui "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js"
click node_activity_ui "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js"
click node_local_store "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js"
click node_firebase_store "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/firebase-setup.js"
click node_sheets_api "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/google-sheets-integration.js"
click node_sheets_handlers "https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/google-sheets-integration.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_alert_ui,node_claim_ui,node_impact_ui,node_activity_ui toneBlue
class node_app toneAmber
class node_local_store,node_local_storage toneMint
class node_firebase_store,node_firebase_db,node_sheets_api,node_sheets_handlers,node_sheets_data,node_notifications toneRose
class node_restaurant,node_volunteer toneIndigo
```

## Components

### Redistribution Workflow

- [Alert Dashboard](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js): `surplus2serve/app.js`
- [Claim Flow](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js): `surplus2serve/app.js`
- [Impact Views](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js): `surplus2serve/app.js`
- [Activity & Partners](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js): `surplus2serve/app.js`

### Browser Application

- [Web App](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js): `surplus2serve/app.js`

### Data Stores

- [Local Store](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/app.js): `surplus2serve/app.js`
- **Browser Storage**

### Optional Integrations

- [Firebase Store](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/firebase-setup.js): `surplus2serve/firebase-setup.js`
- **Firebase Database**
- [Sheets Web API](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/google-sheets-integration.js): `surplus2serve/google-sheets-integration.js`
- [Alert & Claim Logic](https://github.com/nikhil-4404/surplus2serve/blob/main/surplus2serve/google-sheets-integration.js): `surplus2serve/google-sheets-integration.js`
- **Sheets Data**
- **Email & WhatsApp**

### Other components

- **Restaurant**
- **Volunteer**

## Connections

- Restaurant → Web App: submits offer
- Volunteer → Web App: browses and claims
- Web App → Local Store: handles alert actions
- Web App → Alert Dashboard: renders alerts
- Web App → Claim Flow: handles claims
- Web App → Impact Views: renders impact
- Web App → Activity & Partners: renders activity
- Alert Dashboard → Local Store: reads alerts
- Claim Flow → Local Store: claims alert
- Impact Views → Local Store: reads statistics
- Activity & Partners → Local Store: reads alerts
- Local Store → Browser Storage: reads and writes
- Firebase Store → Firebase Database: reads and writes
- Sheets Web API → Alert & Claim Logic: dispatches actions
- Alert & Claim Logic → Sheets Data: reads and writes
- Alert & Claim Logic → Email & WhatsApp: sends alerts