158 lines
6.1 KiB
Markdown
158 lines
6.1 KiB
Markdown
# 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)
|
||
|
||
1. **Job cards can only go Active → Done. No rollback.**
|
||
2. **All financial entries are timestamped and cannot be deleted.** Admin can "void" but not delete.
|
||
3. **Salary formula:** `(monthly_salary / 26) × days_present`. Admin can override the final paid amount.
|
||
4. **Job card number format:** `SAC-YYYYMMDD-001` (sequential per day).
|
||
5. **Staff code format:** `SAC-STF-001` (sequential).
|
||
6. **Parts code format:** `SAC-PRT-001` (sequential).
|
||
7. **Currency:** Always INR ₹. Indian date format DD/MM/YYYY.
|
||
8. **Stock auto-deducts** on parts sale entry.
|
||
9. **Parts sales can be linked to a job card** (optional — admin selects).
|
||
10. **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 |
|