# Payment Registration System Architecture

## Overview
A payment registration system that allows guardians/students to register payments for classes and enables admins to track payment status.

## Requirements
- **Users**: Guardians/students can register payments, admins can view payment status
- **Payment Information**: Value, date/time, optional receipt image
- **Access Control**: Only admins can view payment details; guardians/students can only register their own payments

## Database Schema Design

### Payment Model
```javascript
{
  _id: ObjectId,
  classId: ObjectId (ref: Class),
  userId: ObjectId (ref: User),
  amount: Number,
  paymentDate: Date,
  paymentMethod: String (e.g., "pix", "bank_transfer", "cash"),
  status: String (enum: ["pending", "verified", "rejected"]),
  receiptUrl: String (optional, from file upload),
  notes: String (optional),
  createdAt: Date,
  updatedAt: Date
}
```

### Key Features
- **One-to-Many**: A class can have multiple payments (partial payments)
- **Many-to-One**: A user can make multiple payments across different classes
- **Status Tracking**: Pending → Verified/Rejected workflow

## API Routes Structure

### 1. Payment API Routes
```
/api/payments
  GET    - List all payments (admin only)
  POST   - Create new payment (guardian/student only)
  GET/:id - Get single payment (admin only)
  PUT/:id - Update payment status (admin only)
  DELETE/:id - Delete payment (admin only)

/api/payments/class/:classId
  GET - Get all payments for a specific class (admin only)

/api/payments/user/:userId
  GET - Get all payments for a specific user (guardian/student only)
```

### 2. File Upload Integration
- Use existing `/api/files` routes
- Set `relatedToType` = "payment"
- Set `relatedToId` = payment ID
- Store receipt image URL in payment record

## UI Components Structure

### Admin Dashboard
```
/app/(protected)/admin/dashboard/payments/
  page.jsx                    - Main payments dashboard
  components/
    PaymentsTable.jsx         - Table showing all payments
    PaymentDetail.jsx         - Modal showing payment details
    PaymentStats.jsx          - Statistics cards
    VerifyPaymentButton.jsx   - Button to verify/reject payments
```

### Guardian Dashboard
```
/app/(protected)/dashboard/guardian/payments/
  page.jsx                    - List of registered payments
  register/
    page.jsx                  - Payment registration form
    components/
      PaymentForm.jsx         - Form to register payment
      ReceiptUpload.jsx       - File upload component

/app/(protected)/dashboard/guardian/class/[id]/payments/
  page.jsx                    - Payments for specific class
```

### Student Dashboard
```
/app/(protected)/dashboard/student/payments/
  page.jsx                    - List of registered payments
  register/
    page.jsx                  - Payment registration form
```

## Payment Flow Diagram

```mermaid
sequenceDiagram
    participant G as Guardian/Student
    participant UI as UI Component
    participant API as API Route
    participant DB as Database
    participant FS as File Storage

    G->>UI: Submit payment form (amount, date, receipt)
    UI->>API: POST /api/payments
    API->>DB: Create payment record (status: pending)
    API->>FS: Upload receipt image
    API->>DB: Update payment with receipt URL
    API-->>UI: Return payment confirmation
    UI-->>G: Show success message

    Note over Admin: Admin views dashboard
    Admin->>UI: View payments dashboard
    UI->>API: GET /api/payments
    API-->>UI: Return all payments
    UI-->>Admin: Display payment table with status
```

## Class View Integration

### Guardian Class Detail Page
- Add payment status indicator
- Show "Register Payment" button if not paid
- Show payment history for the class

### Admin Class View
- Show payment status for all students
- Filter by payment status
- Quick actions to verify/reject payments

## Implementation Steps

### Phase 1: Database & API
1. Create Payment model
2. Create API routes for payment CRUD operations
3. Integrate with existing file upload system

### Phase 2: Admin Dashboard
1. Create payments dashboard page
2. Build payments table with filtering
3. Add payment detail modal
4. Implement verify/reject functionality

### Phase 3: Guardian/Student Interface
1. Create payment registration form
2. Build payment history view
3. Integrate receipt upload
4. Add payment status indicators

### Phase 4: Integration
1. Update class detail pages
2. Add payment status to class cards
3. Add payment reminders (optional)

## Security Considerations
- **Role-Based Access Control**: Only admins can view payment details
- **Data Validation**: Validate payment amounts and dates
- **File Upload Security**: Validate receipt images before storing
- **User Authorization**: Users can only register payments for their own classes

## Data Validation Rules
- Amount: Must be positive number
- Payment Date: Must be in the past or present
- Receipt: Max file size, allowed image formats only
- Payment Method: Must be from predefined list

## Status Workflow
```
Pending (default) → Verified (admin approves) → Rejected (admin rejects)
```

## Future Enhancements
- Payment reminders for pending payments
- Payment history export
- Bulk payment verification
- Payment analytics and reports
- Integration with payment gateways (optional)