# devtanisha-max/food-to-ngo-distribution-system architecture

> Architecture diagram of the GitHub repository devtanisha-max/food-to-ngo-distribution-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devtanisha-max/food-to-ngo-distribution-system
- Repository: https://github.com/devtanisha-max/food-to-ngo-distribution-system

## Overview

1. **Overall shape**
   - This is a small monolithic Flask application for a two-sided workflow: **restaurants donate surplus food** and **NGOs request and pick it up**.
   - The backend, HTML pages, and database live in one repository, with no separate service boundaries beyond the app, database, and file uploads.

2. **Primary runtime boundary**
   - `app.py` is the main server entrypoint and likely owns routing, session handling, business rules, and page/API responses.
   - The browser-facing UI is file-based HTML/CSS/JS under `frontend/`, so the app is not a full SPA; it is a server-backed multi-page web app.

3. **User-facing surfaces**
   - The frontend consists of role-oriented pages: `login.html`, `signup.html`, `restaurant.html`, `ngo.html`, and `otp.html`.
   - `frontend/script.js` appears to contain the client-side behavior for form handling, page interactions, and possibly AJAX calls to the Flask backend.
   - `frontend/styles.css` provides shared styling across these pages.

4. **Core business domains**
   - The app models three main actors: **Restaurant**, **NGO**, and **Admin**.
   - Restaurants register, upload certificates, publish surplus food, and confirm handoff.
   - NGOs register with an SMU capacity, browse nearby food, place requests, and verify pickup using OTP.
   - Admin responsibility is verification/approval of restaurants, with the README noting local auto-approval for development.

5. **Key workflow data flow**
   - Registration flows from the browser to Flask, then into persistent storage, with restaurant onboarding including file upload to `uploads/`.
   - Restaurants create surplus food entries; these become available to NGOs through the same backend and database.
   - NGOs consume those listings subject to the SMU capacity rules enforced by the server.
   - On pickup, the backend generates and verifies an OTP to complete distribution.

6. **Business-rule boundary**
   - The most important server-side constraint is the **Standard Meal Unit (SMU)** model.
   - This is the fairness gate that limits NGO orders and blocks requests that exceed remaining capacity.
   - This means allocation logic is not just CRUD; it is a central policy enforcement layer in the backend.

7. **Persistence layer**
   - The repository includes both `db.py` and `db_mysql.py`, plus `setup_db.py`, indicating a database abstraction that can work with either SQLite or PostgreSQL/MySQL-style backends depending on configuration.
   - `food_to_ngo.db` suggests a local SQLite database for development.
   - `database/database_schema_raunak.sql` appears to be the schema definition source for setting up tables.
   - `setup_db.py` is the bootstrap script that initializes those tables.

8. **File storage**
   - `uploads/` stores uploaded certificates locally.
   - This is a separate persistence concern from the relational database: metadata likely lives in tables, while the actual files live on disk.

9. **Security and trust controls**
   - Authentication is session-based, so login state is maintained by the Flask server rather than a separate identity provider.
   - Certificate upload and approval create a trust boundary for restaurants.
   - OTP verification creates a second trust boundary at pickup time, preventing unauthorized collection.
   - SMU capacity limits act as anti-hoarding controls.

10. **Deployment and environment**
   - The README points to deployment on **Render** and mentions a PostgreSQL option via **Supabase**.
   - The repo also includes `.env`, which likely stores the database connection string and other runtime configuration.
   - This means the application is designed to run locally on SQLite but can be switched to hosted relational storage in production.

11. **Repository structure cues**
   - The root contains a `login.html` in addition to `frontend/login.html`, which suggests either a legacy copy or a deployment convenience file.
   - `food-to-ngo-distribution-system/` is present as an extra directory name in the tree, likely a nested project copy or artifact; it is not described as a separate subsystem in the README.
   - The meaningful architecture still centers on `app.py`, the DB layer, and `frontend/`.

