GSB-Construction/SYSTEM_AUDIT.md

System Audit Report

System analysis

This is a Laravel 11 modular monolith with:

• 24 domain modules
• Inertia.js + React frontend
• Eloquent ORM with SQLite currently configured
• Spatie permissions and custom tenant scoping
• 289 registered routes
• Approval, finance, procurement, inventory, project, document, and reporting workflows

The architecture is coherent, but authorization is distributed across global scopes, controller checks, roles, and route middleware. Tenant isolation and workflow rules are the highest-risk areas.

Confirmed findings

🔴 1. Invoice approval workflow is incorrect

A Project Manager can directly transition an invoice to Approved, despite the expected workflow requiring executive approval.

Evidence:

• FinanceController.php:153
• FinanceController.php:163
• ComprehensiveSystemE2ETest.php:207

The test suite confirms this:

• 119 tests passed
• 1 test failed
• Failed test: financial invoice and retention flow

Recommended tweak: separate approval-chain review from final invoice approval, and enforce the transition in the domain service rather than only checking role names.

🔴 2. Task endpoints appear vulnerable to cross-tenant access

Task does not use the tenant trait:

• Task.php:19
• Task.php:21

Several controller actions retrieve tasks directly through route model binding or unrestricted lookup:

• TaskController.php:161
• TaskController.php:269

This affects update, delete, transition, evidence, and related task operations.

Recommended tweak: always resolve tasks through an authorized project query and add cross-tenant tests for every task mutation endpoint.

🔴 3. Inventory mutations do not consistently enforce tenant ownership

Warehouse has no tenant scope:

• Warehouse.php:12
• Warehouse.php:14

Mutation methods perform unrestricted ULID lookups:

• MaterialController.php:219
• MaterialController.php:220
• MaterialController.php:275
• MaterialController.php:368

The visible-warehouse query is used for display, but mutation methods do not consistently reuse it.

Recommended tweak: centralize authorizeWarehouseAccess() and authorizeProjectAccess() checks and call them before every stock mutation.

🟠 4. Inventory operations are race-condition prone

WarehouseService checks available stock and then decrements it without locking the row:

• WarehouseService.php:82
• WarehouseService.php:87

Two concurrent dispatches can both pass the availability check and overspend inventory.

Recommended tweak:

• Use lockForUpdate().
• Perform conditional atomic updates.
• Add concurrency tests.
• Use decimal-safe quantity handling.

🟠 5. Several high-volume foreign keys lack useful indexes

Runtime schema inspection showed missing indexes for relationships such as:

• tasks.project_id
• financial_invoices.project_id
• retention_ledger.project_id
• task_activities.task_id

Examples:

• create_tasks_table.php:13
• create_financial_tables.php:14
• create_financial_tables.php:48

Recommended tweak: add indexes based on actual query patterns, especially (project_id, created_at) for reporting tables.

🟠 6. Frontend has multiple god components

The production build succeeds, but several React pages are very large:

• Projects/Wizard.tsx — 1,654 lines
• Projects/Show.tsx — 1,627 lines
• Projects/Edit.tsx — 1,058 lines
• Labors/Index.tsx — 1,010 lines
• Inventory/OperationsForm.tsx — 962 lines

The frontend also contains substantial any usage, particularly in daily reports and approval screens.

Recommended tweak: split pages into UI components, form schemas, API/data hooks, and domain types. The largest immediate candidates are the project wizard and project detail page.

🟡 7. Dependency audit reports high-severity vulnerabilities

npm audit reports two high-severity issues:

• js-yaml
• nanoid

composer audit reports high-severity advisories affecting packages including:

• Guzzle
• Laravel framework
• CommonMark
• PhpSpreadsheet
• Symfony components

Recommended tweak: update dependencies in a controlled branch, rerun the full test suite, and review file-upload, PDF, spreadsheet, and HTTP-client usage after upgrades.

🟡 8. Production configuration needs hardening

The current local environment has:

• APP_DEBUG=true
• LOG_LEVEL=debug

See .env:2.

Production deployment must explicitly enforce:

APP_ENV=production
APP_DEBUG=false
LOG_LEVEL=warning

Verification summary

• Application boot: passed
• Route registration: passed, 289 routes
• Database migrations: all applied
• Frontend TypeScript/Vite build: passed
• Feature tests: 119 passed, 1 failed
• Git working tree: clean
• Dependency audits: vulnerabilities present

Recommended priority

1. Fix tenant-safe task and inventory mutations.
2. Correct the invoice approval state machine.
3. Update vulnerable dependencies.
4. Add inventory concurrency protection.
5. Add missing database indexes.
6. Refactor the largest frontend pages.