# 25ag1a6767-cyber/collegebit architecture

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

- Interactive diagram: https://gitdiagram.com/25ag1a6767-cyber/collegebit
- Repository: https://github.com/25ag1a6767-cyber/collegebit

## Overview

<purpose>The product is a college-canteen ordering and operations platform: a customer using the mobile app or customer web/PWA initiates the main workflow by browsing and ordering; the backend validates the cart, handles payment and pickup, and exposes order state to customers and staff. Staff operate kitchen and pickup flows, while administrators manage the business and view reports. The README documents one centralized FastAPI backend and PostgreSQL database shared by the applications.</purpose>

<components>
**Backend API and shared domain**
- **FastAPI application and routes** — `backend/app/main.py`: Application entry point and HTTP route layer; sampled routes include login and catalogue administration, and its source index references the domain modules it imports.
- **Shared domain rules** — `backend/app/modules/common.py`: Implements shared pricing, tax and discount rules, inventory/recipe helpers, notifications, and audit support.
- **Relational domain model** — `backend/app/models.py`: Defines persisted entities, including counters, staff assignments, carts, and discounts.
- **Database sessions** — `backend/app/database.py`: Configures SQLAlchemy engine and sessions for PostgreSQL, SQLite, and PgBouncer transaction pooling.
- **Authentication and authorization** — `backend/app/security.py`: Implements password/token security, refresh sessions, MFA-related security, and counter-scoped access control.
- **Authentication and customer profiles** — `backend/app/modules/auth_profile.py`: Handles account/profile domain operations, using shared security, database, and email facilities.
- **Menu and cart** — `backend/app/modules/menu_cart.py`: Implements menu/cart operations and uses shared domain rules and persistence.
- **Orders and payments** — `backend/app/modules/orders_payments.py`: Owns order and payment workflows, including order quotes and pickup-related domain operations.
- **Staff operations** — `backend/app/modules/staff_ops.py`: Implements kitchen and staff workflows; its contents were not sampled.
- **Enterprise administration** — `backend/app/modules/admin_enterprise.py`: Implements enterprise administration; its contents were not sampled.
- **Admin portal operations** — `backend/app/modules/admin_portal.py`: Implements admin-portal operations over shared domain, database, and security modules.
- **AI services** — `backend/app/modules/ai_services.py`: Implements AI-facing application features, with dependencies on menu/cart and analytics; provider execution details are not established by the excerpts.
- **Analytics and BI** — `backend/app/modules/analytics_bi.py`: Implements business-intelligence analytics over the relational domain.
- **Report generation** — `backend/app/modules/reporting_engine.py`: Builds operational and business reports and records generated-report metadata; README documents PDF, Excel, and CSV exports.
- **Retention and backups** — `backend/app/modules/retention_backup.py`: Implements retention and backup domain operations; a repository script also references this module.
- **Realtime events** — `backend/app/realtime.py`: Provides backend realtime functionality; the mobile client connects to the backend WebSocket endpoint.
- **Email delivery** — `backend/app/emailer.py`: Provides configured email functionality used by authentication and order-related modules.

**Customer application**
- **Mobile app and screens** — `mobile/App.tsx`: Composes the customer experience from authentication, home, menu, cart/checkout, order tracking, profile, and AI-assistant screens.
- **Mobile API and realtime client** — `mobile/src/api/client.ts`: Sends authenticated API requests, manages access/refresh tokens, and opens the `/api/v1/ws` WebSocket.
- **Mobile identity state** — `mobile/src/context/AuthContext.tsx`: Maintains user/authentication and realtime connection state through the API client.
- **Mobile cart state** — `mobile/src/context/CartContext.tsx`: Manages cart lines and quotes, synchronizing student cart changes and quote requests with the API.
- **Mobile API contracts** — `mobile/src/types/api.ts`: Defines shared client-side representations for menus, quotes, orders, pickup tokens, and AI responses.
- **Customer web/PWA scripts** — `frontend/js/app.js`: Implements the customer-facing web application behavior; the README documents customer web/PWA capabilities.

**Staff and administration interfaces**
- **Staff portal client** — `frontend/js/staff-portal.js`: Implements staff-portal browser behavior, including the documented kitchen and pickup workflows.
- **Admin portal client** — `frontend/js/admin-portal.js`: Implements the admin/BI browser experience; README documents management, dashboards, reporting, and backup capabilities.