12. **How to draw the diagram**
   - Show one central **Flask backend** connected to:
     - the **browser UI** pages and JS,
     - the **relational database**,
     - and the **uploads filesystem**.
   - Within the backend, separate the concerns into:
     - authentication/session management,
     - restaurant onboarding and food publishing,
     - NGO discovery/order placement,
     - OTP verification,
     - and SMU-based allocation enforcement.

Main entry points: [`app.py`](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py) (Flask app), [`db.py`](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/db.py) (DB layer), [`setup_db.py`](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/setup_db.py) (Setup DB), [`frontend/script.js`](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/frontend/script.js) (Client JS)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_pages["UI pages<br/>multi-page ui"]
  node_frontend_script["Client JS<br/>browser script<br/>[script.js]"]
  node_frontend_styles["Styles<br/>[styles.css]"]
  node_login_page["Login page<br/>html page<br/>[login.html]"]
end

subgraph group_backend["Backend"]
  node_app["Flask app<br/>entrypoint<br/>[app.py]"]
  node_auth(("Auth<br/>session<br/>[app.py]"))
  node_restaurant_flow{{"Restaurant flow<br/>workflow<br/>[app.py]"}}
  node_ngo_flow{{"NGO flow<br/>workflow<br/>[app.py]"}}
  node_smu_policy{{"SMU policy<br/>rule engine<br/>[app.py]"}}
  node_otp_service(("OTP verify<br/>verification<br/>[app.py]"))
  node_db_layer["DB layer<br/>persistence adapter<br/>[db.py]"]
  node_db_mysql["MySQL adapter<br/>[db_mysql.py]"]
end

subgraph group_data["Data"]
  node_uploads[("Uploads<br/>file store")]
  node_sqlite_db[("SQLite DB<br/>database file<br/>[food_to_ngo.db]")]
  node_schema["Schema"]
  node_setup_db["Setup DB<br/>bootstrap<br/>[setup_db.py]"]
  node_env["Env config<br/>runtime config<br/>[.env]"]
end

node_ui_pages -->|"loads"| node_frontend_script
node_ui_pages -->|"styles"| node_frontend_styles
node_login_page -.->|"serves"| node_app
node_frontend_script -->|"requests"| node_app
node_app -->|"handles"| node_auth
node_app -->|"handles"| node_restaurant_flow
node_app -->|"handles"| node_ngo_flow
node_app -->|"enforces"| node_smu_policy
node_app -->|"verifies"| node_otp_service
node_restaurant_flow -->|"stores files"| node_uploads
node_restaurant_flow -->|"persists"| node_db_layer
node_ngo_flow -->|"reads/writes"| node_db_layer
node_smu_policy -->|"reads"| node_db_layer
node_otp_service -->|"updates"| node_db_layer
node_db_layer -->|"uses"| node_sqlite_db
node_db_layer -.->|"switches to"| node_db_mysql
node_setup_db -->|"initializes"| node_schema
node_setup_db -->|"creates"| node_sqlite_db
node_env -->|"configures"| node_db_layer

