%% docs/architecture.mmd
%%
%% Novel Systems — request flow, as merged.
%%
%% This diagram describes what is in `main` and deployed, not what the PRD
%% plans. A dashed border means the node is a third party outside our control:
%% the edge exists in code and is tested up to the provider boundary, and what
%% happens past that boundary is theirs.
%%
%% WHAT THIS DIAGRAM DELIBERATELY DOES NOT SAY.
%%
%% Until 5 August 2026 the three provider nodes carried their own readiness on
%% their faces — "awaiting STRIPE_SECRET_KEY", "awaiting tenant consent" — and
%% were drawn dashed amber to match. Every one of those labels was wrong by the
%% time anyone read it. Stripe had been transacting in test mode for a day and
%% `GET /api/connectors` reported it `platform_account_live`; the other two were
%% `operator_credentials_missing`, which is a further-back state than the
%% consent screen the label described.
%%
%% The mistake was not the labels being stale. It was writing a perishable fact
%% into an artifact that is rendered by hand and can only be corrected by hand.
%% lib/connector-readiness.ts states the rule about itself and it applies here
%% with more force, not less: whether a connector can transact today is derived
%% from the deployment at request time and published at /integrations. A
%% hand-rendered PNG is the worst possible carrier for it.
%%
%% So these nodes now state only the durable structural fact — which trigger
%% fires the call, whether credentials are platform-wide or per-tenant, which
%% object gets written — and the reader is sent to /integrations for the state.
%% `scripts/check-diagram-current.mjs` fails the build if readiness vocabulary
%% comes back into a provider node.
%%
%% Render:  double-click render-diagram.command in the repository root. It drives
%%          the Chrome already installed on the machine and writes
%%          docs/architecture.png beside this file. mermaid-cli is not used —
%%          it needs a Chromium that does not exist for arm64 Linux, which is
%%          what this repository is built on. The script explains the rest.
%%
%% Read it as three horizontal bands. The top band is what a browser touches.
%% The middle is the two Vercel projects. The bottom is Postgres, and the line
%% across it — the RLS boundary — is the one structural claim this platform
%% makes that is worth drawing: every query the API issues runs as a
%% non-privileged role inside a transaction that has declared which tenant it
%% is acting for.

