# Architecture

**Analysis Date:** 2026-02-13

## Pattern Overview

**Overall:** MVC (Model-View-Controller) with Service Layer for complex business logic

**Key Characteristics:**
- **Layered architecture**: Controllers → Services → Models → Traits
- **Multi-tier approval workflows**: Amount-based approval hierarchy (Secretary → Chair → Board)
- **Double-entry bookkeeping**: Automatic accounting entry generation for financial documents
- **Trait-based shared behavior**: Cross-cutting concerns (approval workflow, accounting entries)
- **Audit logging**: Centralized action tracking via `AuditLogger::log()`
- **Role-based access control (RBAC)**: Spatie Laravel Permission with financial roles

## Layers

**Presentation Layer:**
- Purpose: Render web UI and handle HTTP requests
- Location: `resources/views/`, `app/Http/Controllers/`
- Contains: Blade templates, controllers, Form Requests, API Resources
- Depends on: Models, Services, View Components
- Used by: Web browsers, Next.js frontend (via API)

**Controller Layer:**
- Purpose: HTTP request handling, input validation, orchestration
- Location: `app/Http/Controllers/`
- Contains: Controllers split by domain (Admin, Auth, Api)
- Depends on: Models, Services, Form Requests
- Pattern: Validation via Form Request classes (e.g., `StoreFinanceDocumentRequest`), service calls for business logic

**Service Layer:**
- Purpose: Encapsulate complex business logic
- Location: `app/Services/`
- Contains: `FinanceDocumentApprovalService`, `MembershipFeeCalculator`, `SettingsService`, `PaymentVerificationService`, `SiteRevalidationService`
- Depends on: Models, Audit Logger, Mail
- Example: `FinanceDocumentApprovalService` orchestrates multi-tier approval workflow; returns `['success' => bool, 'message' => string, 'complete' => bool]`

**Model Layer:**
- Purpose: Data access, business rules, relationships
- Location: `app/Models/`
- Contains: 36 Eloquent models including `Member`, `FinanceDocument`, `User`, `Issue`, `Article`, `Document`
- Depends on: Database, Traits
- Key models and relationships documented in Finance Workflow section

**Trait Layer:**
- Purpose: Shared behavior across multiple models
- Location: `app/Traits/`
- Contains: `HasApprovalWorkflow`, `HasAccountingEntries`
- Usage: Models use these traits to inherit approval/accounting behavior without duplication

**Support Layer:**
- Purpose: Utility functions and helper classes
- Location: `app/Support/`
- Contains: `AuditLogger` (centralized audit logging), `DownloadFile` (file download handler)
- Global helper: `settings('key')` function in `app/helpers.php` — returns cached system settings

## Data Flow

### Member Lifecycle Flow

1. **Registration**: Non-member completes form at `/register/member` → stored in `Members` table with `status = pending`
2. **Profile Activation**: Member logs in, fills profile at `/create-member-profile`
3. **Payment Submission**: Member submits payment proof at `/member/submit-payment` → `MembershipPayments` table
4. **Payment Verification**: Admin verifies payment via multi-tier approval workflow
5. **Activation**: Admin activates member → `status = active`, `membership_expires_at` set
6. **Expiry**: Cron job or admin action → `status = expired` when `membership_expires_at` passes

**Key Methods:**
- `Member::hasPaidMembership()` — checks if active with future expiry
- `Member::canSubmitPayment()` — validates pending status with no pending payments
- `Member::getNextFeeType()` — returns entrance_fee or annual_fee

### Finance Document Approval Flow (3-Stage Lifecycle)

#### Stage 1: Approval (Amount-Based Multi-Tier)

1. **Submission**: User submits finance document → `FinanceDocument::STATUS_PENDING`
   - `submitted_by_user_id`, `submitted_at`, `amount`, `title` set
   - Amount tier auto-determined: `determineAmountTier()` → small/medium/large

2. **Secretary Approval**: Secretary reviews → `approveBySecretary()`
   - For small amount (<5,000): Approval complete, notifies submitter
   - For medium/large: Escalates to Chair, notifies next approvers
   - Status: `STATUS_APPROVED_SECRETARY`

3. **Chair Approval**: Chair reviews (if amount ≥ 5,000) → `approveByChair()`
   - For medium amount (5,000-50,000): Approval complete
   - For large amount (>50,000): Escalates to Board, notifies board members
   - Status: `STATUS_APPROVED_CHAIR`