click node_app "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py"
click node_auth "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py"
click node_restaurant_flow "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py"
click node_ngo_flow "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py"
click node_smu_policy "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py"
click node_otp_service "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py"
click node_db_layer "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/db.py"
click node_db_mysql "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/db_mysql.py"
click node_frontend_script "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/frontend/script.js"
click node_frontend_styles "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/frontend/styles.css"
click node_login_page "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/login.html"
click node_uploads "https://github.com/devtanisha-max/food-to-ngo-distribution-system/tree/main/uploads"
click node_sqlite_db "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/food_to_ngo.db"
click node_schema "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/database/database_schema_raunak.sql"
click node_setup_db "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/setup_db.py"
click node_env "https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/.env"

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_ui_pages,node_frontend_script,node_frontend_styles,node_login_page toneBlue
class node_app,node_auth,node_restaurant_flow,node_ngo_flow,node_smu_policy,node_otp_service,node_db_layer,node_db_mysql toneAmber
class node_uploads,node_sqlite_db,node_schema,node_setup_db,node_env toneMint
```

## Components

### Frontend

Browser-facing pages and client behavior

- **UI pages**: multi-page ui · Role-oriented HTML screens for login, signup, restaurant, NGO, and OTP
- [Client JS](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/frontend/script.js): browser script · Client-side form handling, interactions, and backend calls · `frontend/script.js`
- [Styles](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/frontend/styles.css): stylesheet · Shared visual styling for the web pages · `frontend/styles.css`
- [Login page](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/login.html): html page · Root-level login entry page or convenience copy · `login.html`

### Backend

Flask server and workflow logic

- [Flask app](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py): entrypoint · Main server entrypoint with routes, sessions, and request handling · `app.py`
- [Auth](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py): session · Login, signup, and session-based identity management · `app.py`
- [Restaurant flow](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py): workflow · Restaurant onboarding, certificate upload, and surplus food publishing · `app.py`
- [NGO flow](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py): workflow · NGO registration, browsing, requests, and pickup coordination · `app.py`
- [SMU policy](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py): rule engine · Standard Meal Unit capacity checks that limit NGO requests · `app.py`
- [OTP verify](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/app.py): verification · Pickup-time OTP generation and validation · `app.py`
- [DB layer](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/db.py): persistence adapter · Database access abstraction used by the Flask workflows · `db.py`
- [MySQL adapter](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/db_mysql.py): adapter · Alternative SQL connector for hosted database deployments · `db_mysql.py`

### Data

Persistence, schema, and uploaded files

- [Uploads](https://github.com/devtanisha-max/food-to-ngo-distribution-system/tree/main/uploads): file store · Local storage for restaurant certificates and related files · `uploads`
- [SQLite DB](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/food_to_ngo.db): database file · Local development database file · `food_to_ngo.db`
- [Schema](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/database/database_schema_raunak.sql): sql schema · Table definitions used to initialize the database · `database/database_schema_raunak.sql`
- [Setup DB](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/setup_db.py): bootstrap · Script that creates and initializes database tables · `setup_db.py`
- [Env config](https://github.com/devtanisha-max/food-to-ngo-distribution-system/blob/main/.env): runtime config · Environment settings for database and deployment options · `.env`

## Connections

- UI pages → Client JS: loads · Pages use client-side behavior for forms and interactions
- UI pages → Styles: styles · Pages share common presentation
- Login page → Flask app: serves · Root login page connects to the Flask application
- Client JS → Flask app: requests · Browser actions submit data to backend endpoints
- Flask app → Auth: handles · Server manages login, signup, and sessions
- Flask app → Restaurant flow: handles · Restaurant onboarding and surplus food publishing
- Flask app → NGO flow: handles · NGO discovery, requests, and pickup workflow
- Flask app → SMU policy: enforces · Allocation rules are checked before accepting NGO requests
- Flask app → OTP verify: verifies · Pickup completion depends on OTP validation
- Restaurant flow → Uploads: stores files · Restaurant certificates and related uploads are written to disk
- Restaurant flow → DB layer: persists · Restaurant records and food listings are saved through the data layer
- NGO flow → DB layer: reads/writes · NGO profiles, listings, and requests are stored and queried
- SMU policy → DB layer: reads · Capacity checks use persisted NGO and order state
- OTP verify → DB layer: updates · OTP state and pickup completion are recorded
- DB layer → SQLite DB: uses · Default local development database backend
- DB layer → MySQL adapter: switches to · Alternative backend for hosted deployments
- Setup DB → Schema: initializes · Bootstrap script creates tables from schema definition
- Setup DB → SQLite DB: creates · Local database file can be provisioned during setup
- Env config → DB layer: configures · Runtime settings supply connection details
