Dispatch — Production Implementation Design

Status: Draft for review · Last updated: 2026-06-15

This document is the agreed production architecture for taking Dispatch — the operating system for an AI-augmented BPO cooperative — from the current design-system reference (design-system/) to a shipping product. It is the input to the implementation plan; it defines intent and architecture, not a task list.

Read alongside:

• design-system/design.md — product + UI spec and the Angular handoff (§8). Source of truth for intent.
• design-system/STATUS.md — current state of the reference build.
• docs/implementation/backend-architecture.md — the Contract-Q&A scaffold whose stack we adopt (see §1).

---

1. Foundational decisions

#	Decision	Choice	Rationale
D1	Relationship to docs/implementation/ (Contract-Q&A platform)	Option A — adopt its stack as the Dispatch backend foundation; the document-Q&A pipeline becomes the basis of Dispatch AI.	The scaffold is a proven Go + Python + Supabase + Redis + RAG stack and deploy pattern. It covers only a sliver of Dispatch's domain, so the broader domain is built on the same stack.
D2	Primary backend	One Go (Gin) API for the whole relational/CRUD/governance/GACx/validation domain.	Single API surface; Go's concurrency suits sync + SSE streaming.
D3	Async worker	Python (Celery + FastAPI) scoped only to document ingestion + embeddings.	Python's libraries (PyMuPDF, chunking) earn their place there and nowhere else.
D4	Authorization model	Role-based, not owner-only RLS.	Dispatch members see their own queue; MPs/Admins manage everyone. The scaffold's per-owner RLS is the wrong model and is replaced.
D5	Auth provider	Supabase Auth with Google Workspace (OIDC), hosted-domain restricted.	Provides the JWT the Go API expects, the OIDC name claim for registration prefill (design.md §5.4), and the SSO gate.
D6	Vector store	pgvector (in Supabase Postgres), not Pinecone.	One fewer managed dependency; vectors co-located with mandate/document rows; sufficient at co-op scale. A thin vector-store interface keeps Pinecone a drop-in if scale demands.
D7	GACx	Internal double-entry ledger in Postgres, 1:1 USD-pegged unit of account; on-chain settlement deferred behind a SettlementProvider interface.	De-risks launch; the wallet UI already assumes a balances/transactions shape.
D8	Realtime/notifications	Supabase Realtime (Postgres change feed).	Broadcasts cross-user (e.g. MP alerted on member registration) without extra infra.
D9	v1 scope	MVP core first, then phase (see §10).	Shortest path to a real, usable backend; AI/GACx-movement/pulse/OKR/voting follow.
D10	Hosting	Angular → Cloudflare (SSG + SSR Worker, CDN/WAF/DNS); Go API + Python worker → Fly.io; Redis → Upstash (managed); DB/auth/storage/realtime → Supabase.	User-chosen split, refined: managed Redis over a self-hosted container; Cloudflare fronts everything.
D11	Frontend	Latest Angular — standalone + signals, zoneless, SSR/SSG — per design.md §8. The scaffold's Angular 17 UI is reference only.	The committed target; theme/tokens port unchanged.
D12	AI models	Haiku 4.5 (routing/summaries) · Sonnet 4.6 (default Q&A) · Opus 4.8 (heavy analysis), with the scaffold's cost-tracking + semantic-cache layer repriced to current rates.	The scaffold pins stale model IDs/pricing (claude-3-5-*, opus-4-6); see §8.
D13	API documentation	OpenAPI via swaggo/swag + gin-swagger annotations; Swagger UI served at /swagger.	Standardizes the API contract; the generated spec drives a typed Angular client so FE/BE stay in sync, and CI catches drift between annotations and routes.
D14	Document → ingestion format	Convert PDF / Word / Excel → Markdown (via MarkItDown) as the normalization step before chunking/embedding.	Markdown is a clean, structure-preserving representation for LLM ingestion, and one converter handles all three office/PDF formats. Lands in Phase 2 with Dispatch AI.

What we adopt vs. correct from the Contract-Q&A scaffold

