# vengurlekarmayuresh/cafe architecture

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

- Interactive diagram: https://gitdiagram.com/vengurlekarmayuresh/cafe
- Repository: https://github.com/vengurlekarmayuresh/cafe

## Overview

1. This repository is a two-tier full-stack application for a gated-society ordering and POS workflow: a Node/Express backend API and a React/Vite frontend. The system is split by user role into customer ordering, staff operations/POS, and admin oversight.

2. The backend is the application core. `backend/src/index.js` is the server entrypoint, with HTTP routes organized under `routes/` and business logic in `controllers/`. The structure suggests a fairly standard API layering: routes handle URL boundaries, controllers orchestrate use cases, and models represent persistence.

3. Persistence is PostgreSQL through Sequelize. The domain model is centered around `User`, `Product`, `Order`, `OrderItem`, `Review`, and `Notification`, which indicates the main data flow: users browse products, create orders, order items capture line-level contents, reviews attach to purchases/products, and notifications track operational events.

4. Authentication and authorization are first-class concerns. JWT helpers, `auth` middleware, and `rbac` middleware enforce identity and role-based access control across the API. The README’s approval/blocking flows and the `adminController` indicate that user lifecycle is not just login-based; some users are gated by admin approval before full access.

5. The order subsystem is the main transactional boundary. `orderController` and `/routes/orders` support both customer online orders and staff-created onsite POS orders. The documented state machine is important for diagrams: online orders move through pending/accepted/delivered or rejected, while POS orders are created in an already accepted/paid state.

6. Product management is a separate operational subsystem. `productController` and `/routes/products` expose browse/create/update/toggle-delete behavior with role restrictions. This is likely the shared catalog used by both customers and staff POS screens, so product availability changes affect both ordering channels.

7. Real-time feedback is handled with notifications. The backend includes `notificationController`, `Notification` model, and a Firebase config file, while the README calls out Socket.io for real-time notifications. The front end also has a `NewOrderAlert` component, so the architecture includes asynchronous push-style updates for staff when new orders arrive.

8. Media and integration hooks are present but secondary. `utils/cloudinary.js` suggests external image storage for product/media assets, and Firebase config on both backend and frontend suggests a messaging or notification integration point. These are supporting services rather than the primary system of record.

9. The frontend is a role-driven SPA built with React, Tailwind, and Vite. `AuthContext` holds session state, `ProtectedRoute` enforces access on the client side, and `api.js` centralizes backend calls. Routing is organized by audience: public auth pages, customer pages, staff pages, and admin pages.

10. The customer UI is focused on browsing and self-service ordering. Pages like `Home`, `Menu`, `Cart`, `Orders`, and `Profile`, plus components such as `InvoiceModal` and `ConfirmationModal`, show a flow from product discovery to checkout, order tracking, and post-order interaction.

11. The staff UI is an operational console. `staff/Dashboard`, `POS`, and `Products` indicate that staff can both process walk-in sales and manage the catalog. The presence of `NewOrderAlert` and order-management backend endpoints reinforces that staff are the live execution layer for incoming customer orders.

12. The admin UI is supervisory rather than transactional. `admin/Dashboard`, `Users`, `Orders`, and `Customers` align with approval workflows, account moderation, and reporting/analytics. The backend’s `admin` routes support these boundaries with user approval/blocking and revenue/order aggregation.

13. Bootstrap and lifecycle support are explicit. `setup.sql` and `scripts/seed.js` indicate the database can be initialized and seeded independently of the runtime app, which is useful for local development or demo environments. Frontend deployment configuration (`vercel.json`) suggests the UI is intended for static hosting, while the API remains a separate service.

14. For an architecture diagram, the key flows are: browser user authenticates against the API, receives JWT-based session state, reads/writes domain data through the REST endpoints, and receives live order notifications through the realtime channel. PostgreSQL is the system of record, while the frontend is a role-aware presentation layer over the backend domain services.

