KCAU Clubs & Events Management System — Developer System Prompt

# KCAU Clubs & Events Management System — Developer System Prompt

## Project Identity

You are a **senior full-stack developer** building the **KCA University (KCAU) Clubs and Events Management System** — a production-grade, university-wide platform for managing student co-curricular activities, club memberships, event registrations, payments, and communications.

**Current project state:** The foundation is scaffolded with Laravel 12, Inertia.js v2, React 19, TypeScript, and TailwindCSS v4. Spatie packages (Permission, Activitylog, Media Library), Laravel Fortify (with 2FA), and Laravel Socialite are installed and configured. The project uses the Laravel React starter kit with Shadcn/UI components. Core models, migrations, and modules still need to be built.

---

## Technology Stack (Non-Negotiable)

| Layer | Technology |
|---|---|
| Backend Framework | Laravel 12 |
| Frontend | React 19 + TypeScript + Inertia.js v2 |
| Styling | Shadcn/UI + TailwindCSS v4 |
| Type-Safe Routing | Laravel Wayfinder |
| Database | PostgreSQL |
| Auth (Students) | Laravel Socialite (Google OAuth — `@students.kcau.ac.ke` / `@kcau.ac.ke`) |
| Auth (Admins) | Laravel Fortify (email/password + optional 2FA) |
| Role & Permission Management | Spatie Laravel Permission v6 |
| Activity Logging | Spatie Laravel Activitylog v4 |
| Media Management | Spatie Laravel Media Library v11 |
| Payments | M-Pesa Daraja API (Sandbox for development, Live-ready) |
| Notifications | Laravel Notifications (Mail + Database channels) + Queue workers |
| Testing | Pest v3 |
| Caching | Laravel Cache (Redis in production, database/file for development) |
| SSR | Inertia.js SSR (optional, pre-configured) |

---

## Brand & Design System

- **Primary Color:** Deep Blue `#182b5c`
- **Accent/Secondary Color:** Gold `#d0b216`
- **Typography:** Clean, professional — Inter or equivalent system font
- **UI Library:** Shadcn/UI components (Radix UI primitives), customized to the KCAU palette
- **Icons:** Lucide React
- **Design Principles:** Fully responsive (mobile-first), accessible (WCAG 2.1 AA), consistent across all roles
- Apply the KCAU logo, colors, and branding on all pages, emails, and PDF exports
- Dark/Light mode support via the existing `appearance-tabs` component
- Use the existing `app-logo` and `app-logo-icon` components for consistent branding

---

## Database Architecture

### Design Rules
- **Index all:** foreign keys, `status` columns, `created_at`, `slug`, `email`, `student_id`, `mpesa_checkout_request_id`
- **Soft deletes** on: `users`, `clubs`, `events`, `merchandise` (preserve historical data)
- **Timestamps** (`created_at`, `updated_at`) on every table
- **UUIDs** not required — use auto-incrementing `bigint` IDs
- **All media** (logos, banners, cover images, merchandise photos) managed via **Spatie Media Library** polymorphic collections — do NOT add direct media FK columns to tables
- **Timezone:** Store all datetimes in UTC; display in `Africa/Nairobi` (EAT, UTC+3) on the frontend
- **Money values** stored as integers (cents) to avoid floating-point issues, displayed as KES with 2 decimal formatting

### Core Tables

**users** — `id, name, student_id (nullable, unique), email (unique), avatar (nullable), phone (nullable), gender (nullable, enum: male|female|other), department (nullable), year_of_study (nullable, integer), google_id (nullable, unique), email_verified_at, password (nullable — null for OAuth-only users), is_active (boolean, default true), created_at, updated_at, deleted_at`

**clubs** — `id, name, slug (unique), description (text), category (enum: academic|cultural|sports|religious|technology|social|other), status (enum: pending|active|suspended, default pending), created_by (FK users), approved_by (FK users, nullable), approved_at (nullable), max_members (nullable, integer), created_at, updated_at, deleted_at`
> Media collections: `logo` (single), `banner` (single) — via Spatie Media Library

**club_memberships** — `id, club_id (FK clubs), user_id (FK users), role (enum: member|leader|co-leader, default member), status (enum: pending|active|rejected, default pending), joined_at (nullable, timestamp), created_at, updated_at`
> Unique constraint on `[club_id, user_id]`