flowchart TB

  %% ── Clients ────────────────────────────────────────────────────────────
  subgraph clients["Clients"]
    direction LR
    visitor["Anonymous visitor<br/>novelsystems.ca"]
    operator["Authenticated operator<br/>ADMIN · SALES"]
    tech["Technician<br/>mobile, TECHNICIAN"]
    integrator["Integrator's own system<br/>ERP · dispatch board"]
  end

  %% ── Edge ───────────────────────────────────────────────────────────────
  cloudflare["Cloudflare DNS<br/><i>novelsystems.ca, www, docs, status</i>"]

  %% ── Frontend ───────────────────────────────────────────────────────────
  subgraph frontend["Vercel · novelsystems.ca — Next.js 14 App Router"]
    direction TB
    pages["Server components<br/><i>marketing, /developers, /security</i>"]
    sandbox["CPQ sandbox<br/><i>components/cpq — browser engine</i>"]
    browserEngine["lib/cpq-engine.ts<br/><b>bundled to the browser</b><br/>cut list · 50% floor"]
    proxy["app/api/cpq/calculate<br/><i>server-side credential</i>"]
    forms["app/api/{contact,careers,support,quote}"]
  end

  %% ── Backend ────────────────────────────────────────────────────────────
  subgraph backend["Vercel · novel-systems-backend — Express + TypeScript"]
    direction TB

    subgraph chain["Middleware, in order"]
      direction LR
      helmet["helmet"] --> corsmw["cors<br/><i>allowlist</i>"] --> rawmw["raw 1mb<br/><i>webhook path only</i>"] --> bodymw["json 256kb"] --> ratemw["rateLimit<br/>300/min"]
    end

    health["GET /api/health<br/><i>select 1 · exempt from the limiter</i>"]
    login["POST /api/v1/auth/login<br/><i>argon2 · 10 per 15 min per account</i>"]
    authmw["requireAuth<br/><i>JWT, 900s · re-checked against the row</i>"]
    rolemw["requireRole<br/><i>ADMIN · SALES · TECHNICIAN</i>"]
    quotes["/api/v1/quotes<br/><i>calculate · list · approve</i>"]
    workorders["/api/v1/work-orders<br/><i>list · create · status</i>"]
    serverEngine["services/cpq-engine.ts<br/><b>never bundled to a browser</b><br/>cut list · 50% floor · rate cards"]
    dispatcher["services/webhook-dispatcher.ts<br/><i>HMAC · 5 attempts · ~1 min</i>"]
    tenantctx["db/tenant.ts — withTenant()<br/><b>set_config('app.current_organization_id', …, local)</b>"]

    subgraph integlayer["src/integrations — provider layer"]
      direction TB
      integroutes["/api/v1/integrations<br/><i>list · connect · callback · disconnect · syncs</i>"]
      stripehook["POST /integrations/stripe/webhook<br/><i>unauthenticated · signature is the auth</i>"]
      oauthstate["oauth-state.ts<br/><i>HMAC state · 600s · signature checked first</i>"]
      envelope["crypto.ts — AES-256-GCM<br/><b>v1.iv.tag.ciphertext</b><br/><i>refresh tokens never land in plaintext</i>"]
      fanout["fan-out.ts<br/><i>runs on quote.approved, after commit</i>"]
      connstore["connection-store.ts<br/><i>one row per tenant × provider</i>"]
      syncstore["sync-store.ts<br/><i>idempotency + attempt counter</i>"]
    end
  end

  %% ── Data ───────────────────────────────────────────────────────────────
  subgraph data["Supabase Postgres 15 · ca-central-1"]
    direction TB
    rls{{"ROW LEVEL SECURITY<br/>role novel_app · FORCE RLS<br/><i>every table, per-tenant policy</i>"}}
    coretables[("organizations · users<br/>inventory_skus · labor_tiers<br/>quotes · work_orders<br/>webhooks · webhook_deliveries<br/>integration_connections · integration_syncs")]
    lookupfn["integration_sync_lookup()<br/><b>SECURITY DEFINER</b><br/><i>the only way in without a tenant</i>"]
    sitetables[("leads · job_applications<br/>support_tickets · quotes (marketing)<br/>audit_events")]
  end

  %% ── Outbound ───────────────────────────────────────────────────────────
  resend["Resend<br/><i>notification mail</i>"]
  subscriber["Subscriber endpoint<br/><i>customer-registered</i>"]

  %% Third parties. Dashed because the far side of the edge is not ours, not
  %% because of anything about how ready it is — see the header. Each label is
  %% the durable fact: where the credential lives, and what object the adapter
  %% writes when quote.approved fires.
  stripe["Stripe<br/><i>platform credential · one account</i><br/><b>writes an invoice</b>"]
  quickbooks["QuickBooks Online<br/><i>per-tenant OAuth</i><br/><b>writes an invoice</b>"]
  salesforce["Salesforce<br/><i>per-tenant OAuth</i><br/><b>writes an opportunity</b>"]

  %% The one place readiness is allowed to appear, and it appears as an address
  %% rather than as a value.
  readiness["Which of these can transact today<br/>is derived per deployment, not drawn here.<br/><b>GET /api/connectors</b> · published at /integrations"]

  %% ── Flows ──────────────────────────────────────────────────────────────
  visitor --> cloudflare
  operator --> cloudflare
  tech --> cloudflare
  cloudflare --> pages
  cloudflare --> proxy
  integrator -->|"Bearer JWT, direct"| chain

  pages --> sandbox
  sandbox -->|"instant, no network"| browserEngine
  sandbox -->|"priced quote"| proxy
  proxy -->|"service credential<br/>8s timeout"| chain
  forms --> resend
  forms -->|"service_role key<br/><i>bypasses RLS by design</i>"| sitetables

  chain --> health
  chain --> login
  chain --> stripehook
  chain --> authmw
  authmw --> rolemw
  rolemw --> quotes
  rolemw --> workorders
  rolemw -->|"ADMIN only"| integroutes
  quotes --> serverEngine
  quotes --> tenantctx
  workorders --> tenantctx
  serverEngine --> tenantctx
  health -.->|"select 1"| data

  tenantctx ==>|"one transaction<br/>one tenant"| rls
  rls --> coretables

  quotes -->|"quote.approved<br/><i>after commit, not awaited</i>"| dispatcher
  workorders -->|"work_order.*"| dispatcher
  dispatcher -->|"POST · x-novel-signature"| subscriber
  dispatcher --> coretables

  %% ── Integrations ───────────────────────────────────────────────────────
  quotes ==>|"quote.approved<br/><i>same trigger as the dispatcher</i>"| fanout
  fanout --> syncstore
  fanout --> connstore
  integroutes --> oauthstate
  integroutes --> connstore
  integroutes --> syncstore
  connstore --> envelope
  connstore --> tenantctx
  syncstore --> tenantctx

  %% An inbound Stripe delivery names a Stripe invoice, not a tenant. The
  %% SECURITY DEFINER function is the one read allowed to answer "whose is
  %% this?" — after which everything reverts to withTenant.
  stripehook -->|"raw bytes<br/>HMAC · 300s tolerance"| syncstore
  syncstore -.->|"resolveByExternalId"| lookupfn
  lookupfn --> coretables

  fanout -.->|"invoice"| stripe
  fanout -.->|"invoice"| quickbooks
  fanout -.->|"opportunity"| salesforce
  stripe -.- readiness
  readiness -.- salesforce
  oauthstate -.->|"authorize · consent · token exchange"| quickbooks
  oauthstate -.->|"authorize · consent · token exchange"| salesforce
  stripe -.->|"invoice.paid<br/>invoice.payment_failed"| stripehook

  %% ── The claim worth drawing ────────────────────────────────────────────
  note["The two engines cannot import from each other —<br/>one ships to a browser, one must not.<br/>They are held together by fixtures/cut-list-parity.json<br/>and by check:cpq-parity in CI. See D-002, D-010."]
  browserEngine -.- note
  note -.- serverEngine

  %% ── Styling ────────────────────────────────────────────────────────────
  %% Renamed from `unbuilt` on 5 August 2026. The old name asserted a fact about
  %% our code — that these paths did not exist — which was never true of any of
  %% them and had stopped being defensible about Stripe. Third-party is a
  %% property of the node that cannot go stale.
  classDef thirdparty stroke-dasharray:6 4,stroke:#0f766e,color:#0f766e,fill:#f0fdfa
  classDef boundary fill:#fee2e2,stroke:#b91c1c,stroke-width:2px,color:#7f1d1d
  classDef engine fill:#eef2ff,stroke:#4338ca,color:#312e81
  classDef store fill:#f0fdf4,stroke:#15803d,color:#14532d
  classDef annotation fill:#f8fafc,stroke:#94a3b8,stroke-dasharray:3 3,color:#475569

  class stripe,quickbooks,salesforce,resend,subscriber thirdparty
  class readiness annotation
  class rls,tenantctx,envelope,lookupfn boundary
  class browserEngine,serverEngine engine
  class coretables,sitetables store
  class note annotation