# shishirbaidya/cse311 architecture

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

- Interactive diagram: https://gitdiagram.com/shishirbaidya/cse311
- Repository: https://github.com/shishirbaidya/cse311

## Overview

1. **Overall shape**
   - This is a two-tier application: a Python backend API and a React/Vite frontend.
   - The frontend is organized around shopping workflows, user accounts, and an admin console.
   - The backend is organized by resource domain using router modules and a shared database/config/security layer.

2. **Backend entrypoint and core layers**
   - `backend/app/app.py` is the main application entrypoint.
   - `config.py` centralizes runtime configuration, and `database.py` is the shared database connection/access layer.
   - `services/` contains business logic that sits between routes and persistence, with `auth_service.py` being the clearest example.
   - `utils/` contains cross-cutting helpers such as security and upload handling.

3. **Backend API boundaries**
   - The backend is split into domain routers: `auth_router`, `user_router`, `orders_router`, `drinks_router`, `grocery_router`, `restaurant_router`, `admin_router`, `root_service_router`, and `upload.py`.
   - This suggests the API is segmented by business capability rather than by generic CRUD only.
   - The presence of separate store-type routers implies the product catalog is partitioned into multiple shop categories.

4. **Backend data and persistence**
   - `backend/app/SQL/sql1.sql` indicates a relational schema is part of the repo, likely used to initialize or document the database.
   - The application likely reads/writes users, products, carts/orders, and admin-managed entities through this schema.
   - `database.py` is the boundary between the API layer and the database, so it is a key node in the architecture diagram.

5. **Authentication and security flow**
   - Authentication is handled in the backend by `auth_router` plus `services/auth_service.py`.
   - `utils/security.py` is likely responsible for password hashing, token creation/validation, or other auth-related primitives.
   - On the frontend, `contexts/AuthContext.jsx` holds the current auth state, and `components/ProtectedRoute.jsx` guards private routes.
   - The auth boundary separates public browsing from logged-in profile, checkout, and admin features.

6. **File upload and static asset handling**
   - `backend/app/utils/upload.py`, `routers/upload.py`, and `backend/app/static/uploads/` form a dedicated upload pipeline.
   - This is important for item images or avatar/profile media.
   - The backend appears to store uploaded files locally and expose them through static serving rather than via an external object store.

7. **Frontend app structure**
   - The frontend is a React single-page app built with Vite (`vite.config.js`, `main.jsx`, `App.css`).
   - Navigation and page composition are split across `pages/`, `components/`, `profile/`, `admin/`, and category-specific folders like `grocery/`, `juices/`, and `restaurants/`.
   - `Layout.jsx`, `ShopLayout.jsx`, `Home.jsx`, `Shops.jsx`, `About.jsx`, `Checkout.jsx`, and `ErrorPage.jsx` define the top-level user experience flow.

8. **Frontend state and client-side orchestration**
   - `contexts/CartContext.jsx` manages shopping cart state across the app.
   - `contexts/AuthContext.jsx` manages login/session state and likely drives conditional rendering of protected areas.
   - This means the frontend is not just a view layer; it also owns important session and cart state before sending data to the backend.

9. **Shop/category features**
   - The storefront is split into multiple domain views: `DrinkHome.jsx`, `GroceryHome.jsx`, and `RestaurantHome.jsx`.
   - Reusable card components under `components/`, `grocery/components/`, `juices/components/`, and `restaurants/components/` are used to render product listings.
   - This suggests a catalog browsing flow where the frontend requests category-specific data from the corresponding backend routers.

10. **Profile and order lifecycle**
   - `profile/CurrentOrder.jsx`, `PreviousOrders.jsx`, `OrderCard.jsx`, and related components indicate a user account area focused on order tracking/history.
   - This aligns with the backend `orders_router` and `user_router`, which likely serve current order state, past orders, and profile details.
   - The architecture separates end-user order visibility from administrative order management.

11. **Admin subsystem**
   - `admin/AdminHome.jsx` and components like `AddItemForm.jsx`, `OrdersManager.jsx`, and `UsersTable.jsx` form a distinct admin dashboard.
   - The admin UI maps directly to backend management routes, especially `admin_router`, plus likely `orders_router` and `user_router`.
   - `AddItemForm` implies admins can create catalog entries, probably including uploads for item images.

12. **Client-server data flow**
   - Frontend API access is centralized in `src/services/api.js` and `src/services/auth.jsx`.
   - Typical flow is: user action in a page/component → local context state updates → API call via the services layer → backend router/service/database → updated UI state.
   - This keeps network concerns out of the page components and makes the frontend easier to diagram as presentation, state, and API layers.

