# Source Inventory and Reading Guide

Date: 2026-06-15

This guide tells Claude which files carry the important business logic and which files should be inspected first.

## Entry Points and Runtime

| File | Why it matters |
| --- | --- |
| `public/index.php` | Main service wiring, route table, demo auto-login, security headers |
| `src/Application/App.php` | Exact-route dispatcher, CSRF gate, 404 and 403 handling |
| `src/Infrastructure/Http/Request.php` | Method/path/query/post abstraction and XAMPP base-path stripping |
| `src/Infrastructure/Http/Response.php` | Response body/status/header sending |
| `src/Infrastructure/View/PhpRenderer.php` | Template rendering and base URL rewriting |
| `src/Infrastructure/Security/SessionAuth.php` | Session login/logout, permissions, platform support impersonation |
| `src/Infrastructure/Security/RbacService.php` | Role-permission matrix |
| `src/Infrastructure/Security/CsrfService.php` | CSRF token/validation |
| `src/Infrastructure/Security/PasswordHasher.php` | Password hashing and basic policy |
| `src/Infrastructure/Persistence/Database.php` | PDO database factory from environment |

## Operations Modules

| Module | Controllers | Services | Repositories | Templates |
| --- | --- | --- | --- | --- |
| Dashboard | `src/Dashboard/Controller/DashboardController.php` | `src/Job/Service/JobWorkflowService.php`, `src/Demo/Service/OperationsDemoData.php` | demo data | `templates/dashboard/index.php` |
| Clients | `src/Client/Controller/ClientController.php`, `src/Demo/Controller/OperationsController.php` | `src/Client/Service/ClientService.php` | `src/Client/Repository/ClientRepository.php`, `src/Client/Repository/DemoClientSessionRepository.php` | `templates/client/*` |
| Jobs | `src/Job/Controller/JobController.php` | `src/Job/Service/JobWorkflowService.php` | `src/Job/Repository/JobRepository.php` | `templates/job/*` |
| Schedule | `src/Schedule/Controller/ScheduleController.php` | `src/Schedule/Service/ScheduleService.php` | `src/Schedule/Repository/DemoAppointmentSessionRepository.php` | `templates/schedule/index.php` |
| Quotes | `src/Quote/Controller/QuoteController.php`, `src/Demo/Controller/OperationsController.php` | `src/Quote/Service/QuoteService.php`, `src/Quote/Service/QuoteCalculator.php` | `src/Quote/Repository/DemoQuoteSessionRepository.php` | `templates/quote/*` |
| Invoices | `src/Invoice/Controller/InvoiceController.php`, `src/Demo/Controller/OperationsController.php` | `src/Invoice/Service/InvoiceService.php`, `src/Invoice/Service/InvoiceCalculator.php` | `src/Invoice/Repository/DemoInvoiceSessionRepository.php` | `templates/invoice/*` |
| Team | `src/Team/Controller/TeamController.php`, `src/Demo/Controller/OperationsController.php` | `src/Team/Service/TeamMemberService.php` | `src/Team/Repository/DemoTeamMemberSessionRepository.php` | `templates/team/*` |
| Reports | `src/Demo/Controller/OperationsController.php` | `src/Demo/Service/OperationsDemoData.php` | demo data | `templates/reports/index.php` |
| Settings | `src/Demo/Controller/OperationsController.php` | demo services | session/demo | `templates/settings/index.php` |

## Import, Export, AI, and Integrations

| Area | Main files |
| --- | --- |
| Import schemas | `src/Importing/Service/ImportSchemaRegistry.php` |
| Import validation | `src/Importing/Service/ImportValidationService.php` |
| Import/export platform admin dashboard | `src/Importing/Service/ImportExportAdminService.php` |
| Export CSV generation | `src/Demo/Controller/OperationsController.php` |
| LLM provider settings | `src/Llm/Controller/LlmSettingsController.php`, `src/Llm/Service/LlmProviderRegistry.php`, `src/Llm/Service/LlmConnectionService.php` |
| Accounting providers | `src/Accounting/Controller/AccountingSettingsController.php`, `src/Accounting/Service/AccountingProviderRegistry.php`, `src/Accounting/Service/AccountingConnectionService.php` |
| Accounting repositories | `src/Accounting/Repository/AccountingConnectionRepository.php`, `src/Accounting/Repository/DemoPlatformAccountingConnectionRepository.php` |
| Calendar providers | `src/Calendar/Controller/CalendarSettingsController.php`, `src/Calendar/Service/CalendarProviderRegistry.php`, `src/Calendar/Service/CalendarSyncService.php` |

## SaaS and Platform Admin