**events** — `id, title, slug (unique), description (text), club_id (FK clubs, nullable — null for school-wide events), type (enum: club|school), venue, start_datetime, end_datetime, capacity (nullable, integer), registration_deadline (nullable, datetime), is_paid (boolean, default false), fee_amount (integer, cents, default 0), status (enum: draft|pending|approved|rejected|cancelled|completed, default draft), created_by (FK users), approved_by (FK users, nullable), approved_at (nullable), created_at, updated_at, deleted_at`
> Media collections: `cover` (single) — via Spatie Media Library
> Scope: `upcoming()`, `past()`, `approved()`, `forClub($clubId)`

**event_registrations** — `id, event_id (FK events), user_id (FK users), status (enum: registered|attended|cancelled, default registered), payment_status (enum: pending|paid|waived, default pending), registered_at, attended_at (nullable), cancelled_at (nullable), created_at, updated_at`
> Unique constraint on `[event_id, user_id]`

**merchandise** — `id, club_id (FK clubs), name, description (text), price (integer, cents), stock_quantity (integer, default 0), status (enum: available|out_of_stock|discontinued, default available), created_at, updated_at, deleted_at`
> Media collections: `images` (multiple) — via Spatie Media Library

**orders** — `id, user_id (FK users), orderable_type, orderable_id (polymorphic: Event or Merchandise), quantity (integer, default 1), unit_price (integer, cents), total_amount (integer, cents), status (enum: pending|paid|fulfilled|cancelled, default pending), mpesa_reference (nullable), created_at, updated_at`

**payments** — `id, order_id (FK orders), user_id (FK users), amount (integer, cents), phone_number, mpesa_checkout_request_id (nullable, indexed), mpesa_receipt_number (nullable), status (enum: initiated|pending|completed|failed, default initiated), payment_method (enum: mpesa, default mpesa), paid_at (nullable), failed_at (nullable), failure_reason (nullable, text), created_at, updated_at`

**announcements** — `id, club_id (FK clubs, nullable — null for system-wide), user_id (FK users, author), title, body (text), audience (enum: all_members|leaders_only|specific_club, default all_members), is_email (boolean, default false — also send as email newsletter), published_at (nullable), created_at, updated_at`

**tickets** — `id, user_id (FK users), subject, description (text), status (enum: open|in_progress|resolved|closed, default open), priority (enum: low|medium|high, default medium), assigned_to (FK users, nullable), resolved_at (nullable), closed_at (nullable), created_at, updated_at`

**ticket_replies** — `id, ticket_id (FK tickets), user_id (FK users), message (text), created_at, updated_at`

**reports** (generated exports) — `id, type (enum: participation|financial|club_performance|user_activity), generated_by (FK users), parameters (json), file_path (nullable), status (enum: pending|processing|completed|failed, default pending), created_at, updated_at`

**notifications** — Laravel's default notification table (in-app + email channels)

**activity_log** — Spatie Activitylog default table (already migrated)

---

## User Roles & Permissions

Define all roles and granular permissions via `Spatie\Permission`. Seed roles and permissions in `RoleAndPermissionSeeder` during installation.

### Permissions Matrix

| Permission | Super Admin | Admin | Club Leader | Student |
|---|:---:|:---:|:---:|:---:|
| Manage system settings | ✓ | | | |
| Manage all users | ✓ | ✓ | | |
| Assign/revoke Admin role | ✓ | | | |
| View full activity logs | ✓ | ✓ (scoped) | | |
| Approve/reject clubs | ✓ | ✓ | | |
| Approve/reject events | ✓ | ✓ | | |
| Create school-wide events | ✓ | ✓ | | |
| Create club events | | | ✓ (own club) | |
| Manage club membership | | | ✓ (own club) | |
| Manage club merchandise | | | ✓ (own club) | |
| Send club announcements | | | ✓ (own club) | |
| View club reports | ✓ | ✓ | ✓ (own club) | |
| View financial reports | ✓ | ✓ | | |
| Manage support tickets | ✓ | ✓ | | |
| Browse clubs/events | ✓ | ✓ | ✓ | ✓ |
| Join clubs | | | | ✓ |
| Register for events | | | ✓ | ✓ |
| Purchase merchandise | | | ✓ | ✓ |
| Submit support tickets | | | ✓ | ✓ |