4. **Board Approval**: Board members review (if amount > 50,000) → `approveByBoard()`
   - Final approval stage
   - Status: `STATUS_APPROVED_BOARD`

**Rejection Handling**: User can reject at any stage → `STATUS_REJECTED`, triggers email notification

**Helper Methods**:
```php
$doc->isApprovalComplete()      // All required approvals obtained
$doc->canBeApprovedBySecretary($user)  // Validates secretary can approve
$doc->canBeApprovedByChair($user)      // Validates chair can approve
$doc->getAmountTierLabel()      // Returns 小額/中額/大額
```

#### Stage 2: Disbursement (Dual Confirmation)

1. **Requester Confirmation**: Document requester confirms disbursement details
   - `DISBURSEMENT_REQUESTER_CONFIRMED` status
   - Field: `disbursement_requester_confirmed_at`

2. **Cashier Confirmation**: Cashier verifies funds transferred
   - `DISBURSEMENT_CASHIER_CONFIRMED` status
   - Field: `disbursement_cashier_confirmed_at`
   - Creates `PaymentOrder` record

3. **Completion**: Once both confirm → `DISBURSEMENT_COMPLETED`

**Helper**: `$doc->isDisbursementComplete()` — both parties confirmed

#### Stage 3: Recording (Ledger Entry)

1. **Cashier Ledger Entry**: Cashier records transaction to ledger
   - Creates `CashierLedgerEntry` with debit/credit amounts
   - Status: `RECORDING_PENDING` → `RECORDING_COMPLETED`

2. **Accounting Entry**: Automatic double-entry bookkeeping via `HasAccountingEntries` trait
   - Creates `AccountingEntry` records (debit + credit pair)
   - Account codes from `config/accounting.php`
   - Field: `chart_of_account_id`

**Helper**: `$doc->isRecordingComplete()` — ledger entry created

**Full Completion**: `$doc->isFullyProcessed()` — all three stages complete

---

### Payment Verification Flow

Separate approval workflow for `MembershipPayments` with three tiers:

1. **Cashier Approval**: Verifies payment received
2. **Accountant Approval**: Validates accounting entry
3. **Chair Approval**: Final sign-off for large payments

**Route**: `/admin/payment-verifications` with status-based filtering

---

### CMS Content Flow (Articles/Pages)

1. **Creation**: Admin creates article at `/admin/articles/create` with:
   - Title, slug, body (markdown via EasyMDE), featured image, status
   - Categories and tags (many-to-many relationships)

2. **Publication**: Admin publishes → `status = published`, `published_at` set

3. **API Exposure**: Content available via `/api/v1/articles`, `/api/v1/pages`

4. **Site Revalidation**: On publish/archive, fires webhook to Next.js for static site rebuild
   - Service: `SiteRevalidationService`
   - Webhook: POST to `services.nextjs.revalidate_url` with token

---

### Document Library Flow

1. **Upload**: Admin uploads document at `/admin/documents/create`
   - Creates `Document` with `status = active`
   - Multiple versions tracked via `DocumentVersion` table

2. **Version Control**:
   - New version upload creates `DocumentVersion` record
   - Promote version: sets as current version
   - Archive: soft delete via `status = archived`

3. **Public Access**: Documents visible at `/documents` if `access_level` allows
   - Access tracking via `DocumentAccessLog`
   - QR code generation at `/documents/{uuid}/qrcode`

4. **Permission Check**:
   - Method: `$doc->canBeViewedBy($user)` validates access
   - Visibility: public, members-only, or admin-only

---

**State Management:**

- **Status Fields**: Use class constants, not enums (e.g., `FinanceDocument::STATUS_PENDING`)
- **Timestamps**: Created/updated via timestamps; specific approval/rejection times via explicit fields
- **Soft Deletes**: Used for documents (`status = archived`), not traditional soft delete
- **Transactions**: DB transactions wrap multi-step operations (approval, payment, recording)

## Key Abstractions

**HasApprovalWorkflow Trait:**
- Purpose: Provides reusable multi-tier approval methods
- Files: `app/Traits/HasApprovalWorkflow.php`
- Used by: `FinanceDocument`, `MembershipPayment`, `Budget`
- Methods: `isSelfApproval()`, `canProceedWithApproval()`, `canBeRejected()`, `getApprovalHistory()`
- Pattern: Models define STATUS_* constants; trait provides helper methods; services orchestrate workflow

