#TradeForce — system architecture

#Purpose

TradeForce is a shift marketplace where companies post construction jobs, contractors claim and work them, both sides track time and approvals, and platform admins verify people and rates. This document describes the running target application: a React SPA under app/ talking to Supabase Auth, Postgres with row-level security, and Edge Functions for secrets and privileged orchestration.

The source product was a Bubble app. The migration keeps product journeys and data meaning, but does not copy Bubble’s browser-as-database trust model. Assessment finding LOG-CLIENT-WRITES (about 97% of database writes lived in client workflows) is an architecture law here: every persistent write lands behind authenticated server authority (RLS policies and/or SECURITY DEFINER RPCs / Edge Functions under app/supabase). Money-adjacent mutations (rates, paid amounts, approval flags) additionally follow MON-CLIENT-WRITES: transactional server authority, never trust the browser as the writer of record.

Programme boundary MON-MARKETPLACE fences Stripe Connect, KYC, live balances, and payouts as separate scope until answered. Auth cutover ACC-AUTH-SURFACE chooses how existing Bubble identities move onto Supabase Auth.

#Runtime context

Target stack: React + Vite + TypeScript SPA (app/) and Supabase backend (app/supabase/ — migrations, RLS, Edge Functions). The browser holds only the anon key and the user JWT. Service-role keys and third-party secrets stay on the server.

Delivery is by vertical slice: each product journey ships UI, client calls, domain rules, and any backend surface together. There is no separate “build the API first” phase.

#SPA modules

Capability modules map to authenticated host routes inside a shared cabinet workspace (header + role sidebar + main outlet). Auth and onboarding sit outside that chrome.

Shared job UI (detailed job view, end-job popup, shift row actions) has a single implement owner in the company-shifts module. Contractor and time-tracking modules reuse those components; they do not fork alternate implementations.

The Bubble stub 404 page is out of product scope.

#Auth and session

Identity target is Supabase Auth (email/password), with a profiles row created on signup for role, active, onboarding-complete, and approved flags used by post-login routing and gates.

Public flows:

1. Sign in → session JWT → redirect by role and profile flags (onboarding vs role home).
2. Sign up with contractor/company role → profile defaults (inactive until activation path) → verify / onboarding.
3. Request reset email → confirm new password on the reset surface → return to sign-in.

Session client lives under app/src/integrations/supabase with the anon key only. Auth errors map once at the boundary to stable domain errors shown in the UI.

ACC-AUTH-SURFACE is still open: the export uses Bubble native login/signup/reset, which do not transfer sessions or password material. An ADR must record (a) credential cutover for existing users (forced reset, dual-run, or equivalent — not a silent password migration) and (b) whether signup activation preserves the active=yes deep-link semantics or replaces them with Supabase confirm-email. Until that ADR is accepted, auth foundation work remains blocked on those decisions (see HQ-1).

Unauthenticated hits to authenticated host routes redirect to the auth index. Chrome is not shown without a session.

#Data access

Schema authority is docs/DATA-MODEL.md (idiomatic Postgres names) realized as migrations under app/supabase/migrations/. The SPA uses the user JWT against PostgREST and RPCs. RLS is the default read/write gate; the SPA must not ship a service-role key or reimplement authorization in the client.

#Server authority (LOG-CLIENT-WRITES / MON-CLIENT-WRITES)

Source backend events that ran with privacy rules disabled (create_list_tracking, send_tracking_approve) have no automatic RLS equivalent. Their elevated behaviour must be expressed as tightly scoped privileged server paths or redesigned under ordinary RLS (see HQ-3).

#Core entity families (target-oriented)

Detailed columns and naming maps belong in the data-model document, not here.

#External systems

#Failure modes

#Traceability

#IR evidence

#Module evidence roots and pages

Supporting slices (prepared bundle): ir/slices/bTGbC____root.json, AAW____root.json, bTHDr0____root.json, bTHMh*, bTIbd*, bTJIF0____root.json, bTIzW0____root.json, bTHuo0*, bTJSr0____root.json, edef_* for shell/reusables, styles____part_all.json.

Path-key aliases: inventory id → prefer inventory pointer (e.g. page id bTGYf → /pages/bTGbC). API event ids resolve to wf_name in inventory meta (create_list_tracking, send_tracking_approve, 15_minuts_delay, shift).

#Backend API events

#Privacy and authorization

• Source ships 25 privacy_role entries across types; deepest conditions are non-trivial — re-express as Postgres RLS / policy helpers, not client checks.
• Assessment ACC-NO-RULES hits no live type: the five types with no privacy roles (company, job, rates, time_tracking, current_contractors_info) are deleted: true in the export and are not migrated, so there is no unprotected table to model. All nine surviving types carry rules. One of them needs a deliberate call rather than a copy: privacy_role:user:everyone is the only everyone role with a permission set (search_for: true), i.e. the source lets unauthenticated visitors search User records.
• Ignore-privacy API events above must become privileged Edge/RPC with hard authz or redesigned under normal RLS (HQ-3).

#External HTTP namespaces

• external_ns:bTNMZ — Postmark templates (canceled shifts, new message, time-tracking report, upcoming payment cycle).
• external_ns:bTKtr — Country State City (states, cities calls).
• Stripe: public_key:stripe_client_id_test, public_key:stripe_public_key_test, secret ref stripe_private_key_test; user fields stripe_account_id_text, stripe_name_text.

#Secrets to re-provision (values are redacted in the sanitized export)

The export carries 14 secret_ref keys. None transfers; each is either re-issued in Supabase/Edge config or retired with the surface it served. Named here because nothing else in the docs claims them:

#Open risks (module-map)

#Needs human clarification