# Source Reading Guide

Use this guide to inspect the codebase efficiently.

## 1. Start Here

| Purpose | File |
| --- | --- |
| Active route table and dependency wiring | `public/index.php` |
| Request routing and CSRF gate | `src/Application/App.php` |
| Path parsing and XAMPP base path | `src/Infrastructure/Http/Request.php` |
| Response object | `src/Infrastructure/Http/Response.php` |
| Rendering | `src/Infrastructure/View/PhpRenderer.php` |
| RBAC permissions | `src/Infrastructure/Security/RbacService.php` |
| Session auth and support impersonation | `src/Infrastructure/Security/SessionAuth.php` |
| CSRF token service | `src/Infrastructure/Security/CsrfService.php` |
| Security headers | `src/Infrastructure/Security/SecurityHeaderService.php` |
| Session cookie policy | `src/Infrastructure/Security/SessionCookiePolicy.php` |

## 2. Core Operations

| Module | Controller | Service | Repository | Templates |
| --- | --- | --- | --- | --- |
| Dashboard | `src/Dashboard/Controller/DashboardController.php` | `src/Job/Service/JobWorkflowService.php`, `src/Demo/Service/OperationsDemoData.php` | demo/session + job repo | `templates/dashboard/index.php` |
| Jobs | `src/Job/Controller/JobController.php` | `src/Job/Service/JobWorkflowService.php` | `src/Job/Repository/*` | `templates/job/*` |
| Recurring jobs | `src/Recurring/Controller/RecurringJobController.php` | `src/Recurring/Service/RecurringJobService.php` | `src/Recurring/Repository/*` | `templates/recurring/index.php` |
| Dispatch | `src/Dispatch/Controller/DispatchController.php` | `src/Dispatch/Service/DispatchService.php` | `src/Dispatch/Repository/*` | `templates/dispatch/index.php` |
| Schedule | `src/Schedule/Controller/ScheduleController.php` | `src/Schedule/Service/ScheduleService.php` | `src/Schedule/Repository/*` | `templates/schedule/index.php` |
| Clients | `src/Client/Controller/ClientController.php` | `src/Client/Service/ClientService.php` | `src/Client/Repository/*` | `templates/client/*` |
| Quotes | `src/Quote/Controller/QuoteController.php` | `src/Quote/Service/QuoteService.php`, `src/Quote/Service/QuoteCalculator.php` | `src/Quote/Repository/*` | `templates/quote/*` |
| Invoices | `src/Invoice/Controller/InvoiceController.php` | `src/Invoice/Service/InvoiceService.php`, `src/Invoice/Service/InvoiceCalculator.php` | `src/Invoice/Repository/*` | `templates/invoice/*` |
| Team | `src/Team/Controller/TeamController.php` | `src/Team/Service/TeamMemberService.php` | `src/Team/Repository/*` | `templates/team/*` |

## 3. Import, Export, AI, Integrations

| Module | Files |
| --- | --- |
| Import/export controller methods | `src/Demo/Controller/OperationsController.php` |
| Import schema/validation/pipeline | `src/Importing/Service/ImportSchemaRegistry.php`, `ImportValidationService.php`, `ImportPipelineService.php` |
| AI assistant runtime | `src/Llm/Service/AiAssistantService.php`, `templates/ai-assistant/index.php` |
| LLM settings | `src/Llm/Controller/LlmSettingsController.php`, `src/Llm/Service/LlmConnectionService.php`, `src/Llm/Service/LlmProviderRegistry.php`, `templates/llm/index.php` |
| Accounting | `src/Accounting/*`, `templates/accounting/index.php` |
| Calendar | `src/Calendar/*`, `templates/calendar/index.php` |
| Customer portal | `src/Portal/*`, `templates/portal/view.php` |
| Offline/mobile | `src/Mobile/*`, `templates/mobile/offline.php`, `public/assets/js/offline-technician.js`, `public/service-worker.js`, `public/manifest.json`, `capacitor.config.json` |

