# SCHOWANA — MASTER CONTEXT (put this in CLAUDE.md at repo root)

**Product:** SCHOWANA — "The Digital Operating System for Schools". School Management Platform for Botswana, architected to grow School → Cluster → District → Region → National.
**Goal now:** a demo that looks and behaves like a real commercial/government-grade product, NOT a CRUD template.

## Hard constraints
- PHP 8.x, MySQL/MariaDB, Bootstrap 5, vanilla JS (fetch/AJAX), light charts lib (Chart.js). Runs on cPanel shared hosting: upload to `public_html/`, import SQL. No Node server, Docker, Redis, queues, VPS services.
- Config via `.env` outside web root or protected; `/install` wizard.
- Languages: English (`en`) + Setswana (`tn`). Zero hard-coded UI text; keys like `student.date_of_birth` in `/lang/en.php`, `/lang/tn.php`. Language switcher always visible, persisted. RTL/LTR-ready CSS (logical properties).
- Currency BWP, timezone Africa/Gaborone — stored in config tables, never hard-coded.

## Architecture rules
- Modular: `/app` (Controllers, Models, Services, Repositories, Middleware, Helpers, Workflows), `/modules/<name>`, `/public`, `/storage`, `/lang`, `/database`. No giant files. Front controller + router.
- **Multi-tenant from day one:** every business table has `organization_id` and `school_id`. `organizations` is a tree (`parent_id`, `level` = national/region/district/cluster/school, `path`). Never assume a single school.
- **RBAC:** permissions as `module.action` (view, create, edit, delete, approve, print, export, manage). Check in middleware AND service layer. Roles: super_admin, national_admin, district_admin, school_admin, principal, vice_principal, teacher, accountant, hr_officer, admissions_officer, librarian, transport_manager, hostel_manager, parent, student.
- **Simple CRUD vs workflow:** plain entities are plain CRUD. Real processes (admission, transfer, marks publication, procurement, maintenance, HR requests) use: status + task + assignee + due date + approval + notification + audit + history. Do not over-workflow simple things.
- **Security:** password_hash, PDO prepared statements only, CSRF tokens, output escaping, secure sessions + timeout, upload validation (MIME, size, extension, stored outside web root), login rate limit, login audit, secure reset. Never show raw errors: "Something went wrong. Reference ID: XXXX" + log details.
- **Audit log:** append-only, no UI edit/delete. Fields: user, action, module, record, ip, old/new value, timestamp. Written through one `AuditService`.
- **Provider abstraction:** SMS / WhatsApp / Email / Payment behind interfaces with a Demo provider. UI must show "Demo". Never pretend real sending or real money.
- **API-ready:** services return data; controllers/JSON endpoints under `/api/*` reuse them. Token auth stub only.
- **Performance:** paginate everything, index FKs and filter columns, no N+1, no polling, small assets.
- **UX:** sidebar + topbar + breadcrumbs, cards, filterable tables, modals/drawers, status badges, notifications, timelines. Serious, clean, not childish, not a generic admin template. Mobile-first (attendance + parent portal especially). Accessible (keyboard, labels, contrast).

## Honesty rule (critical)
Every feature is labelled in docs and UI as **Implemented / Demo Simulation / Future Integration**. Never claim something works if it is only visual. All government-level data is labelled **DEMO / FICTIONAL DATA**. All people are fictional.

## Definition of Done (per module)
UI + create + edit + view + search/filter + pagination + permissions + validation + audit + demo data + print (where relevant) + mobile layout + EN/TN strings + error handling. A DB table alone is not "done".

## Working protocol (every phase)
1. Read this file and `STATUS.md` first.
2. Do ONLY the phase file you were given. No future-phase work except schema hooks explicitly listed.
3. Seed demo data for what you build (generator script, not hand-written SQL).
4. Run the phase's acceptance checks; fix failures.
5. Update `STATUS.md` (tick items, list limitations, note decisions).
6. Finish with a report: files created/modified, DB changes, features done (Implemented/Demo/Future), demo credentials, test scenarios run, known limitations, next phase.

## Phase files
P1 Foundation · P2 Core School · P3 Academic · P4 Finance · P5 Communication & Parent Portal · P6 Workflow/Tasks/Audit/Search · P7 Reports, Print, Import/Export, Full Seed · P8 Optional Modules · P9 Offline · P10 National Demo