25ag1a6767-cyber/collegebit

<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>