13. **Notable repository boundary**
   - The `frontend/app/public/juice_gsap*` assets look like bundled static content from a design or animation source and are not part of the core application logic.
   - They matter only as static frontend assets; they do not change the backend/frontend architectural split.

Main entry points: [`backend/app/app.py`](https://github.com/shishirbaidya/cse311/blob/master/backend/app/app.py) (App entry), [`frontend/app/src/main.jsx`](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/main.jsx) (SPA shell), [`backend/app/database.py`](https://github.com/shishirbaidya/cse311/blob/master/backend/app/database.py) (Database), [`frontend/app/src/services/api.js`](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app["App entry<br/>Flask app<br/>[app.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_db[("Database<br/>persistence layer<br/>[database.py]")]
  node_backend_auth_router["Auth API<br/>router<br/>[auth_router.py]"]
  node_backend_user_router["User API<br/>router<br/>[user_router.py]"]
  node_backend_orders_router["Orders API<br/>router<br/>[orders_router.py]"]
  node_backend_catalog_routers["Catalog APIs<br/>routers"]
  node_backend_admin_router["Admin API<br/>router<br/>[admin_router.py]"]
  node_backend_root_router["Root API<br/>router"]
  node_backend_upload_router["Upload API<br/>router<br/>[upload.py]"]
  node_backend_auth_service["Auth service<br/>business logic<br/>[auth_service.py]"]
  node_backend_security["Security utils<br/>crypto/auth helpers<br/>[security.py]"]
  node_backend_upload_utils["Upload utils<br/>file handling<br/>[upload.py]"]
  node_backend_schema["SQL schema<br/>relational schema<br/>[sql1.sql]"]
  node_backend_static_uploads[("Static uploads<br/>file store")]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["SPA shell<br/>React/Vite app<br/>[main.jsx]"]
  node_frontend_layout["Layouts<br/>routing/layout<br/>[Layout.jsx]"]
  node_frontend_state(("App state<br/>context state<br/>[AuthContext.jsx]"))
  node_frontend_api["API client<br/>client services<br/>[api.js]"]
  node_frontend_public["Public pages<br/>views<br/>[Home.jsx]"]
  node_frontend_catalog["Storefronts<br/>domain views<br/>[GroceryHome.jsx]"]
  node_frontend_profile["Profile area<br/>account views<br/>[Profile.jsx]"]
  node_frontend_admin["Admin console<br/>management UI<br/>[AdminHome.jsx]"]
end

node_backend_app -->|"reads"| node_backend_config
node_backend_app -->|"connects"| node_backend_db
node_backend_app -->|"registers"| node_backend_auth_router
node_backend_app -->|"registers"| node_backend_user_router
node_backend_app -->|"registers"| node_backend_orders_router
node_backend_app -->|"registers"| node_backend_catalog_routers
node_backend_app -->|"registers"| node_backend_admin_router
node_backend_app -->|"registers"| node_backend_root_router
node_backend_app -->|"registers"| node_backend_upload_router
node_backend_auth_router -->|"uses"| node_backend_auth_service
node_backend_auth_service -->|"uses"| node_backend_security
node_backend_auth_service -->|"persists"| node_backend_db
node_backend_user_router -->|"queries"| node_backend_db
node_backend_orders_router -->|"queries"| node_backend_db
node_backend_catalog_routers -->|"queries"| node_backend_db
node_backend_admin_router -->|"mutates"| node_backend_db
node_backend_upload_router -->|"uses"| node_backend_upload_utils
node_backend_upload_utils -->|"stores"| node_backend_static_uploads
node_backend_schema -.->|"defines"| node_backend_db
node_frontend_app -->|"composes"| node_frontend_layout
node_frontend_app -->|"wraps"| node_frontend_state
node_frontend_app -->|"routes to"| node_frontend_public
node_frontend_app -->|"routes to"| node_frontend_catalog
node_frontend_app -->|"routes to"| node_frontend_profile
node_frontend_app -->|"routes to"| node_frontend_admin
node_frontend_state -->|"calls"| node_frontend_api
node_frontend_public -->|"fetches"| node_frontend_api
node_frontend_catalog -->|"fetches"| node_frontend_api
node_frontend_profile -->|"fetches"| node_frontend_api
node_frontend_admin -->|"mutates"| node_frontend_api
node_frontend_state -.->|"authenticates"| node_backend_auth_router
node_frontend_public -.->|"browses"| node_backend_catalog_routers
node_frontend_profile -.->|"tracks"| node_backend_orders_router
node_frontend_admin -.->|"manages"| node_backend_admin_router
node_frontend_admin -.->|"uploads"| node_backend_upload_router

click node_backend_app "https://github.com/shishirbaidya/cse311/blob/master/backend/app/app.py"
click node_backend_config "https://github.com/shishirbaidya/cse311/blob/master/backend/app/config.py"
click node_backend_db "https://github.com/shishirbaidya/cse311/blob/master/backend/app/database.py"
click node_backend_auth_router "https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/auth_router.py"
click node_backend_user_router "https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/user_router.py"
click node_backend_orders_router "https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/orders_router.py"
click node_backend_admin_router "https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/admin_router.py"
click node_backend_root_router "https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/root_service_router.py"
click node_backend_upload_router "https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/upload.py"
click node_backend_auth_service "https://github.com/shishirbaidya/cse311/blob/master/backend/app/services/auth_service.py"
click node_backend_security "https://github.com/shishirbaidya/cse311/blob/master/backend/app/utils/security.py"
click node_backend_upload_utils "https://github.com/shishirbaidya/cse311/blob/master/backend/app/utils/upload.py"
click node_backend_schema "https://github.com/shishirbaidya/cse311/blob/master/backend/app/SQL/sql1.sql"
click node_backend_static_uploads "https://github.com/shishirbaidya/cse311/tree/master/backend/app/static/uploads"
click node_frontend_app "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/main.jsx"
click node_frontend_layout "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/Layout.jsx"
click node_frontend_state "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/contexts/AuthContext.jsx"
click node_frontend_api "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/services/api.js"
click node_frontend_public "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/pages/Home.jsx"
click node_frontend_catalog "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/grocery/GroceryHome.jsx"
click node_frontend_profile "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/profile/Profile.jsx"
click node_frontend_admin "https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/admin/AdminHome.jsx"

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_backend_app,node_backend_config,node_backend_db,node_backend_auth_router,node_backend_user_router,node_backend_orders_router,node_backend_catalog_routers,node_backend_admin_router,node_backend_root_router,node_backend_upload_router,node_backend_auth_service,node_backend_security,node_backend_upload_utils,node_backend_schema,node_backend_static_uploads toneBlue
class node_frontend_app,node_frontend_layout,node_frontend_state,node_frontend_api,node_frontend_public,node_frontend_catalog,node_frontend_profile,node_frontend_admin toneAmber
```

## Components

### Backend

Python API, routers, services, persistence, and upload/static handling.

- [App entry](https://github.com/shishirbaidya/cse311/blob/master/backend/app/app.py): Flask app · Main backend application bootstrap and router wiring. · `backend/app/app.py`
- [Config](https://github.com/shishirbaidya/cse311/blob/master/backend/app/config.py): runtime config · Central runtime settings and environment-driven configuration. · `backend/app/config.py`
- [Database](https://github.com/shishirbaidya/cse311/blob/master/backend/app/database.py): persistence layer · Shared database access boundary used by routers and services. · `backend/app/database.py`
- [Auth API](https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/auth_router.py): router · Login, registration, and authentication endpoints. · `backend/app/routers/auth_router.py`
- [User API](https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/user_router.py): router · User profile and account endpoints. · `backend/app/routers/user_router.py`
- [Orders API](https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/orders_router.py): router · Current and historical order endpoints. · `backend/app/routers/orders_router.py`
- **Catalog APIs**: routers · Category-specific product and browsing endpoints for drinks, grocery, and restaurants.
- [Admin API](https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/admin_router.py): router · Administrative management endpoints for users, orders, and catalog data. · `backend/app/routers/admin_router.py`
- [Root API](https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/root_service_router.py): router · Shared or top-level service endpoints. · `backend/app/routers/root_service_router.py`
- [Upload API](https://github.com/shishirbaidya/cse311/blob/master/backend/app/routers/upload.py): router · File upload endpoints for images and other media. · `backend/app/routers/upload.py`
- [Auth service](https://github.com/shishirbaidya/cse311/blob/master/backend/app/services/auth_service.py): business logic · Authentication and account logic between auth routes and persistence. · `backend/app/services/auth_service.py`
- [Security utils](https://github.com/shishirbaidya/cse311/blob/master/backend/app/utils/security.py): crypto/auth helpers · Cross-cutting password, token, or security primitives. · `backend/app/utils/security.py`
- [Upload utils](https://github.com/shishirbaidya/cse311/blob/master/backend/app/utils/upload.py): file handling · Helpers for storing and handling uploaded files locally. · `backend/app/utils/upload.py`
- [SQL schema](https://github.com/shishirbaidya/cse311/blob/master/backend/app/SQL/sql1.sql): relational schema · Database schema and initialization script. · `backend/app/SQL/sql1.sql`
- [Static uploads](https://github.com/shishirbaidya/cse311/tree/master/backend/app/static/uploads): file store · Local storage for uploaded media served by the backend. · `backend/app/static/uploads`

### Frontend

React/Vite SPA with shared state, routes, and domain screens.

- [SPA shell](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/main.jsx): React/Vite app · Frontend application entry and overall shell. · `frontend/app/src/main.jsx`
- [Layouts](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/Layout.jsx): routing/layout · Top-level page composition and shop layout structure. · `frontend/app/src/Layout.jsx`
- [App state](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/contexts/AuthContext.jsx): context state · Global auth and cart state shared across the frontend. · `frontend/app/src/contexts/AuthContext.jsx`
- [API client](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/services/api.js): client services · Centralized client-side HTTP access and auth helpers. · `frontend/app/src/services/api.js`
- [Public pages](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/pages/Home.jsx): views · Home, shop discovery, about, checkout, and error screens. · `frontend/app/src/pages/Home.jsx`
- [Storefronts](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/grocery/GroceryHome.jsx): domain views · Category storefronts for groceries, drinks, and restaurants. · `frontend/app/src/grocery/GroceryHome.jsx`
- [Profile area](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/profile/Profile.jsx): account views · User profile, current order, and past order screens. · `frontend/app/src/profile/Profile.jsx`
- [Admin console](https://github.com/shishirbaidya/cse311/blob/master/frontend/app/src/admin/AdminHome.jsx): management UI · Admin dashboard and catalog/order/user management screens. · `frontend/app/src/admin/AdminHome.jsx`

## Connections

- App entry → Config: reads · Loads runtime settings during startup.
- App entry → Database: connects · Initializes shared database access.
- App entry → Auth API: registers · Mounts auth endpoints into the app.
- App entry → User API: registers · Mounts user endpoints into the app.
- App entry → Orders API: registers · Mounts order endpoints into the app.
- App entry → Catalog APIs: registers · Mounts category-specific catalog routers.
- App entry → Admin API: registers · Mounts admin endpoints into the app.
- App entry → Root API: registers · Mounts shared or root service endpoints.
- App entry → Upload API: registers · Mounts upload endpoints into the app.
- Auth API → Auth service: uses · Delegates authentication logic to service layer.
- Auth service → Security utils: uses · Relies on auth/security primitives.
- Auth service → Database: persists · Reads and writes identity data through the database layer.
- User API → Database: queries · Accesses user records through shared persistence.
- Orders API → Database: queries · Accesses order state through shared persistence.
- Catalog APIs → Database: queries · Serves category catalog data from persistence.
- Admin API → Database: mutates · Performs administrative writes against persisted data.
- Upload API → Upload utils: uses · Delegates file handling to upload helpers.
- Upload utils → Static uploads: stores · Writes uploaded files to local static storage.
- SQL schema → Database: defines · Provides the relational structure used by the app.
- SPA shell → Layouts: composes · Builds the app around route/layout structure.
- SPA shell → App state: wraps · Provides global context for auth and cart state.
- SPA shell → Public pages: routes to · Serves public landing and checkout-related pages.
- SPA shell → Storefronts: routes to · Serves category storefront experiences.
- SPA shell → Profile area: routes to · Serves authenticated account and order pages.
- SPA shell → Admin console: routes to · Serves admin dashboard views.
- App state → API client: calls · Uses the API layer for server communication.
- Public pages → API client: fetches · Loads data and submits actions through the client API.
- Storefronts → API client: fetches · Requests category data through the client API.
- Profile area → API client: fetches · Loads profile and order data through the client API.
- Admin console → API client: mutates · Sends admin actions through the client API.
- App state → Auth API: authenticates · Login/session state is validated against backend auth endpoints.
- Public pages → Catalog APIs: browses · Public storefront views consume category APIs.
- Profile area → Orders API: tracks · Profile and order views depend on order endpoints.
- Admin console → Admin API: manages · Admin UI maps to backend management endpoints.
- Admin console → Upload API: uploads · Admin item creation can attach media through upload endpoints.