Architecture and execution model
Two application data paths
Section titled “Two application data paths”Ordinary tenant-internal reads and edits commonly use reusable frontend hooks and the Supabase browser client under row-level security (RLS). Privileged portals, integrations and transactional operations use FastAPI, services and database functions. Some domains use both paths; a page name alone does not determine its authorization or transaction model.
flowchart TD UI[React role surface] --> Hooks[Tenant-aware hooks] Hooks --> Browser[Supabase browser client] Browser --> RLS[PostgreSQL RLS] Hooks --> API[FastAPI identity and policy] API --> Scope[Active tenant, capability and resource scope] Scope --> Services[Domain services] Services --> RPC[Transactional database functions] RLS --> DB[(Persistent application state)] RPC --> DB Services --> DB Services --> Providers[External adapters]
The frontend implementation uses these data paths. API policy and row-level security enforce their respective authorization boundaries.
The frontend entry is frontend/src/SupabaseApp.tsx. The client in
frontend/src/lib/supabase.ts uses browser-safe configuration and persists and
refreshes sessions. Its public client key is not a replacement for RLS.
Privileged service-role credentials remain on the server.
Browser and privileged data paths gives the detailed contract, examples and evidence limits.
Identity, company context and resource authority
Section titled “Identity, company context and resource authority”backend/services/auth_context.py owns verified caller identity and membership
models. backend/services/common.py owns shared active-tenant and capability
helpers. Capability checks describe what an actor may do; resource checks
establish which company’s record that actor may act on.
Service-role database calls bypass RLS. A privileged handler must therefore establish identity, required capabilities and the target resource’s scope before business reads, changes or external effects. Authentication/capability lookups are themselves authorization reads and may use the privileged client.
Navigation and hidden controls are presentation, not enforcement. Customer contact membership, deduction-recipient selection, portal grants, worker assignment and UE commitments are different relationships. The access overview distinguishes these relationships and the checks they require.
Caller authority across application layers gives the detailed contract, examples and evidence limits.
Frontend data and cache ownership
Section titled “Frontend data and cache ownership”Reusable tenant CRUD belongs in hooks. Query keys include tenant identity through
tenantQueryKey; the query provider also changes its client when the active
tenant changes. Project hooks demonstrate both Supabase reads and scoped API
requests. A correct cache key does not replace a tenant filter or server policy.
Components and pages own presentation. Services own reusable privileged domain and provider behaviour. The database owns constraints and transactional invariants. This division guides where a change belongs without claiming every existing module already follows the ideal structure.
Transaction and external-effect boundaries
Section titled “Transaction and external-effect boundaries”Business changes that must be atomic belong in one database transaction. Active migrations define tables, functions, policies and forward schema changes. Generated TypeScript database types are derived from the local stack, not maintained by hand.
An external operation cannot be made atomic simply by placing it after a database write. Each integration needs its own durable intent, identity, reconciliation and retry rules. The integration recovery contract determines how an individual operation can be reconciled and retried.
Schedulers are wired through backend/server.py, including accounting,
purchase invoices, mail intake, imports and customer notifications. Their
configuration, cadence, overlap controls and recovery belong in the scheduler inventory.
Application transactions and external effects gives the detailed contract, examples and evidence limits.
AI and agent surface
Section titled “AI and agent surface”The current public MCP contract resolves the active company and live permissions
per call. Ordinary MCP entry requires projects:read; individual readers apply
narrower permissions. Results carry source, freshness, missing-information and
truncation information. Supported quote proposals remain distinct from native
quotes until human confirmation.
The public /mcp, the separate /api/mcp-gateway contractor integration and
synthetic demonstration servers have different purposes. Historical V1 notes
about a read-only tool set must not override docs/mcp/contract.md or the
connected server’s current catalogue.
Versioning and delivery
Section titled “Versioning and delivery”Git and active migrations own code/schema evolution. Frontend and API releases are built from exact commits; deployment scripts use locks, health checks and guarded publication. Schema releases have their own backup, compatibility and forward-recovery contract. Application rollback does not reverse schema changes.
Main, the frontend, the API and the applied schema can represent different states. A source-reviewed page must not label a commit deployed without runtime evidence. The current environment agreement also allows controlled pre-launch application candidates to be published before their batch merges.
Verification boundaries
Section titled “Verification boundaries”Unit/component checks, hermetic backend suites, local-stack/RLS suites,
authenticated browser checks and shared functional evidence answer different
questions. make ci-plan selects checks for a candidate; neither a selected CI
pass nor a handbook build establishes every business outcome.
Test execution identifies automated and manual checks. Evidence interpretation defines what a scenario result establishes.
Implementation map and detailed owners
Section titled “Implementation map and detailed owners”| Concern | Starting implementation | Owning explanation and evidence boundary |
|---|---|---|
| Role surfaces | frontend/src/pages/, frontend/src/components/ |
Routes and presentation; complete device/accessibility acceptance is separate |
| Queries and mutations | frontend/src/hooks/ |
Query state and mutations; domain-specific recovery remains explicit |
| Privileged policy | backend/routes/, backend/services/ |
API policy and services; metadata alone does not prove every resource check |
| Persistent invariants | supabase/migrations/, supabase/tests/ |
Records, RLS and transactions; test execution has its own scope |
| Runtime and release | ops/, scripts/ops/, deployment runbooks |
Runtime entry points; runtime services, publication and operations own the detailed contracts |
See the topic map for each subject’s reader question and article type. Coverage records all 85 reviewed answers and their evidence limits.