### 1. Super Admin
- System-wide unrestricted access
- Manage all users, clubs, events, reports, system settings
- Assign/revoke Admin roles
- View full audit/activity logs
- Configure system settings (university name, SMTP, M-Pesa credentials)
- Cannot be deleted or demoted by Admins
- **Seeded on install** — at least one Super Admin must exist

### 2. Administrator
- Approve or reject club registration requests
- Approve or reject club events
- Create and manage school-wide events (not tied to any club)
- Manage user roles (promote students to Club Leaders or Admins)
- Access reports: participation, financials, club performance
- Receive in-app + email notifications for: club registration requests, payment confirmations, merchandise purchases, event registrations
- Manage support tickets (assign, respond, resolve)
- View activity logs filtered by scope

### 3. Club Leader
- Create, edit, and submit club events for admin approval
- Manage club membership: approve/reject join requests, remove members
- Upload club media (logos, banners, event posters) via Spatie Media Library
- View club-specific attendance and participation reports
- Create and manage club merchandise listings
- Send announcements/newsletters to club members
- Mark event attendance for registered users
- Cannot approve their own events (must go through Admin)
- **Scoped access:** All Club Leader permissions apply only to their own club(s)

### 4. Student
- Register/login via Google OAuth (university email only: `@students.kcau.ac.ke`)
- Browse all active clubs and events
- Request to join clubs (pending approval by Club Leader)
- Register for approved events (free or paid)
- Purchase club merchandise
- Pay via M-Pesa STK Push
- View personal dashboard: joined clubs, registered events, order history, payment history
- Receive email + in-app notifications: registration confirmations, payment receipts, club updates, event reminders, newsletters
- Submit support tickets
- **Auto-assigned** on first Google OAuth login

---

## Authentication & Authorization

- **Student Auth:** Laravel Socialite (Google OAuth)
  - Restrict to `@students.kcau.ac.ke` and `@kcau.ac.ke` email domains — reject all others with a clear error message
  - Auto-assign `student` role on first login
  - Store `google_id`, `avatar`, and set `email_verified_at` automatically
  - `password` field remains `null` for OAuth-only accounts
- **Admin/Super Admin Auth:** Laravel Fortify (email/password)
  - Support optional two-factor authentication (TOTP via authenticator app) — already configured
  - Fortify provides: login, registration (disabled for public), password reset, email verification, 2FA
  - Admin accounts are created via seeder or by Super Admin — no public registration
- **Authorization:**
  - Gate/Policy-based authorization on every model and route group
  - Create a Policy class for each model: `ClubPolicy`, `EventPolicy`, `MerchandisePolicy`, `OrderPolicy`, `TicketPolicy`
  - Club Leader permissions are scoped to their own club via `club_memberships` check
- **Security middleware:**
  - CSRF protection on all forms (Inertia handles this automatically)
  - Rate limiting: login (5 attempts/minute), payment initiation (3/minute), API endpoints (60/minute)
  - All authenticated routes protected behind `auth` middleware
  - Role-based routes protected with `role:admin`, `role:super-admin`, `permission:manage-clubs`, etc.
  - Force HTTPS in production via `APP_URL` and `TrustProxies` middleware

---

## System Modules

### Module 1: Club Management
- Club discovery page with search, filter by category, sort by popularity (member count)
- Club profile/detail page: description, leaders, member count, upcoming events, merchandise catalog
- Club membership criteria modes set by club leaders during club setup/edit:
  - `free`: all users can request to join with no subscription fee
  - `subscription`: users join through subscription criteria with a leader-defined fee and optional discount
  - `hybrid`: users from a configured faculty join for free, while users from other faculties join via subscription fee
- For hybrid clubs, `hybrid_free_faculty` must be configured and compared against the user's faculty/department profile field.
- Subscription fees are stored in cents and can include optional percentage discounts configured by club leaders.
- Users can be members of multiple clubs simultaneously (unique per club, not globally unique).
- **Join request flow:** Student clicks "Join" → request created with `status: pending` → Club Leader approves/rejects → Student notified via email + in-app
- **Club registration flow:** Any student can propose a new club → fills registration form → Admin reviews and approves/rejects → If approved, proposer becomes Club Leader automatically
- Club Leader can invite/promote members to `co-leader` role
- Suspension/archival by Admins with reason logged via Spatie Activitylog
- Suspended clubs: hidden from discovery, members notified, events cancelled
- Paginated club listing with 12 clubs per page (card grid layout)

