Architecture orientation

Status: living reference, replacing the dated snapshot formerly inlined as AGENTS.md §2 (“current as of 2026-04-27”). The rules that were mixed into it — deployment-contract discipline, migration safety, script conventions — stay in §2. Everything here is a fact about the current stack and is expected to drift: verify against source before relying on it. Relocated by BI-0020D511 Phase 1.

Which overview wins (BI-79BCE3F2). This page is the entry point — a one-screen index of facts and pointers. platform-overview.md is canonical for depth: runtime topology (the full compose service set and profiles), the two deployment models, the sandbox/build workflow, data architecture, and hardware guidance. Where the two disagree, platform-overview wins; fix the drift here rather than forking the story. Volatile counts (models, migrations, enums, principles, routes) are generated — cite architecture-counts.generated.md, never a hand-typed number.

• Stack. Next.js 16 monorepo (pnpm workspaces): apps/web, packages/db (Prisma 7.x). Docker Compose: one dpf compose project — Postgres (single datastore: relational + pgvector + the graph mirror) plus the portal and the capability-gated service profiles (observability, durable automation, edge, …); the authoritative service list is platform-overview.md → Current Runtime Core and the compose files themselves. Local AI via Docker Model Runner (Docker Desktop 4.40+). All inference uses OpenAI-compatible /v1/chat/completions (apps/web/lib/ai-inference.ts). ⟦runtime: pins drift every upgrade — re-verify against package.json + compose files, never cite from here⟧
• Deployment doctrine. Every deployment target (Windows installer today; macOS / Linux / cloud / TAPPaaS per the architecture work in flight) wraps the same canonical contracts. See docs/superpowers/specs/2026-05-09-deployment-contracts.md for the 10 contracts and the spec ownership map. Substrate-specific deltas live in their owning specs; universal rules live in the doctrine. Before adding anything host-coupled (a scrape target, service, bind mount, host path, default URL/port, or shell builtin), check the cross-platform gotcha tally at docs/install/platform-support-watchlist.md and add a row when you fix a new platform-specific defect.
• Shell scripts run in Linux containers — LF endings only, enforced by .gitattributes. Use pnpm --filter <pkg> exec <tool>, never npx <tool> (npx ignores pinned versions).
• PowerShell scripts target Windows 10/11 + PS 5.1+. Plain ASCII only — no Unicode, BOM, smart quotes, em-dashes, emoji. Bash equivalents for macOS / Linux are landing per docs/superpowers/plans/2026-05-09-macos-linux-native-support.md; both surfaces remain canonical going forward. ⟦runtime: in-flight — “landing” expires when that plan closes; check it before trusting Bash parity⟧
• Migrations live in packages/db/prisma/migrations/. Create with pnpm --filter @dpf/db exec prisma migrate dev --name <name>. Never npx prisma. Migration files are immutable after commit — Prisma stores checksums; modifying a committed migration causes drift.
• Backfill SQL for any data-moving migration goes inline in the same migration file, not a separate script.
• A migration must apply cleanly against ANY existing data state, not just a clean schema. Migrations are forward-only and self-upgrade is fail-closed (migrate runs pre-swap under set -e), so a “tightening” migration that fails on an install’s existing rows does not just error — it wedges that install’s forward-only chain, freezing the busiest installs (most data) on the old version. Before adding a constraint that existing rows could violate — UNIQUE, EXCLUDE, CHECK, FOREIGN KEY, PRIMARY KEY, SET NOT NULL, or ADD COLUMN … NOT NULL without a DEFAULT — do ONE of: (1) remediate the offending rows idempotently in the SAME migration before the constraint (quarantine/backfill in a DO $$ block or UPDATE/DELETE — precedents: 20260521120000_fix_wiki_backslash_slug_duplicates, 20260426150500_backfill_missing_principals, 20260413170000_rename_ollama_to_local; prefer quarantine over destruction per kernel decision D5); (2) split expand → contract across two releases (add the loose form + backfill now, tighten in a later release once the fleet has converged); (3) add the constraint NOT VALID (FK/CHECK) and VALIDATE in a later release; or (4) if genuinely data-safe, attest in-file with -- @migration-safety: data-safe: <why no existing row can violate this>. This is enforced, not advisory: the migration-safety-guard (.githooks/pre-commit Guard 7 + .github/workflows/migration-safety-guard.yml) blocks a tightening migration that has none of the above. See docs/superpowers/specs/2026-07-03-fleet-safe-schema-evolution-design.md (EP under BI-5B3FA415); the shadow-DB dry-run preflight (BI-UPGRADE-008) is the planned real-data backstop.
• Prompts live in prompts/<category>/<slug>.prompt.md with YAML frontmatter, seeded to PromptTemplate on deploy, editable via Admin > Prompts. Hardcoded TS constants are fallback only.
• Skills live in skills/<category>/<name>.skill.md, seeded to SkillDefinition + SkillAssignment. Belong to coworkers, not routes.
• Authorized product surfaces. packages/types/src/authorized-surface.ts is the renderer-neutral wire contract for what a human/coworker principal may perceive and do. Definitions compile in apps/web/lib/coworker/authorized-surface-registry.ts; browser, accessibility, mobile REST, workroom/headless, external MCP, and legacy screen_* consumers are projections/adapters. A feature’s React renderer and surface projector share one read model, and persistent surface actions re-enter governedExecuteTool. The read/act registry and repo guard live at apps/web/lib/mcp/governed-surface-tool-contracts.json and scripts/check-no-governed-surface-without-mcp-tool.mjs.
• Portal archetype. StorefrontConfig.archetypeId is the single source of truth for portal industry. Organization.industry and BusinessContext.industry are derived. Vocabulary resolution: resolveVocabularyKey({ archetypeCategory, industry }) — archetype wins.
• Adding a business archetype. Use the dpf-add-archetype skill (packages/dpf-skill-pack/skills/dpf-add-archetype/SKILL.md) — do not copy a prior archetype design doc. An archetype provisions four dimensions, not one: template substrate, WSID profession corpus, an AI-coworker decision, and skills/tools. The Archetype Completeness Guard CI job enforces this — structural presence blocks all categories; the depth floor (≥1 corpus page + a recorded coworker decision in scripts/archetype-coworker-decisions.txt) hard-blocks NEW archetypes, while pre-existing gaps ratchet down from scripts/archetype-completeness-baseline.txt. A new archetype must meet the full floor, never be parked in the baseline. Spec: docs/superpowers/specs/2026-07-21-archetype-provisioning-playbook-design.md.
• Enterprise operating-model standard. The Four-Portfolio Archetype and AI Workforce Operating Standard is the canonical bridge among the four portfolios, business Products and Offers, industry operational value streams, IT4IT-referenced DigitalProducts, non-digital work, human/AI allocation, TAK/GAID/TAK-JSI, conformance, and gap analysis. Its profile catalog reconciles the leaf-key and category inventory for the 2026-08-01 snapshot and records every current leaf delta; archetype source remains executable truth, and complete per-leaf conformance manifests remain an explicit implementation gap.
• Portal routes. Internal management lives at /storefront. /portal is reserved for external/customer experience. /admin/storefront, /admin/business-context, /admin/operating-hours are legacy redirects.
• Background-operation observation. Durable work is independent of the page that launches or observes it. Browser progress uses a cheap durable-state projection, best-effort event invalidation, reconnect rehydration, and the single shell-owned system event connection; timer-driven route refresh is prohibited. See the background-operation observation contract.