**External actors and systems**
- **Customer** — *no repository path*: Uses the mobile or customer web/PWA interface to browse and place orders.
- **Staff operator** — *no repository path*: Uses the staff website to process kitchen orders and pickup.
- **Canteen administrator** — *no repository path*: Uses the admin website to manage operations and view BI.
- **ASGI server/operator** — *no repository path*: Starts the application with Uvicorn as documented in the README quickstart.
- **PostgreSQL database** — *no repository path*: Centralized relational persistence documented by the README; deployment may use self-hosted PostgreSQL or optional Neon.
- **Razorpay** — *no repository path*: Payment provider named in the README; exact API call sites were not sampled.
</components>

<relationships>
- **ASGI server/operator -> FastAPI application and routes**: serves the application; evidence: README.md.
- **Customer -> Mobile app and screens**: initiates browsing and ordering; evidence: README.md.
- **Customer -> Customer web/PWA scripts**: uses the customer web/PWA; evidence: README.md.
- **Mobile app and screens -> Mobile identity state**: composed with the authentication provider; evidence: mobile/App.tsx.
- **Mobile app and screens -> Mobile cart state**: composed with the cart provider; evidence: mobile/App.tsx.
- **Mobile identity state -> Mobile API and realtime client**: calls API operations and establishes realtime connection; evidence: mobile/src/context/AuthContext.tsx.
- **Mobile cart state -> Mobile API and realtime client**: sends cart mutations and quote requests; evidence: mobile/src/context/CartContext.tsx.
- **Mobile API and realtime client -> FastAPI application and routes**: sends HTTP requests and connects to the backend WebSocket; evidence: mobile/src/api/client.ts.
- **FastAPI application and routes -> Database sessions**: imports and uses database facilities; evidence: backend/app/main.py.
- **Database sessions -> PostgreSQL database**: configures a SQLAlchemy engine from the configured database URL; evidence: backend/app/database.py.
- **FastAPI application and routes -> Authentication and authorization**: imports and uses security functionality; evidence: backend/app/main.py.
- **FastAPI application and routes -> Orders and payments**: imports the order/payment module; evidence: backend/app/main.py.
- **Orders and payments -> Shared domain rules**: uses common helpers; evidence: SOURCE INDEX for `backend/app/modules/orders_payments.py`.
- **Orders and payments -> Razorpay**: handles the payment workflow involving the documented provider; evidence: README.md.
- **Staff operator -> Staff portal client**: uses the staff website; evidence: README.md.
- **Staff portal client -> FastAPI application and routes**: backend route wiring is not shown in the sampled client or source index; evidence: none (inferred).
- **Canteen administrator -> Admin portal client**: uses the admin website; evidence: README.md.
- **Admin portal client -> FastAPI application and routes**: backend route wiring is not shown in the sampled client or source index; evidence: none (inferred).
- **FastAPI application and routes -> Analytics and BI**: imports the analytics module; evidence: backend/app/main.py.
- **Report generation -> Analytics and BI**: imports analytics functionality; evidence: SOURCE INDEX for `backend/app/modules/reporting_engine.py`.
- **AI services -> Analytics and BI**: imports analytics functionality; evidence: SOURCE INDEX for `backend/app/modules/ai_services.py`.
- **Mobile API and realtime client -> FastAPI application and routes**: opens the `/api/v1/ws` connection for realtime updates; evidence: mobile/src/api/client.ts.
</relationships>

<coverage>Several substantial backend modules, including staff operations and enterprise administration, are present in the tree but their source was not sampled, so their internal routes and exact interactions are uncertain. The customer HTML, staff HTML, and admin HTML named in the README are not in the supplied tree. The excerpts do not establish precise payment-provider calls, AI-provider calls, or the full order-to-pickup event sequence; those details are not represented as definite wiring.</coverage>