## 4. SaaS and Platform Admin

| Module | Files |
| --- | --- |
| SaaS tenant pages | `src/Saas/Controller/SaasController.php`, `templates/saas/workspace.php`, `templates/saas/subscription.php`, `templates/saas/pricing.php` |
| Pricing admin | `src/Saas/Controller/PricingAdminController.php`, `src/Saas/Service/PricingConfigurationService.php`, `templates/saas/pricing-admin.php` |
| Platform admin controller | `src/Saas/Controller/PlatformAdminController.php` |
| Platform admin services | `src/Saas/Service/PlatformAdminService.php`, `PlatformBillingService.php`, `SystemHealthService.php`, `SecurityAdminService.php`, `MobileOfflineStatusService.php`, `TenantSubscriptionService.php`, `TradePlanCatalog.php` |
| Platform admin repositories | `src/Saas/Repository/*` |
| Platform admin templates | `templates/saas/platform-admin.php`, `tenant-index.php`, `tenant-view.php`, `system-health.php`, `security-admin.php`, `mobile-offline.php` |

## 5. Audit and Security

| Purpose | File |
| --- | --- |
| Audit service | `src/Audit/Service/AuditLogService.php` |
| Audit repositories | `src/Audit/Repository/*` |
| Password hashing | `src/Infrastructure/Security/PasswordHasher.php` |
| Auth service | `src/User/Service/AuthService.php` |
| User repository | `src/User/Repository/UserRepository.php` |
| Store-readiness pages | `src/Site/Controller/SiteController.php`, `templates/site/privacy.php`, `terms.php`, `support.php`, `delete-request.php` |

## 6. Tests and Tools

| Purpose | File |
| --- | --- |
| Main PHP regression suite | `tests/run.php` |
| PHP lint | `tools/lint-php.php` |
| Route/link/button inventory | `tools/qa-inventory.php` |
| Browser route smoke | `tools/browser-smoke.cjs` |
| Role/RBAC/support/AI walkthrough | `tools/role-walkthrough.cjs` |
| Production auth/security smoke | `tools/auth-production-smoke.cjs` if present in cloned copy |

## 7. Documentation To Cross-Reference

| Doc | Why it matters |
| --- | --- |
| `docs/COMMANDS.md` | Exact local commands |
| `docs/QA_ROUTE_ACTION_INVENTORY.md` | Current route/link/form/button inventory |
| `docs/TESTING_STRATEGY.md` | Current testing strategy |
| `docs/COMMERCIAL_TEST_PLAN.md` | Broad commercial QA planning |
| `docs/PRODUCTION_READINESS_QA_REPORT.md` | Latest readiness evidence and unresolved production caveats |
| `docs/SECURITY_TEST_REPORT.md` | Security test status |
| `docs/DEFECT_REGISTER.md` | Known defects and status |
| `docs/IMPORT_AND_LLM.md` | Import and AI/LLM guardrails |
| `docs/ACCOUNTING_INTEGRATIONS.md` | Accounting provider notes |
| `docs/CALENDAR_INTEGRATIONS.md` | Calendar provider notes |
| `docs/SAAS_PLATFORM.md` | SaaS platform overview |
| `docs/RELEASE_CHECKLIST.md` | Release gates |

## 8. Current Source Facts To Verify

Claude should verify these before finalising the test plan:

- Route inventory still shows 98 routes.
- `POST /ai-assistant/generate` exists and is CSRF/RBAC protected.
- `tools/role-walkthrough.cjs` contains `ai-assistant-flow`.
- `RbacService` still denies `trainee` AI/schedule/quote/invoice access.
- Platform admin tenant support still requires reason and duration.
- `/admin` still does not exist.
- Live accounting/calendar/LLM/payment integrations are still foundation-only unless new code proves otherwise.