# Southend School — Module Integration Report

## Integration Architecture

```mermaid
flowchart LR
    subgraph school [School Layer]
        Students
        Staff
        Attendance
        Results
    end

    subgraph finance [Finance Layer]
        Invoices
        Receipts
        Expenses
        Billing
    end

    subgraph accounting [Accounting Core]
        COA
        Journal
        GL
        TB
    end

    subgraph portals [Portals]
        Admin
        Teacher
        Parent
    end

    Students --> Billing
    Billing --> Invoices
    Invoices --> Journal
    Receipts --> Journal
    Expenses --> Journal
    Journal --> GL
    GL --> TB
    TB --> Reports

    Students --> Parent
    Staff --> Teacher
    Attendance --> Parent
    Results --> Parent
    Invoices --> Parent
```

## Cross-Module Connections

### Student Management ↔ Finance
- `Student` has many `Invoice`, `Receipt`, `PaymentAllocation`
- `BillingService::assignFee()` → `InvoiceService::issue()` → `JournalService::post()`
- Parent `FeeController` reads `BillingService::studentStatement()` scoped to guardian's children
- Parent `storePay()` creates pending `Payment` linked to invoice for finance reconciliation

### Student Management ↔ Academics
- `GradebookEntry` linked to `Student`, `Assessment`, `Subject`, `Term`
- `ResultsCompilation` aggregates gradebook data → `ReportCard` → parent portal (published only)

### Staff ↔ Teacher Portal
- `User.staff_id` links login to `Staff` record
- Teacher routes filter by `SchoolClass.class_teacher_id`
- `AuthorizesTeacherClass` trait enforces class access on POST actions

### Parent ↔ Guardian
- `Guardian.user_id` links parent login to guardian record
- All parent controllers filter via `$guardian->students()`

### Finance ↔ Accounting
- Every financial write goes through `JournalService`
- `AccountBalanceService` computes balances from posted journal lines only
- `FinancialReportService` generates income statement, balance sheet, cashflow from journal data
- `TrialBalanceService` feeds all financial reports

### Analytics ↔ All Modules
- `AnalyticsService` queries live tables: `Invoice`, `Receipt`, `JournalLine`, `Student`, `Staff`, `AttendanceRecord`, `FixedAsset`
- No hardcoded dashboard numbers

## Database Relationship Summary

| From | To | Relationship |
|------|-----|--------------|
| User | Staff | belongsTo |
| User | Guardian | hasOne |
| Guardian | Student | belongsToMany |
| Student | SchoolClass | belongsTo |
| Student | Invoice | hasMany |
| Invoice | InvoiceLine | hasMany |
| InvoiceLine | Account | belongsTo (income) |
| Receipt | JournalEntry | via ReceiptService |
| JournalEntry | JournalLine | hasMany |
| JournalLine | Account | belongsTo |
| Staff | SchoolClass | hasMany (class_teacher) |
| Assessment | GradebookEntry | hasMany |

## API Integration

Sanctum-authenticated REST at `/api/*`:
- Auth: login, logout, me
- Resources: students, staff, invoices, receipts, payments, attendance, results, analytics summary
- Permission middleware on all endpoints

## Audit & Observability

- `Auditable` trait on sensitive models → `audit_logs` table
- `SouthendAuditCommand` validates nav routes, journal balance, OBE equity
- Dashboard surfaces overdue invoices, pending expenses, pending result submissions

## Test Coverage

| Test | Integration verified |
|------|---------------------|
| FeeWorkflowTest | Student → invoice → receipt → AR reduced → journal balanced |
| JournalBalanceTest | Unbalanced entries rejected |
| RolePermissionTest | RBAC on admin routes |
| TeacherPortalTest | Class scoping, finance 403 |
| ParentPortalTest | Child-only access |
| PermissionIntegrationTest | Bursar/Auditor/Teacher boundaries |
| CashflowReportTest | Financial report route |
| AnnouncementTest | Communications CRUD |