📄 system-state-view-spec.md 7,242 bytes Apr 26, 2026 📋 Raw

🎨 Icarus Phase 5 — System State View Spec

For: Daedalus 🎨 (Frontend Architect)
From: Socrates 🧠 (Backend)
Sprint: Phase 5 — 'Real World'
Date: 2026-04-26
Priority: P1 — Execute after family_loader.py completion

MISSION

Build a read-only System State dashboard that lets Matt see exactly how Icarus is making decisions. No editor, no forms, no buttons — pure visibility.

API CONTRACT

Endpoint: GET /system/state

Authentication: Session cookie (same auth as /admin/)
Content-Type:* application/json

Response Schema:

{
  "status": "ok",
  "family": {
    "family_id": "hoffmann",
    "version": "1.0.0",
    "last_updated": "2026-04-26",
    "member_count": 4,
    "rule_count": 7
  },
  "members": [
    {
      "id": "sully",
      "name": "Sullivan",
      "nickname": "Sully",
      "current_grade": 1,
      "school": "St. John's Elementary",
      "teacher": "Mrs. Smith",
      "calendar_color": "blue",
      "stats": {
        "documents_routed": 12,
        "avg_confidence": 0.94
      }
    }
  ],
  "rules": [
    {
      "id": "rule_001",
      "description": "Sully's grade level and teacher",
      "pattern": "first grade|1st grade|grade 1|Mrs\\. Smith",
      "assign_to": ["sully"],
      "confidence": 0.95,
      "status": "active",
      "last_triggered": "2026-04-26T14:30:00Z",
      "trigger_count": 15
    }
  ],
  "routing_decisions": [
    {
      "id": 123,
      "timestamp": "2026-04-26T14:30:00Z",
      "document_title": "Field Trip Permission Slip",
      "source": "telegram",
      "inferred_members": ["sully"],
      "confidence": 0.95,
      "rule_triggered": "rule_001",
      "action": "auto_routed",
      "briefing_sent": true
    }
  ],
  "telemetry": {
    "total_documents": 45,
    "auto_routed": 38,
    "user_asked": 5,
    "errors": 2,
    "avg_processing_time_ms": 3200,
    "confidence_distribution": {
      "high": 38,
      "medium": 5,
      "low": 2
    }
  }
}

UI REQUIREMENTS

Layout: Single Page, Read-Only

┌─────────────────────────────────────────┐
│ 🔍 Icarus System State                  │
│ Family: Hoffmann (4 members, 7 rules)   │
├─────────────────────────────────────────┤
│                                         │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐   │
│  │ Docs    │ │ Auto    │ │ Asked   │   │
│  │ 45      │ │ 38 (84%)│ │ 5 (11%) │   │
│  └─────────┘ └─────────┘ └─────────┘   │
│                                         │
├─────────────────────────────────────────┤
│ 👥 Family Members                       │
│ ┌─────────────────────────────────────┐ │
│ │ [Avatar] Sullivan (Sully)          │ │
│ │ Grade 1 | Mrs. Smith | 12 docs     │ │
│ │ ████████████ Confidence: 94%        │ │
│ │ [Avatar] Harper                     │ │
│ │ Pre-K | Ms. Johnson | 8 docs        │ │
│ │ █████████ Confidence: 89%          │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ 📋 Active Rules                         │
│ ┌─────────────────────────────────────┐ │
│ │ Rule 001: Sully's grade/teacher     │ │
│ │ Pattern: first grade|1st grade...   │ │
│ │ → Sully (95%) | Triggered: 15×      │ │
│ │                                     │ │
│ │ Rule 002: Harper's grade/teacher    │ │
│ │ Pattern: pre-K|preschool...         │ │
│ │ → Harper (90%) | Triggered: 8×      │ │
│ └─────────────────────────────────────┘ │
├─────────────────────────────────────────┤
│ 📊 Confidence Distribution              │
│                                         │
│ High (>90%):   ████████████████████ 38 │
│ Medium (70-90%): █████ 5               │
│ Low (<70%):    ██ 2 (user asked)      │
│                                         │
├─────────────────────────────────────────┤
│ 📜 Recent Routing Decisions (last 10) │
│ ┌─────────────────────────────────────┐ │
│ │ ✅ Field Trip → Sully (95%) 14:30   │ │
│ │ ✅ Dentist → Sully (98%) 09:15      │ │
│ │ ❓ Community Event → Asked user 08:45│ │
│ │ ✅ Pre-K Grad → Harper (92%) Mon    │ │
│ └─────────────────────────────────────┘ │
│                                         │
└─────────────────────────────────────────┘

Design Tokens (from your design system)

  • Colors: Use existing family member colors (blue, pink, purple, green)
  • Typography: Monospace for patterns/regex, sans-serif for labels
  • Charts: Simple bar charts (no external charting libs needed — CSS flex bars)

CONSTRAINTS

✅ Allowed ❌ Forbidden
Read-only display Any form inputs
CSS flex bar charts Chart.js, D3, etc.
HTMX for polling React, Vue, Svelte
Static HTML + CSS JavaScript frameworks
HTMX hx-get for refresh POST/PUT/PATCH endpoints

FILES

File Purpose
api.py — GET /system/state Socrates provides
templates/system_state.html Daedalus builds
static/css/system-state.css Daedalus builds

SUCCESS CRITERIA

  1. ✅ Page loads at /system/state
  2. ✅ Shows all 4 family members with stats
  3. ✅ Shows all 7 rules with patterns and trigger counts
  4. ✅ Shows confidence distribution as bar chart
  5. ✅ Shows last 10 routing decisions with status icons
  6. ✅ Refreshes via HTMX polling (every 30s)
  7. ✅ Zero forms, zero buttons, zero editable fields

Reference Implementation:
Backend: icarus/core/family_loader.py (load config, get stats)
Example response: See API contract above

Questions? @mention Socrates or Wadsworth in The Hoffmann Board.

Contract-First: API spec approved by Matt. Build UI against this spec.

← Back