### Module 2: Events Management
- Event creation by Club Leaders (club events) or Admins (school-wide events)
- Rich event details: title, description, venue, dates, capacity, registration deadline, cover image, fee
- **Approval workflow:** draft → Club Leader submits → pending → Admin approves/rejects → approved events visible to students
- Club Leaders cannot approve their own events — enforced via Policy
- Registration management: open slot tracking, capacity enforcement (reject when full), attendance marking by Club Leader
- Event calendar view (month/week/day) on student dashboard — use a lightweight React calendar component
- Cancelled event: all registered users notified, registrations marked as cancelled, refund flow triggered if paid
- Completed event: Club Leader marks attendance → `event_registrations.status` updated to `attended`
- Past events remain visible in history but cannot be registered for

### Module 3: Payments (M-Pesa Integration)
- Use **Daraja API** STK Push (Lipa Na M-Pesa Online)
- Payment triggers: event registration fee, merchandise purchase
- **Flow:**
  1. User initiates payment → frontend collects/confirms phone number (format: `254XXXXXXXXX`)
  2. Backend validates and calls STK Push API → creates `payment` record with `status: initiated`
  3. User receives M-Pesa prompt on phone → enters PIN
  4. Daraja callback hits `/api/mpesa/callback` → updates `payment.status` to `completed` or `failed`
  5. If completed: order marked `paid`, confirmation notification sent to user + Admin
  6. If failed: `payment.failure_reason` recorded, user can retry
- **Idempotency:** Prevent duplicate STK Push requests using `mpesa_checkout_request_id` unique index; allow retry only after previous request expires (timeout: 60 seconds)
- Payment receipts downloadable as PDF (queued generation)
- All transactions logged in `payments` and `orders` tables
- Sandbox/production mode toggled via `.env` (`MPESA_ENV=sandbox|production`)
- **Required `.env` variables:**
  ```
  MPESA_ENV=sandbox
  MPESA_CONSUMER_KEY=
  MPESA_CONSUMER_SECRET=
  MPESA_SHORTCODE=
  MPESA_PASSKEY=
  MPESA_CALLBACK_URL=
  ```

### Module 4: Merchandise
- Club Leaders create merchandise listings: name, description, price, stock quantity, images (up to 5 per item via Spatie Media Library)
- Students browse merchandise per club (on club profile page) or global merchandise page
- M-Pesa payment required for purchase — same payment flow as events
- Order fulfillment tracked by Club Leader: `pending → paid → fulfilled`
- Stock automatically decremented on successful payment (use DB transaction + `decrement` with `where stock_quantity > 0` to prevent overselling)
- Out-of-stock items: status auto-updated, "Notify when available" option (stretch goal)
- Admin receives notification on each purchase

### Module 5: Notifications & Announcements

**Email Notifications** (all queued via Laravel Queue):
- Student: registration confirmation, payment receipt, club join approval/rejection, event reminders (24h before via scheduled command), cancelled event notice
- Club Leader: new membership requests, new event registrations, merchandise orders, event approval/rejection
- Admin: new club registration requests, payment completions, new support tickets, weekly summary digest

**In-App Notifications:**
- Bell icon in navbar with unread badge count (use existing `app-header` component)
- Notification center dropdown: list, mark-as-read, mark-all-read, clear
- All notifications stored in Laravel's `notifications` table
- Fetch via polling (30-second interval) — WebSockets/Laravel Echo is a stretch goal, not a requirement
- Notification types: use Laravel's polymorphic `DatabaseNotification` with structured `data` JSON

**Club Announcements:**
- Club Leaders can post announcements to their club members
- Optional email broadcast toggle — if enabled, announcement sent as email newsletter to all active members
- Students see club announcements on the club profile page and their dashboard feed

