# System Architecture and Module Map

## Architectural style

Use a tenant-aware modular monolith deployed as a stateless Laravel web application,
with queue workers, scheduler, Redis, MySQL, and private object storage. A modular
monolith is preferable initially because admissions, finance, registration, results,
and graduation share strong transactional boundaries. Modules communicate through
application actions and domain events, not cross-module controller calls.

```text
Browser / Mobile Web
        |
 CDN / WAF / TLS / Rate Limiting
        |
 Laravel Web + JSON endpoints
   |        |          |
 MySQL    Redis     Object Storage
   |        |          |
 Scheduler + Queue Workers
        |
 Payment / Email / SMS / Meeting adapters
```

### Runtime responsibilities

- **Web nodes:** authentication, policy checks, validation, HTML/API responses.
- **MySQL:** source of truth for transactional and auditable records.
- **Redis:** cache, queues, sessions, distributed locks, rate limits, and short-lived
  CBT state. Redis is never the sole durable store for submitted examination answers.
- **Workers:** notifications, imports/exports, PDFs, media processing, reports, and
  webhook follow-up.
- **Scheduler:** exam closure, reminders, overdue invoices, publication jobs, backup
  checks, and cleanup.
- **Object storage:** private documents, learning materials, submissions, media, and
  generated records.

## Module map

| Domain | Responsibilities | Key dependencies |
|---|---|---|
| Tenancy & Settings | institutions, campuses, branding, terminology, feature flags | Identity, Audit |
| Identity & Access | users, authentication, MFA readiness, roles, permissions, sessions, suspension | Tenancy, Audit |
| Organization | faculties, colleges/schools, departments, study centres | Tenancy |
| Academic Calendar | sessions, semesters, levels, calendars, deadlines | Tenancy |
| Admissions | forms, applications, documents, reviews, interviews, offers, onboarding | Programmes, Finance, Identity |
| People | students, guardians, sponsors, staff, status histories, restricted records | Identity, Organization |
| Programmes & Curriculum | awards, programmes, options, courses, curriculum versions, prerequisites, allocations | Academic Calendar |
| Registration | course selection, rules, overrides, approvals, financial clearance | Curriculum, Results, Finance |
| LMS | classrooms, modules, materials, discussions, progress, acknowledgements | Registration, Files |
| Assignments | assignments, rubrics, versioned submissions, grading, review | LMS, Results |
| Live Learning | meetings, reminders, check-in, recordings | LMS, Attendance, Communications |
| CBT | question bank, exams, eligibility, attempts, answers, marking, incidents | Registration, Results, Audit |
| Results | score batches, approvals, publishing, grade scales, GPA/CGPA | Curriculum, CBT, Audit |
| Finance | fees, invoices, ledger, payments, gateways, refunds, reconciliation | People, Admissions, Audit |
| Records | transcript requests, transcripts, certificates, verification | Results, Finance, Graduation |
| Attendance | course, chapel, online, exam, fieldwork, and staff attendance | People, Academic Calendar |
| Formation | ministry, chapel, pastoral assessment, placements, recommendations | People, restricted permissions |
| Research | thesis/dissertation, versions, supervision, ethics, defence, repository | People, Programmes, Files |
| Library | resource catalogue, access grants, views/downloads | Identity, Registration |
| Clearance & Graduation | clearance stages, eligibility rules, graduation cohorts | Results, Finance, Research |
| CMS | public pages, posts, menus, events, downloads, SEO | Tenancy, Files |
| Communications | announcements, messages, preferences, mandatory notifications | Identity, queues |
| Reporting | operational dashboards, exports, regulatory datasets | read models across domains |
| Audit & Compliance | immutable audit trail, activity/security events, retention | every module |

## Dependency rules

1. Domain services and actions may depend on contracts, not provider SDKs.
2. Controllers validate input then call one application action.
3. Cross-domain state changes emit events after the database transaction commits.
4. Reporting queries may read multiple domains but cannot mutate them.
5. Tenant context is resolved before model binding and authorization.
6. Direct writes to finance ledger, published results, transcripts, certificates,
   examination submissions, and audit logs are prohibited outside approved actions.

## Folder structure

```text
app/
├── Domain/
│   ├── Admissions/
│   ├── Audit/
│   ├── CBT/
│   ├── Curriculum/
│   ├── Finance/
│   ├── Identity/
│   ├── LMS/
│   ├── Organization/
│   ├── People/
│   ├── Records/
│   ├── Registration/
│   ├── Research/
│   ├── Results/
│   └── Tenancy/
│       └── {Actions,Data,Enums,Events,Models,Policies,Services}/
├── Http/
│   ├── Controllers/{Admin,Applicant,Public,Staff,Student}/
│   ├── Middleware/
│   └── Requests/
├── Infrastructure/
│   ├── Audit/
│   ├── Files/
│   ├── Payments/
│   ├── PDF/
│   └── Tenancy/
├── Jobs/
├── Listeners/
├── Livewire/
├── Notifications/
└── Providers/
```

## Non-functional targets

- Responsive, accessible server-rendered UI with progressive enhancement.
- Pagination and eager loading by default; no unbounded administrative listings.
- Queue long-running work and expose job status.
- Idempotent integrations and retry-safe jobs.
- Structured logs with correlation IDs, without secrets or sensitive answers.
- Point-in-time database recovery and versioned object storage in production.
- Horizontal web/worker scaling without sticky application state.

## Architectural decision records to create during implementation

- ADR-001 tenancy resolution (subdomain, custom domain, or explicit selection).
- ADR-002 database-per-tenant threshold and migration path.
- ADR-003 PDF rendering engine after transcript/certificate template prototype.
- ADR-004 object storage and malware-scanning provider.
- ADR-005 real-time transport requirements for CBT and notifications.