# rvcodes-1/motoserve architecture

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

- Interactive diagram: https://gitdiagram.com/rvcodes-1/motoserve
- Repository: https://github.com/rvcodes-1/motoserve

## Overview

1. **Overall shape**  
   MotoServe is a split MERN application: a React/Vite single-page frontend talks to an Express/Mongoose backend over `/api/*` routes, with MongoDB as the system of record. The backend owns all persistence, business rules, stock updates, and accounting state; the frontend is a role-aware operational UI.

2. **Frontend boundary**  
   The frontend is organized by route-level pages in `src/pages` with shared layout components (`Sidebar`, `Header`, `Layout`) and reusable UI controls in `src/components/ui`. `AuthContext` and `ThemeContext` provide cross-app state, while hooks such as keyboard shortcuts, idle timeout, and SSE subscription add app-wide behavior. API access is centralized in `src/services/api.js` and `src/api/axios.js`.

3. **Backend boundary**  
   The backend is a modular Express app with separate route files for each business area: auth, customers, vehicles, job cards, invoices, OTC sales, inventory, daybook, dashboard, mechanics/team, notifications, activity log, and backup. Middleware handles JWT auth, role checks, ID validation, security headers, and error normalization.

4. **Domain model and persistence**  
   MongoDB collections map directly to the workshop domain: `User`, `Customer`, `Vehicle`, `Inventory`, `JobCard`, `Invoice`, `OTCSale`, `ActivityLog`, `Notification`, and a `Counter` for numbering. The data model centers on references and snapshots so that operational history remains stable even after later edits or stock changes.

5. **Authentication and access control**  
   Login uses JWT stored in an httpOnly cookie, not client-side token storage. Route access is role-based, matching the roles documented in the README (`admin`, `manager`, `advisor`, `floor_manager`, `billing`, `otc_staff`, `mechanic`). The frontend mirrors this with capability-aware navigation and page access, while the backend enforces the real boundary.

6. **Core workshop workflow**  
   The main operational flow is customer intake → job card creation → mechanic assignment → parts/labour logging → ready status → invoice generation → payment capture → completion. `JobCard` is the central working record, and its state transitions drive downstream records like invoices, activity logs, and notifications.

7. **Inventory and stock control**  
   `Inventory` is shared by workshop and OTC flows. Stock is deducted atomically when an invoice is generated, and invoice cancellation restores stock from a stored snapshot. This means stock integrity is owned by backend transactions rather than UI state, which is important for diagramming the true system boundary.

8. **Billing, invoices, and daybook**  
   `Invoice` and `OTCSale` both support multi-line items, taxes, and multiple payment methods. The invoices module unifies workshop and OTC billing views, while the daybook route aggregates payments by date range and payment method, including reference notes for UPI/card. Financial reporting is therefore derived from transactional sales data, not from a separate ledger service.

9. **Printing and document output**  
   Print output is generated on the client with `window.print()` via `utils/printPDF.js`, covering A4 tax invoices, thermal receipts, and job card print layouts. This is a frontend rendering concern, but it depends on backend invoice/OTC/job-card data and tax breakdowns.

10. **Real-time and operational feedback**  
   `utils/sse.js`, the `useSSE` hook, and the notifications model indicate server-sent events are used for lightweight real-time updates. The app also keeps an activity log for auditing operational actions, which is exposed through its own route and utility wrapper.

11. **Import/export and maintenance**  
   Backup support is a first-class backend feature: JSON export/import plus selective CSV import for customers, vehicles, and inventory. The seed scripts (`seed.js`, `seed-demo.js`, `seed-prod.js`) show a deliberate separation between demo data, production bootstrap, and admin-only setup.

12. **Deployment and runtime constraints**  
   The project is designed to run locally with Node 18+, MongoDB, and a React dev server, but also includes deployment configs for Render and Vercel. In diagram terms, the frontend is a static SPA, the backend is a standalone API server, and MongoDB is the only durable datastore.