• Adopt: Go API + SSE streaming; Python/Celery ingestion; Redis queue; Supabase Postgres + Storage; Voyage AI embeddings; Claude RAG pipeline; the cost-tracking + semantic-cache + model-routing layer; Fly/Upstash deploy pattern.
• Correct: owner-only RLS → role-aware authZ (D4); Pinecone → pgvector (D6); thin users/mandates/documents/chat_messages schema → full Dispatch domain (§5); Angular 17 reference UI → latest-Angular target (D11); stale Claude model IDs/pricing → current generation (D12). "Mandate" in the scaffold is a generic document folder; in Dispatch it is a client engagement with rate/duration/assignee/scope/status and derived completion.

---

2. System topology

┌──────────────────────────────────────────────────────────────────────────────────┐
│  USERS   Member Partners · Managing Partners · Admins · Board                      │
└───────────────────────────────┬────────────────────────────────────────────────────┘
                                 │ HTTPS
                 ┌───────────────▼───────────────────────────────────────┐
                 │  CLOUDFLARE  — DNS · CDN · WAF                          │
                 │  ┌───────────────────────────┐  ┌────────────────────┐ │
                 │  │ Angular (latest)           │  │ SSG (prerendered)  │ │
                 │  │ standalone·signals·zoneless│  │ landing/login/reg  │ │
                 │  │ SSR Worker (authed app)    │  │ + static assets    │ │
                 │  │ tokens: styles/bespoke.css │  └────────────────────┘ │
                 │  └───────────────────────────┘                          │
                 └───────┬───────────────────────────────┬─────────────────┘
            REST + SSE   │                                │  OIDC redirect
                         ▼                                ▼
        ┌────────────────────────────────┐      ┌──────────────────────────┐
        │  FLY.io                         │      │  GOOGLE WORKSPACE OAuth   │
        │ ┌────────────────────────────┐ │      │  (hosted-domain restricted)│
        │ │ GO API (Gin :7070)         │ │      └─────────────┬────────────┘
        │ │  auth/role-guard           │ │                    │ JWT + name claim
        │ │  crud[T] (schema engine)   │ │◄───────────────────┘
        │ │  completion · skills/valid │ │
        │ │  gacx ledger               │ │      ┌──────────────────────────┐
        │ │  dispatch-ai (SSE)         │ │◄────►│  UPSTASH REDIS            │
        │ │  notifications · /health   │ │      │  job queue · rate limit  │
        │ └───────────┬────────────────┘ │      │  semantic cache          │
        │             │ enqueue ingest    │      └──────────────────────────┘
        │ ┌───────────▼────────────────┐ │
        │ │ PYTHON WORKER (Celery)     │ │      ┌──────────────────────────┐
        │ │  PyMuPDF→chunk→embed→upsert│ │◄────►│  VOYAGE AI (embeddings)   │
        │ └───────────┬────────────────┘ │      └──────────────────────────┘
        └─────────────┼──────────────────┘
                      │ SQL / pgvector / storage / realtime           ┌──────────────────────┐
                      ▼                                               │ CLAUDE API           │
        ┌────────────────────────────────────────────┐  dispatch-ai  │ Haiku 4.5  (routing) │
        │  SUPABASE                                   │◄─────────────►│ Sonnet 4.6 (default) │
        │  Postgres + pgvector · Storage · Auth ·     │   SSE stream  │ Opus 4.8   (heavy)   │
        │  Realtime (change-feed → notifications)     │               └──────────────────────┘
        └────────────────────────────────────────────┘

