# Tutorials Module — Architecture Map

> **Last updated:** 2026-06-10
> **Status:** Living document — incrementally updated as new information is discovered

---

## 1. Purpose & Responsibilities

The Tutorials module is the **internal documentation and training system** of the ERP. It provides:
- Step-by-step guided tutorials for all ERP modules (membership, sports, treasury, etc.)
- Categorized tutorial browsing with section-based navigation
- A full "Book of the ERP" export (HTML for print-to-PDF)
- Tutorial content served as rendered PHP views (rich HTML with screenshots)
- A registry system for dynamically adding tutorials from a large metadata file

It is a **read-only documentation module** — it does not create, modify, or interact with any business data. All content is static, defined in code (no database tables).

It does **NOT**:
- Store any data in the database
- Interact with any other module's services or models
- Dispatch or consume events
- Have any cron jobs or background processes

---

## 2. Directory & File Structure

```
app/Modules/Tutorials/
├── bootstrap.php                              # Menu + permission registration
├── Routes.php                                 # 11 routes (index, sections, slugs, book, export)
├── TutorialRegistry.php                       # Master registry (sections, tutorials, categories, steps)
├── Controllers/
│   └── TutorialController.php                # Single controller handling all tutorial views
└── Views/
    ├── index.php                              # Main dashboard (grouped module listing)
    ├── book.php                               # "Book of the ERP" landing page
    ├── export_pdf.php                         # Full book export (print-ready HTML)
    ├── section_index.php                      # Generic section index (from TutorialRegistry)
    ├── section_show.php                       # Generic section tutorial detail
    ├── membership/                            # 27 membership tutorials
    │   ├── index.php                         # Membership section index
    │   ├── new_member_registration.php       # Tutorial: new member registration
    │   ├── pay_form_fee.php                  # Tutorial: form fee payment
    │   ├── fill_form.php                     # Tutorial: fill membership form
    │   ├── membership_pricing.php            # Tutorial: pricing explanation
    │   ├── pay_membership_cash.php           # Tutorial: cash payment
    │   ├── pay_membership_installments.php   # Tutorial: installment payment
    │   ├── collective_payment.php            # Tutorial: collective payment
    │   ├── add_spouse.php                    # Tutorial: add spouse
    │   ├── add_child.php                     # Tutorial: add child
    │   ├── add_temporary_member.php          # Tutorial: add temporary member
    │   ├── children_aging.php                # Tutorial: children aging rules
    │   ├── transfer_separation.php           # Tutorial: child separation
    │   ├── divorce_transfer.php              # Tutorial: divorce transfer
    │   ├── death_transfer.php                # Tutorial: death transfer
    │   ├── waiver_process.php                # Tutorial: waiver
    │   ├── full_new_member_scenario.php      # Tutorial: full scenario
    │   └── ... (27 total)
    ├── sports_activity/                       # 25 sports activity tutorials
    │   ├── _layout.php                       # Shared layout for SA tutorials
    │   ├── index.php                         # SA section index
    │   ├── setup_discipline.php              # Tutorial: create discipline
    │   ├── setup_facility.php                # Tutorial: create facility
    │   ├── register_coach.php                # Tutorial: register coach
    │   ├── register_player.php               # Tutorial: register player
    │   ├── enroll_player.php                 # Tutorial: enroll in group
    │   ├── full_swimming_workflow.php         # Tutorial: full swimming scenario
    │   ├── full_football_workflow.php         # Tutorial: full football scenario
    │   └── ... (25 total)
    └── treasury/                              # 9 treasury tutorials
        ├── index.php                         # Treasury section index
        ├── open_session.php                  # Tutorial: open session
        ├── collect_payment.php               # Tutorial: collect payment
        ├── close_session.php                 # Tutorial: close session
        ├── full_cycle.php                    # Tutorial: full cycle scenario
        └── ... (9 total)
```

---

## 3. Database Schema

**This module has NO database tables.** All tutorial content is defined statically in:
- `TutorialController.php` — constants for Sports Activity, Membership, and Treasury tutorials
- `TutorialRegistry.php` — master registry for all other sections (extensible)

---

## 4. Routes (11 total)

| Method | Path | Handler | Permission |
|--------|------|---------|------------|
| GET | `/tutorials` | TutorialController@index | tutorials.view |
| GET | `/tutorials/book` | TutorialController@bookPage | tutorials.view |
| GET | `/tutorials/export-pdf` | TutorialController@exportPdf | tutorials.view |
| GET | `/tutorials/sports-activity` | TutorialController@sportsActivity | tutorials.view |
| GET | `/tutorials/sports-activity/{slug}` | TutorialController@show | tutorials.view |
| GET | `/tutorials/membership` | TutorialController@membership | tutorials.view |
| GET | `/tutorials/membership/{slug}` | TutorialController@showMembership | tutorials.view |
| GET | `/tutorials/treasury` | TutorialController@treasury | tutorials.view |
| GET | `/tutorials/treasury/{slug}` | TutorialController@showTreasury | tutorials.view |
| GET | `/tutorials/{section}` | TutorialController@section | tutorials.view |
| GET | `/tutorials/{section}/{slug}` | TutorialController@showSection | tutorials.view |

**Note:** The last two routes are catch-all for sections registered via `TutorialRegistry`. Specific sections (membership, sports-activity, treasury) have dedicated handlers above and must appear first in the route file to avoid being caught by the generic `{section}` pattern.

---

## 5. Events Dispatched

None.

---

## 6. Events Consumed