Main entry points: [`backend/routes`](https://github.com/rvcodes-1/motoserve/tree/main/backend/routes) (Routes), [`backend/models`](https://github.com/rvcodes-1/motoserve/tree/main/backend/models) (Data models), [`frontend/src/pages`](https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/pages) (Pages), [`backend/server.js`](https://github.com/rvcodes-1/motoserve/blob/main/backend/server.js) (API server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>SPA entry<br/>[main.jsx]"]
  node_frontend_routes["Pages<br/>route views"]
  node_frontend_layout["Layout<br/>shared chrome"]
  node_frontend_state(("App state<br/>contexts"))
  node_frontend_behaviors{{"App hooks<br/>client behaviors"}}
  node_frontend_api["API client<br/>HTTP access<br/>[api.js]"]
  node_frontend_print["Print output<br/>client printing<br/>[printPDF.js]"]
end

subgraph group_backend["Backend"]
  node_backend_server["API server<br/>Express entry<br/>[server.js]"]
  node_backend_auth{{"Auth<br/>security middleware<br/>[auth.js]"}}
  node_backend_routes["Routes<br/>business API"]
  node_backend_workshop["Workshop flow<br/>core domain<br/>[jobcards.js]"]
  node_backend_billing["Billing flow<br/>finance domain<br/>[invoices.js]"]
  node_backend_inventory[("Stock control<br/>inventory domain<br/>[inventory.js]")]
  node_backend_accounts["Accounts<br/>reporting domain<br/>[daybook.js]"]
  node_backend_models[("Data models<br/>mongoose schemas")]
  node_backend_services{{"Utilities<br/>backend services"}}
  node_backend_backup["Backup<br/>maintenance API<br/>[backup.js]"]
  node_backend_db[("MongoDB<br/>persistent store<br/>[db.js]")]
end

subgraph group_infra["Runtime"]
  node_infra_seed["Seed data<br/>bootstrap scripts<br/>[seed.js]"]
  node_infra_deploy["Deploy config<br/>runtime config<br/>[render.yaml]"]
end

node_frontend_app -->|"renders"| node_frontend_routes
node_frontend_app -->|"wraps"| node_frontend_layout
node_frontend_routes -->|"uses"| node_frontend_state
node_frontend_routes -->|"fetches"| node_frontend_api
node_frontend_routes -.->|"enhanced by"| node_frontend_behaviors
node_frontend_routes -.->|"prints"| node_frontend_print
node_frontend_api -->|"calls"| node_backend_server
node_frontend_behaviors -.->|"subscribes"| node_backend_services
node_backend_server -->|"protects"| node_backend_auth
node_backend_server -->|"mounts"| node_backend_routes
node_backend_routes -->|"includes"| node_backend_workshop
node_backend_routes -->|"includes"| node_backend_billing
node_backend_routes -->|"includes"| node_backend_inventory
node_backend_routes -->|"includes"| node_backend_accounts
node_backend_routes -->|"includes"| node_backend_backup
node_backend_workshop -->|"persists"| node_backend_models
node_backend_billing -->|"persists"| node_backend_models
node_backend_inventory -->|"updates"| node_backend_models
node_backend_accounts -->|"reads"| node_backend_models
node_backend_services -.->|"logs"| node_backend_models
node_backend_routes -->|"stores"| node_backend_db
node_backend_models -->|"maps to"| node_backend_db
node_infra_seed -.->|"seeds"| node_backend_db
node_infra_deploy -.->|"deploys"| node_backend_server
node_infra_deploy -.->|"deploys"| node_frontend_app

click node_frontend_app "https://github.com/rvcodes-1/motoserve/blob/main/frontend/src/main.jsx"
click node_frontend_routes "https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/pages"
click node_frontend_layout "https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/components/layout"
click node_frontend_state "https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/context"
click node_frontend_behaviors "https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/hooks"
click node_frontend_api "https://github.com/rvcodes-1/motoserve/blob/main/frontend/src/services/api.js"
click node_frontend_print "https://github.com/rvcodes-1/motoserve/blob/main/frontend/src/utils/printPDF.js"
click node_backend_server "https://github.com/rvcodes-1/motoserve/blob/main/backend/server.js"
click node_backend_auth "https://github.com/rvcodes-1/motoserve/blob/main/backend/middleware/auth.js"
click node_backend_routes "https://github.com/rvcodes-1/motoserve/tree/main/backend/routes"
click node_backend_workshop "https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/jobcards.js"
click node_backend_billing "https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/invoices.js"
click node_backend_inventory "https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/inventory.js"
click node_backend_accounts "https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/daybook.js"
click node_backend_models "https://github.com/rvcodes-1/motoserve/tree/main/backend/models"
click node_backend_services "https://github.com/rvcodes-1/motoserve/tree/main/backend/utils"
click node_backend_backup "https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/backup.js"
click node_backend_db "https://github.com/rvcodes-1/motoserve/blob/main/backend/config/db.js"
click node_infra_seed "https://github.com/rvcodes-1/motoserve/blob/main/backend/seed.js"
click node_infra_deploy "https://github.com/rvcodes-1/motoserve/blob/main/render.yaml"

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_routes,node_frontend_layout,node_frontend_state,node_frontend_behaviors,node_frontend_api,node_frontend_print toneBlue
class node_backend_server,node_backend_auth,node_backend_routes,node_backend_workshop,node_backend_billing,node_backend_inventory,node_backend_accounts,node_backend_models,node_backend_services,node_backend_backup,node_backend_db toneAmber
class node_infra_seed,node_infra_deploy toneMint
```

## Components

### Frontend

React/Vite SPA for workshop operations and role-aware workflows

- [App shell](https://github.com/rvcodes-1/motoserve/blob/main/frontend/src/main.jsx): SPA entry · Bootstraps the React application and route composition · `frontend/src/main.jsx`
- [Pages](https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/pages): route views · Route-level screens for dashboard, workshop, billing, admin, and reporting flows · `frontend/src/pages`
- [Layout](https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/components/layout): shared chrome · Persistent navigation and page framing across the app · `frontend/src/components/layout`
- [App state](https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/context): contexts · Auth and theme state shared across the frontend · `frontend/src/context`
- [App hooks](https://github.com/rvcodes-1/motoserve/tree/main/frontend/src/hooks): client behaviors · Idle timeout, keyboard shortcuts, and SSE subscription hooks · `frontend/src/hooks`
- [API client](https://github.com/rvcodes-1/motoserve/blob/main/frontend/src/services/api.js): HTTP access · Centralized axios/service layer for backend requests · `frontend/src/services/api.js`
- [Print output](https://github.com/rvcodes-1/motoserve/blob/main/frontend/src/utils/printPDF.js): client printing · Generates invoice, receipt, and job-card print layouts in the browser · `frontend/src/utils/printPDF.js`

### Backend

Express API, business rules, persistence, and operational services

- [API server](https://github.com/rvcodes-1/motoserve/blob/main/backend/server.js): Express entry · Main server composition and route mounting · `backend/server.js`
- [Auth](https://github.com/rvcodes-1/motoserve/blob/main/backend/middleware/auth.js): security middleware · JWT session handling and role-based access control · `backend/middleware/auth.js`
- [Routes](https://github.com/rvcodes-1/motoserve/tree/main/backend/routes): business API · Domain route modules for workshop, billing, inventory, and admin operations · `backend/routes`
- [Workshop flow](https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/jobcards.js): core domain · Job cards, vehicles, customers, mechanics, and operational progress · `backend/routes/jobcards.js`
- [Billing flow](https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/invoices.js): finance domain · Invoices, OTC sales, daybook aggregation, and payment capture · `backend/routes/invoices.js`
- [Stock control](https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/inventory.js): inventory domain · Inventory mutations and atomic stock reconciliation · `backend/routes/inventory.js`
- [Accounts](https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/daybook.js): reporting domain · Dashboard summaries, daybook reporting, and productivity views · `backend/routes/daybook.js`
- [Data models](https://github.com/rvcodes-1/motoserve/tree/main/backend/models): mongoose schemas · Workshop entities persisted in MongoDB with snapshot-friendly records · `backend/models`
- [Utilities](https://github.com/rvcodes-1/motoserve/tree/main/backend/utils): backend services · Activity logging, notifications, SSE, and audit helpers · `backend/utils`
- [Backup](https://github.com/rvcodes-1/motoserve/blob/main/backend/routes/backup.js): maintenance API · Export/import and data maintenance endpoints · `backend/routes/backup.js`
- [MongoDB](https://github.com/rvcodes-1/motoserve/blob/main/backend/config/db.js): persistent store · System of record for users, customers, vehicles, job cards, invoices, sales, inventory, logs, and notifications · `backend/config/db.js`

### Runtime

Deployment, seeding, and shared runtime entry points

- [Seed data](https://github.com/rvcodes-1/motoserve/blob/main/backend/seed.js): bootstrap scripts · Demo, production, and general seeding entry points · `backend/seed.js`
- [Deploy config](https://github.com/rvcodes-1/motoserve/blob/main/render.yaml): runtime config · Render and Vercel deployment manifests for frontend and backend · `render.yaml`

## Connections

- App shell → Pages: renders · Application root mounts route-level screens
- App shell → Layout: wraps · Pages share common chrome and navigation
- Pages → App state: uses · Pages depend on auth and theme context
- Pages → API client: fetches · Screens read and mutate backend data through the API client
- Pages → App hooks: enhanced by · Keyboard, idle, and SSE behaviors augment user workflows
- Pages → Print output: prints · Billing and job-card views produce client-side print output
- API client → API server: calls · Frontend talks to the backend over /api routes
- App hooks → Utilities: subscribes · SSE hook consumes server-pushed operational events
- API server → Auth: protects · Server applies authentication and authorization middleware
- API server → Routes: mounts · Primary API entry mounts domain route modules
- Routes → Workshop flow: includes · Workshop operations are handled by customer, vehicle, job card, and mechanic routes
- Routes → Billing flow: includes · Billing routes cover invoices, OTC sales, and daybook reporting
- Routes → Stock control: includes · Inventory routes manage stock state and adjustments
- Routes → Accounts: includes · Dashboard and productivity/reporting endpoints summarize operations
- Routes → Backup: includes · Backup routes handle export/import maintenance
- Workshop flow → Data models: persists · Workshop workflow reads and writes core workshop documents
- Billing flow → Data models: persists · Invoices and OTC sales are stored as transactional records
- Stock control → Data models: updates · Stock changes are persisted in inventory documents
- Accounts → Data models: reads · Reporting aggregates operational data from stored records
- Utilities → Data models: logs · Activity, notifications, and SSE events are derived from domain state
- Routes → MongoDB: stores · All major backend routes ultimately persist into MongoDB
- Data models → MongoDB: maps to · Mongoose schemas define the MongoDB collections
- Seed data → MongoDB: seeds · Bootstrap scripts initialize or repopulate the database
- Deploy config → API server: deploys · Backend runs as a standalone API service
- Deploy config → App shell: deploys · Frontend is deployed as a static SPA
