How devtanisha-max/food-to-ngo-distribution-system works
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 Flask app · db.py DB layer · setup_db.py Setup DB · script.js Client JS
Components 17
Frontend
Browser-facing pages and client behavior
- UI pages · Role-oriented HTML screens for login, signup, restaurant, NGO, and OTP
- Client JS · Client-side form handling, interactions, and backend calls
frontend/script.js - Styles · Shared visual styling for the web pages
frontend/styles.css - Login page · Root-level login entry page or convenience copy
login.html
Backend
Flask server and workflow logic
- Flask app · Main server entrypoint with routes, sessions, and request handling
app.py - Auth · Login, signup, and session-based identity management
app.py - Restaurant flow · Restaurant onboarding, certificate upload, and surplus food publishing
app.py - NGO flow · NGO registration, browsing, requests, and pickup coordination
app.py - SMU policy · Standard Meal Unit capacity checks that limit NGO requests
app.py - OTP verify · Pickup-time OTP generation and validation
app.py - DB layer · Database access abstraction used by the Flask workflows
db.py - MySQL adapter · Alternative SQL connector for hosted database deployments
db_mysql.py
Data
Persistence, schema, and uploaded files
- Uploads · Local storage for restaurant certificates and related files
uploads - SQLite DB · Local development database file
food_to_ngo.db - Schema · Table definitions used to initialize the database
database/database_schema_raunak.sql - Setup DB · Script that creates and initializes database tables
setup_db.py - Env config · Environment settings for database and deployment options
.env
Connections 19
- 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