FIN Central

Platform Observability & Onboarding Projection Architecture

11 min read

Platform Observability & Onboarding Projection Architecture

Fifth and final companion in the projection-architecture family (QC + Sales & Market + Recall/Proof + Agent Audit + this). Source catalog: docs/projections/PROJECTION_CATALOG_2026-05-15.md §6.7 + §6.8.

This family is FIN Central control-plane, not tenant operational. The audience is the FIN operator (you + any future hires), with one cross-over: tenant onboarding pages are tenant-visible during the onboarding window.

0. TL;DR

Every platform health signal + onboarding step + agent-enrichment outcome ripples into 6 vault MDs + 3 JSONB projections + ~4 backlink edges per event. Substrate is mostly built (kb_health_summary + system_health_snapshot already live as JSONB; channel_health is a small new projection per the catalog). The gap is the vault MD projector family that turns observability JSONB into the readable + grepable + drill-throughable artifacts the operator role + onboarding cohorts consume.

inbound signals                       → ripple
─────────────────────────────────────────────────────────────────
ALL events (sampled / aggregated)     → kb_health_summary (LIVE)
                                       → system_health_snapshot (LIVE)
                                       → channel_health (NEW)
tenant lifecycle events               → tenant_readiness_projection (NEW)
                                       → onboarding_progress_projection (NEW)
agent.* + doc.edit_*                  → agent_enrichment_metrics (Agent Audit
                                         family §2.2 — feed into vault MD here)
federal-readiness feature flags       → federal_readiness_tracker (NEW vault MD)
                                       → reads existing tenant projection state

  6 vault MDs (rung 3 with Central reads where applicable):
  - kb_health_summary
  - channel_health.<tenant>
  - tenant_readiness.<tenant>
  - agent_enrichment_metrics
  - federal_readiness_tracker
  - onboarding_progress.<tenant>.<actor>  +  cohort_status.<tenant>

Strategic value: this family is what closes “the platform runs itself” claim. Without it, FIN Central operators are blind to per-tenant health + onboarding throughput + federal readiness gaps + agent ROI.

0.5 Central-overlay reads contract (3-rung taproot — see AOL §13.6)

This family is mixed: some projectors are FIN-Central-native (live on fin-central-renderer Worker, write to fin-central-intranet:docs/operations/), others are rung-3 tenant projectors that read both tenant operational data AND Central-side rules (especially _taproot_mirror/docs/certifications/<slug>.md for federal-readiness compliance rules).

