course-plat/plans/payment-system-architecture.md

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

{
  _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

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)