| Area | Main files |
| --- | --- |
| Tenant workspace/subscription/pricing public | `src/Saas/Controller/SaasController.php` |
| Platform admin controller | `src/Saas/Controller/PlatformAdminController.php` |
| Pricing admin controller | `src/Saas/Controller/PricingAdminController.php` |
| Platform tenant/admin service | `src/Saas/Service/PlatformAdminService.php` |
| Platform billing ledger/overrides | `src/Saas/Service/PlatformBillingService.php` |
| Pricing settings and catalog | `src/Saas/Service/PricingConfigurationService.php`, `src/Saas/Service/TradePlanCatalog.php` |
| Tenant subscription/usage | `src/Saas/Service/TenantSubscriptionService.php` |
| System health | `src/Saas/Service/SystemHealthService.php`, `templates/saas/system-health.php` |
| Security admin | `src/Saas/Service/SecurityAdminService.php`, `templates/saas/security-admin.php` |
| Mobile/offline status | `src/Saas/Service/MobileOfflineStatusService.php`, `templates/saas/mobile-offline.php` |
| Demo repositories | `src/Saas/Repository/DemoPricingSettingsRepository.php`, `src/Saas/Repository/DemoPlatformTenantRepository.php`, `src/Saas/Repository/DemoPlatformBillingRepository.php` |
| Platform templates | `templates/saas/platform-admin.php`, `templates/saas/tenant-index.php`, `templates/saas/tenant-view.php`, `templates/saas/pricing-admin.php`, `templates/saas/pricing.php`, `templates/saas/workspace.php`, `templates/saas/subscription.php` |

## Audit and Demo

| File | Purpose |
| --- | --- |
| `src/Audit/Service/AuditLogService.php` | Audit writer and event helpers |
| `src/Audit/Repository/AuditLogRepository.php` | Audit repository contract |
| `src/Audit/Repository/DemoAuditLogRepository.php` | Session-backed audit log |
| `src/Audit/Repository/DatabaseAuditLogRepository.php` | DB-backed audit log |
| `src/Demo/Service/OperationsDemoData.php` | Seeded operations data for jobs, clients, quotes, invoices, team |
| `src/Demo/Service/DemoResetService.php` | Demo cleanup scope |
| `src/Demo/Service/DemoManagementService.php` | Demo status, usage, reset and audit |

## Database and Migrations

| File | Purpose |
| --- | --- |
| `database/schema.sql` | Main production-oriented schema |
| `database/seed.sql` | Local demo seed |
| `migrations/m250613_000001_initial_schema.sql` | Migration copy/foundation |

## Tests and Tools

| File | Purpose |
| --- | --- |
| `tests/run.php` | Current lightweight regression suite |
| `tools/lint-php.php` | PHP lint helper used by `composer check` |
| `tools/browser-smoke.cjs` | Browser smoke helper, inspect before use |
| `composer.json` | Dependencies and scripts |
| `composer.lock` | Locked dependencies |

## Existing Documentation To Cross-Reference

| File | Use |
| --- | --- |
| `README.md` | Setup, current feature list, local credentials |
| `AGENTS.md` | Project rules and architecture constraints |
| `SECURITY_NOTES.md` | Security baseline notes |
| `docs/ARCHITECTURE.md` | Current high-level architecture |
| `docs/API_REFERENCE.md` | API direction; note many API routes are not wired yet |
| `docs/SAAS_PLATFORM.md` | SaaS platform foundations |
| `docs/IMPORT_AND_LLM.md` | Import and LLM foundations |
| `docs/ACCOUNTING_INTEGRATIONS.md` | Accounting provider foundations |
| `docs/CALENDAR_INTEGRATIONS.md` | Calendar provider foundations |
| `docs/FEATURE_ROADMAP.md` | Competitor-driven roadmap |
| `docs/COMPETITOR_RESEARCH.md` | Competitor research basis |
| `docs/TESTING_ARCHITECT_BRIEF.md` | Older testing architect brief; compare against this newer pack |
| `docs/CLAUDE_TESTING_PLAN_HANDOFF.md` | Older Claude handoff; superseded by this dated pack |
| `docs/DEFECT_REGISTER.md` | Known defects/gaps |
| `docs/COMMERCIAL_TEST_PLAN.md` | Existing commercial test-plan draft |
| `docs/SECURITY_TEST_REPORT.md` | Existing security-test notes |
| `docs/XAMPP_INSTALL_GUIDE.md` | Local XAMPP setup details |

## Files Claude Should Inspect For Business Logic First

1. `public/index.php`
2. `src/Infrastructure/Security/RbacService.php`
3. `src/Infrastructure/Security/SessionAuth.php`
4. `src/Application/App.php`
5. `src/Demo/Service/OperationsDemoData.php`
6. `src/Job/Service/JobWorkflowService.php`
7. `src/Schedule/Service/ScheduleService.php`
8. `src/Quote/Service/QuoteService.php`
9. `src/Invoice/Service/InvoiceService.php`
10. `src/Client/Service/ClientService.php`
11. `src/Team/Service/TeamMemberService.php`
12. `src/Importing/Service/ImportSchemaRegistry.php`
13. `src/Importing/Service/ImportValidationService.php`
14. `src/Saas/Service/PricingConfigurationService.php`
15. `src/Saas/Service/PlatformAdminService.php`
16. `src/Saas/Service/PlatformBillingService.php`
17. `src/Audit/Service/AuditLogService.php`
18. `src/Accounting/Service/AccountingProviderRegistry.php`
19. `src/Accounting/Service/AccountingConnectionService.php`
20. `src/Calendar/Service/CalendarSyncService.php`
21. `src/Llm/Service/LlmConnectionService.php`
22. `tests/run.php`
23. `database/schema.sql`