# 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 |