Runtime components, repository boundaries and request flows for the Encik Beku Sales Module.
Browser
└─ Next.js frontend on Vercel
├─ server-side proxy/adoption of the shared UtopiaSpace session
└─ HTTPS calls to Laravel `/api/v1`
├─ Encik Beku PostgreSQL on Supabase
├─ S3-compatible file storage
├─ Utopia Hub profile/policy services
├─ OE notification endpoint
└─ Hub Edge Function for vehicle listing
UtopiaSpace Ops mobile app ── `/api/v1/ops/*` ──┘
OE/Hub services ── `/api/v1/oe/*` ──┘
Reporting/Finance clients ── scoped API token ─┘
The frontend and backend are separate deployable applications. A rollback or failed deployment of one does not automatically roll back the other.
Location in encik-beku |
Purpose |
|---|---|
frontend/app |
Next.js routes and layouts |
frontend/components |
UI primitives and domain components |
frontend/hooks |
Client data and application hooks |
frontend/lib/api |
Typed calls to backend resources |
frontend/proxy.ts |
Shared-domain session adoption and request proxy behavior |
backend/app/Http/Controllers |
HTTP entry points |
backend/app/Http/Requests |
Request validation |
backend/app/Http/Resources |
Public JSON shape |
backend/app/Services |
Multi-step business operations and transaction boundaries |
backend/app/Models |
Eloquent mappings to the existing schema |
backend/routes/api.php |
API routes, auth boundaries and permission middleware |
backend/supabase/migrations |
Authoritative database schema history |
backend/tests |
Backend regression and contract tests |
API/openapi.yaml |
General API contract; verify it against routes before relying on completeness |
API/finance-api.md |
Finance/reporting feed contract |
hub-functions |
Edge Functions deployed manually to the UtopiaSpace Hub project |
| Context | Representative records |
|---|---|
| Identity and access | app_users, roles, permission modules, branch overrides, API tokens |
| Customer and sales | customers, addresses, quotations, orders, order items |
| Fulfilment | job logs, proofs, dispatch drafts, technicians, vehicles |
| Finance | payments, refunds, itemize snapshots, invoices and verification state |
| Inventory | items, variants, stock levels, stock movements and tools |
| Partner work | partner orders, LG order details and partner invoices |
| Governance | audit records, lookups, companies and account mappings |
The API is rooted at /api/v1 and has four important access patterns:
| Surface | Authentication | Intended caller |
|---|---|---|
| General application routes | Supabase JWT in an HTTP-only Encik Beku cookie or authorization header | Browser application |
/ops/* |
Supabase JWT for direct field users, or a scoped API token where configured | UtopiaSpace Ops and technicians |
/oe/* |
Scoped API token or JWT | OE/Hub integration |
/reports/* |
Scoped API token or JWT, plus report throttling | Reporting and finance consumers |
Permissions are enforced in Laravel middleware such as permission:<module>,<level>. Hiding a frontend button is not an authorization control.
There are two supported entry paths:
GET /auth/google/login and GET /auth/callback.POST /auth/session, where the Next.js proxy adopts the shared UtopiaSpace Supabase access token.Both produce the Encik Beku access_token HTTP-only cookie. Silent SSO deliberately does not copy or rotate the shared refresh token; when the adopted access token expires, the frontend adopts a current token again. The token issuer is verified centrally by SupabaseJwtVerifier.
Identity and authorization are separate. A valid UtopiaSpace identity does not automatically grant Encik Beku access. Local app_users, role, work-list and branch-scope records decide what the person can do.
Draft order
→ dispatch validation
→ order number and company facts frozen
→ stock effects
→ job log scheduling
→ technician/Ops work
→ itemize snapshots and payment evidence
→ Finance verification
→ accounting/reporting output
Dispatch is a transactionally sensitive path and is not safe to repeat. OrderService::dispatch() must continue to reject a second attempt when the order is no longer a draft. Any change to order creation, wizard validation, dispatch, permissions or OrderService requires the dispatch regression suite and an exercised happy path.
env() directly.utopiaspace-ops, Utopia Hub/OE and the Hub Supabase project are external ownership boundaries. Changes across those boundaries need coordinated versions and named owners.frontend/CLAUDE.md still describes an earlier mock-data phase and says Supabase is future work, while the current application uses a live Laravel/Supabase integration. Treat that file as historical until it is reconciled. backend/BACKEND-NOTES.md describes the superseded Spring Boot implementation; the current backend authority is Laravel source plus backend/CLAUDE.md.