Main entry points: [`backend/app/main.py`](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/main.py) (FastAPI routes), [`mobile/src/api/client.ts`](https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/src/api/client.ts) (Mobile API/realtime client), [`mobile/App.tsx`](https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/App.tsx) (Mobile app), [`backend/app/modules/orders_payments.py`](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/orders_payments.py) (Orders and payments)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer experience"]
  node_customer(("Customer<br/>actor"))
  node_mobile_app["Mobile app<br/>customer application"]
  node_customer_web["Customer web/PWA<br/>customer application"]
  node_mobile_identity["Mobile identity state<br/>client state"]
  node_mobile_cart["Mobile cart state<br/>client state"]
  node_mobile_client["Mobile API/realtime client<br/>API client"]
end

subgraph group_platform["Backend platform"]
  node_asgi_operator(("ASGI server/operator"))
  node_fastapi["FastAPI routes<br/>HTTP and WebSocket API"]
  node_database_sessions["Database sessions<br/>database access"]
  node_postgres[("PostgreSQL<br/>relational database")]
  node_security["Authentication and authorization<br/>security"]
  node_orders["Orders and payments<br/>domain service"]
  node_common["Shared domain rules<br/>domain service"]
  node_razorpay["Razorpay<br/>payment provider"]
end

subgraph group_operations["Staff and administration"]
  node_staff_operator(("Staff operator<br/>actor"))
  node_staff_portal["Staff portal<br/>staff interface"]
  node_administrator(("Canteen administrator<br/>actor"))
  node_admin_portal["Admin portal<br/>administration interface"]
end

subgraph group_analytics["Analytics services"]
  node_analytics["Analytics and BI<br/>analytics service"]
  node_reporting["Report generation<br/>reporting service"]
  node_ai_services["AI services<br/>AI application service"]
end

node_asgi_operator -->|"serves"| node_fastapi
node_customer -->|"browses and orders"| node_mobile_app
node_customer -->|"uses"| node_customer_web
node_mobile_app -->|"composes"| node_mobile_identity
node_mobile_app -->|"composes"| node_mobile_cart
node_mobile_identity -->|"calls API"| node_mobile_client
node_mobile_cart -->|"syncs cart and quotes"| node_mobile_client
node_mobile_client -->|"sends HTTP requests"| node_fastapi
node_mobile_client -->|"connects by WebSocket"| node_fastapi
node_fastapi -->|"uses sessions"| node_database_sessions
node_database_sessions -->|"configures engine"| node_postgres
node_fastapi -->|"uses security"| node_security
node_fastapi -->|"imports"| node_orders
node_orders -->|"uses helpers"| node_common
node_orders -->|"handles payment"| node_razorpay
node_staff_operator -->|"uses"| node_staff_portal
node_staff_portal -.->|"uses backend"| node_fastapi
node_administrator -->|"uses"| node_admin_portal
node_admin_portal -.->|"uses backend"| node_fastapi
node_fastapi -->|"imports"| node_analytics
node_reporting -->|"imports"| node_analytics
node_ai_services -->|"imports"| node_analytics