flowchart TB
  subgraph CF["Cloudflare — CDN · WAF · DNS"]
    NG["Angular (standalone·signals·zoneless)<br/>SSR Worker + SSG prerender<br/>tokens: styles/bespoke.css"]
  end
  subgraph FLY["Fly.io"]
    GO["Go API (Gin :7070)<br/>auth·crud[T]·completion<br/>skills·gacx·dispatch-ai·health"]
    PY["Python worker (Celery)<br/>extract→chunk→embed→upsert"]
  end
  RED["Upstash Redis<br/>queue · rate limit · cache"]
  subgraph SB["Supabase"]
    PG["Postgres + pgvector"]
    ST["Storage"]
    AU["Auth"]
    RT["Realtime"]
  end
  GW["Google Workspace OAuth (OIDC)"]
  VO["Voyage AI (embeddings)"]
  CL["Claude API<br/>Haiku 4.5 · Sonnet 4.6 · Opus 4.8"]

  USERS["Members · MPs · Admins"] -->|HTTPS| CF
  NG -->|REST + SSE| GO
  NG -->|OIDC| GW
  GW -->|JWT + name| AU
  AU --> GO
  GO <-->|queue / cache| RED
  GO -->|SQL / pgvector| PG
  GO -->|publish| RT
  RT -->|notifications| NG
  PY <--> RED
  PY -->|embed| VO
  PY -->|vectors| PG
  PY --> ST
  GO -->|embed query| VO
  GO -->|SSE stream| CL

Request flows

1. Login — Angular → Google OIDC → Supabase Auth → JWT (with role) → Go API role-guard.
2. CRUD — Angular → Go API crud[T] → Supabase Postgres (MP/Admin: all rows · Member: own).
3. Ask (RAG) — Angular → Go /mandates/:id/ask → embed (Voyage) → pgvector top-k → context + live tasks/OKRs/pulse → Claude → SSE → browser-only render.
4. Ingest — upload → Go (202 Accepted) → Upstash queue → Python worker → convert (PDF/Word/Excel → Markdown) → chunk → embed → pgvector → mark ready.
5. GACx — task transitions to Passed → Go gacx → double-entry posting (Supabase).
6. Notify — registration/event → Supabase Realtime → all MP clients; connection pill polls /health.

Hosting caveat (SSR placement)

Angular SSR on Cloudflare runs on the Workers runtime (not full Node), and SSR render-time fetches hop Cloudflare-edge → Fly-region. Mitigate with TransferState + edge caching + a Fly primary region near most members. Fallback if SSR latency or Workers-runtime limits bite: move only the SSR server to Fly beside the API, keeping Cloudflare for SSG/static + CDN. The current Angular-on-Workers adapter status is to be re-verified during implementation.

---

3. Backend services (Go API)

The Go API is the single public gateway. Modules:

• auth — verifies the Supabase JWT; role-guard middleware enforces membership_role (Member Partner / Managing Partner / Admin). MP-only actions (skill validation) gated server-side.
• crud[T] — a generic, typed CRUD engine that mirrors the reference admin.js SCHEMA: one schema definition drives table columns, create/edit validation, and seed concerns per entity. Adding a field/entity = extend the schema + model.
• completion — derives mandate completion live from tasks, weighted by status (Passed 100% · Live 60% · Progress 50% · Queued/Failed 0%). Shared rule, never stored.
• skills/validation — skills catalog, per-user-skill self/validated scores (0.00–10.00, 2 decimals), coefficient (default 0), and the validation queue.
• gacx — the double-entry ledger (see §6).
• dispatch-ai — RAG ask endpoint, SSE streaming (see §7).
• notifications — writes notifications + publishes via Supabase Realtime.
• health — heartbeat for the connection indicator.

REST surface (mirrors design.md §8 routing)

/organizations                      CRUD
/mandates                           CRUD
/mandates/:id/tasks                 CRUD (tasks scoped to a mandate)
/mandates/:id/documents/upload      POST → 202, enqueues ingestion
/mandates/:id/ask                   POST (SSE) — Dispatch AI
/users                              CRUD
/users/:id/skills                   self/validated scores, coefficient
/validation-queue                   pending skills across all members
/votes                              CRUD + ballots
/gacx/accounts /gacx/transactions   ledger reads + transfers
/notifications                      list/mark-read
/health                             connection heartbeat

Python worker (narrow)

Document ingestion only: download from Storage → convert to Markdown (PDF / Word / Excel → MD via MarkItDown) → chunk the Markdown with overlap → embed in batches (Voyage AI) → upsert vectors to pgvector → mark document ready. The Markdown is also retained for citation/preview. At-least-once delivery (Celery task_acks_late), retry with backoff, scale by queue depth.

