Architecture

The canonical, always-current architecture spec lives in the product repo’s Starlight docs (vincentmcleese/discoverability-platform → docs/). This page holds only the durable invariants + the entry points to read. Do not restate the spec here — link to it and let it drift in the repo, not the brain.

Current truth (the load-bearing invariants)

• Four Neon schemas only: catalog (brands, integrations, registry), shared (accounts, proxies, sessions, cost/health/ban events), intelligence (prompts, runs, turns, responses, extractions, rollups), identity (users, orgs, memberships). No monitor/frontend schemas.
• Append-only tables (never UPDATE/DELETE, no updated_at): prompt_responses, prompt_run_turns, prompt_run_artifacts, account_spend_ledger, account_health_events, platform_ban_events. Re-extraction preserves history — add columns/tables, don’t mutate the past.
• Platforms are adapters behind one PlatformClient interface; adding a host touches the platform package + a detail migration + fleet config, not core orchestration.
• Capture tiers: UI-tier runs capture raw response + DOM snapshot + network + console + screenshots; API-tier capture raw response + optional network. This capture is the moat.
• context_hash is both data identity and routing identity — deterministic across equivalent context tuples.
• Deploy: Railway by default; Fly only for static egress / self-hosted browser; managed browsers (Browserless/Browserbase) are the baseline.

Read these (canonical docs, in order)

1. Vocabulary — read first; the authoritative glossary (ADO≠AEO, Prompt≠query, Brand, Integration, Substrate, Run/turn).
2. System overview — the component landscape and how data flows through it.
3. The runtime loop — the seven stages of agent decision-making that the platform instruments.
4. Data model — the four schemas in detail (catalog, shared, intelligence, identity).

Go deeper

• Platform adapters — one interface, many hosts, tiered execution.
• Orchestration — two-tier job system; Celery-first, Temporal-ready.
• Capture layer — what we record per run and why it’s the moat.
• Extraction pipeline — captured responses → structured facts.
• Rollups and analytics — daily aggregates + semantic dashboard facts.
• For the score specifically, see ado-score-model (which links the measurement methodology).

Open questions

• (none open — add architecture uncertainties here as they arise)

Timeline

• [2026-06-14] (setup) Page created as a thin pointer into the repo docs/ Starlight site; invariants summarized from the product CLAUDE.md. Links target main on GitHub.