Swish Auto Care — Garage Management System (GMS)

Master Project Context

For Claude Opus Agent: Read this file first before any other file. This is your north star.

What You Are Building

A web-based Garage Management System for Swish Auto Care — an automotive service and car wash studio in India. They currently run everything on paper: job cards, staff attendance, parts sales, billing, and cash management. You are replacing all of that with a clean, functional digital system.

This is a working demo build — a single-admin system running locally (localhost). No cloud, no multi-branch, no mobile app. Just a solid, functional demo that proves value to the client.

The Big Picture

Admin logs in
    ↓
Dashboard (today's snapshot: jobs, revenue, staff, cash)
    ↓
┌─────────────────────────────────────────────────────┐
│  M1: Login & Dashboard                              │
│  M2: Job Card Management (Full + Quick Wash)        │
│  M3: Job Status Board (Active → Done)               │
│  M4: Staff Management & Attendance                  │
│  M5: Staff Salary & Payment                         │
│  M6: Parts Inventory + POS Sales                    │
│  M7: Accounts (Consolidated Financial View)         │
│  M8: Daily Sales Report (Excel Download)            │
│  M9: Cash In / Cash Out Ledger                      │
│  M10: Data Export to Excel (4 databases)            │
└─────────────────────────────────────────────────────┘

Tech Stack (Fixed — Do Not Deviate)

Layer	Technology
Frontend	React 18 + TypeScript + Vite + React Router v6 + CSS Modules
Backend	Node.js + Express.js
Database	MySQL 8.x
Excel Export	SheetJS (xlsx npm package)
Auth	JWT (jsonwebtoken) + bcrypt
HTTP Client	Axios (frontend → backend)

Project Folder Structure

swish-gms/
├── backend/
│   ├── src/
│   │   ├── config/
│   │   │   └── db.js              # MySQL connection pool
│   │   ├── middleware/
│   │   │   └── auth.js            # JWT verify middleware
│   │   ├── routes/
│   │   │   ├── auth.js
│   │   │   ├── dashboard.js
│   │   │   ├── jobCards.js
│   │   │   ├── staff.js
│   │   │   ├── attendance.js
│   │   │   ├── salary.js
│   │   │   ├── parts.js
│   │   │   ├── partsSales.js
│   │   │   ├── cashLedger.js
│   │   │   ├── accounts.js
│   │   │   └── exports.js
│   │   └── server.js
│   ├── .env
│   └── package.json
│
└── frontend/
    ├── src/
    │   ├── api/
    │   │   └── axios.ts           # Axios instance with JWT header
    │   ├── components/
    │   │   ├── Layout/
    │   │   │   ├── Sidebar.tsx
    │   │   │   ├── TopBar.tsx
    │   │   │   └── Layout.tsx
    │   │   └── shared/
    │   │       ├── Badge.tsx
    │   │       ├── Modal.tsx
    │   │       └── Table.tsx
    │   ├── pages/
    │   │   ├── Login.tsx
    │   │   ├── Dashboard.tsx
    │   │   ├── JobCards.tsx
    │   │   ├── JobCardNew.tsx
    │   │   ├── StatusBoard.tsx
    │   │   ├── Staff.tsx
    │   │   ├── Attendance.tsx
    │   │   ├── Salary.tsx
    │   │   ├── Parts.tsx
    │   │   ├── PartsSales.tsx
    │   │   ├── CashLedger.tsx
    │   │   ├── Accounts.tsx
    │   │   ├── DailyReport.tsx
    │   │   └── Exports.tsx
    │   ├── context/
    │   │   └── AuthContext.tsx
    │   ├── App.tsx
    │   └── main.tsx
    ├── index.html
    └── package.json

Key Business Rules (Never Break These)

Job cards can only go Active → Done. No rollback.
All financial entries are timestamped and cannot be deleted. Admin can "void" but not delete.
Salary formula: (monthly_salary / 26) × days_present. Admin can override the final paid amount.
Job card number format: SAC-YYYYMMDD-001 (sequential per day).
Staff code format: SAC-STF-001 (sequential).
Parts code format: SAC-PRT-001 (sequential).
Currency: Always INR ₹. Indian date format DD/MM/YYYY.
Stock auto-deducts on parts sale entry.
Parts sales can be linked to a job card (optional — admin selects).
Demo is single admin only — no staff login in this scope.

What "Done" Looks Like

The demo passes when all 10 Acceptance Criteria (AC-01 to AC-10) pass:

AC-01: Admin can log in → dashboard
AC-02: Admin can create Full and Quick Wash job cards
AC-03: Jobs show as Active, can be marked Done with payment
AC-04: Admin can mark daily attendance for all staff
AC-05: Admin can log salary/advance payment and view history
AC-06: Admin can record parts sale, stock decreases
AC-07: Admin can enter cash in/out with reasons
AC-08: Accounts module shows today's income, expenses, balance
AC-09: Admin downloads Daily Sales Report as .xlsx
AC-10: All 4 Excel exports produce correct downloadable files

Reference Files in This Kit

File	What It Covers
`00_PROJECT_OVERVIEW.md`	This file — master context
`01_DATABASE_SCHEMA.md`	All 7 MySQL tables, full schema with SQL
`02_API_REFERENCE.md`	All backend routes, request/response shapes
`03_FRONTEND_PAGES.md`	Every page, its fields, actions, and UI behavior
`04_BUSINESS_LOGIC.md`	Rules, calculations, validations
`05_IMPLEMENTATION_PLAN.md`	Phase-by-phase build order with agent prompts
`06_AGENT_PROMPTS.md`	All prompts to feed the agent, phase by phase

6.1 KiB Raw Permalink Blame History Unescape Escape