How rvcodes-1/motoserve works
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: routes Routes · models Data models · pages Pages · server.js API server
Components 20
Frontend
React/Vite SPA for workshop operations and role-aware workflows
- App shell · Bootstraps the React application and route composition
frontend/src/main.jsx - Pages · Route-level screens for dashboard, workshop, billing, admin, and reporting flows
frontend/src/pages - Layout · Persistent navigation and page framing across the app
frontend/src/components/layout - App state · Auth and theme state shared across the frontend
frontend/src/context - App hooks · Idle timeout, keyboard shortcuts, and SSE subscription hooks
frontend/src/hooks - API client · Centralized axios/service layer for backend requests
frontend/src/services/api.js - Print output · 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 · Main server composition and route mounting
backend/server.js - Auth · JWT session handling and role-based access control
backend/middleware/auth.js - Routes · Domain route modules for workshop, billing, inventory, and admin operations
backend/routes - Workshop flow · Job cards, vehicles, customers, mechanics, and operational progress
backend/routes/jobcards.js - Billing flow · Invoices, OTC sales, daybook aggregation, and payment capture
backend/routes/invoices.js - Stock control · Inventory mutations and atomic stock reconciliation
backend/routes/inventory.js - Accounts · Dashboard summaries, daybook reporting, and productivity views
backend/routes/daybook.js - Data models · Workshop entities persisted in MongoDB with snapshot-friendly records
backend/models - Utilities · Activity logging, notifications, SSE, and audit helpers
backend/utils - Backup · Export/import and data maintenance endpoints
backend/routes/backup.js - MongoDB · 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 · Demo, production, and general seeding entry points
backend/seed.js - Deploy config · Render and Vercel deployment manifests for frontend and backend
render.yaml
Connections 25
- 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