Database ownership, API surfaces, scheduled work and external integration contracts.
The backend connects to PostgreSQL on the Encik Beku Supabase project. The schema source of truth is the ordered SQL under backend/supabase/migrations; Eloquent models map onto that schema. Do not use Laravel's default migration assumptions to recreate the database.
At the inspected commit there are 172 SQL migration files and more than 50 Eloquent models. The main relationship spine is:
Customer ──< Customer Address
└───────< Order ──< Order Item
├─< Job Log ──< Proof
├─< Payment
├─< Refund
├─< Itemize Snapshot ──< Snapshot Line
└─< Invoice
Hidden database keys preserve relationships. Human references and order numbers are display/search identities and must not be used as replacement foreign keys.
numeric and is calculated with exact decimal operations, not floating point.| Source | Use |
|---|---|
backend/routes/api.php |
Current route and middleware authority |
API/openapi.yaml |
General API contract; compare with routes for drift |
/swagger |
Generated/readable API documentation when enabled |
API/finance-api.md |
Detailed reporting and Finance consumer contract |
| Backend Form Requests | Input validation authority |
| Backend API Resources | Output serialization authority |
The API error envelope is standardized with timestamp, HTTP status, error code, message, path and field errors. Lists that use Spring-compatible pagination return content, totalElements, totalPages, zero-based number and size.
| Surface | Examples |
|---|---|
| Authentication | Login, callback, session adoption, refresh, logout and current user |
| Core portal | Customers, orders, quotations, branches, users, roles, items, payments and refunds |
| Field operations | /ops/my-jobs, start, complete, outcome, payment, itemize, warranty and proof |
| OE | Dispatch queue/board, drafts, commit, job logs, vehicles and technician roster |
| Finance | Verification queues, outstanding balances and bulk verification |
| Reports | Sales summaries, orders, payments, finance invoices and Finance feeds |
| Administration | Companies, lookups, accounts, terms templates and API tokens |
| System | Direction | Contract/concern |
|---|---|---|
| UtopiaSpace Supabase Auth | Inbound identity | JWT issuer and shared session; Encik Beku authorization is still local |
| Utopia Hub policy/profile services | Backend outbound | Auto-provision and profile resolution; cache and failure policy must be understood |
| UtopiaSpace Ops | Bidirectional API consumer | Separate repository and release lifecycle; consumes /ops/* |
| OE/Hub | Bidirectional | Dispatch/notification surface and vehicle ownership |
Hub oe-vehicle-listing Edge Function |
Backend outbound | Secret-header protected fleet list; deployed manually on the Hub project |
| S3-compatible storage | Backend outbound | Proofs and documents; distinguish private and public disks |
| Vercel | Hosts frontend | Environment variables and frontend release record |
| DigitalOcean App Platform | Hosts backend | Container, environment variables and backend release record |
| AutoCount/AR Portal | Outbound/read feeds | Accounting output and reporting contracts; verify operational owner |
| Wiki update workflow | Source repository outbound | Notifies the Sales Module Wiki after relevant pushes or merged PRs |
The oe-vehicle-listing Edge Function runs on the Hub Supabase project. It accepts GET /functions/v1/oe-vehicle-listing with x-oe-secret. It fails closed when unconfigured, rejects a wrong secret and returns no partial list on a query failure because a partial response could incorrectly deactivate vehicles.
Deployment is manual and is not part of this repository's CI. The same secret must be configured at the function and in the Encik Beku backend.
| Work | Mechanism | Handover concern |
|---|---|---|
| Monthly LG invoice generation | Laravel schedule on the 20th at 02:00 | Requires an actual schedule:run runner or external trigger; verify production evidence |
| Fleet synchronization | On-demand command and refresh when vehicle picker opens | Intentionally not cron-scheduled |
| Queued jobs | Laravel synchronous queue | Runs inside the caller's process; best-effort jobs must not rethrow into committed user actions |
Useful commands include lg:generate-invoices and fleet:sync. Import and backfill commands also exist; they are data-changing tools and require a scoped, reviewed runbook before production use.
For every external integration, the outgoing owner must provide: