# SkatePro Academy - Complete Technical Specification

## Project Overview
**Project Name:** SkatePro Academy Management System  
**Type:** Progressive Web App (PWA) with PHP Backend  
**Brand:** Sandbox's Innovation (Orange #F26522)  
**Status:** 100% Complete - Ready for Production Deployment  

---

## 1. Technology Stack

### Frontend
| Technology | Version | Purpose |
|-----------|---------|---------|
| **React** | 19 | UI framework |
| **TypeScript** | 5.x | Type-safe JavaScript |
| **Vite** | 7.x | Build tool and dev server |
| **Tailwind CSS** | 3.4.19 | Utility-first CSS framework |
| **shadcn/ui** | latest | 40+ pre-built UI components |
| **Zustand** | latest | State management (9 stores) |
| **React Router DOM** | latest | Client-side routing (HashRouter) |
| **Chart.js** | 4.x | Charts and analytics |
| **react-chartjs-2** | latest | React wrapper for Chart.js |
| **date-fns** | latest | Date formatting and calculations |
| **lucide-react** | latest | Icon library (500+ icons) |

### Backend
| Technology | Version | Purpose |
|-----------|---------|---------|
| **PHP** | 7.4+ | Server-side API |
| **MySQL** | 5.7+ | Database |
| **PDO** | built-in | Database abstraction |
| **bcrypt** | built-in | Password hashing |

### Mobile (Optional)
| Technology | Version | Purpose |
|-----------|---------|---------|
| **Capacitor** | 7.x | Convert to native iOS/Android app |

---

## 2. Project Architecture

