# HMB Architecture — Matt Approval

**Date:** 2026-04-29
**Status:** ✅ APPROVED by Matt

---

## Decision Log

### ✅ Event Graph = Static-ish upcoming week view
- Read-only display of next 7-14 days
- Populated by: email pipeline, chat coordination, manual entry
- Auto-refreshes every few minutes via HTMX

### ✅ Dashboard interactions
- Click "Confirm" → state changes, syncs to calendar
- Click "Decline" → moves to hidden/archive
- Click "Reschedule" → opens date/time picker
- No chat required for simple state changes

### ✅ Logistic coordination = Telegram "Hoffmann Home Hub"
- Natural conversation (no commands, no forms)
- HBM detects coordination requests
- Bot speaks up ONLY on conflicts
- Silent updates for everything else

### ✅ Escalation ladder closer to event
- 7 days: Silent Event Graph update
- 48h: Mention in daily brief
- 24h: Specific reminder
- 4h: Urgent + actionable details
- 1h: Final confirmation

---

## Architecture Summary

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│     Email       │     │   Telegram      │     │    Dashboard    │
│   (IMAP)        │     │  (HHH Group)    │     │   (iPad/Web)    │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Document Pipe  │     │   HBM Bot       │     │  User Actions   │
│  (extract)      │     │  (tripwire →    │     │  (buttons)      │
│                 │     │   heavy lifter) │     │                 │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌─────────────────────────┐
                    │      EVENT GRAPH        │
                    │  (static-ish view)      │
                    └───────────┬─────────────┘
                                │
                    ┌───────────┴───────────┐
                    ▼                       ▼
           ┌─────────────┐         ┌─────────────┐
           │   Calendar  │         │   HBM Bot   │
           │  (Radicale) │         │  (speak up  │
           │             │         │   on confl) │
           └─────────────┘         └─────────────┘
```

---

## Next Actions

| Priority | Task | Owner | When |
|----------|------|-------|------|
| P0 | Dashboard "Confirm/Decline" buttons | Socrates | This week |
| P1 | Event state machine API | Socrates | This week |
| P2 | HBM Bot tripwire module | Socrates | Next sprint |
| P3 | Escalation ladder logic | Socrates | Next sprint |
| P4 | Aundrea Telegram interaction | Socrates + Daedalus | Phase 8 |

---

## State Machine (Approved)

```
[needs_confirmation] ──✅──► [confirmed] ──► Calendar
       │
       ├──❌──► [declined] (hidden)
       │
       └──💬──► [pending] (counter-proposed)

[pending] ──✅──► [confirmed]
    │
    ├──❌──► [cancelled]
    │
    └──📝──► [pending] (modified)
```

| State | Visible | Actions |
|-------|---------|---------|
| confirmed | ✅ Yes | Reschedule, Cancel |
| pending | ✅ Yes | Confirm, Decline, Modify |
| needs_confirmation | ✅ Yes | ✅ Yes, ❌ No, 💬 Counter |
| declined/cancelled | ❌ Hidden | View in archive only |

---

*Architecture approved by Matt 2026-04-29*
*File: shared/project-docs/hmb-architecture-approved.md*