Platform
Source Map
Where the major platform concepts live in the Symfony codebase.
Application root
The production application is the Symfony app in app/. The Fumadocs site lives separately in docs-site/ so the Next.js documentation app does not collide with Symfony's existing app/ directory.
| Area | Primary files | Purpose |
|---|---|---|
| Web portals | app/src/Controller/Portal/*Controller.php | Browser flows for admin, client, electrician, supervisor, payroll, and finance users. |
| Mobile and API | app/src/Controller/Api/*, app/src/Controller/Api/V2/* | API Platform resources, mobile v2 endpoints, invitation APIs, and Xero submission APIs. |
| Payroll rules | app/src/Service/Payroll/* | Allowance matrix, award calculation snapshots, and recalculation orchestration. |
| Timesheet domain | app/src/Service/Timesheet/*, app/src/Entity/Timesheet.php, app/src/Entity/TimeEntry.php | Hours calculation, edit policy, risk scoring, snapshots, approval sheets, and change logs. |
| Finance domain | app/src/Service/Portal/PayrollInvoiceService.php, app/src/Service/Portal/PortalFinanceService.php, app/src/Entity/PayrollInvoice*.php | Invoice preview, invoice generation, rate/allowance/material normalization, and finance portal data. |
| Integrations | app/src/Service/Xero*, app/src/Service/Auth0ManagementService.php, app/config/packages/security.yaml | Xero OAuth/submission and Auth0 web/API authentication. |
| Notifications | app/src/Service/TimesheetExpenseNotificationService.php, app/src/Service/ExpoPushNotificationService.php, app/src/Entity/InboxNotification.php | In-app notifications and Expo push payloads after approval/rejection events. |
| Configuration | app/src/Entity/Client*, app/src/Entity/MasterConfigurationItem.php, app/src/Command/SeedMasterConfigurationCommand.php | Client-scoped and master data for rates, allowances, event rates, materials, categories, and work conditions. |
Controller density
Graphify identified the biggest coupling points in the codebase:
| Code node | Why it matters |
|---|---|
ClientController | Central client portal controller. It touches projects, materials, cost codes, timesheets, expenses, rates, event rates, allowances, users, reports, payroll summaries, and invoices. |
AdminClientManagementController | Admin's detailed client setup surface. It joins client setup, project setup, user assignment, and imported configuration. |
FinanceController and PayrollFinanceController | Finance and payroll finance invoice flows. They depend on invoice generation, PDF views, Xero statuses, and project/client scoping. |
PayrollController | Payroll dashboard, timesheet review, approval, weekly reports, payslips, expense review, and Xero handoff. |
Timesheet, Project, and User | The three entities most other features converge on. Timesheets connect users to projects and calculation outputs. |
Route inventory from Symfony
php bin/console debug:router --format=json reports 427 routes. The broad route groups are:
| Group | Count | Examples |
|---|---|---|
| Admin portal | 108 | /admin/clients, /admin/clients/{id}/award-matrix, /admin/configuration |
| Client portal | 75 | /client/projects, /client/timesheetsv2, /client/finances/allowances |
| Payroll portal | 55 | /payroll/timesheets, /payroll/expenses, /payroll/finances/invoices |
| Supervisor portal | 26 | /supervisor/timesheets, /supervisor/timesheet-sheets/{id}, /supervisor/expenses |
| Finance portal | 18 | /finance/invoices, /finance/invoices/{id}/pdf, /finance/reports/weekly |
| Electrician portal | 14 | /electrician/timesheets, /electrician/expenses, /electrician/notifications |
| API v2 electrician | 12 | /api/v2/electrician/timesheets, /api/v2/electrician/expenses |
| API v2 supervisor | 10 | /api/v2/supervisor/timesheets/{id}/approve, /api/v2/supervisor/expenses/{id}/reject |
| API Xero submission | 4 | /api/xero/timesheets/{id}/submit, /api/xero/expenses/submit-batch |
| Registration | 4 | /register/invite/{token}, /register/client-user/{token} |
| Xero OAuth | 4 | /xero/auth, /xero/callback, /xero/disconnect |
Practical reading order for developers
- Start at
Timesheet,TimeEntry,Project,User, andCliententities. - Read
TimesheetHoursCalculatorto understand raw working-hour breakdowns. - Read
AllowanceMatrixCalculatorto understand calculated allowance lines. - Read
AwardTimesheetCalculationManagerandAwardTimesheetCalculatorto understand current calculation snapshots. - Read
PayrollInvoiceServiceto understand final invoice item amounts and fallback behavior. - Read the portal controller for the role being changed, then push shared behavior into a service if the same rule appears in more than one portal.