# 🎨 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:**

```json
{
  "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.*