Subsystem map

The subsystems the platform runs that this page previously omitted entirely (pass 2026-08-16 §3.5). One pointer each — the linked page is the canonical home:

• AI coworker runtime — what an agent/coworker is made of (identity, registry, grants, loop): AI agent meta-model; development principles: ai-coworker-development-principles.md.
• MCP plane — the coordination plane and tool authorization (transport, tokens, grants, packs): MCP tool authorization runbook · MCP tool packs.
• Build Studio & delivery surfaces — the embedded pipeline and its three external CLI peers, one process: delivery surfaces runbook.
• Decision governance — TAK, WWMD/WWWD/WSID, autonomy dials, principle_decide: Trusted AI Kernel · Autonomy and WWMD.
• Edge nodes — outbound-only discovery/telemetry satellites with a fleet lifecycle: edge-node design (binding) · fleet operations.
• EA substrate & data architecture — the Prisma→EA mirror, stewardship rules, and the in-Postgres graph/vector layers: data model stewardship runbook · platform-overview.md → Data Architecture.

Channel adapter capabilities

When an operation is contractually defined on a channel adapter interface but operationally unsupported by a specific provider, the adapter must explicitly signal support status using capability flags rather than silent failure. Unimplemented methods must throw a typed error or return a structured unsupported response (e.g., throwing an IntegrationApiError with status code UNSUPPORTED_OPERATION or returning a supported: false status) to allow the caller to degrade gracefully. For example, a marketing channel adapter that contractually implements engagement tracking but lacks underlying API support on a specific provider must advertise this via its capability registration. (BI-IMP-27126FA9)