AI-powered virtual executive team — a single coherent executive persona backed by 8 specialist agents (FastAPI + Next.js).
"""The fixed registry of architecture-page sections.
The section IDs must match the SECTIONS const in
packages/ui/src/app/architecture/page.tsx so deep links keep working
and the sidebar renders instantly without waiting for the backend.
Each entry tells the generator three things:
* `kb_query` – seed query passed to the RAG retriever to fetch
relevant context chunks for grounding.
* `wants_mermaid` – whether this section should include a diagram.
* `diagram_kind` – `"flowchart"` or `"sequence"`; passed to the prompt
so Claude picks the right Mermaid dialect.
"""
from __future__ import annotations
from typing import Literal
from pydantic import BaseModel
DiagramKind = Literal["flowchart", "sequence"]
class SectionSpec(BaseModel):
id: str
title: str
sub: str
kb_query: str
wants_mermaid: bool
diagram_kind: DiagramKind | None = None
SECTIONS: list[SectionSpec] = [
# ── "Without the Jargon" cluster ──────────────────────────────────
# Plain-language landing sections for non-engineers being walked
# through the system. Tone + content rails live in
# architecture-facts.yaml → `for_executives:`. Each one ends with
# a "see also" pointer to the deeper technical sibling below.
SectionSpec(
id="nojargon_what_it_is",
title="Without the Jargon: What It Is",
sub="The 90-second version. A virtual executive with a council of specialists.",
kb_query="virtual executive specialist council elevator overview",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="nojargon_authority",
title="Without the Jargon: How It Decides To Act",
sub="Three modes — act on its own, propose for approval, or escalate to you.",
kb_query="act propose escalate authority gate three modes",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="nojargon_proactive",
title="Without the Jargon: When You're Not Watching",
sub="Morning brief, check-ins, nudges — Open Executive doesn't wait to be asked.",
kb_query="proactive scheduler morning brief nudges cadences",
wants_mermaid=True,
diagram_kind="sequence",
),
SectionSpec(
id="nojargon_org",
title="Without the Jargon: Who Approves What",
sub="Departments, heads, and approval tags — how proposals find the right person.",
kb_query="departments heads authority scope find approvers",
wants_mermaid=True,
diagram_kind="flowchart",
),
# ── Technical sections (existing) ─────────────────────────────────
SectionSpec(
id="overview",
title="System Overview",
sub="High-level topology: clients, API, orchestrator, specialist agents, knowledge layer.",
kb_query="multi-agent system architecture overview",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="lifecycle",
title="Request Lifecycle",
sub="Full round-trip of a single chat message, including tool-use loop and parallel specialist calls.",
kb_query="chat request lifecycle tool use loop",
wants_mermaid=True,
diagram_kind="sequence",
),
SectionSpec(
id="agents",
title="Agent Council",
sub="The Executive orchestrator and its specialist sub-agents — roles, models, and domains.",
kb_query="specialist agents roles domains",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="caching",
title="Prompt Caching",
sub="How the system prompt is partitioned for Anthropic prompt caching, and what breaks the cache.",
kb_query="anthropic prompt caching cache_control system prompt blocks",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="rag",
title="Knowledge & RAG",
sub="ChromaDB collections, per-specialist domain filtering, and where retrieved context is injected.",
kb_query="ChromaDB knowledge retrieval RAG domain filter",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="review",
title="SME Knowledge Review",
sub="The pending-review queue, priority ordering, and how rejected/approved items affect retrieval.",
kb_query="knowledge review queue SME approval rejection priority",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="memory",
title="Memory System",
sub="Episodic SQLite memory (decisions, initiatives, advice, scheduled actions) and how it's surfaced.",
kb_query="episodic memory decisions initiatives sqlite",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="peer_memory",
title="Peer Memory (Person + Department)",
sub="External peer-keyed memory layer. Two scopes: per-person (cross-channel continuity keyed by Person.id) and per-department (institutional voice keyed by department_<slug>). Dialectic prefetch, fire-and-forget sync, peer-graph cross-pollination, per-fixture workspace isolation, audit trail.",
kb_query="peer memory person department peer card prefetch sync_turn sync_department_turn append_department_note cross channel workspace",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="attunement",
title="Attunement (Open Loops)",
sub="How the Executive keeps track of what each person owes: sender attribution, 👍/👎 feedback, and open loops from anyone on the roster that the nudge engine chases once due and closes when done.",
kb_query="attunement open loops commitments asks sender attribution feedback nudge chase close",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="org",
title="Org Structure (Departments & People)",
sub="Departments, goals, checklists, cadences; people registry; authority gates and channel resolution (Discord/Telegram/email).",
kb_query="departments people authority gate cadence head persona scope tokens",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="audit",
title="Audit Log",
sub="Searchable, append-only record of chat turns, specialist consults, tool calls, scheduled actions, alerts, and inbound integrations.",
kb_query="audit log events sqlite searchable trail",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="schemas",
title="Data Schemas",
sub="Key Pydantic models and database tables — the shape of the data flowing through the system.",
kb_query="pydantic models database schema",
wants_mermaid=False,
),
SectionSpec(
id="workflows",
title="Workflows",
sub="Deterministic, multi-step orchestrations that produce structured artifacts (board prep, quarterly plan, perf review), including the wait-for-human pause primitive.",
kb_query="workflows board prep quarterly plan performance review wait_for_human resumer",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="scheduler",
title="Scheduler & Cadences",
sub="The async scheduler runner, cadence DSL (weekly@DOW-HH:MM, quarterly@DD-HH:MM), scheduled_actions, and proactive nudge delivery through the user's last-used channel.",
kb_query="scheduler cadence scheduled actions proactive nudge runner",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="integrations",
title="Integrations",
sub="External channels (Slack, Discord, email, Telegram, Google Chat, MCP gateway), cross-platform attachments, and how they connect to the Executive.",
kb_query="integrations slack discord email telegram google chat MCP gateway attachments",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="external_monitoring",
title="External Monitoring",
sub=(
"How OE watches the outside world. A periodic scan polls the "
"watchlist's vendor status pages, RSS / Atom feeds, and stock "
"tickers; qualifying signals flow into the existing alert "
"pipeline so they surface as briefing proposals on the same "
"path as inbound email / Slack. The watchlist is editable "
"from chat, and a `watchlist_research` workflow uses the "
"7-specialist council with web_search to propose what to "
"watch for THIS company."
),
kb_query=(
"external monitoring watchlist signal vendor status rss stock "
"external_monitor_scan promote_signal_to_alert SSRF "
"external_signal_received external_signal_promoted "
"watchlist_research propose_watchlist_entries specialist "
"research onboarding"
),
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="today",
title="Today / Morning Brief",
sub="The /today route and API: per-department goal health, a roster with awaiting-action counts, and proposals routed to a person.",
kb_query="today morning brief department health roster proposals awaiting",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="api",
title="API Reference",
sub="The FastAPI HTTP surface — endpoints grouped by router, with brief descriptions of each.",
kb_query="fastapi http endpoints routers",
wants_mermaid=False,
),
SectionSpec(
id="mcp_server",
title="MCP Server",
sub="Open Executive exposed as an MCP server: company-grounded context as resources and the specialist council as tools, over Streamable-HTTP at /mcp for external agents (Claude Desktop, Cursor, Claude Code).",
kb_query="MCP server streamable http resources tools consult_specialist mount fastmcp x-api-key",
wants_mermaid=True,
diagram_kind="flowchart",
),
SectionSpec(
id="user_guide",
title="User Guide Surface",
sub="The /guide page — plain-language, per-feature overviews served from static prebuilt JSON, sharing the architecture page's loader and renderer but separate from this technical reference.",
kb_query="user guide feature overview prebuilt static sections plain language settings tile",
wants_mermaid=True,
diagram_kind="flowchart",
),
# `clients` — named client-company slots for fractional / multi-client
# use. New top-level module; see `clients:` in architecture-facts.yaml.
SectionSpec(
id="clients",
title="Client Companies (Slots)",
sub="Multi-client mode for fractional executives: named save files of the full company context, one active at a time, with save-back switching and per-client MCP tool configs.",
kb_query="client slots fractional multi-client switch save restore activate company context",
wants_mermaid=True,
diagram_kind="flowchart",
),
# `delegation` — Act as me: the Executive writing as a person, as a
# draft in their own Gmail. New top-level module; see `delegation:` in
# architecture-facts.yaml.
SectionSpec(
id="delegation",
title="Act as Me (Delegation)",
sub="The one place the Executive writes as a person instead of itself: drafts in the principal's own Gmail, in their voice, offered only on their own verified turn, and sent only when they tap Send on a reply card.",
kb_query="act as me delegation ghostwrite draft own gmail voice profile how I write principal verified turn",
wants_mermaid=True,
diagram_kind="flowchart",
),
]
_SECTION_INDEX = {s.id: s for s in SECTIONS}
def get_section(section_id: str) -> SectionSpec:
spec = _SECTION_INDEX.get(section_id)
if spec is None:
raise KeyError(f"Unknown architecture section: {section_id}")
return spec