# utsoft7/pos-system architecture

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

- Interactive diagram: https://gitdiagram.com/utsoft7/pos-system
- Repository: https://github.com/utsoft7/pos-system

## Overview

1. **System shape**
   - This is a classic 3-tier restaurant POS: a **React frontend**, an **Express/Node API**, and a **MongoDB/Mongoose data layer**.
   - The app is containerized with **Docker / Docker Compose**, and the frontend includes an **Nginx** config for production serving.

2. **Frontend boundary**
   - The frontend is a **Vite React app** organized by feature area: auth, dashboard, home, menu, kitchen, orders, tables, invoice, and shared UI.
   - `src/pages` acts as the route-level shell, while `src/components/*` contains the domain screens and widgets.

3. **Client state and server-state split**
   - **Redux Toolkit** is used for local/global app state: `cart`, `customer`, and `user`.
   - Server interaction is handled separately through `src/https` (Axios wrapper) and `src/hooks/useLoadData.js`, suggesting cached/query-style fetching for backend data.

4. **User-facing workflow**
   - The main operational flow is: **authenticate → select table → build cart → place order → generate KOT/invoice → take payment**.
   - The frontend has dedicated UI pieces for each step: menu cart info, customer info, bill/invoice, kitchen ticket, table cards, and order cards.

5. **Backend API layout**
   - The backend is structured conventionally: **routes → controllers → models**, with each business area separated into its own module.
   - Routes exist for **users, tables, orders, and payments**, each mapped to a corresponding controller.

6. **Domain model boundaries**
   - Mongo collections are represented by Mongoose models for **users, tables, orders, payments, KOTs, and counters**.
   - The presence of a **counter model** suggests sequence generation for order/KOT/invoice numbering, which is important for POS-style records.

7. **Authentication and request protection**
   - Authentication is JWT-based, with a dedicated **token verification middleware** guarding protected backend routes.
   - User registration/login lives in the auth components on the frontend and user controller/route on the backend, with bcrypt implied by the README for password hashing.

8. **Order, kitchen, and billing flow**
   - Orders are a central backend entity and appear to feed both **kitchen tickets** and **billing/invoice generation**.
   - The separate KOT model indicates kitchen dispatch is treated as its own record, not just a UI artifact.

9. **Payments**
   - Payment handling is isolated behind the payment route/controller and likely records transaction state in the database.
   - The README indicates support for both **cash** and **Razorpay** online payments, so payment is a distinct integration boundary rather than being embedded in order creation.

10. **Tables and occupancy management**
   - Table state is managed as first-class data, with the UI showing **Booked** vs **Available** status.
   - This is likely updated by order lifecycle events and used to drive the floor/table selection experience.

11. **Dashboard and analytics**
   - The dashboard aggregates operational metrics like **earnings, recent orders, and daily performance**.
   - Frontend dashboard components suggest the API exposes summary endpoints or combined read operations for dashboard cards and recent activity lists.

12. **Infrastructure and deployment**
   - The repository is designed to run as separate containers for frontend and backend, with Compose coordinating the stack.
   - The frontend’s Nginx setup indicates production deployment behind a static web server, while the backend runs as an API service connected to MongoDB.

