39294-vm/05_IMPLEMENTATION_PLAN.md

Implementation Plan — Swish Auto Care GMS

For Claude Opus Agent — Build Order & Phase Structure

---

Overview

Build this system in 6 phases, one at a time. Each phase is self-contained and delivers working, testable functionality before moving to the next. Do NOT start the next phase until the current phase is fully working.

---

Pre-Build Checklist (Do First)

Before writing any code, verify the environment:

# Required installed:
node --version    # 18+ required
mysql --version   # 8.x
npm --version     # 9+

# Create project structure:
mkdir swish-gms && cd swish-gms
mkdir backend frontend

---

Phase 1 — Foundation (Build First)

Goal: Database up, backend server running, admin can login, frontend shell renders.

Backend Tasks:

1. cd backend && npm init -y
2. Install: npm install express mysql2 jsonwebtoken bcryptjs dotenv cors
3. Install dev: npm install -D nodemon
4. Create .env:

   PORT=5000
   DB_HOST=localhost
   DB_USER=root
   DB_PASS=your_mysql_password
   DB_NAME=swish_gms
   JWT_SECRET=swishgms_secret_key_2026
   

5. Create src/config/db.js — MySQL connection pool using mysql2/promise
6. Run the full schema SQL from 01_DATABASE_SCHEMA.md in MySQL
7. Create src/middleware/auth.js — JWT verify middleware
8. Create src/routes/auth.js — POST /login, GET /me
9. Create src/server.js — Express app with CORS, JSON body parser, routes
10. Create seed script — hash password, insert admin user, insert sample staff and parts
11. Test: POST http://localhost:5000/api/auth/login with Postman/curl

Frontend Tasks:

1. cd frontend && npm create vite@latest . -- --template react-ts
2. Install: npm install react-router-dom axios
3. Create src/api/axios.ts — Axios instance with base URL and JWT interceptors
4. Create src/context/AuthContext.tsx — Auth state, login/logout functions
5. Create src/pages/Login.tsx — Login form
6. Create src/components/Layout/ — Sidebar, TopBar, Layout wrapper
7. Create src/App.tsx — Router setup with ProtectedRoute wrapper
8. Create placeholder page components for all 14 routes (just <div>Page Name</div>)
9. Test: Open http://localhost:5173, login page shows, login works, redirects to dashboard placeholder

Phase 1 Done When:

• MySQL schema created, all 8 tables exist
• Admin can login via API and get JWT
• Frontend shows login page at /
• After login, sidebar shows with all nav items
• Logout works and returns to login page

---

Phase 2 — Job Cards & Status Board

Goal: Admin can create, view, and close job cards. Status board works.

Backend Tasks:

1. Create src/routes/jobCards.js with all routes from 02_API_REFERENCE.md
2. Implement job number generation (SAC-YYYYMMDD-001)
3. Implement GET with filters (status, date, reg_no, pagination)
4. Implement POST (create full and quick wash)
5. Implement PUT (edit while active)
6. Implement POST /:id/close (mark done with validation)
7. Create src/routes/dashboard.js — GET /today (needs job data)

Frontend Tasks:

1. Build src/pages/JobCards.tsx — table with search, filter, actions
2. Build src/pages/JobCardNew.tsx — dual-form (Full / Quick Wash toggle)
3. Build close job modal (inline in JobCards.tsx)
4. Build src/pages/StatusBoard.tsx — two-column Active/Done view
5. Build src/pages/Dashboard.tsx — 6 widget cards, quick actions
6. Build shared <Badge> component
7. Build shared <Modal> component

Phase 2 Done When:

• AC-02: Can create Full and Quick Wash job cards
• AC-03: Jobs show as Active, can be marked Done with amount + payment
• AC-01 (partial): Dashboard loads with active/done job counts and revenue
• Status board shows two columns

---

Phase 3 — Staff, Attendance & Salary

Goal: Staff management, daily attendance marking, and salary logging all work.

Backend Tasks:

1. Create src/routes/staff.js — CRUD, toggle active
2. Create src/routes/attendance.js — GET by date, bulk POST, monthly summary
3. Create src/routes/salary.js — list, create payment, GET calculate endpoint
4. Update src/routes/dashboard.js — add staff_present count
5. Add staff count to dashboard API

Frontend Tasks:

1. Build src/pages/Staff.tsx — table, add/edit modal, toggle active
2. Build src/pages/Attendance.tsx — bulk attendance marking grid with date picker
3. Build src/pages/Salary.tsx — payment form with auto-calculate + history table

Phase 3 Done When:

• AC-04: Admin can mark daily attendance for all staff
• AC-05: Admin can log salary/advance, view history
• Dashboard shows staff_present count correctly
• New job card dropdown shows active staff list

---

Phase 4 — Parts, Sales & Cash Ledger

Goal: Inventory, POS-style parts sales, and manual cash entries all work.