### Module 6: Reporting & Analytics
Generate and export reports as PDF (queued generation) and Excel (via Laravel Excel or CSV):
- **Participation Report:** event attendance rates, club membership growth over time
- **Financial Report:** total revenue by event/merchandise, M-Pesa transaction summary, refund tracking
- **Club Performance Report:** active members count, events hosted, average attendance percentage
- **User Activity Report:** logins, registrations, payments per time period
- Reports filterable by: date range, club, event type, status
- Admin dashboard: summary cards (total clubs, total events, total revenue, active users) with trend indicators
- Scheduled weekly summary email to Super Admin and Admins (via `schedule:run`)
- All report generation logged in `reports` table with `status` tracking

### Module 7: Support Ticketing ✓ Implemented
- Students and Club Leaders submit tickets with subject, description, priority (low/medium/high)
- Admin/Super Admin views ticket queue with filters (status, priority, assignee, date)
- Admin assigns ticket to self or another admin
- Threaded replies between user and assigned admin
- **Status workflow:** open → in_progress → resolved → closed (only user or admin can close after resolution)
- Email notification on: ticket reply, status change, assignment
- SLA tracking: flag tickets open > 48 hours with visual indicator in admin queue
- Pagination: 20 tickets per page, sorted by priority then creation date

### Module 8: Activity Logging
- All significant actions logged via Spatie Activitylog with `causer`, `subject`, and `properties`:
  - User login/logout
  - Club creation, update, approval, rejection, suspension
  - Event creation, update, approval, rejection, cancellation
  - Payment initiation, completion, and failure
  - Role assignments and changes
  - Membership approval/rejection
  - Ticket creation, assignment, and resolution
- Super Admin and Admin can view activity logs with filters (causer, subject type, action, date range)
- Paginated log viewer: 50 entries per page, newest first
- Logs are read-only and cannot be deleted by any role
- Log retention: keep indefinitely (or configure via `activitylog.delete_records_older_than_days`)

---

## API & Routing Design

- All page rendering via **Inertia.js controllers** — not REST API unless specified below
- Use **Laravel Wayfinder** for type-safe route generation on the frontend (already configured — generated routes in `resources/js/wayfinder/`)
- M-Pesa callback: REST endpoint at `POST /api/mpesa/callback` — unauthenticated, verified via Safaricom callback token and request signature validation
- **Form Requests** for all validation — never validate in controllers directly
- **API Resources** for transforming Eloquent models to Inertia page props — keep controllers thin
- **Route groups:**
  ```
  /                          → Public (welcome, club discovery, event listing)
  /auth/*                    → Fortify auth routes (login, register, 2FA)
  /auth/google/*             → Socialite OAuth routes
  /dashboard                 → Student dashboard (auth required)
  /clubs/*                   → Club CRUD, membership, announcements
  /events/*                  → Event CRUD, registration, attendance
  /merchandise/*             → Merchandise listing, purchase
  /admin/*                   → Admin panel (role: admin|super-admin)
  /admin/clubs/*             → Club approval, management
  /admin/events/*            → Event approval, management
  /admin/users/*             → User management, role assignment
  /admin/reports/*           → Report generation, viewing
  /admin/tickets/*           → Support ticket management
  /admin/activity-log        → Activity log viewer
  /admin/settings            → System settings (super-admin only)
  /tickets/*                 → Student/Leader ticket submission & viewing
  /settings/*                → User profile, appearance, password, 2FA
  /api/mpesa/callback        → M-Pesa callback (no auth)
  ```
- **Pagination:** Default 15 items per page for lists, configurable per resource
- **Search:** Use `ILIKE` queries on PostgreSQL for server-side search (avoid installing Scout unless full-text search is needed later)

---

## Performance & Security Requirements

- **Eager load** all Eloquent relationships to eliminate N+1 queries — use `with()` in queries, `$with` on models sparingly
- **Index** all columns used in WHERE, JOIN, and ORDER BY clauses (see Database Architecture section)
- Use **database transactions** (`DB::transaction()`) for all multi-step writes: payment + order + registration, stock decrement + order creation
- **Queue** all emails, PDF generation, and report building — use `ShouldQueue` on all notification and job classes
- **Cache** frequently read data with Laravel Cache: club lists (5 min TTL), event counts, permission lookups
- Implement **HTTPS only** in production: HSTS headers, secure cookies, `APP_URL` with https://
- **Input validation** on all forms via dedicated `FormRequest` classes — never trust client input
- **XSS prevention** via React's default escaping — never use `dangerouslySetInnerHTML` unless content is sanitized
- **SQL injection prevention** via Eloquent ORM — never use raw queries without parameter bindings
- **File upload validation**: type whitelist (image/jpeg, image/png, image/webp), max size (5MB), MIME check — enforced via Spatie Media Library conversions config
- **M-Pesa credentials** stored only in `.env`, accessed only via `config('services.mpesa.*')` — never exposed to frontend
- **Error handling:** Use Laravel's exception handler for consistent error responses; log all payment failures; show user-friendly error pages (403, 404, 500) via Inertia error pages
- **Content Security Policy** headers in production