Main entry points: [`frontend/src/App.jsx`](https://github.com/utsoft7/pos-system/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/https/axiosWrapper.js`](https://github.com/utsoft7/pos-system/blob/main/frontend/src/https/axiosWrapper.js) (API client), [`backend/server.js`](https://github.com/utsoft7/pos-system/blob/main/backend/server.js) (API server), [`backend/models/orderModel.js`](https://github.com/utsoft7/pos-system/blob/main/backend/models/orderModel.js) (Data models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>Vite React shell<br/>[App.jsx]"]
  node_frontend_pages["Pages<br/>[index.js]"]
  node_frontend_auth["Auth UI<br/>Auth components<br/>[Login.jsx]"]
  node_frontend_dashboard["Dashboard<br/>[Metrics.jsx]"]
  node_frontend_home["Home ops<br/>Home widgets<br/>[Greetings.jsx]"]
  node_frontend_menu["Menu flow<br/>Ordering UI<br/>[MenuContainer.jsx]"]
  node_frontend_kitchen["Kitchen ticket<br/>Kitchen UI<br/>[KitchenTicket.jsx]"]
  node_frontend_tables["Tables<br/>Floor plan UI<br/>[TableCard.jsx]"]
  node_frontend_orders["Orders<br/>Order UI<br/>[OrderCard.jsx]"]
  node_frontend_invoice["Invoice<br/>Billing UI<br/>[Invoice.jsx]"]
  node_frontend_state["Redux state<br/>Client state<br/>[store.js]"]
  node_frontend_data["API client<br/>HTTP access<br/>[axiosWrapper.js]"]
end

subgraph group_backend["Backend"]
  node_backend_server["API server<br/>Express app<br/>[server.js]"]
  node_backend_auth["Users<br/>Auth controller<br/>[userController.js]"]
  node_backend_orders["Orders API<br/>Order module<br/>[orderController.js]"]
  node_backend_tables["Tables API<br/>Table module<br/>[tableController.js]"]
  node_backend_payments["Payments API<br/>Payment module"]
  node_backend_models[("Data models<br/>Mongoose models<br/>[orderModel.js]")]
  node_backend_middleware["Auth guard<br/>JWT middleware"]
end

subgraph group_infra["Infrastructure"]
  node_infra_compose["Compose stack<br/>Container orchestration<br/>[docker-compose.yml]"]
  node_infra_nginx["Nginx serving<br/>Static web server<br/>[nginx.conf]"]
end

node_frontend_pages -->|"renders"| node_frontend_app
node_frontend_app -->|"uses"| node_frontend_auth
node_frontend_app -->|"uses"| node_frontend_dashboard
node_frontend_app -->|"uses"| node_frontend_home
node_frontend_app -->|"uses"| node_frontend_menu
node_frontend_app -->|"uses"| node_frontend_kitchen
node_frontend_app -->|"uses"| node_frontend_tables
node_frontend_app -->|"uses"| node_frontend_orders
node_frontend_app -->|"uses"| node_frontend_invoice
node_frontend_menu -->|"updates"| node_frontend_state
node_frontend_auth -->|"updates"| node_frontend_state
node_frontend_dashboard -->|"loads"| node_frontend_data
node_frontend_home -->|"loads"| node_frontend_data
node_frontend_menu -->|"loads"| node_frontend_data
node_frontend_orders -->|"loads"| node_frontend_data
node_frontend_tables -->|"loads"| node_frontend_data
node_frontend_invoice -->|"loads"| node_frontend_data
node_frontend_data -->|"calls"| node_backend_server
node_backend_server -->|"protects with"| node_backend_middleware
node_backend_server -->|"routes to"| node_backend_auth
node_backend_server -->|"routes to"| node_backend_orders
node_backend_server -->|"routes to"| node_backend_tables
node_backend_server -->|"routes to"| node_backend_payments
node_backend_auth -->|"reads/writes"| node_backend_models
node_backend_orders -->|"reads/writes"| node_backend_models
node_backend_tables -->|"reads/writes"| node_backend_models
node_backend_payments -->|"reads/writes"| node_backend_models
node_backend_orders -->|"triggers"| node_backend_payments
node_backend_orders -->|"updates"| node_backend_tables
node_infra_compose -->|"runs"| node_backend_server
node_infra_compose -->|"connects"| node_frontend_data
node_infra_compose -->|"provides db"| node_backend_models
node_infra_nginx -->|"serves"| node_frontend_app

click node_frontend_app "https://github.com/utsoft7/pos-system/blob/main/frontend/src/App.jsx"
click node_frontend_pages "https://github.com/utsoft7/pos-system/blob/main/frontend/src/pages/index.js"
click node_frontend_auth "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/auth/Login.jsx"
click node_frontend_dashboard "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/dashboard/Metrics.jsx"
click node_frontend_home "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/home/Greetings.jsx"
click node_frontend_menu "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/menu/MenuContainer.jsx"
click node_frontend_kitchen "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/kitchen/KitchenTicket.jsx"
click node_frontend_tables "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/tables/TableCard.jsx"
click node_frontend_orders "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/orders/OrderCard.jsx"
click node_frontend_invoice "https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/invoice/Invoice.jsx"
click node_frontend_state "https://github.com/utsoft7/pos-system/blob/main/frontend/src/redux/store.js"
click node_frontend_data "https://github.com/utsoft7/pos-system/blob/main/frontend/src/https/axiosWrapper.js"
click node_backend_server "https://github.com/utsoft7/pos-system/blob/main/backend/server.js"
click node_backend_auth "https://github.com/utsoft7/pos-system/blob/main/backend/controllers/userController.js"
click node_backend_orders "https://github.com/utsoft7/pos-system/blob/main/backend/controllers/orderController.js"
click node_backend_tables "https://github.com/utsoft7/pos-system/blob/main/backend/controllers/tableController.js"
click node_backend_payments "https://github.com/utsoft7/pos-system/blob/main/backend/controllers/paymentController.js"
click node_backend_models "https://github.com/utsoft7/pos-system/blob/main/backend/models/orderModel.js"
click node_backend_middleware "https://github.com/utsoft7/pos-system/blob/main/backend/middlewares/tokenVerification.js"
click node_infra_compose "https://github.com/utsoft7/pos-system/blob/main/docker-compose.yml"
click node_infra_nginx "https://github.com/utsoft7/pos-system/blob/main/frontend/nginx.conf"

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_frontend_app,node_frontend_pages,node_frontend_auth,node_frontend_dashboard,node_frontend_home,node_frontend_menu,node_frontend_kitchen,node_frontend_tables,node_frontend_orders,node_frontend_invoice,node_frontend_state,node_frontend_data toneBlue
class node_backend_server,node_backend_auth,node_backend_orders,node_backend_tables,node_backend_payments,node_backend_models,node_backend_middleware toneAmber
class node_infra_compose,node_infra_nginx toneMint
```

## Components

### Frontend

React/Vite POS client

- [App shell](https://github.com/utsoft7/pos-system/blob/main/frontend/src/App.jsx): Vite React shell · Top-level client app and route composition · `frontend/src/App.jsx`
- [Pages](https://github.com/utsoft7/pos-system/blob/main/frontend/src/pages/index.js): Route pages · Route-level screens for auth, dashboard, home, menu, orders, tables, and more · `frontend/src/pages/index.js`
- [Auth UI](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/auth/Login.jsx): Auth components · Login and registration flows · `frontend/src/components/auth/Login.jsx`
- [Dashboard](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/dashboard/Metrics.jsx): Ops dashboard · Metrics and recent order summaries · `frontend/src/components/dashboard/Metrics.jsx`
- [Home ops](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/home/Greetings.jsx): Home widgets · Greeting, highlights, popular dishes, and recent activity · `frontend/src/components/home/Greetings.jsx`
- [Menu flow](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/menu/MenuContainer.jsx): Ordering UI · Menu browsing, cart, customer info, and bill generation · `frontend/src/components/menu/MenuContainer.jsx`
- [Kitchen ticket](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/kitchen/KitchenTicket.jsx): Kitchen UI · KOT-style kitchen dispatch view · `frontend/src/components/kitchen/KitchenTicket.jsx`
- [Tables](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/tables/TableCard.jsx): Floor plan UI · Table cards and occupancy selection · `frontend/src/components/tables/TableCard.jsx`
- [Orders](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/orders/OrderCard.jsx): Order UI · Order list and order cards · `frontend/src/components/orders/OrderCard.jsx`
- [Invoice](https://github.com/utsoft7/pos-system/blob/main/frontend/src/components/invoice/Invoice.jsx): Billing UI · Invoice rendering and payment handoff · `frontend/src/components/invoice/Invoice.jsx`
- [Redux state](https://github.com/utsoft7/pos-system/blob/main/frontend/src/redux/store.js): Client state · Cart, customer, and user slices · `frontend/src/redux/store.js`
- [API client](https://github.com/utsoft7/pos-system/blob/main/frontend/src/https/axiosWrapper.js): HTTP access · Axios wrapper and data loading hook · `frontend/src/https/axiosWrapper.js`

### Backend

Express API and data layer

- [API server](https://github.com/utsoft7/pos-system/blob/main/backend/server.js): Express app · Server entrypoint wiring routes, middleware, and config · `backend/server.js`
- [Users](https://github.com/utsoft7/pos-system/blob/main/backend/controllers/userController.js): Auth controller · User registration, login, and protected session handling · `backend/controllers/userController.js`
- [Orders API](https://github.com/utsoft7/pos-system/blob/main/backend/controllers/orderController.js): Order module · Order create/read/update flow · `backend/controllers/orderController.js`
- [Tables API](https://github.com/utsoft7/pos-system/blob/main/backend/controllers/tableController.js): Table module · Table state and availability management · `backend/controllers/tableController.js`
- [Payments API](https://github.com/utsoft7/pos-system/blob/main/backend/controllers/paymentController.js): Payment module · Cash and online payment processing · `backend/controllers/paymentController.js`
- [Data models](https://github.com/utsoft7/pos-system/blob/main/backend/models/orderModel.js): Mongoose models · Users, tables, orders, payments, KOTs, and counters · `backend/models/orderModel.js`
- [Auth guard](https://github.com/utsoft7/pos-system/blob/main/backend/middlewares/tokenVerification.js): JWT middleware · Token verification and global error handling · `backend/middlewares/tokenVerification.js`

### Infrastructure

Container and web serving setup

- [Compose stack](https://github.com/utsoft7/pos-system/blob/main/docker-compose.yml): Container orchestration · Runs frontend, backend, and database containers together · `docker-compose.yml`
- [Nginx serving](https://github.com/utsoft7/pos-system/blob/main/frontend/nginx.conf): Static web server · Production frontend serving configuration · `frontend/nginx.conf`

## Connections

- Pages → App shell: renders · Route pages are assembled by the app shell
- App shell → Auth UI: uses · Auth routes and screens
- App shell → Dashboard: uses · Dashboard screens
- App shell → Home ops: uses · Home and operations widgets
- App shell → Menu flow: uses · Menu, cart, customer, and bill workflow
- App shell → Kitchen ticket: uses · Kitchen ticket view
- App shell → Tables: uses · Table selection and occupancy UI
- App shell → Orders: uses · Order screens
- App shell → Invoice: uses · Invoice and billing screens
- Menu flow → Redux state: updates · Cart and customer state are managed locally
- Auth UI → Redux state: updates · Authenticated user state
- Dashboard → API client: loads · Fetches server summaries and metrics
- Home ops → API client: loads · Fetches operational lists and highlights
- Menu flow → API client: loads · Fetches menu and order-related data
- Orders → API client: loads · Fetches order records
- Tables → API client: loads · Fetches table state
- Invoice → API client: loads · Submits or reads billing data
- API client → API server: calls · HTTP API access
- API server → Auth guard: protects with · Token verification and error handling
- API server → Users: routes to · User API module
- API server → Orders API: routes to · Orders API module
- API server → Tables API: routes to · Tables API module
- API server → Payments API: routes to · Payments API module
- Users → Data models: reads/writes · User records and authentication data
- Orders API → Data models: reads/writes · Orders and KOT/counter records
- Tables API → Data models: reads/writes · Table occupancy and status
- Payments API → Data models: reads/writes · Payment transaction records
- Orders API → Payments API: triggers · Order settlement and payment handoff
- Orders API → Tables API: updates · Order lifecycle affects table availability
- Compose stack → API server: runs · Backend service container
- Compose stack → API client: connects · Frontend service container and API access
- Compose stack → Data models: provides db · MongoDB-backed persistence for the API
- Nginx serving → App shell: serves · Production static frontend hosting