**HasAccountingEntries Trait:**
- Purpose: Automatic double-entry bookkeeping
- Files: `app/Traits/HasAccountingEntries.php`
- Used by: `FinanceDocument`, `Income`, `Transaction`
- Methods: `debitEntries()`, `creditEntries()`, `validateBalance()`, `autoGenerateAccountingEntries()`
- Pattern: Account IDs from `config/accounting.php`; amount tier determines debit/credit mapping

**Audit Logging:**
- Purpose: Track all business-critical actions
- Class: `app/Support/AuditLogger`
- Usage: `AuditLogger::log('finance_document.approved_by_secretary', $document, ['approved_by' => $user->name])`
- Storage: `AuditLog` model with JSON metadata
- Pattern: Static method callable from anywhere; filters secrets/uploads

**Settings Service:**
- Purpose: Centralized system configuration
- File: `app/Services/SettingsService`
- Usage: `settings('membership.entrance_fee')` or `settings('key', 'default')`
- Cache: Redis/cache layer to avoid repeated DB queries
- Locations: `SystemSetting` model, `config/` files

## Entry Points

**Web Routes:**
- Location: `routes/web.php` (393 lines covering all web endpoints)
- Public: `/`, `/register/member` (if enabled), `/documents`
- Authenticated: `/dashboard`, `/my-membership`, `/member/submit-payment`
- Admin: `/admin/*` with `admin` middleware and named route prefix `admin.{module}.{action}`

**API Routes:**
- Location: `routes/api.php`
- Version: v1 prefix
- Endpoints: `/api/v1/articles`, `/api/v1/pages`, `/api/v1/homepage`, `/api/v1/public-documents`
- Authentication: Sanctum (optional for public endpoints)

**Artisan Commands:**
- Location: `app/Console/Commands/`
- Custom commands: `assign:role`, `import:members`, `import:accounting-data`, `import:documents`, `send:membership-expiry-reminders`, `archive:expired-documents`

**Auth Routes:**
- Location: `routes/auth.php`
- Includes: Login, registration (if enabled), password reset, email verification
- Middleware: `auth`, `verified`

## Error Handling

**Strategy:** Exception-based with Blade error views

**Patterns:**
- **Form validation errors**: Automatically displayed in Blade templates via `@error` directive
- **Authorization errors**: Thrown by `@can` directive or `authorize()` in controllers
- **Business logic errors**: Services return `['success' => false, 'message' => 'reason']` or throw exceptions
- **Audit logging errors**: Wrapped in try-catch to prevent breaking main flow
- **Exception handling**: `app/Exceptions/Handler.php` defines response rendering

**File uploads:**
- Stored in `storage/app/` (private by default)
- Finance documents: `storage/app/finance-documents/`
- Article uploads: `storage/app/articles/`
- Disability certificates: `storage/app/disability-certificates/`

## Cross-Cutting Concerns

**Logging:**
- Framework: Laravel's default logging (PSR-3 via Monolog)
- Audit trail: `AuditLogger` class for business actions
- Config: `config/logging.php`

**Validation:**
- Location: `app/Http/Requests/` — Form Request classes enforce rules
- Pattern: Controller calls `$request->validated()` after implicit validation
- Examples: `StoreMemberRequest`, `StoreFinanceDocumentRequest`, `UpdateMemberRequest`

**Authentication:**
- Framework: Laravel Breeze (session-based)
- Models: `User` model with `HasFactory` and relationships to roles/permissions
- Guards: `web` (default for sessions), `sanctum` (for API)

**Authorization:**
- Framework: Spatie Laravel Permission
- Roles: `admin`, `finance_requester`, `finance_cashier`, `finance_accountant`, `finance_chair`, `finance_board_member`, `membership_manager`
- Permissions: `view_*`, `create_*`, `edit_*`, `delete_*`, `publish_*`, custom permissions for finance tiers
- Checking: `$user->can('permission-name')` in controllers, `@can` in Blade

**Encryption:**
- National IDs: AES-256 encrypted in `national_id_encrypted` column
- Hash for searching: SHA256 in `national_id_hash` column
- Virtual accessor `national_id`: Auto-decrypts on read
- Method: `Member::findByNationalId($id)` uses hash for query

---

*Architecture analysis: 2026-02-13*