Portal Control Plane Requirements

Portal Control Plane Requirements

One-Line Rule

Portal is the primary human workflow surface over FractalOps truth planes. It is not a universal stack governance dashboard.

What Portal Must Do

• show the current workflow path:
  • onboarding
  • work
  • proposal
  • proof
  • recovery
• read canonical truth planes and read models
• queue or trigger work through approved backend contracts
• expose operator visibility for Ouroboros and runtime health
• keep launch, auth, and recovery continuity visible before the user hits a dead end

Strongly-Owned vs Endpoint Surfaces

Portal must distinguish these two cases.

Strongly-owned execution substrate:

• portal
• api
• worker
• execution-runtime
• Temporal
• DB / Hasura / Supabase Realtime
• Daytona
• PlaywrightGrid

Ordinary integration endpoints:

• Nexus
• Penpot
• Dokploy
• Headlamp
• most connector targets

Portal may show launch or health affordances for endpoint systems, but it should treat them as URL/auth/health contracts rather than product-owned sub-planes.

Required Surface Families

1. Work and Launch

• pre-auth preview must show:
  • project spine
  • session continuity
  • validation
  • next actions
• login continuation must preserve route intent
• launch guidance must make browser-first expectations explicit

2. Proposal and Recovery

• proposal remains the only non-read mutation gate
• blocked routes must downshift into recovery rather than hiding the failure
• auth-only blockers must not be mislabeled as product logic failure

3. Proof and Lineage

• proof path remains:
  • Semantics / FractalOps graph
  • ClickHouse warehouse
  • Chronicle evidence
• DataHub should expose project RDF steward reports for catalog search, lineage discovery, and impact navigation, while ClickHouse exposes the same lifecycle as queryable warehouse events/facts; DataHub is not proof authority by itself
• portal should show proof closure and lineage joins, not invent alternative proof sources

4. Operator and Ouroboros

• operator live truth must come from:
  • portal_live_events
  • harness-projection
• operators and minimap must read the same projection snapshot
• heavy historical summary endpoints are debug surfaces, not live truth
• selected session detail should stay compact:
  • continuity summary
  • source lineage
  • launch contract status
  • first tool family
  • practical next step

Execution Rules

• API may validate, queue, and record
• Temporal performs heavy execution
• Portal must not perform proposal-bound side effects synchronously
• secrets and tokens must come from SSOT-backed secret contracts
• public URL, executor URL, and local/internal URL must stay separate

Anti-Requirements

Portal should not:

• become a per-stack lifecycle console by default
• merge multiple live truths in the client
• depend on direct stack-local control nouns as product vocabulary
• treat every adjacent tool as if FractalOps owned its lifecycle

Acceptance Signals

• a user can understand what FractalOps owns directly versus what it only integrates
• live operator and minimap both follow harness-projection
• launch/auth continuity is visible before work begins
• proposal and proof stay on canonical rails