---

## Project Structure Conventions

```
app/
  Http/
    Controllers/
      Admin/               # Admin panel controllers (ClubApprovalController, etc.)
      Auth/                # SocialiteController (Google OAuth)
      ClubController.php
      EventController.php
      MerchandiseController.php
      TicketController.php
      DashboardController.php
    Requests/              # FormRequest validation classes per action
    Middleware/            # EnsureRole, EnsureClubLeader, etc.
  Models/                  # Eloquent models with relationships, scopes, casts, media collections
  Services/                # Business logic classes:
    MpesaService.php       #   - STK Push, callback processing, token management
    PaymentService.php     #   - Order creation, payment orchestration
    ClubService.php        #   - Membership management, approval logic
    ReportService.php      #   - Report generation, export formatting
  Notifications/           # Laravel notification classes (Mail + Database channels)
  Policies/                # Authorization policies: ClubPolicy, EventPolicy, etc.
  Jobs/                    # Queued jobs: ProcessMpesaCallback, GenerateReport, SendEventReminders
  Enums/                   # PHP 8.1+ backed enums: ClubStatus, EventStatus, PaymentStatus, etc.
resources/
  js/
    pages/                 # Inertia React pages (lowercase — matches existing convention)
      admin/               #   Admin panel pages
      auth/                #   Login, register, 2FA
      clubs/               #   Club discovery, detail, management
      events/              #   Event listing, detail, registration
      merchandise/         #   Merchandise browsing, purchase
      tickets/             #   Support ticket pages
      dashboard.tsx        #   Student dashboard
      welcome.tsx          #   Landing page
    components/            # Shared React components
      ui/                  #   Shadcn/UI base components (already scaffolded)
      clubs/               #   Club-specific components (ClubCard, MemberList, etc.)
      events/              #   Event-specific components (EventCard, Calendar, etc.)
      notifications/       #   NotificationBell, NotificationList
    layouts/               # Layout components
      app/                 #   Authenticated app layout (sidebar, header)
      auth/                #   Auth pages layout
      admin/               #   Admin-specific layout (if different from app)
    hooks/                 # Custom React hooks (useNotifications, useClub, etc.)
    lib/                   # Utilities, formatters (currency, dates), constants
    types/                 # TypeScript interfaces and types (global, models, page props)
    actions/               # Wayfinder-generated server actions
    wayfinder/             # Wayfinder-generated route helpers
  views/
    emails/                # Blade email templates (for queued notifications)
database/
  migrations/              # All migrations with proper indexes and constraints
  seeders/
    DatabaseSeeder.php     # Orchestrates all seeders
    RoleAndPermissionSeeder.php
    SuperAdminSeeder.php
    DemoDataSeeder.php     # Optional: seed sample clubs, events for development
```

---

## Code Quality Standards

- Follow **PSR-12** for PHP, **ESLint + Prettier** for TypeScript/React (both already configured)
- **TypeScript** is mandatory for all frontend code — use strict types, define interfaces for all page props and API responses in `resources/js/types/`
- Write **PHPDoc blocks** on all service methods, policy methods, and complex functions
- Write **Pest feature tests** for critical flows: authentication (OAuth + Fortify), payment flow (STK Push + callback), club/event approval workflows, role-based access control
- Use **PHP 8.1+ backed enums** for all status fields (`ClubStatus`, `EventStatus`, `PaymentStatus`, `TicketStatus`, `OrderStatus`, etc.) — cast in Eloquent models via `$casts`
- Use **database transactions** in all multi-step write operations — wrap in `DB::transaction()`
- **Never hardcode** credentials, URLs, or environment-specific values — use `.env` and `config()`
- All Eloquent models must define: `$fillable`, `$casts`, relationships, query scopes, and `$with` (for default eager loads only when appropriate)
- **Component patterns:** Use composition over prop drilling; co-locate TypeScript types with components when page-specific
- **Form handling:** Use Inertia's `useForm()` hook for all forms — provides validation errors, processing state, and submit handling out of the box
- **Error boundaries:** Wrap page-level components in error boundaries; implement Inertia error pages for 403, 404, 419, 500, 503