Main entry points: [`frontend/src/utils/api.js`](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/utils/api.js) (API client), [`backend/src/models/index.js`](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/models/index.js) (Domain models), [`backend/src/index.js`](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/index.js) (Server entry), [`backend/src/routes/admin.js`](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/admin.js) (Admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend API"]
  node_backend_entry(("Server entry<br/>Express bootstrap<br/>[index.js]"))
  node_auth_routes["Auth API<br/>route layer<br/>[auth.js]"]
  node_auth_controller["Auth logic<br/>controller<br/>[authController.js]"]
  node_admin_routes["Admin API<br/>route layer<br/>[admin.js]"]
  node_admin_controller["Admin logic<br/>controller<br/>[adminController.js]"]
  node_product_routes["Product API<br/>route layer<br/>[products.js]"]
  node_product_controller["Product logic<br/>controller"]
  node_order_routes["Order API<br/>route layer<br/>[orders.js]"]
  node_order_controller["Order logic<br/>controller<br/>[orderController.js]"]
  node_notification_routes["Notif API<br/>route layer<br/>[notifications.js]"]
  node_notification_controller["Notif logic<br/>controller"]
  node_auth_mw["Auth guard<br/>middleware<br/>[auth.js]"]
  node_rbac_mw["Role guard<br/>middleware<br/>[rbac.js]"]
  node_models[("Domain models<br/>Sequelize models<br/>[index.js]")]
end

subgraph group_frontend["Frontend SPA"]
  node_frontend_app(("SPA shell<br/>React app<br/>[App.jsx]"))
  node_auth_context(("Session state<br/>React context<br/>[AuthContext.jsx]"))
  node_protected_route["Route gate<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_api_client["API client<br/>HTTP client<br/>[api.js]"]
  node_customer_pages["Customer UI<br/>page set<br/>[Home.jsx]"]
  node_staff_pages["Staff UI<br/>page set<br/>[Dashboard.jsx]"]
  node_admin_pages["Admin UI<br/>page set<br/>[Dashboard.jsx]"]
  node_realtime_alert["Order alerts<br/>UI component<br/>[NewOrderAlert.jsx]"]
end

subgraph group_data["Data & Services"]
  node_postgres[("PostgreSQL<br/>database<br/>[setup.sql]")]
  node_firebase{{"Firebase<br/>integration<br/>[firebase.js]"}}
  node_cloudinary{{"Cloudinary<br/>media service<br/>[cloudinary.js]"}}
  node_seed_setup["Seed setup<br/>bootstrap script<br/>[seed.js]"]
end

node_backend_entry -->|"mounts"| node_auth_routes
node_backend_entry -->|"mounts"| node_admin_routes
node_backend_entry -->|"mounts"| node_product_routes
node_backend_entry -->|"mounts"| node_order_routes
node_backend_entry -->|"mounts"| node_notification_routes
node_auth_routes -->|"uses"| node_auth_controller
node_admin_routes -->|"uses"| node_admin_controller
node_product_routes -->|"uses"| node_product_controller
node_order_routes -->|"uses"| node_order_controller
node_notification_routes -->|"uses"| node_notification_controller
node_auth_controller -->|"reads/writes"| node_models
node_admin_controller -->|"reads/writes"| node_models
node_product_controller -->|"reads/writes"| node_models
node_order_controller -->|"reads/writes"| node_models
node_notification_controller -->|"reads/writes"| node_models
node_auth_routes -.->|"protects"| node_auth_mw
node_admin_routes -.->|"protects"| node_auth_mw
node_admin_routes -.->|"restricts"| node_rbac_mw
node_product_routes -.->|"protects"| node_auth_mw
node_product_routes -.->|"restricts"| node_rbac_mw
node_order_routes -.->|"protects"| node_auth_mw
node_notification_routes -.->|"protects"| node_auth_mw
node_notification_routes -.->|"restricts"| node_rbac_mw
node_frontend_app -->|"holds"| node_auth_context
node_frontend_app -->|"guards"| node_protected_route
node_frontend_app -->|"calls"| node_api_client
node_protected_route -->|"checks"| node_auth_context
node_customer_pages -->|"calls"| node_api_client
node_staff_pages -->|"calls"| node_api_client
node_admin_pages -->|"calls"| node_api_client
node_staff_pages -->|"contains"| node_realtime_alert
node_api_client -->|"requests"| node_auth_routes
node_api_client -->|"requests"| node_product_routes
node_api_client -->|"requests"| node_order_routes
node_api_client -->|"requests"| node_admin_routes
node_api_client -->|"requests"| node_notification_routes
node_models -->|"persists to"| node_postgres
node_notification_controller -.->|"integrates"| node_firebase
node_realtime_alert -.->|"integrates"| node_firebase
node_product_controller -.->|"uploads"| node_cloudinary
node_seed_setup -->|"initializes"| node_postgres

click node_backend_entry "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/index.js"
click node_auth_routes "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/auth.js"
click node_auth_controller "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/authController.js"
click node_admin_routes "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/admin.js"
click node_admin_controller "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/adminController.js"
click node_product_routes "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/products.js"
click node_product_controller "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/productController.js"
click node_order_routes "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/orders.js"
click node_order_controller "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/orderController.js"
click node_notification_routes "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/notifications.js"
click node_notification_controller "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/notificationController.js"
click node_auth_mw "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/middleware/auth.js"
click node_rbac_mw "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/middleware/rbac.js"
click node_models "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/models/index.js"
click node_frontend_app "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/context/AuthContext.jsx"
click node_protected_route "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/utils/ProtectedRoute.jsx"
click node_api_client "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/utils/api.js"
click node_customer_pages "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/pages/customer/Home.jsx"
click node_staff_pages "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/pages/staff/Dashboard.jsx"
click node_admin_pages "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/pages/admin/Dashboard.jsx"
click node_realtime_alert "https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/components/NewOrderAlert.jsx"
click node_postgres "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/setup.sql"
click node_firebase "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/config/firebase.js"
click node_cloudinary "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/utils/cloudinary.js"
click node_seed_setup "https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/scripts/seed.js"

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_entry,node_auth_routes,node_auth_controller,node_admin_routes,node_admin_controller,node_product_routes,node_product_controller,node_order_routes,node_order_controller,node_notification_routes,node_notification_controller,node_auth_mw,node_rbac_mw,node_models toneBlue
class node_frontend_app,node_auth_context,node_protected_route,node_api_client,node_customer_pages,node_staff_pages,node_admin_pages,node_realtime_alert toneAmber
class node_postgres,node_firebase,node_cloudinary,node_seed_setup toneMint
```

## Components

### Backend API

Node/Express service that owns auth, catalog, orders, admin workflows, and notifications.

- [Server entry](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/index.js): Express bootstrap · Starts the API server and wires the application runtime. · `backend/src/index.js`
- [Auth API](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/auth.js): route layer · Login, registration, and session-facing auth endpoints. · `backend/src/routes/auth.js`
- [Auth logic](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/authController.js): controller · Coordinates authentication and account onboarding flows. · `backend/src/controllers/authController.js`
- [Admin API](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/admin.js): route layer · Approval, moderation, and oversight endpoints. · `backend/src/routes/admin.js`
- [Admin logic](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/adminController.js): controller · Handles user approval, blocking, and administrative reporting flows. · `backend/src/controllers/adminController.js`
- [Product API](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/products.js): route layer · Catalog endpoints for browsing and staff management. · `backend/src/routes/products.js`
- [Product logic](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/productController.js): controller · Implements product create, update, toggle, and browse behavior. · `backend/src/controllers/productController.js`
- [Order API](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/orders.js): route layer · Customer and staff order endpoints. · `backend/src/routes/orders.js`
- [Order logic](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/orderController.js): controller · Coordinates online orders, POS orders, and order state transitions. · `backend/src/controllers/orderController.js`
- [Notif API](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/routes/notifications.js): route layer · Notification endpoints used by the live order workflow. · `backend/src/routes/notifications.js`
- [Notif logic](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/controllers/notificationController.js): controller · Creates and serves notifications for operational updates. · `backend/src/controllers/notificationController.js`
- [Auth guard](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/middleware/auth.js): middleware · Verifies JWT identity on protected API requests. · `backend/src/middleware/auth.js`
- [Role guard](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/middleware/rbac.js): middleware · Enforces role-based access for customer, staff, and admin actions. · `backend/src/middleware/rbac.js`
- [Domain models](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/models/index.js): Sequelize models · Persistence layer for users, products, orders, items, reviews, and notifications. · `backend/src/models/index.js`

### Frontend SPA

React/Vite client organized by customer, staff, and admin roles.

- [SPA shell](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/App.jsx): React app · Top-level client shell, routing, and presentation composition. · `frontend/src/App.jsx`
- [Session state](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/context/AuthContext.jsx): React context · Holds user session, role, and auth state in the client. · `frontend/src/context/AuthContext.jsx`
- [Route gate](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/utils/ProtectedRoute.jsx): route guard · Client-side access control for authenticated and role-scoped pages. · `frontend/src/utils/ProtectedRoute.jsx`
- [API client](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/utils/api.js): HTTP client · Centralized frontend entry for backend requests. · `frontend/src/utils/api.js`
- [Customer UI](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/pages/customer/Home.jsx): page set · Browsing, cart, orders, and profile experience for end customers. · `frontend/src/pages/customer/Home.jsx`
- [Staff UI](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/pages/staff/Dashboard.jsx): page set · Operational console for POS, dashboard, and catalog handling. · `frontend/src/pages/staff/Dashboard.jsx`
- [Admin UI](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/pages/admin/Dashboard.jsx): page set · Supervisory pages for users, customers, orders, and reporting. · `frontend/src/pages/admin/Dashboard.jsx`
- [Order alerts](https://github.com/vengurlekarmayuresh/cafe/blob/main/frontend/src/components/NewOrderAlert.jsx): UI component · Live notification component used to surface new orders to staff. · `frontend/src/components/NewOrderAlert.jsx`

### Data & Services

Persistent storage and external integrations used by the app.

- [PostgreSQL](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/setup.sql): database · System of record for application data and transactional state. · `backend/setup.sql`
- [Firebase](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/config/firebase.js): integration · Messaging/notification integration point used by backend and frontend. · `backend/src/config/firebase.js`
- [Cloudinary](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/utils/cloudinary.js): media service · External image storage for product and media assets. · `backend/src/utils/cloudinary.js`
- [Seed setup](https://github.com/vengurlekarmayuresh/cafe/blob/main/backend/src/scripts/seed.js): bootstrap script · Initial database schema and seed data for local or demo environments. · `backend/src/scripts/seed.js`

## Connections

- Server entry → Auth API: mounts · Registers authentication endpoints on the server.
- Server entry → Admin API: mounts · Registers administrative endpoints on the server.
- Server entry → Product API: mounts · Registers catalog endpoints on the server.
- Server entry → Order API: mounts · Registers order endpoints on the server.
- Server entry → Notif API: mounts · Registers notification endpoints on the server.
- Auth API → Auth logic: uses · Routes delegate auth use cases to controller logic.
- Admin API → Admin logic: uses · Routes delegate admin workflows to controller logic.
- Product API → Product logic: uses · Routes delegate catalog actions to controller logic.
- Order API → Order logic: uses · Routes delegate ordering actions to controller logic.
- Notif API → Notif logic: uses · Routes delegate notification actions to controller logic.
- Auth logic → Domain models: reads/writes · Auth flows persist and load user records.
- Admin logic → Domain models: reads/writes · Admin workflows update user and order state.
- Product logic → Domain models: reads/writes · Catalog operations persist product data.
- Order logic → Domain models: reads/writes · Order workflows persist orders and line items.
- Notif logic → Domain models: reads/writes · Notification workflows persist event state.
- Auth API → Auth guard: protects · Protected auth-adjacent paths use JWT verification.
- Admin API → Auth guard: protects · Admin paths require authenticated users.
- Admin API → Role guard: restricts · Admin paths are role-restricted.
- Product API → Auth guard: protects · Catalog mutations require authentication.
- Product API → Role guard: restricts · Write operations are role-restricted.
- Order API → Auth guard: protects · Order operations require authenticated users.
- Notif API → Auth guard: protects · Notification access is authenticated.
- Notif API → Role guard: restricts · Operational notification actions are role-scoped.
- SPA shell → Session state: holds · Client shell uses shared session state.
- SPA shell → Route gate: guards · Client routing is gated by auth and role checks.
- SPA shell → API client: calls · UI uses a centralized backend API client.
- Route gate → Session state: checks · Route gating reads session and role state.
- Customer UI → API client: calls · Customer screens load products, orders, and profile data.
- Staff UI → API client: calls · Staff screens interact with POS, product, and order endpoints.
- Admin UI → API client: calls · Admin screens interact with oversight endpoints.
- Staff UI → Order alerts: contains · Staff console surfaces live incoming order alerts.
- API client → Auth API: requests · Frontend auth flows talk to the auth API.
- API client → Product API: requests · Frontend catalog views and edits hit the product API.
- API client → Order API: requests · Frontend order flows hit the order API.
- API client → Admin API: requests · Frontend admin screens hit oversight APIs.
- API client → Notif API: requests · Frontend notification views hit the notification API.
- Domain models → PostgreSQL: persists to · Sequelize stores domain data in PostgreSQL.
- Notif logic → Firebase: integrates · Backend notification flows can use Firebase as an external channel.
- Order alerts → Firebase: integrates · Client alerting is aligned with Firebase-backed messaging.
- Product logic → Cloudinary: uploads · Product media may be stored in external image storage.
- Seed setup → PostgreSQL: initializes · Schema and seed data prepare the database.