click node_mobile_app "https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/App.tsx"
click node_customer_web "https://github.com/25ag1a6767-cyber/collegebit/blob/main/frontend/js/app.js"
click node_mobile_identity "https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/src/context/AuthContext.tsx"
click node_mobile_cart "https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/src/context/CartContext.tsx"
click node_mobile_client "https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/src/api/client.ts"
click node_fastapi "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/main.py"
click node_database_sessions "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/database.py"
click node_security "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/security.py"
click node_orders "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/orders_payments.py"
click node_common "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/common.py"
click node_staff_portal "https://github.com/25ag1a6767-cyber/collegebit/blob/main/frontend/js/staff-portal.js"
click node_admin_portal "https://github.com/25ag1a6767-cyber/collegebit/blob/main/frontend/js/admin-portal.js"
click node_analytics "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/analytics_bi.py"
click node_reporting "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/reporting_engine.py"
click node_ai_services "https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/ai_services.py"

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_customer,node_mobile_app,node_customer_web,node_mobile_identity,node_mobile_cart,node_mobile_client toneBlue
class node_asgi_operator,node_fastapi,node_database_sessions,node_postgres,node_security,node_orders,node_common,node_razorpay toneAmber
class node_staff_operator,node_staff_portal,node_administrator,node_admin_portal toneMint
class node_analytics,node_reporting,node_ai_services toneRose
```

## Components

### Customer experience

- **Customer**: actor
- [Mobile app](https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/App.tsx): customer application · `mobile/App.tsx`
- [Customer web/PWA](https://github.com/25ag1a6767-cyber/collegebit/blob/main/frontend/js/app.js): customer application · `frontend/js/app.js`
- [Mobile identity state](https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/src/context/AuthContext.tsx): client state · `mobile/src/context/AuthContext.tsx`
- [Mobile cart state](https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/src/context/CartContext.tsx): client state · `mobile/src/context/CartContext.tsx`
- [Mobile API/realtime client](https://github.com/25ag1a6767-cyber/collegebit/blob/main/mobile/src/api/client.ts): API client · `mobile/src/api/client.ts`

### Backend platform

- **ASGI server/operator**: operator
- [FastAPI routes](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/main.py): HTTP and WebSocket API · `backend/app/main.py`
- [Database sessions](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/database.py): database access · `backend/app/database.py`
- **PostgreSQL**: relational database
- [Authentication and authorization](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/security.py): security · `backend/app/security.py`
- [Orders and payments](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/orders_payments.py): domain service · `backend/app/modules/orders_payments.py`
- [Shared domain rules](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/common.py): domain service · `backend/app/modules/common.py`
- **Razorpay**: payment provider

### Staff and administration

- **Staff operator**: actor
- [Staff portal](https://github.com/25ag1a6767-cyber/collegebit/blob/main/frontend/js/staff-portal.js): staff interface · `frontend/js/staff-portal.js`
- **Canteen administrator**: actor
- [Admin portal](https://github.com/25ag1a6767-cyber/collegebit/blob/main/frontend/js/admin-portal.js): administration interface · `frontend/js/admin-portal.js`

### Analytics services

- [Analytics and BI](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/analytics_bi.py): analytics service · `backend/app/modules/analytics_bi.py`
- [Report generation](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/reporting_engine.py): reporting service · `backend/app/modules/reporting_engine.py`
- [AI services](https://github.com/25ag1a6767-cyber/collegebit/blob/main/backend/app/modules/ai_services.py): AI application service · `backend/app/modules/ai_services.py`

## Connections

- ASGI server/operator → FastAPI routes: serves (evidence: `README.md`)
- Customer → Mobile app: browses and orders (evidence: `README.md`)
- Customer → Customer web/PWA: uses (evidence: `README.md`)
- Mobile app → Mobile identity state: composes (evidence: `mobile/App.tsx`)
- Mobile app → Mobile cart state: composes (evidence: `mobile/App.tsx`)
- Mobile identity state → Mobile API/realtime client: calls API (evidence: `mobile/src/context/AuthContext.tsx`)
- Mobile cart state → Mobile API/realtime client: syncs cart and quotes (evidence: `mobile/src/context/CartContext.tsx`)
- Mobile API/realtime client → FastAPI routes: sends HTTP requests (evidence: `mobile/src/api/client.ts`)
- Mobile API/realtime client → FastAPI routes: connects by WebSocket (evidence: `mobile/src/api/client.ts`)
- FastAPI routes → Database sessions: uses sessions (evidence: `backend/app/main.py`)
- Database sessions → PostgreSQL: configures engine (evidence: `backend/app/database.py`)
- FastAPI routes → Authentication and authorization: uses security (evidence: `backend/app/main.py`)
- FastAPI routes → Orders and payments: imports (evidence: `backend/app/main.py`)
- Orders and payments → Shared domain rules: uses helpers (evidence: `backend/app/modules/orders_payments.py`)
- Orders and payments → Razorpay: handles payment (evidence: `README.md`)
- Staff operator → Staff portal: uses (evidence: `README.md`)
- Staff portal → FastAPI routes: uses backend · Inferred; not shown in the code that was read.
- Canteen administrator → Admin portal: uses (evidence: `README.md`)
- Admin portal → FastAPI routes: uses backend · Inferred; not shown in the code that was read.
- FastAPI routes → Analytics and BI: imports (evidence: `backend/app/main.py`)
- Report generation → Analytics and BI: imports (evidence: `backend/app/modules/reporting_engine.py`)
- AI services → Analytics and BI: imports (evidence: `backend/app/modules/ai_services.py`)