```
SkatePro-Academy/
|
|-- public/
|   |-- logo.jpg                    # Sandbox's Innovation logo
|   |-- icons/                      # App icons
|
|-- src/
|   |-- App.tsx                     # Main router with 3-role auth guards
|   |-- main.tsx                    # Entry point
|   |-- index.css                   # Global styles + brand colors
|   |
|   |-- types/
|   |   |-- index.ts                # All TypeScript types
|   |
|   |-- stores/                     # 9 Zustand state stores
|   |   |-- authStore.ts            # Login/logout/session (calls auth.php)
|   |   |-- studentStore.ts         # Student CRUD (calls students.php)
|   |   |-- timingStore.ts          # Stopwatch + timing (calls timing.php)
|   |   |-- sprintRaceStore.ts      # LAP-based race timer (calls sprint_races.php)
|   |   |-- attendanceStore.ts      # Attendance marking (calls attendance.php)
|   |   |-- feeStore.ts             # Fee receipts (calls fees.php)
|   |   |-- equipmentStore.ts       # Equipment buy/sell (calls equipment.php)
|   |   |-- expenseStore.ts         # Expense tracking (calls expenses.php)
|   |   |-- batchStore.ts           # Batch management (local)
|   |   |-- uiStore.ts              # Navigation + toast + UI state
|   |
|   |-- screens/                    # All page screens
|   |   |-- auth/
|   |   |   |-- SplashScreen.tsx
|   |   |   |-- AdminLoginScreen.tsx
|   |   |   |-- AssistantLoginScreen.tsx
|   |   |   |-- StudentLoginScreen.tsx
|   |   |
|   |   |-- dashboard/
|   |   |   |-- AdminDashboard.tsx
|   |   |   |-- AssistantDashboard.tsx
|   |   |
|   |   |-- students/
|   |   |   |-- StudentListScreen.tsx
|   |   |   |-- StudentDetailScreen.tsx
|   |   |   |-- AssistantStudentDetail.tsx
|   |   |   |-- AddStudentScreen.tsx
|   |   |
|   |   |-- timing/
|   |   |   |-- TimingEntryScreen.tsx
|   |   |   |-- TimingHistoryScreen.tsx
|   |   |
|   |   |-- sprint/
|   |   |   |-- SprintRaceListScreen.tsx
|   |   |   |-- SprintRaceCreateScreen.tsx
|   |   |   |-- SprintRaceTimerScreen.tsx
|   |   |   |-- SprintRaceDetailScreen.tsx
|   |   |
|   |   |-- attendance/
|   |   |   |-- AttendanceMarkingScreen.tsx
|   |   |
|   |   |-- fees/
|   |   |   |-- FeeDashboardScreen.tsx
|   |   |   |-- RecordPaymentScreen.tsx
|   |   |   |-- CoachFeeScreen.tsx
|   |   |
|   |   |-- equipment/
|   |   |   |-- EquipmentListScreen.tsx
|   |   |   |-- RecordBuyScreen.tsx
|   |   |   |-- RecordSellScreen.tsx
|   |   |
|   |   |-- sales/
|   |   |   |-- SalesDashboardScreen.tsx
|   |   |
|   |   |-- coaches/
|   |   |   |-- ManageCoachesScreen.tsx
|   |   |
|   |   |-- profit/
|   |   |   |-- ProfitDashboardScreen.tsx
|   |   |
|   |   |-- expenses/
|   |   |   |-- AddExpenseScreen.tsx
|   |   |
|   |   |-- student-portal/
|   |   |   |-- StudentDashboard.tsx
|   |   |   |-- StudentMoreMenu.tsx
|   |   |
|   |   |-- more/
|   |   |   |-- MoreMenuScreen.tsx
|   |   |   |-- AssistantMoreMenu.tsx
|   |   |   |-- SettingsScreen.tsx
|   |   |
|   |-- components/
|   |   |-- layout/
|   |   |   |-- AppShell.tsx          # Main layout wrapper
|   |   |   |-- Header.tsx            # Top header bar
|   |   |   |-- BottomNav.tsx         # Bottom tab navigation
|   |   |   |-- LoginLayout.tsx       # Shared login page design
|   |   |
|   |   |-- common/
|   |   |   |-- index.tsx             # Avatar, Badges, Cards, FAB, Search
|   |   |
|   |   |-- ui/                       # 40+ shadcn/ui components
|   |
|   |-- lib/
|   |   |-- apiClient.ts              # Frontend API connector (all PHP endpoints)
|   |   |-- formatters.ts             # Currency, dates, ID generation
|   |   |-- chartConfig.ts            # Chart.js configuration
|   |
|   |-- backend/                      # PHP API FILES (upload to server)
|       |-- config/
|       |   |-- database.php          # MySQL connection config
|       |
|       |-- api/                      # ALL API ENDPOINTS
|       |   |-- auth.php              # POST login
|       |   |-- students.php          # GET/POST/PUT/DELETE students
|       |   |-- timing.php            # GET/POST timing records
|       |   |-- attendance.php        # GET/POST attendance
|       |   |-- fees.php              # GET/POST fee receipts
|       |   |-- sprint_races.php      # GET/POST/DELETE races
|       |   |-- equipment.php         # GET/POST equipment
|       |   |-- expenses.php          # GET/POST/DELETE expenses
|       |   |-- coaches.php           # GET/POST/DELETE coaches
|       |   |-- import_students.php   # POST CSV file upload
|       |   |-- clean_database.php    # POST reset all data
|       |
|       |-- sql/
|       |   |-- setup_database.sql    # MySQL table creation script
|
|-- index.html                        # Entry HTML
|-- vite.config.ts                    # Vite build configuration
|-- tailwind.config.js                # Tailwind CSS theme
|-- postcss.config.js                 # CSS processing
|-- tsconfig.json                     # TypeScript configuration
|-- package.json                      # Dependencies
|-- capacitor.config.ts               # Mobile app configuration
```

---

## 3. Complete API Documentation

### Base URL: `https://yourserver.com/api/`

### 3.1 Authentication
| Endpoint | Method | Body | Response |
|----------|--------|------|----------|
| `auth.php` | POST | `{username, password}` | `{success, token, user}` |

### 3.2 Students
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `students.php` | GET | `?search=&batch=&status=` | List all students |
| `students.php` | GET | `?id=1` | Get single student |
| `students.php` | POST | `{fullName, phone, email, ...}` | Create student |
| `students.php` | PUT | `?id=1` + body | Update student |
| `students.php` | DELETE | `?id=1` | Soft delete student |

### 3.3 Timing
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `timing.php` | GET | `?studentId=&distance=` | List timing records |
| `timing.php` | POST | `{studentId, distance, time, date, notes}` | Save timing |

### 3.4 Attendance
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `attendance.php` | GET | `?date=2025-06-01` | Get attendance for date |
| `attendance.php` | GET | `?studentId=1` | Get student attendance |
| `attendance.php` | POST | `{studentId, date, status, markedBy}` | Mark attendance |

### 3.5 Fees
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `fees.php` | GET | `?receipts=1` | Get all receipts |
| `fees.php` | GET | `?due=1` | Get due fees list |
| `fees.php` | POST | `{studentId, amount, paymentMethod, paymentDate, notes}` | Record payment |

### 3.6 Sprint Races
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `sprint_races.php` | GET | - | Get all races |
| `sprint_races.php` | GET | `?studentId=1` | Get student races |
| `sprint_races.php` | POST | `{action: 'create', name, distance, participants[]}` | Create race |
| `sprint_races.php` | POST | `{action: 'saveRound', raceId, roundId, results[]}` | Save round |
| `sprint_races.php` | DELETE | `?id=1` | Delete race |

### 3.7 Equipment
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `equipment.php` | GET | - | Get all equipment |
| `equipment.php` | POST | `{name, category, initialStock, unitCost}` | Add equipment |
| `equipment.php` | POST | `{action: 'buy', equipmentId, quantity, unitCost, ...}` | Record buy |
| `equipment.php` | POST | `{action: 'sell', equipmentId, quantity, unitSellingPrice, ...}` | Record sell |

### 3.8 Expenses
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `expenses.php` | GET | - | Get all expenses |
| `expenses.php` | POST | `{category, description, amount, expenseDate}` | Add expense |
| `expenses.php` | DELETE | `?id=1` | Delete expense |

### 3.9 Coaches
| Endpoint | Method | Parameters | Action |
|----------|--------|------------|--------|
| `coaches.php` | GET | - | Get all coaches |
| `coaches.php` | POST | `{username, name, phone, password}` | Add coach |
| `coaches.php` | DELETE | `?id=1` | Delete coach |

### 3.10 Import Students (CSV)
| Endpoint | Method | Body | Action |
|----------|--------|------|--------|
| `import_students.php` | POST | `multipart/form-data` with `file` field | Import CSV |

### 3.11 Clean Database
| Endpoint | Method | Action |
|----------|--------|--------|
| `clean_database.php` | POST | Remove all student data, keep admin |

---

## 4. Database Schema (MySQL)

### 4.1 Tables (11 total)
```sql
users                      -- Login accounts (admin, assistant, student)
students                   -- Student information
timing_records             -- Timing/speed records
attendance                 -- Daily attendance
sprint_races               -- Race definitions
sprint_rounds              -- Race rounds
sprint_results             -- Race participant results
fee_receipts               -- Fee payment receipts
equipment                  -- Equipment catalog
equipment_transactions     -- Buy/sell transactions
expenses                   -- Academy expenses
batches                    -- Training batches
```

### 4.2 Key Relationships
- `students.email` = `users.username` (student login)
- `sprint_results.round_id` -> `sprint_rounds.id`
- `sprint_rounds.race_id` -> `sprint_races.id`
- `equipment_transactions.equipment_id` -> `equipment.id`
- `fee_receipts.student_id` -> `students.id`

---

## 5. User Roles & Access Control

| Feature | Admin | Assistant Coach | Student |
|---------|-------|-----------------|---------|
| Dashboard (full stats) | Yes | Limited | Personal only |
| Add/Edit/Delete Students | Yes | View only | No |
| Mark Attendance | Yes | Yes | No |
| Record Timing | Yes | Yes | No |
| Sprint Races (create/run) | Yes | Yes | View own only |
| Fee Management (record) | Yes | No | No |
| Fee Status (mark paid/due) | Yes | Yes (toggle) | No |
| Equipment (buy/sell) | Yes | No | No |
| Add Expenses | Yes | No | No |
| Profit Dashboard | Yes | No | No |
| Manage Coaches | Yes | No | No |
| WhatsApp Messages | Yes | Yes | No |
| Settings | Yes | Yes | Yes |

### Login URLs
- Admin: `/#/admin` (or `/#/admin/login`)
- Assistant Coach: `/#/coach`
- Student: `/#/student`

---

## 6. Key Features Implemented

### 6.1 Student Management
- Add student with form validation
- Auto-generate Student ID (SK001, SK002...)
- Auto-generate password or use provided password
- View student details with login info (admin sees email)
- Edit/Delete students
- WhatsApp integration for sending credentials
- CSV bulk import with variable fees

### 6.2 Attendance System
- Toggle Present/Absent per student per day
- Batch-wise filtering
- Attendance percentage calculation
- Visual charts

### 6.3 Timing System
- Built-in stopwatch with lap recording
- Manual time entry
- Multiple distances: 500m, 1lap, 1000m, 1500m, 3000m
- Performance charts (lower = better)
- Improvement tracking

### 6.4 Sprint Races (LAP-based Timer)
- Create custom races with any distance
- Select 1-10 students
- **LAP button**: Press when student crosses finish line
- Assign student names to laps after race
- Edit lap times
- Add missed students with manual time entry
- Mark DNF (Did Not Finish)
- Multiple rounds per race

### 6.5 Fee Management
- Record fee payments with receipts
- Due fees list with overdue tracking
- **WhatsApp fee reminders** (pre-written message)
- Variable fees per student
- Coach can mark Paid/Not Paid (no amounts shown)

### 6.6 Equipment Inventory
- Add equipment with buy price
- Record sales with profit calculation
- Stock tracking with low stock alerts
- Sales dashboard with profit analytics

### 6.7 Expense Tracking
- 8 categories: Rent, Salary, Electricity, Water, Maintenance, Transport, Food, Other
- Deducted from fee revenue (NOT from equipment sales)

### 6.8 Profit Dashboard (4 Boards)
1. **Fees Profit**: Fee Revenue - Expenses = Fee Profit
2. **Equipment**: Total Buy | Sell Revenue | Equipment Profit
3. **Total Profit**: Fee Profit + Equipment Profit = Net Profit
4. **Total Revenue**: Fee Revenue + Equipment Revenue

---

## 7. Deployment Steps

### Step 1: Create MySQL Database
```bash
mysql -u your_username -p
CREATE DATABASE skatepro_academy;
USE skatepro_academy;
source backend/sql/setup_database.sql;
```

### Step 2: Upload PHP Files
Upload `backend/api/` and `backend/config/` to `/public_html/api/`

### Step 3: Update Database Config
Edit `backend/config/database.php`:
```php
define('DB_HOST', 'localhost');
define('DB_USER', 'your_mysql_username');
define('DB_PASS', 'your_mysql_password');
define('DB_NAME', 'skatepro_academy');
```

### Step 4: Upload Frontend
Upload `dist/` folder contents to `public_html/`

### Step 5: Login
- Admin: `admin` / `admin123`
- Assistant: `assistant` / `assistant123`

---

## 8. Mobile App (Optional)
The project includes Capacitor configuration for native mobile apps:

```bash
npm install @capacitor/core @capacitor/cli
npx cap add android    # For APK
npx cap add ios        # For IPA
npx cap sync
npx cap open android   # Opens Android Studio
```

---

## 9. External APIs Used
| API | Purpose | Cost |
|-----|---------|------|
| WhatsApp (wa.me) | Send messages to parents | FREE |

No other external APIs required. Fully self-hosted.

---

## 10. WhatsApp Integration
Pre-written messages for:
- Fee reminders: "Dear Parent, fee of [amount] for [student] is overdue..."
- Welcome message with login credentials
- Custom messages via `https://wa.me/[phone]?text=[message]`

---

**Developed for:** Sandbox's Innovation  
**Brand Color:** #F26522 (Orange)  
**Status:** 100% Complete - Production Ready
