Architecture

High-Level Architecture

Layering

Layers	Location	Responsibilities
Routing	routes/*.php, routes/API/V1/api.php	endpoint map + middleware
Controllers	app/Http/Controllers/*	orchestration request/response
Request Validation	app/Http/Requests/*	payload validation
Model Domains	app/Models/*, app/Modules/*/Models/*	domain + relationship rules
Action (SPK/PO module)	app/Modules/*/Actions/*	segmented business operations
API Resources	app/Http/Resources/*	transform response API
Persistence	database/migrations/*	schema + data evolution
Async	app/Jobs/*	export/pdf/push async

Route Grouping

Groups	Prefix	Middleware
Admin	/admin/*	web, auth, access:*
API V1	/api/v1/*	api, partial auth:sanctum + access:*
Membership	custom route file	register/login/otp/fcm

Auth & Access Control

• Session auth for web admin.
• Sanctum token for API.
• Gate policy in AuthServiceProvider.
• The EnsureUserHasRole middleware validates soft-deleted project roles + edge cases.

Key Module

1. SPB Module: submission of project materials/goods.
2. PO Module: purchase order per supplier, lifecycle approval until acceptance.
3. Payment Module: payment terms, tax, verification, split payment.
4. SPK Module: work contract + revision + payment + accounting + receipt.

Pattern Used

• Fat-model scopes for filtering status (scopeCondition, notComplete, etc.).
• PHP native enum (SPK/PO receipt/payment split status).
• Action classes for complex operations of the SPK/PO receipt module.
• Soft delete on several entities (users, suppliers, spbs, pre_orders, spks).

Detected Technical Debt

Areas	Observation	Impact
Query SPB notComplete/complete	complex raw SQL + refactor TODO	low maintainability
Mixed model/module styles	some domains are still controller-heavy	low consistency
The admin route is huge	>100 routes in one file	difficult onboarding

Verification Notes

• Status: Partial
• Scope: Raw SPB query performance on large data volumes has not been benchmarked.
• Action: Run profiling query + baseline response time on staging/production-like dataset.