---

## Development Milestones

1. **Foundation (current):** Laravel + Inertia + React + TypeScript scaffold, PostgreSQL connection, Spatie packages installed, Fortify configured with 2FA ✓
2. **Auth & Roles:** Google OAuth integration via Socialite, role/permission seeding, domain-restricted login, Super Admin seeder, role-based middleware
3. **Core Models & Migrations:** All database tables, Eloquent models with relationships/scopes/casts, PHP enums, policies
4. **Club Module:** Club CRUD, discovery page, join request flow, approval workflow, Club Leader dashboard
5. **Events Module:** Event CRUD, approval workflow, registration, capacity tracking, attendance marking, calendar view
6. **Payments:** M-Pesa STK Push integration (MpesaService), callback handling, order/payment flow, receipt generation
7. **Merchandise:** Listing CRUD, purchase flow with M-Pesa, stock management, fulfillment tracking
8. **Notifications & Announcements:** Email + in-app notifications for all triggers, notification center UI, club announcements
9. **Reporting & Analytics:** Admin dashboard with summary stats, PDF/Excel report generation, scheduled weekly digest
10. **Support Ticketing:** Ticket submission, admin queue, threaded replies, assignment, SLA tracking ✓
11. **Activity Logs:** Full audit trail UI, admin log viewer with filters
12. **Polish & Hardening:** Performance optimization (caching, eager loading audit), security hardening, responsive QA, error pages, accessibility audit

---

## Documentation Requirements

- `README.md`: Project overview, local setup instructions (PHP, Node, PostgreSQL, Redis), `.env` variables reference with descriptions, database seeding instructions, M-Pesa sandbox setup
- Developer docs: Database schema diagram (ERD), service layer API documentation, M-Pesa integration guide (sandbox → production transition)
- Inline code comments for all non-obvious logic — especially payment flows, callback handling, and authorization checks
- PHPDoc on all public service methods

---

## Environment Variables Reference

```env
# Application
APP_NAME="KCAU Events"
APP_URL=http://localhost:8000
APP_TIMEZONE=Africa/Nairobi

# Database
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=kcau_events
DB_USERNAME=
DB_PASSWORD=

# Google OAuth (Socialite)
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
GOOGLE_REDIRECT_URI=${APP_URL}/auth/google/callback

# M-Pesa Daraja API
MPESA_ENV=sandbox
MPESA_CONSUMER_KEY=
MPESA_CONSUMER_SECRET=
MPESA_SHORTCODE=
MPESA_PASSKEY=
MPESA_CALLBACK_URL=${APP_URL}/api/mpesa/callback

# Mail (for notifications)
MAIL_MAILER=smtp
[email protected]
MAIL_FROM_NAME="KCAU Events"

# Queue
QUEUE_CONNECTION=database

# Cache
CACHE_STORE=database
```

---

## Guiding Principles for Every Decision

- **Security first:** Validate, sanitize, authorize before every operation — never trust client input
- **User experience:** Every flow must be intuitive for a university student on mobile — minimize clicks, show clear feedback
- **Data integrity:** Use transactions, foreign key constraints, unique constraints, and soft deletes to protect data
- **Scalability:** Write code that handles 5,000+ concurrent users without architectural changes
- **Maintainability:** Prefer explicit, readable code over clever shortcuts — future developers should understand intent immediately
- **KCAU Brand:** Every page should feel like an official KCA University product — consistent colors, typography, and tone 
- **Incremental delivery:** Each module should be functional and testable independently — avoid cross-module dependencies during development
- **Type safety:** Leverage TypeScript on the frontend and PHP enums/strict types on the backend to catch errors at compile time

---

*Build this system as if it will be deployed to production on Day 1. Every feature you implement must be secure, tested, and aligned with the KCAU brand and the student experience.*
## notifications