Backend Tasks:

1. Create src/routes/parts.js — CRUD, stock adjustment
2. Create src/routes/partsSales.js — list, create sale (with stock deduction)
3. Create src/routes/cashLedger.js — list, create entry
4. Add parts_revenue to dashboard totals

Frontend Tasks:

1. Build src/pages/Parts.tsx — parts table with low stock badge, restock modal
2. Build src/pages/PartsSales.tsx — sales table, new sale modal with stock check
3. Build src/pages/CashLedger.tsx — ledger table, cash in/out modal

Phase 4 Done When:

• AC-06: Admin can record parts sale, stock quantity decreases
• AC-07: Admin can enter cash in/out with reasons
• Dashboard today_revenue now includes parts_revenue

---

Phase 5 — Accounts, Reports & Exports

Goal: Accounts consolidation, daily report download, and all 4 Excel exports work.

Backend Tasks:

1. Create src/routes/accounts.js — summary (aggregate query), transactions list
2. Create src/routes/reports.js — daily report JSON + Excel download
3. Create src/routes/exports.js — 4 separate Excel export endpoints
4. Install SheetJS: npm install xlsx
5. Create src/utils/excel.js — helper for creating Excel files (see 04_BUSINESS_LOGIC.md)

Frontend Tasks:

1. Build src/pages/Accounts.tsx — summary cards, income/expense breakdown, transactions
2. Build src/pages/DailyReport.tsx — date picker, on-screen preview tables, download button
3. Build src/pages/Exports.tsx — 4 export cards with date pickers and download buttons
4. Handle file download in frontend (trigger blob download from axios response)

Excel Download Pattern (Frontend):

const downloadExcel = async (url: string, filename: string, params?: object) => {
  const response = await api.get(url, { params, responseType: 'blob' });
  const blob = new Blob([response.data], {
    type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
  });
  const link = document.createElement('a');
  link.href = URL.createObjectURL(blob);
  link.download = filename;
  link.click();
  URL.revokeObjectURL(link.href);
};

Phase 5 Done When:

• AC-08: Accounts shows today's income, expenses, balance
• AC-09: Daily report downloads as formatted Excel
• AC-10: All 4 export buttons produce correct .xlsx files

---

Phase 6 — Polish, Testing & Seed Data

Goal: Everything looks good, works reliably, has realistic demo data.

Tasks:

1. Run through all 10 AC acceptance criteria manually
2. Fix any bugs found
3. Create comprehensive seed data:
   • 5-10 job cards (mix of active and done, various dates)
   • 30 days of attendance for all 4 staff
   • 3-4 salary payment records
   • 10-15 parts sales
   • 15-20 cash ledger entries (mix in/out)
4. UI polish:
   • Loading states (skeleton loaders or spinner) on all data tables
   • Error states when API calls fail
   • Empty states ("No job cards yet" with create button)
   • Toast notifications for all create/update actions
   • Confirm dialog before marking job done
5. Update Dashboard today_revenue to include ALL income sources
6. Verify all date formatting is DD/MM/YYYY
7. Verify all currency shows ₹ with Indian comma formatting
8. Final test: full demo walkthrough

Phase 6 Done When:

• All 10 ACs pass
• Demo data loaded and looks realistic
• No console errors in browser
• No server errors in terminal
• Admin password works: username=admin, password=swish@2024

---

Dependency Install Summary

Backend

cd backend
npm install express mysql2 jsonwebtoken bcryptjs dotenv cors xlsx
npm install -D nodemon

package.json scripts (backend):

{
  "scripts": {
    "start": "node src/server.js",
    "dev": "nodemon src/server.js",
    "seed": "node src/config/seed.js"
  }
}

Frontend

cd frontend
npm install react-router-dom axios

---

Environment Variables (.env — Backend)

PORT=5000
DB_HOST=localhost
DB_USER=root
DB_PASS=your_mysql_root_password
DB_NAME=swish_gms
JWT_SECRET=swishgms_jwt_secret_2026_local
NODE_ENV=development

---

Running the App

# Terminal 1 — Backend
cd backend && npm run dev

# Terminal 2 — Frontend
cd frontend && npm run dev

# Browser
http://localhost:5173
Login: admin / swish@2024

---

Common Mistakes to Avoid

1. Don't use mysql package — use mysql2/promise for async/await support
2. Don't forget CORS — frontend on :5173, backend on :5000 — need CORS middleware
3. Don't store plain passwords — always bcrypt.hash before insert
4. Don't skip the ON DUPLICATE KEY for attendance — must upsert, not insert
5. Don't forget stock validation — check stock before inserting parts sale
6. Don't use DELETE — business rule says no deletion, only voiding (not needed in demo but don't implement delete routes)
7. Excel download needs responseType: 'blob' in frontend axios call
8. JWT_SECRET must match between sign and verify — both use same env var