Skip to content

Architecture and execution model

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 browser's RLS path and the server's explicitly authorized privileged path.

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.

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.

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.

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.

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.

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.