# 🧠 Project Brain

**The map of this project.** Start here to find any feature, its current
version, its integration doc, and where its updates are recorded.

| | |
|---|---|
| Product | **Morvia** (`APP_NAME`) — Saudi training-courses platform: trainees find, pay for and attend in-person or external courses from independent trainers and training centers; halls & events, cashback / points, jobs, central admin. |
| Backend | Laravel 13 API (this repo), PHP 8.3+, JWT (`tymon/jwt-auth`, guard `api`) |
| Apps | Trainee app (Flutter, `client`) · Trainer app (Flutter, `trainer`) · Admin (Vue, `admin`) · Training center (Vue, `center`) · Hall & event provider (Vue, `provider`) — source: `config/docs.php` → `surfaces` (TD-07) |
| BRD in force | **BRD v1.0 (11-8-2026) + additional requirements (7-10-2026, notes 18-10 / 22-10) + cancellation policy (10-11-2026)** → working file [`brd/BRD-Morvia-Project-Guide-en.md`](brd/BRD-Morvia-Project-Guide-en.md); per feature: [`brd/features/`](brd/features/INDEX.md). |
| Screens | [32 design exports indexed](app_screens/INDEX.md): 14 trainee, 13 individual trainer, 5 academy trainer; trainer API surface not yet defined. |
| Data model | Base tables only (migrations in `database/migrations`). Target schema (final, 2026-11-12): [`database/db-schema.sql`](database/db-schema.sql) (78 tables) + [`schema-design.md`](database/schema-design.md); write migrations from it. |
| Current phase | **Phase 0 → 1.** BRD ingested (148 features, D1–D9, DEC-01…34); target database schema final (TD-10…13); no BRD feature is built. |
| Brain last updated | 2026-11-12 — cancellation policy ingested (D5–D9); 15 DECs answered by the owner; DEC-33, TD-09. History: [CHANGELOG.md](CHANGELOG.md). |

---

## 1. How to use this file