ProjectorLives whereCentral MDs read
kb_health_summarytenant-side (per tenant)none — pure tenant introspection
channel_health.<tenant>tenant-side (per tenant)none — pure tenant infrastructure state
tenant_readiness.<tenant>tenant-side (per tenant)_taproot_mirror/docs/operations/onboarding-checklist.md (Central canonical 10-step checklist) — drives “what step the tenant is on”
agent_enrichment_metricstenant-side (per tenant)none
federal_readiness_trackertenant-side, but reads heavy Central_taproot_mirror/docs/certifications/*.md (each cert defines required-artifact set); _taproot_mirror/docs/operations/federal-readiness-checklist.md
onboarding_progress.<tenant>.<actor>tenant-side (per actor)_taproot_mirror/docs/operations/onboarding-checklist.md + _taproot_mirror/docs/roles/<role>.md (per-role step list)
cohort_status.<tenant>tenant-side (per tenant)(aggregates onboarding_progress; reads same Central as that)

Read graceful-degradation: if _taproot_mirror/docs/operations/onboarding-checklist.md is missing, fall back to a hard-coded built-in checklist (versioned in the projector code) + flag central_pending: true. Onboarding cannot wait on Central sync.

Write contract: all projectors write to tenant paths (docs/operations/<projector-name>/...). Never to _taproot_mirror/.

Cross-cutting: kb_health_summary is unique in that it ALSO mirrors a Central rollup once per day — Central-side aggregate of all tenants’ summaries (anonymized) becomes fin-central-intranet:docs/operations/platform-kb-health-summary-rollup.md. That’s a rung-1 write driven by the cross-tenant aggregator, not by this family’s tenant-side projector.

1. Vault MD projectors

All 6 follow the QC arch §1 pattern: pure renderer + tenant-projector orchestrator + injectable deps. Output paths under nathel-intranet:docs/operations/.

1.1 kb_health_summary

  • doc_kind: system_projected
  • audience: FIN operator + employee (admin)
  • cadence: daily 06:00 UTC
  • path: nathel-intranet:docs/operations/kb-health/<YYYY-MM-DD>.md
  • sources:
    • Existing kb_health_summary_projection JSONB (migration 043)
    • Domain counts: COUNT(*) by knowledge.domain grouped per tenant
    • Embedding coverage: % of rows with non-null embeddings
    • Stale entries: rows with domain_stale: true flag
    • Ingestion drift flags: rows where expected_count differs from actual_count over the last week
  • output shape:
    • Section 1: domain counts table (commodity / variety / vendor / customer / location / role / doc / etc.)
    • Section 2: embedding coverage % per domain
    • Section 3: stale entries list (with link to source events for staleness cause)
    • Section 4: ingestion drift (recent vault commits with delta vs. expected)
    • Section 5: 24-hour delta vs. prior snapshot

1.2 channel_health.<tenant>

  • doc_kind: system_projected
  • audience: FIN operator
  • cadence: every 15 minutes
  • path: nathel-intranet:docs/operations/channel-health/<YYYY-MM-DD>/T<HH-mm>.md (or rolling latest at latest.md)
  • sources (NEW JSONB substrate per §2.1):
    • Email queue status (inbound + outbound queue depth, last-flushed-at)
    • Telnyx SMS health (delivery rate, fail rate, last-success-at)
    • Telnyx voice health (call success rate, recording capture rate)
    • GitHub vault webhook freshness (last 202 received, recent failures)
    • MCP key validity (per-actor key expiry windows)
    • Render status (last entity_doc.rendered event timestamp; queue depth)
  • output shape:
    • Traffic-light table per channel (green / yellow / red)
    • Recent failures with links to error events
    • SLA budget burn-down per channel

1.3 tenant_readiness.<tenant>

  • doc_kind: system_projected
  • audience: FIN operator + tenant admin (during onboarding window)
  • cadence: on tenant lifecycle events + daily reconciliation
  • path: nathel-intranet:docs/operations/tenant-readiness/<YYYY-MM-DD>.md
  • sources:
    • Tenant provisioning checklist from AOL spec §13
    • Smoke-test events (tenant.smoke_test_passed, tenant.smoke_test_failed)
    • Existing system_health_snapshot_projection JSONB
    • Central onboarding-checklist MD (per §0.5)
  • output shape:
    • Readiness rollup (% complete)
    • Blockers (with links to events showing why blocked)
    • Current onboarding step (per project_agentic_onboarding_program 3-act cohort design)
    • Next required actions
    • Estimated time-to-ready

1.4 agent_enrichment_metrics

  • doc_kind: system_projected
  • audience: FIN operator
  • cadence: weekly Monday 09:00 UTC
  • path: nathel-intranet:docs/operations/agent-enrichment/<YYYY-WW>.md
  • sources:
    • agent_enrichment_metrics_projection JSONB (from Agent Audit family §2.2 — NEW dependency)
    • agent_session_projection (Agent Audit §2.1) for session-level rollups
    • agent_eval_drift_projection (Agent Audit §2.3) for confidence trends
  • output shape:
    • Proposals per agent per week (table)
    • Acceptance rate per agent (line chart inline SVG)
    • Doc enrichment rate (sections proposed vs accepted)
    • Reasoning quality lift (A/B comparison if available)
    • Cost per accepted proposal
    • Drift alerts (which scenarios saw confidence regression)
  • note: This is a DEPENDENT projector — requires Agent Audit family to ship first.

1.5 federal_readiness_tracker

  • doc_kind: system_projected
  • audience: FIN operator only
  • cadence: weekly Monday 09:00 UTC + on federal-relevant event
  • path: nathel-intranet:docs/operations/federal-readiness/<YYYY-WW>.md
  • sources:
    • Federal-runtime feature flags (FedRAMP infrastructure status, federal MCP endpoint readiness)
    • Recall-drill events (R1-B drill_metrics_projection from Recall & Proof family)
    • Audit-export status (event-store export readiness, evidence-bundle retention compliance)
    • SBOM/provenance status (per project_strategic_research memo)
    • Residency notes (CONUS routing verified)
    • VOSB compliance artifacts (per FIN_DATA_SIGNAL_OFFERINGS §4.5)
    • Central reads per §0.5: _taproot_mirror/docs/certifications/*.md for required-artifact set
  • output shape:
    • Federal readiness rollup (% complete per agency target: FDA, USDA, CDC, CBP, FTC, USTR, CISA, ARPA-H, DOD)
    • Missing artifacts list (with links to what’s missing)
    • Last drill date + result (from drill_metrics_projection)
    • Next steps to readiness
    • Contract-vehicle progress (GSA MAS, SBIR/STTR, OTAs, prime sub)
  • note: Heavy Central-MD reads — gates federal MCP endpoint readiness on Central availability.

1.6 onboarding_progress.<tenant>.<actor> + cohort_status.<tenant>

  • doc_kind: portal_page (for onboarding_progress, actor-facing) + system_projected (for cohort_status, operator-facing)
  • audience:
    • onboarding_progress: employee (the actor) + employee (tenant admin) + FIN operator
    • cohort_status: FIN operator + tenant admin
  • cadence: event-driven on onboarding-step completion + daily reconciliation
  • paths:
    • nathel-intranet:docs/operations/onboarding/<actor_slug>/<YYYY-MM-DD>.md
    • nathel-intranet:docs/operations/cohort-status/<YYYY-MM-DD>.md (one per tenant)
  • sources:
    • 10-step onboarding events (per project_pk_v2_implementation memo)
    • 3-act cohort design events (per project_agentic_onboarding_program memo)
    • Central onboarding-checklist MD (per §0.5)
    • Per-role step list from _taproot_mirror/docs/roles/<role>.md
  • output shape:
    • onboarding_progress: progress doc (% complete), next-step prompt, blockers, suggested helper resources, links to documentation
    • cohort_status: multi-actor rollup table, week-over-week throughput, common blockers across cohort, suggested cohort-wide actions

2. JSONB projections

Most JSONB substrate already exists. This family adds 3 NEW projections.

2.1 channel_health_projection (NEW)

  • migration: 078_channel_health_projection.sql
  • schema: tenant_id × channel_id × window → { status, success_count, failure_count, last_success_at, last_failure_at, sla_budget_burn_pct }
  • source events: email.received / email.send_failed, sms.received / sms.send_failed, voice.call_completed / voice.call_failed, webhook.received / webhook.failed, mcp.key_expired_soon, entity_doc.rendered / entity_doc.render_failed
  • replay command: pnpm cli replay-projection --projection=channel_health_projection --tenant=<tenant_id>
  • RLS: required
  • fed-by: event-handlers/projection-channel-health.ts (NEW)
  • consumed-by: channel_health.<tenant> vault MD (§1.2)

2.2 tenant_readiness_projection (NEW)

  • migration: 079_tenant_readiness_projection.sql
  • schema: tenant_id → { onboarding_steps_complete[], smoke_tests_passed[], current_step, blockers[], readiness_pct, last_reconciled_at }
  • source events: tenant.created, tenant.smoke_test_passed, tenant.smoke_test_failed, tenant.onboarding_step_completed, tenant.onboarding_step_blocked
  • replay command: pnpm cli replay-projection --projection=tenant_readiness_projection --tenant=<tenant_id>
  • fed-by: event-handlers/projection-tenant-readiness.ts (NEW)
  • consumed-by: tenant_readiness.<tenant> vault MD (§1.3)

2.3 onboarding_progress_projection (NEW)

  • migration: 080_onboarding_progress_projection.sql
  • schema: tenant_id × actor_id → { steps_complete[], current_step, blockers[], time_per_step_ms[], cohort_id, role }
  • source events: onboarding.step_started, onboarding.step_completed, onboarding.step_blocked, onboarding.actor_assigned_cohort
  • replay command: pnpm cli replay-projection --projection=onboarding_progress_projection --tenant=<tenant_id>
  • fed-by: event-handlers/projection-onboarding-progress.ts (NEW)
  • consumed-by: onboarding_progress.<tenant>.<actor> vault MD + cohort_status.<tenant> vault MD (§1.6)

2.4 Existing substrate (no new migrations)

  • kb_health_summary_projection (043) — feeds §1.1
  • system_health_snapshot_projection (044) — feeds §1.3 + §1.5
  • data_quality_dashboard (existing) — feeds §1.5 federal readiness
  • agent_enrichment_metrics_projection (Agent Audit family §2.2) — feeds §1.4
  • agent_session_projection (Agent Audit §2.1) — feeds §1.4
  • agent_eval_drift_projection (Agent Audit §2.3) — feeds §1.4
  • drill_metrics_projection (Recall & Proof §2.2) — feeds §1.5

3. Native comms integration

SurfaceWhere Platform Observability projections land
FIN operator railkb_health_summary + channel_health daily pinned; tenant_readiness rollup when any tenant in onboarding
Tenant admin railtenant_readiness.<tenant> during onboarding window only
Cohort dashboardcohort_status.<tenant> for current cohort manager
Slackchannel_health red-status events post to #platform-ops; federal_readiness_tracker weekly summary to #leadership Monday 09:30
EmailWeekly agent_enrichment_metrics digest to FIN operator + Anthropic partnership lead
PagerDuty / on-callchannel_health red-status events that persist >5 min trigger PagerDuty page

4. Frontmatter contract (same as 4 prior arch docs)

---
schema_version: 1
doc_id: <projector-output-doc-id>
doc_kind: system_projected | portal_page
title: <human-readable>
slug: <kebab-case>
source_attribution:
  - producer:<projector-name>
  - source_events:<comma-separated event_ids>
  - source_projections:<comma-separated projection rows>
lifecycle_status: active
created_at: <iso>
updated_at: <iso>
maintained_by: <projector-name>
visibility: company | restricted
data_plane: relationship_data
linked_entities:
  - { type: tenant, id: <tenant_id> }
  - { type: actor, id: <actor_id> }
  - { type: channel, id: <channel_id> }
  ... etc per projector
tags: [platform_observability, onboarding, ...]
---

5. Build sequence

Sequence O1 — 3 NEW JSONB projections (~2 days)

  • O1-A channel_health_projection (migration 078 + handler + dispatcher + test)
  • O1-B tenant_readiness_projection (migration 079 + handler + dispatcher + test)
  • O1-C onboarding_progress_projection (migration 080 + handler + dispatcher + test)

Sequence O2 — 6 vault MD renderers (~3-4 days)

  • O2-A kb_health_summary (reads existing JSONB; just needs the renderer)
  • O2-B channel_health.<tenant> (15-min cron)
  • O2-C tenant_readiness.<tenant> (event-driven + daily reconciliation)
  • O2-D agent_enrichment_metrics (weekly cron — gated on Agent Audit family shipping)
  • O2-E federal_readiness_tracker (weekly cron + event-driven)
  • O2-F onboarding_progress.<actor> + cohort_status.<tenant> (event-driven + daily)

Sequence O3 — Agent surface + tooling (~1-2 days)

  • O3-A get_kb_health MCP tool (extend existing per P1-03)
  • O3-B get_channel_health MCP tool
  • O3-C get_tenant_readiness MCP tool
  • O3-D get_agent_enrichment_metrics MCP tool (depends on Agent Audit AA3-C)
  • O3-E get_federal_readiness_tracker MCP tool
  • O3-F get_onboarding_progress + get_cohort_status MCP tools
  • O3-G Operator-rail integration (daily kb_health pinned; channel_health latest at top)

Total: ~6-8 days.

6. Coordination with other arch docs

Other arch docPlatform Observability dependency
QC archNone direct; QC family contributes to channel_health via QC-photo-pipeline failures (if QC photo parse fails, surfaces as channel_health degradation)
Sales & Market archNone direct
Recall & Proof archfederal_readiness_tracker (§1.5) consumes drill_metrics_projection (R1-B) for “last drill date + result”
Agent Audit archagent_enrichment_metrics vault MD (§1.4) consumes agent_enrichment_metrics_projection + agent_session_projection + agent_eval_drift_projection — DEPENDENT

7. Open questions

IDQuestionDefault
PO-Q1channel_health cadence — 15min vs 5min?15min default; PagerDuty page on red-status >5min persists handles urgency
PO-Q2tenant_readiness during the onboarding window — visible to all employees or admin only?Admin only initially; expand to all employees once cohort tooling matures
PO-Q3federal_readiness_tracker — should it ship before first federal conversation, or wait until conversation opens?Ship before; ammunition for the conversation. Per FIN_DATA_SIGNAL_OFFERINGS §4.6 “Wave 4: With Nathel proof in hand, open federal conversations” — we want the readiness tracker IN HAND when those open
PO-Q4agent_enrichment_metrics dependency on Agent Audit — block this whole family on AA, or ship 5 of 6 vault MDs and add §1.4 later?Ship 5 of 6 first; §1.4 lands when Agent Audit family ships. Don’t gate on cross-family dependency
PO-Q5onboarding_progress — actor-facing variant fully featured, or simplified for cohort experience?Fully featured; cohorts are small enough that simplification isn’t worth the divergence cost
PO-Q6Cross-tenant aggregation for platform-kb-health-summary-rollup.md (Central-side) — ship now (1 tenant) or wait for multi-tenant?Wait; aggregating-one-tenant is wasteful — frame as “ready to activate when 2nd tenant onboards”

8. Productization mapping

OfferingPlatform Observability projector that enables it
Internal FIN platform health monitoringAll 6 vault MDs
Tenant SLA reporting (Tier 2 contractual obligation)channel_health.<tenant> + tenant_readiness.<tenant>
Federal contract readiness ammunition (per G-1/G-2/G-3 pipeline)federal_readiness_tracker is the artifact federal conversations consume
Agent platform sales support (B-5 custom reports demonstrating agent ROI)agent_enrichment_metrics
Cohort training program (post-Nathel anchor program)cohort_status.<tenant>

This arch ships substrate that doesn’t directly map to revenue offerings but enables every other family’s commercial use (channel health → SLA; tenant readiness → onboarding throughput; federal readiness → contract close speed; agent metrics → demonstrate ROI for retention + upsell).

9. Strategic priority

This is intentionally the 5th and last arch doc to ship today, not the 1st. Rationale:

  1. Tenant-domain projectors (QC + Sales & Market + Recall & Proof) ship customer value directly
  2. Agent Audit unblocks every other family’s regulatory + audit + replay
  3. Platform Observability is operator-internal — the audience is FIN team itself
  4. Without the four prior families shipping projections, there’s not much for Platform Observability to observe

That said: kb_health_summary (§1.1) can ship Wave 1 immediately — the JSONB is already there since migration 043; only the vault MD renderer is missing. This is a 1-day quick win that gives FIN operator visibility from day one.

10. Sign-off

This arch is the canonical reference for any future platform-observability, onboarding, federal-readiness, or agent-ROI-tracking projection work. Future projectors in this family MUST cite this doc in their PR description. Cross-mirrored to fin-central-intranet:docs/architecture/PLATFORM_OBSERVABILITY_AND_ONBOARDING_PROJECTION_ARCHITECTURE_2026-05-18.md.

— claude_orchestrator (Opus 4.7 1M-context, session 7612a827-b892-47e3-86cd-08835737208e)

Graph View