None.

---

## 7. Cross-Module Dependencies

### 7.1 Tutorials IMPORTS FROM:

None. This module is completely self-contained with no code dependencies on other modules.

### 7.2 Other modules that IMPORT FROM Tutorials:

None. No other module references Tutorials code.

### 7.3 Content Dependencies

While the module has no code dependencies, the **tutorial content** (view files) describes workflows from virtually every module in the ERP. If a module's UI or workflow changes, the corresponding tutorial views become stale. Affected modules include:
- Members, Spouses, Children, Temporary
- Payments, Cashier, Treasury
- SportsActivity, PlayerAffairs, Coaches
- Subscriptions, Installments, Fines
- Reservations, Facilities, Carnets
- HR, Accounting, Inventory, Procurement, Sales

---

## 8. Permissions

| Key | Description |
|-----|-------------|
| tutorials.view | View all tutorials, sections, and the book export |

**Note:** Single permission for the entire module — no write permissions needed since it is read-only.

---

## 9. Content Architecture

### 9.1 Three Hardcoded Sections (in TutorialController)

These have dedicated view directories with individual PHP view files per tutorial:

| Section | Tutorials | Categories |
|---------|-----------|------------|
| Membership | 27 tutorials | registration, financial, family, procedures, transfers, types, scenarios |
| Sports Activity | 25 tutorials | setup, registration, academy, scheduling, financial, operations, scenarios |
| Treasury | 9 tutorials | operations, settlement, deposit, custody, scenarios |

### 9.2 Dynamic Sections (via TutorialRegistry)

The `TutorialRegistry` class defines 25+ additional sections including:
- subscriptions, installments, fines, interviews, documents, seasonal, carnets
- sa-registration, player-affairs, coaches, facilities, playgrounds, reservations, tournaments
- pool-management, cashier, payments, accounting
- inventory, procurement, sales
- hr, medical-board, roles, access-matrix, rules
- trainer-portal, parent-portal

Each section has metadata (title, subtitle, icon, color) and can define tutorials with steps.

### 9.3 Tutorial Metadata Structure

```php
'slug-name' => [
    'title'    => 'Arabic title',
    'subtitle' => 'Short Arabic description',
    'icon'     => 'lucide-icon-name',
    'color'    => '#hexcolor',
    'category' => 'category-key',
    'order'    => integer,
]
```

### 9.4 Navigation Pattern

- Tutorials have prev/next navigation (calculated from array key order)
- Each section groups tutorials by category
- Categories have their own label, icon, and color

---

## 10. Sidebar Menu Structure

The module registers a comprehensive sidebar with 25 child items organized into groups:
- **Operations**: Membership, Family, Transfers, Sports, Reservations, Tournaments, Carnets, Parents
- **Finance**: Cashier, Treasury, Payments, Accounting
- **Supply Chain**: Inventory, Procurement, Sales
- **Administration**: HR, Medical Board
- **Portals**: Trainer Portal, Parent Portal
- **Reports & System**: Reports, Users & Permissions, Access Matrix, Rules & Pricing
- **Export**: Book of the ERP (PDF)

Menu order: 990 (appears near bottom of sidebar).

---

## 11. Book Export Feature

The "Book of the ERP" (`/tutorials/export-pdf`) generates a complete HTML document containing all tutorials:
1. Collects all hardcoded sections (membership, sports, treasury) with view file parsing
2. Collects all TutorialRegistry sections with their steps
3. Extracts tutorial steps from PHP view files using regex (parses `tut-step` HTML structure)
4. Renders `export_pdf.php` view with all collected data
5. Injects a print bar for browser print-to-PDF conversion
6. Returns as inline HTML (not a file download)

---

## 12. High-Risk Areas

### 12.1 TutorialRegistry File Size
- `TutorialRegistry.php` is 350+ KB — extremely large single file
- Contains all tutorial definitions for 25+ sections with full step content
- Could cause memory issues on low-resource environments
- Any syntax error in this file would break all dynamic tutorial sections

### 12.2 View File Parsing (Export)
- `extractTutorialSteps()` uses regex to parse PHP/HTML view files
- Fragile — depends on specific CSS class names (`tut-step`, `tut-step-title`, `tut-step-body`)
- If view structure changes, export will produce empty/broken content

### 12.3 Content Staleness
- Tutorial content is static — not auto-generated from code
- When modules change their UI or workflows, tutorials become inaccurate
- No mechanism to detect or flag stale tutorials
- Manual review required after any significant module change

### 12.4 Catch-All Route Pattern
- `/tutorials/{section}` and `/tutorials/{section}/{slug}` catch any URL under `/tutorials/`
- Could mask 404 errors — user gets "section not found" redirect instead of proper 404
- Must be declared AFTER specific section routes in Routes.php

---

## 13. Known Patterns & Gotchas

1. **No database dependency**: Module works even if DB is down (all content is code-defined)
2. **Slug format**: URL slugs use hyphens (`pay-form-fee`), view files use underscores (`pay_form_fee.php`)
3. **Three rendering paths**: Hardcoded sections render individual view files; registry sections render via `section_show.php` with step data
4. **Export is browser-based PDF**: Not server-side PDF generation — requires user to use browser print dialog
5. **Icon system**: Uses Lucide icon names — must be loaded in the layout for icons to render
6. **Order field**: Controls display order within a category; not globally unique
7. **No search**: Users must browse by section/category — no full-text search across tutorials
8. **Auth required**: All routes require authentication — tutorials are internal-only documentation