**To find what changed in a feature:** find it in the [registry](#4-feature-registry)
→ open its doc → read *Version history* (summary) and *Changelog* (details).

**To see everything that changed recently:** [CHANGELOG.md](CHANGELOG.md) (newest first).

**To know why something behaves the way it does:** the feature doc's BRD IDs →
the BRD in [`brd/`](brd/README.md) → [DECISIONS.md](DECISIONS.md).

**Before building a feature (agents) — cheapest path first:**
1. **`php artisan docs:brief {surface} {feature}`** (MCP: `get-integration-brief`). One call
   returns the registry row and status, the feature doc's Quick reference, the BRD section
   with its AC / BR rows, and the decisions it cites. Stop here if it is enough.
2. Need more of the feature doc? Read one section: MCP `read-doc` with `outline=true`, then
   `section="…"` — or `grep -n "^## " docs/{surface}/{slug}.md` and read that range.
3. Need more of the BRD? `docs/brd/features/{ID}.md` (one feature, written by
   `php artisan docs:split-brd`). Never open the whole BRD.
4. A decision's *why*: `grep -n "DEC-05" docs/DECISIONS_LOG.md`.
5. Screens: read the feature's lines in [`app_screens/INDEX.md`](app_screens/INDEX.md) first;
   open an image only when the line is not enough.
6. Build following `.kiro/steering/*`, then write the doc and update this registry
   + `CHANGELOG.md` (rules: `.kiro/steering/feature-documentation.md`).
7. Regenerate the Postman collection (`php artisan postman:generate`) for every touched route.

### Reading budget (save tokens)

Never read a big file end to end. Limits are enforced by `DocsBudgetTest` (`config/docs.php` → `budgets`).

| Source | Read only | How |
|--------|-----------|-----|
| Feature brief | Everything needed to start | `php artisan docs:brief client auth` |
| This file | The feature's registry row (§4) | `grep -n "auth.md" docs/PROJECT_BRAIN.md` |
| Feature doc `docs/{surface}/{slug}.md` | Quick reference, then one section at a time | `read-doc` `section` / `outline` |
| BRD | One feature file | `docs/brd/features/{ID}.md`; list: `docs/brd/features/INDEX.md` |
| `DECISIONS.md` | The rows the feature cites (one short line each) | `grep -n "DEC-05\|TD-03" docs/DECISIONS.md` |
| `DECISIONS_LOG.md` | One entry, only for *why/when* | `grep -n -A6 "— DEC-05" docs/DECISIONS_LOG.md` |
| `CHANGELOG.md` | The newest lines | `head -30 docs/CHANGELOG.md` |
| `app_screens/` | The feature's index lines, then at most its images | `grep -n "client--auth" docs/app_screens/INDEX.md` |
| `database/db-schema.sql` (if present) | The tables the feature names | `grep -n "CREATE TABLE <name>" docs/database/db-schema.sql` |
| `.kiro/steering/*.md` | Only the files for the task | `CLAUDE.md` → *Load on demand* |

**Write rules that keep reads cheap:** one short line per registry / decision /
changelog row (detail goes to the feature doc or `DECISIONS_LOG.md`); every feature doc
opens with a Quick reference; keep 5 version rows in a doc and move older ones to
`docs/{surface}/_history/{slug}.md`.

---

## 2. Surfaces (guards) and consumers

Source of truth: `config/docs.php` → `surfaces` (written by `project-init`).
Rules for each surface: `.kiro/steering/api-surfaces.md`.

| Surface | Consumer app | Tech | Guard | URL prefix | Route files | Docs folder |
|---------|--------------|------|-------|------------|-------------|-------------|
| `admin` | Admin dashboard | Vue | `api` (JWT) + `active` + `rbac.auto` | `/api/v1/admin/` | `routes/api/v1/admin.php` | [admin/](admin/README.md) |
| `client` | Trainee app | Flutter | `api` (JWT) + `active` | `/api/v1/client/` | `routes/api/v1/client.php`, `guest.php` (public) | [client/](client/README.md) |
| `trainer` | Trainer app (independent + affiliated) | Flutter | `api` (JWT) + `active` | `/api/v1/trainer/` | `routes/api/v1/trainer.php` | [trainer/](trainer/README.md) |
| `center` | Training center dashboard | Vue | `api` (JWT) + `active` | `/api/v1/center/` | `routes/api/v1/center.php` | [center/](center/README.md) |
| `provider` | Hall & event provider dashboard | Vue | `api` (JWT) + `active` | `/api/v1/provider/` | `routes/api/v1/provider.php` | [provider/](provider/README.md) |
| `shared` | All apps | — | per route | `/api/v1/` | `routes/api/v1/shared.php` | [API_CONVENTIONS.md](API_CONVENTIONS.md) |

---

## 3. Sources of truth and documentation map

Priority when sources disagree (details: `.kiro/steering/business-logic.md`):
**DECISIONS.md → target schema (if any) → working BRD → original BRD → screens.**

```
docs/
├── QUICK_SETUP.md          # first-time setup: .env, secrets, database, agents
├── PROJECT_BRAIN.md        # this file — feature registry, surfaces, phases
├── DECISIONS.md            # client decisions (D-n), BRD gaps (DEC-xx), technical (TD-xx)
├── CHANGELOG.md            # every feature-doc version, newest first
├── API_CONVENTIONS.md      # envelope, errors, pagination, headers, Flutter/React setup
├── ARCHITECTURE.md         # base architecture (layers, pipelines, RBAC, caching)
├── MCP_AGENT_GUIDE.md      # how app teams connect their coding agent to `project-docs`
├── MCP_APP_TEAM_KIT.md     # copy-paste MCP setup + rules block for the Flutter / Vue teams
├── AGENT_SETUP.md          # steering files, skills, Codex rules, MCP servers, commands
├── _templates/             # feature-flutter.md, feature-react.md
├── admin/ client/ trainer/ center/ provider/  # one folder per surface: README.md + {feature}.md
├── brd/                    # business requirements (input, read-only)
├── app_screens/            # screen exports per surface (input, read-only)
└── postman-collection.json # generated by `php artisan postman:generate` — never hand-edited
```

---

## 4. Feature registry

Filled from the BRD guide at ingest (2026-11-11). One table per surface; one row per feature doc; a doc may cover several BRD IDs.

Row format — the docs MCP server parses these tables, keep the 9 columns:
`| Doc | Feature | BRD IDs | Module | Phase | Status | Version | Updated | Screens |`

- **Doc:** the path in backticks while only reserved (`` `client/auth.md` ``) → a markdown link to the file once it is written.
- **Status:** `planned` · `in-progress` · `ready` · `base (TD-xx)` (base endpoints documented at 0.x) · `deferred (TD-xx)` · `deprecated`.
- **Version / Updated:** `—` until the doc exists.
- **Screens:** file pattern in `app_screens/`, e.g. `` `client--auth--*` (3) ``, or `—`.

### 4.1 Admin — Admin dashboard (Vue)

| Doc | Feature | BRD IDs | Module | Phase | Status | Version | Updated | Screens |
|-----|---------|---------|--------|-------|--------|---------|---------|---------|
| [admin/auth.md](admin/auth.md) | Admin login | ADM-001 | Accounts | 1 | in-progress | 0.2.0 | 2026-11-15 | — |
| [admin/dashboard.md](admin/dashboard.md) | Home indicators | ADM-002 | Reports | 1 | in-progress | 0.1.1 | 2026-11-15 | — |
| `admin/users.md` | All users, trainee details | ADM-003, ADM-004 | Accounts | 1 | planned | — | — | — |
| [admin/trainers.md](admin/trainers.md) | Independent + affiliated trainers, account review | ADM-005, ADM-006, ADM-007, ADM-008 | Accounts | 1 | ready | 1.0.1 | 2026-11-15 | — |
| [admin/centers.md](admin/centers.md) | Training centers, move an affiliated trainer | ADM-009, ADM-010, ADM-011, ADM-012, ADM-008; DEC-16, DEC-20 | Centers | 1 | ready | 1.0.0 | 2026-11-15 | — |
| [admin/courses.md](admin/courses.md) | Courses: list, review, edits, details, completion, cancellation, threshold cases | ADM-025, ADM-026, ADM-027, ADM-028, ADM-029, ADM-030, ADM-031, ADM-032; D1, D2, D4, DEC-12 | Courses | 1 | ready | 1.0.0 | 2026-11-15 | — |
| `admin/packages.md` | Course packages | ADM-013, ADM-014; DEC-21 | Packages | 1 | planned | — | — | — |
| `admin/enrollments.md` | Enrollments | ADM-033, ADM-034 | Enrollment | 1 | planned | — | — | — |
| `admin/payments.md` | Payments | ADM-035, PLT-002; DEC-06 | Finance | 1 | planned | — | — | — |
| [admin/trainer-finance.md](admin/trainer-finance.md) | Trainer plans, commission, subscriptions (entitlements ADM-037/038 later) | ADM-036, ADM-037, ADM-038; DEC-15, DEC-23 | Finance | 1 | in-progress | 1.1.0 | 2026-11-15 | — |
| `admin/loyalty.md` | Cashback, points, levels | ADM-039, ADM-040, ADM-041; D4, DEC-24, DEC-25, DEC-26 | Loyalty | 1 | planned | — | — | — |
| [admin/hall-providers.md](admin/hall-providers.md) | Providers, hall features, halls, hall commission rate | ADM-015, ADM-016, ADM-017; DEC-14 | Halls | 1 | ready | 1.0.0 | 2026-11-15 | — |
| [admin/hall-bookings.md](admin/hall-bookings.md) | Bookings, commissions (list, settle); cancellation by provider (D8); reports later | ADM-018, ADM-019, ADM-020, ADM-021, ADM-023, ADM-024; D1, DEC-17, DEC-22 | Halls | 1 | ready | 1.0.0 | 2026-11-15 | — |
| `admin/events.md` | Events | ADM-022 | Events | 1 | planned | — | — | — |
| `admin/jobs.md` | Job ads and statistics | ADM-042 | Jobs | 1 | planned | — | — | — |
| [admin/catalog.md](admin/catalog.md) | Cities and categories | ADM-043, ADM-044 | Catalog | 1 | ready | 1.1.0 | 2026-11-15 | — |
| [admin/content-support.md](admin/content-support.md) | Static pages, support requests | ADM-045, ADM-046 | Content | 1 | in-progress | 0.1.0 | 2026-11-12 | — |
| [admin/notifications.md](admin/notifications.md) | Operational notifications | ADM-047, PLT-004; DEC-27, DEC-30 | Notifications | 1 | in-progress | 0.1.0 | 2026-11-12 | — |
| `admin/reports.md` | Reports | ADM-048; DEC-28 | Reports | 1 | planned | — | — | — |
| [admin/access.md](admin/access.md) | Admin users, roles, activity log | ADM-049, ADM-050 | Access | 1 | in-progress | 0.3.0 | 2026-11-15 | — |
| [admin/settings.md](admin/settings.md) | Platform settings | ADM-051, PLT-001; DEC-02 | Settings | 1 | in-progress | 0.1.1 | 2026-11-15 | — |

### 4.2 Client — Trainee app (Flutter)

| Doc | Feature | BRD IDs | Module | Phase | Status | Version | Updated | Screens |
|-----|---------|---------|--------|-------|--------|---------|---------|---------|
| `client/auth.md` | Onboarding, registration (OTP), login, reset, guest | TRN-001, TRN-002, TRN-003, TRN-004, TRN-005; DEC-02, DEC-03, DEC-04 | Accounts | 1 | planned | — | — | `client--auth--*` (3) |
| `client/home.md` | Home | TRN-006 | Discovery | 1 | planned | — | — | `client--home--*` (1), `client--categories--*` (1) |
| `client/courses.md` | Course list, details, trainer page, threshold view | TRN-007, TRN-008, TRN-009, TRN-026; D1 | Courses | 1 | planned | — | — | `client--courses--*` (1), `client--instructors--*` (1) |
| `client/packages-offers.md` | Packages and offers | TRN-017, TRN-018; DEC-31 | Packages | 1 | planned | — | — | `client--bundles--*` (1) |
| [client/enrollment.md](client/enrollment.md) | Enrollment review, payment, confirmation | TRN-010, TRN-011, TRN-012, PLT-002; DEC-05, DEC-06, DEC-07, DEC-29 | Enrollment | 1 | in-progress | 0.2.0 | 2026-11-12 | `client--enrollment--*` (1) |
| `client/my-courses.md` | My courses, enrolled course, ticket, certificate | TRN-013, TRN-014, TRN-024, TRN-025 | Enrollment | 1 | planned | — | — | `client--my-courses--*` (2) |
| `client/loyalty.md` | Cashback, points, levels | TRN-019; D4 | Loyalty | 1 | planned | — | — | — |
| `client/halls-events.md` | Halls and events | TRN-015, TRN-016, TRN-027 | Halls | 1 | planned | — | — | `client--events--*` (1) |
| `client/jobs.md` | Jobs | TRN-020 | Jobs | 1 | planned | — | — | `client--careers--*` (1) |
| `client/notifications.md` | Notifications | TRN-021, PLT-004; DEC-12, DEC-30 | Notifications | 1 | planned | — | — | — |
| `client/profile.md` | Profile, settings, support | TRN-022, TRN-023, PLT-001 | Accounts | 1 | planned | — | — | `client--profile--*` (1) |

### 4.3 Trainer — Trainer app (Flutter)

| Doc | Feature | BRD IDs | Module | Phase | Status | Version | Updated | Screens |
|-----|---------|---------|--------|-------|--------|---------|---------|---------|
| [trainer/auth.md](trainer/auth.md) | Entry, Nafath registration, login, affiliated first login | TRR-001, TRR-002, TRR-003, TRR-004, PLT-003, PLT-005 | Accounts | 1 | ready | 1.0.1 | 2026-11-15 | `trainer--auth--*` (3) |
| [trainer/subscriptions.md](trainer/subscriptions.md) | Business model, plans, commission, renewal | TRR-005, TRR-006, TRR-007, TRR-030 | Finance | 1 | ready | 1.0.0 | 2026-11-15 | `trainer--subscriptions--*` (2) |
| `trainer/home.md` | Trainer dashboard | TRR-008 | Courses | 1 | planned | — | — | `trainer--home--*` (2) |
| [trainer/course-create.md](trainer/course-create.md) | Create course: venue, link, preview, discount, learning points, threshold start | TRR-009, TRR-010, TRR-011, TRR-012, TRR-013, TRR-014, TRR-015; D1, DEC-08 | Courses | 1 | in-progress | 0.2.0 | 2026-11-15 | `trainer--courses--*-create` (2) |
| [trainer/courses.md](trainer/courses.md) | My courses, review, edits, completion, cancellation, enrollees, session link | TRR-017, TRR-018, TRR-019, TRR-020, TRR-021, TRR-022, TRR-023, TRR-024, TRR-027; D2, DEC-10, DEC-11, DEC-12 | Courses | 1 | ready | 1.0.1 | 2026-11-15 | `trainer--courses--*` (4) |
| `trainer/packages.md` | Course packages | TRR-016; DEC-09 | Packages | 1 | planned | — | — | — |
| `trainer/earnings.md` | Entitlements, per-course earnings | TRR-025, TRR-026 | Finance | 1 | planned | — | — | `trainer--wallet--*` (1) |
| [trainer/hall-bookings.md](trainer/hall-bookings.md) | Hall booking requests, link to course | TRR-031, TRR-032, TRR-033; D1, DEC-17 | Halls | 1 | ready | 0.2.0 | 2026-11-15 | `trainer--halls--*` (1) |
| [trainer/profile.md](trainer/profile.md) | Trainer profile | TRR-028; DEC-13 | Accounts | 1 | ready | 1.0.0 | 2026-11-15 | `trainer--profile--*` (2) |
| `trainer/notifications.md` | Notifications | TRR-029, PLT-004; DEC-30 | Notifications | 1 | planned | — | — | `trainer--notifications--*` (1) |

### 4.4 Center — Training center dashboard (Vue)

| Doc | Feature | BRD IDs | Module | Phase | Status | Version | Updated | Screens |
|-----|---------|---------|--------|-------|--------|---------|---------|---------|
| [center/auth.md](center/auth.md) | Login and account states | CTR-001 | Accounts | 1 | ready | 1.0.0 | 2026-11-15 | — |
| [center/dashboard.md](center/dashboard.md) | Home and reports | CTR-002, CTR-013 | Reports | 1 | in-progress | 1.0.0 | 2026-11-15 | — |
| [center/trainers.md](center/trainers.md) | Affiliated trainers | CTR-003, CTR-004, CTR-005, CTR-006, CTR-007; DEC-14 | Accounts | 1 | ready | 1.0.0 | 2026-11-15 | — |
| [center/courses.md](center/courses.md) | Center courses: create, submit, enrollees | CTR-008, CTR-009, CTR-011; D3 | Courses | 1 | ready | 1.0.0 | 2026-11-15 | — |
| `center/earnings.md` | Center and trainer earnings | CTR-010; DEC-15 | Finance | 1 | planned | — | — | — |
| `center/packages.md` | Center packages | CTR-012 | Packages | 1 | planned | — | — | — |
| `center/notifications.md` | Notifications | CTR-014, PLT-004; DEC-30 | Notifications | 1 | planned | — | — | — |
| `center/profile.md` | Center profile | CTR-015 | Accounts | 1 | planned | — | — | — |
| `center/halls.md` | Center's own halls (DEC-16) | CTR-016; DEC-16 | Halls | 1 | planned | — | — | — |

### 4.5 Provider — Hall & event provider dashboard (Vue)

| Doc | Feature | BRD IDs | Module | Phase | Status | Version | Updated | Screens |
|-----|---------|---------|--------|-------|--------|---------|---------|---------|
| [provider/account.md](provider/account.md) | Account, login, profile, permissions | HPV-001, HPV-002, HPV-016 | Accounts | 1 | ready | 1.1.2 | 2026-11-15 | — |
| [provider/halls.md](provider/halls.md) | Halls, features, pricing, availability | HPV-003, HPV-004, HPV-005, HPV-006 | Halls | 1 | ready | 1.2.1 | 2026-11-15 | — |
| [provider/bookings.md](provider/bookings.md) | Booking requests: review, accept, reject, confirm, cancel, history | HPV-007, HPV-008, HPV-009, HPV-010, HPV-011 | Halls | 1 | ready | 1.0.0 | 2026-11-15 | — |
| `provider/hall-courses.md` | Courses in my halls, hall page (DEC-17) | HPV-012, HPV-013; D1, DEC-17 | Halls | 1 | planned | — | — | — |
| `provider/events.md` | Events | HPV-014 | Events | 1 | planned | — | — | — |
| `provider/notifications.md` | Notifications | HPV-015, PLT-004; DEC-19, DEC-30 | Notifications | 1 | planned | — | — | — |

**Screen design map (not a feature or API surface registry):** [trainee](app_screens/INDEX.md#client) · [trainer](app_screens/INDEX.md#trainer). For an academy flow without its own export, the user identifies the individual trainer design as the shared reference; role-specific access remains subject to [SCR-02](DECISIONS.md#screen-differences). Each index entry identifies its source export. Screens columns above use the existing exports; `academy` = center-affiliated trainer.

**Coverage:** 148 / 148 BRD features mapped (57 docs).

---

## 5. Existing base code (pre-BRD)

The project starts from the generic Laravel base (`msaber/laravel-base`). When the
BRD lands, each row below is either **reused** by the BRD feature that owns it or
**replaced** inside that feature — never earlier. Record the choice as a TD.

| Existing code | Endpoints today | Owner feature (doc) | Gap vs BRD |
|---------------|-----------------|---------------------|------------|
| Admin auth (`Admin/AuthController`) | `/admin/auth/login` (public); `/admin/auth/*` session routes behind `auth:api` | `admin/auth.md` | TD-19: email + password; refresh; admin identity and active checks (ADM-049). |
| Shared auth (`Shared/AuthController`) | `/client/auth/{login,register,verify,resend-code,forgot-password,reset-password}` (public), `/client/auth/{logout,refresh}` — login by email/phone + password, OTP via the Verification module | `client/auth.md`, `trainer/auth.md` | Trainee: mobile + password, all fields + OTP; trainer: Nafath / username; TD-08 token separation. |
| Client profile, settings, addresses, wallet, notifications, search | `/client/{profile,settings,addresses,wallet,notifications,search}` | `client/profile.md`, `client/loyalty.md`, `client/notifications.md`, `client/courses.md` | Addresses → one trainee address (DEC-03); wallet → cashback / points ledgers. |
| Admin CRUD: users, supervisors, roles, categories, FAQs, pages, sliders, countries, governorates, regions, shipping zones, settings, feature flags, audit logs, dashboard | `/admin/*` (config-only controllers, `rbac.auto`) | `admin/catalog.md`, `admin/access.md`, `admin/content-support.md`, `admin/settings.md`, `admin/dashboard.md` | BRD uses cities (not regions / shipping zones); roles + activity log reused; sliders = home promo. |
| Shared + public content | `/api/v1/health`, `/api/v1/config/bootstrap`, `/api/v1/notifications/*`; public `/api/v1/{faqs,pages/{type},sliders,countries,cities}`; `/api/v1/client/{upload,contact}` | [API_CONVENTIONS.md](API_CONVENTIONS.md) | — |
| Modules: Media, Verification (OTP), Notification | `modules/*` | — | — |

Exact list: `php artisan route:list --path=api/v1` or the [API console](postman-collection.json).

---

## 6. Delivery phases

*Filled from the BRD by `project-init` step 2.*

The BRD has no delivery plan (DEC-32): every feature is phase 1 until the client splits it.

| Phase | Goal | Gate |
|-------|------|------|
| 0 | Setup: agent tooling, docs, BRD ingested, decisions listed | Done 2026-11-11 — registry filled, DEC-01…32 raised |
| 1 | BRD v1.0 + additional requirements, all five apps | Each feature's blocking DECs answered (§7) before it is built |

## 7. Blocking decisions by phase

Phase 1 — answer before building the features they name ([DECISIONS.md](DECISIONS.md)):

| Area | Open decisions |
|------|----------------|
| Accounts | DEC-14 |
| Courses | DEC-05, DEC-10, DEC-11 |
| Enrollment and payment | DEC-06 |
| Pricing and loyalty | DEC-07, DEC-24, DEC-25, DEC-26 |
| Packages and plans | DEC-23 |
| Centers and halls | DEC-15 (partly: rate source, payout) |
| Notifications and reports | DEC-19, DEC-27, DEC-28, DEC-30 |
| Delivery | DEC-32 |
| Screens | SCR-01, SCR-02, SCR-03 |