API documentation (OpenAPI / Swagger)

The Go API is annotated with swaggo/swag; gin-swagger serves interactive Swagger UI at /swagger/index.html plus the generated swagger.json. The generated OpenAPI spec is the source of the API contract:

• A typed Angular client is generated from the spec (e.g. openapi-generator / orval) so frontend and backend models stay in sync — no hand-written DTOs.
• swag init runs in CI; the build fails on drift between annotations and registered routes, keeping the contract honest.
• Handler annotations document request/response schemas, auth requirements, and error shapes, standardizing the API surface across the crud[T] engine and bespoke endpoints (/ask, /gacx/*, /validation-queue).

---

4. Auth & roles

• Provider: Supabase Auth, Google Workspace OIDC, restricted to the workspace hosted domain (the SSO gate; the reference simulates this).
• Identity: OIDC name claim pre-fills the registration Profile step (design.md §5.4), kept editable.
• Token: Go API verifies the Supabase-issued JWT on every protected route; extracts user_id + membership_role.
• AuthZ (role-based, D4):
  • Member Partner — sees own dispatch queue, own mandates/tasks, own profile/skills/wallet.
  • Managing Partner / Admin — manage all orgs/mandates/tasks/users; run the validation queue; MP-only skill validation.
• Registration — first-run flow writes a pending user with all skills pending (coefficient 0), lands in the admin Users list, fires the MP notification, populates the validation queue.

---

5. Domain data model

All tables carry created_at / updated_at and role-aware policies. Completion is derived, not stored.

                         ┌──────────────┐
              ┌──────────│ organizations│──────────┐
              │ 1      * └──────────────┘          │ 1
              ▼                                     ▼  *
      ┌───────────────┐  *        1 ┌────────────────────┐  1     * ┌──────────────┐
      │   mandates    │◄────────────│      users         │─────────►│  user_skills │
      │ rate·duration │  assignee   │ membership_role    │          │ self_score   │
      │ scope·status  │             │ function·org       │          │ validated 0–10│
      └──────┬────────┘             │ (Supabase identity)│          │ coefficient  │
        1    │  *                   └─────┬───────┬──────┘          │ status       │
             ▼                            │       │                 └──────┬───────┘
      ┌───────────────┐                   │       │ 1            *         │ *
      │    tasks      │                   │       ▼                        ▼
      │ status·due    │           1       │  ┌──────────┐          ┌──────────────┐
      │ gacx_reward   │   completion ◄────┘  │vote_ballots│        │   skills     │
      └──────┬────────┘   (DERIVED)          └────┬─────┘          │  (catalog)   │
             │  *                               * │ 1              └──────────────┘
             ▼                                     ▼
      ┌───────────────┐                     ┌──────────┐     ┌──────────────────────┐
      │  documents    │ 1   * ┌──────────┐  │  votes   │     │ pulse_* · okrs ·     │
      │ status·storage│──────►│ chunks   │  │ quorum % │     │ key_results ·        │
      └───────────────┘  pgvector vectors  └──────────┘     │ notifications        │
                                                             └──────────────────────┘
   GACx LEDGER (double-entry, append-only)
   ┌──────────────┐ 1   * ┌──────────────────┐ 1   * ┌──────────────┐
   │ gacx_accounts│──────►│ gacx_transactions│──────►│ gacx_postings│  Σ legs = 0
   │ user/org/treas│ idempotent             │  debit/credit · 1:1 USD peg
   └──────────────┘       └──────────────────┘       └──────────────┘

Key fields (from design.md §5.3):

• organizations — name, contract, type, mandate count, status.
• mandates — title, org, rate (GACx/h), duration, assignee, status, scope.
• tasks — title, mandate, assignee, due, gacx_reward, status (Queued/Progress/Live/Passed/Failed), updated. A task assigned to a user is referred to as a "dispatch" in product/UI language (the table stays tasks); the member Dispatch tab is a user's queue of dispatches.
• users — name, workspace email (SSO identity), membership_role, function, status, gacx account, skills[].
• user_skills — self_score + validated_score (0.00–10.00, 2 decimals), coefficient (default 0), status (pending/approved/rejected).
• votes / vote_ballots — ref, title, approval %, quorum (voted/eligible), closes, status; one ballot per eligible member.
• documents / chunks — document status + storage path; chunks hold pgvector embeddings + metadata (doc, chunk_index, text, page).

---

6. GACx ledger

Double-entry, append-only:

• gacx_accounts — one per user / org / treasury.
• gacx_transactions — idempotent (client-supplied idempotency key), references the business event (e.g. task pass).
• gacx_postings — debit/credit legs; legs of a transaction sum to zero.

Balance = sum of an account's postings (optionally a maintained materialized balance for read speed). 1:1 USD-pegged unit of account. Task → Passed posts the reward. On-chain settlement is deferred behind a SettlementProvider interface (Phase 3) so no ledger rewrites are needed later.

---

7. Dispatch AI subsystem (Phase 2)

The Contract-Q&A RAG pipeline becomes Dispatch AI.

Member         Angular            Go API (dispatch-ai)        Voyage     pgvector    Claude
  │  question    │                       │                      │           │          │
  ├─────────────►│ POST /ask (JWT)        │                      │           │          │
  │              ├──────────────────────►│ embed(question) ─────►│           │          │
  │              │                        │◄──── vector ─────────┤           │          │
  │              │                        │ top-k search ────────────────────►│         │
  │              │                        │◄──── chunks ──────────────────────┤         │
  │              │                        │ assemble: chunks + live tasks/OKRs/pulse     │
  │              │                        │ (cache check: Upstash) ──► route model       │
  │              │                        │ stream ─────────────────────────────────────►│
  │              │  SSE: sources          │◄──── token stream (Sonnet 4.6 default) ──────┤
  │◄─────────────┤  SSE: token…token      │ record cost + cache (current pricing)         │
  │  (browser-   │  SSE: done             │ persist Q&A                                   │
  │   only render)                        │                                               │

• Ingestion = mandate documents (PDF/Word/Excel) → Markdown (MarkItDown) → chunked → embedded (Voyage) → pgvector, by the Python worker (§3).
• Context = retrieved mandate-document chunks (pgvector) plus the member's live structured data (tasks/mandates/OKRs/pulse), assembled into a typed system prompt server-side.
• Models (D12): Haiku 4.5 for summaries/cheap routing · Sonnet 4.6 default for Q&A · Opus 4.8 for heavy analysis. Prompt-caching on the stable context prefix.
• Cost layer: keep the scaffold's cost-tracking + semantic cache + model router, repriced to current rates (§8).
• SSR-safe: the chat renders browser-only (afterNextRender) — no completion calls during hydration. The Claude API key stays server-side on Fly.

---

8. Claude models & pricing (current)

The scaffold pins stale model IDs (claude-3-5-sonnet-20241022, claude-opus-4-6) and matching pricing. Re-pin to current generation:

Role	Model ID	Input $/MTok	Output $/MTok	Context
Routing / summaries	claude-haiku-4-5	1.00	5.00	200K
Default Q&A	claude-sonnet-4-6	3.00	15.00	1M
Heavy analysis	claude-opus-4-8	5.00	25.00	1M

The cost-tracking query_metrics / query_cache tables and the model-router keyword logic carry over; only the pricing constants and model IDs change. Use streaming for any large output; prompt-cache the stable prefix.

---

9. Frontend (Angular)

• Stack: latest Angular — standalone components, signals, zoneless change detection, SSR + SSG hybrid (design.md §8).
• Theme/tokens port unchanged: import styles.css + bespoke.css at the app root; DaisyUI + Tailwind via PostCSS (drop the CDN injection from app-shell.js). DaisyUI component classes used straight in templates.
• Schema-driven UI: admin.js SCHEMA → typed models + a generic CrudService<T> + schema-driven table/form components.
• State: signals; onclick="" → (click); async via httpResource() / toSignal().
• Rendering: SSG-prerender public routes (landing/login/register entry); SSR the authed app with provideClientHydration(withEventReplay()). Browser-only concerns (connection indicator, service worker, localStorage cache, Dispatch AI) deferred to afterNextRender.
• Mobile template remains a responsive/native design reference, not a literal target.

---

10. v1 scope & phasing

 PHASE 1 — MVP CORE (go-to-prod)        PHASE 2                    PHASE 3 (final)
 ───────────────────────────────       ──────────────────         ─────────────────────
 ▸ Google Workspace auth + roles       ▸ Dispatch AI (RAG)         ▸ GACx wallet
 ▸ Admin CRUD (orgs/mandates/           ▸ Pulse surveys              · double-entry ledger
   tasks/users) on real backend         ▸ OKRs                       · value-movement
 ▸ Member app (Dispatch/Mandates/       ▸ Governance voting          · on-chain settlement
   Tasks)                                                              (SettlementProvider)
 ▸ Skills catalog · registration ·     uses: Python worker,
   validation queue                    Voyage, Claude, pgvector,    (tasks show gacx_reward
 ▸ Completion derivation                Upstash cache                as display-only until
 ▸ Connection indicator · PWA                                        this phase)
 ▸ CI/CD · tests (Go/Py/Angular/e2e)
 ───────────────────────────────
 Foundation built once, all phases:
 Cloudflare · Fly · Upstash · Supabase · role-aware authZ

• Phase 1 (MVP core / go-to-prod): Google Workspace auth + role gating; admin CRUD (orgs/mandates/tasks/users) on the real backend; member app (Dispatch/Mandates/Tasks); skills catalog + registration + validation queue; completion derivation; connection indicator + PWA; CI/CD + tests. Tasks carry gacx_reward as a display-only field in this phase (no ledger postings yet).
• Phase 2: Dispatch AI (RAG pipeline); Pulse surveys; OKRs; governance voting.
• Phase 3 (final): GACx wallet — the double-entry ledger, value-movement, and on-chain settlement (introducing the SettlementProvider interface).

The shared foundation (Cloudflare/Fly/Upstash/Supabase, role-aware authZ) is built once in Phase 1 so later phases add features, not infrastructure. The GACx ledger schema (§5, §6) lands in the final phase, not the Phase-1 foundation — until then gacx_reward is a plain column displayed on tasks.

---

11. Testing & verification

The reference repo has no test runner today; production adds:

• Go API — table-driven unit tests; httptest for handlers; integration against Supabase-local / testcontainers.
• Python worker — pytest on chunking/embedding with a stubbed Voyage client.
• Angular — unit + signal/component tests; Playwright e2e for critical flows (login → dispatch; registration → MP validation; live vote).
• Shared rules — dedicated tests for completion (weighted task status) and 0.00–10.00 / 2-decimal competence on both Go and Angular sides so surfaces agree.

---

12. Deployment & CI

• Cloudflare — Pages/Workers build for Angular (SSG + SSR).
• Fly.io — fly.toml per service: Go API (autoscale 1–N), Python worker (always-on, scale by queue depth).
• Upstash — managed Redis (queue + rate limit + cache).
• Supabase — Postgres + pgvector + Storage + Auth + Realtime; migrations as SQL under supabase/migrations.
• CI (GitHub Actions) — lint/test/build → deploy. Secrets in Fly/Cloudflare secret stores; Claude + Voyage keys server-side only, never in the browser.

---

13. Open questions / risks

• Angular-on-Cloudflare-Workers SSR is the least battle-tested piece — verify the current adapter; SSR-on-Fly fallback (§2) is the contingency.
• pgvector at scale — fine for co-op-scale corpora; revisit Pinecone only if query latency degrades (interface keeps this cheap).
• Eligibility/quorum rules for governance voting (Phase 2) need product definition before that phase.
• Pulse anonymity guarantees (Phase 2) need a privacy review before storing responses.
• GACx (final phase) — the wallet, ledger value-movement, and on-chain settlement (chain choice, custody, peg mechanism) are the last workstream; on-chain is a separate, specialized effort out of scope for v1.

---

Next step: review this spec, then we turn Phase 1 into a step-by-step implementation plan.