HoffDesk Architecture — Sprint Planning Brief

Date: 2026-04-24
Owner: Matt (Director)
Architects: Daedalus 🎨 (Frontend/UX), Socrates 🧠 (Backend/Infra)
Model: OpenClaw agents on Beelink (titanium-butler), Gaming PC (Tailscale) for local LLM

1. Service Topology

A single Beelink machine running everything behind Cloudflare Tunnel.

Internet
   │
   ▼
Cloudflare (hoffdesk.com)
   │
   ▼
Cloudflare Tunnel (cloudflared)
   │
   ├── :5232  → Radicale (CalDAV server)
   │
   └── :8000  → hoffdesk-api (FastAPI — single app serving everything)
                   │
                   ├── Public blog pages (HTML)
                   ├── Blog admin panel (HTML + HTMX)
                   ├── Content generation API (JSON)
                   ├── Family dashboard API (JSON)
                   ├── Family admin (HTML)
                   ├── Auth endpoints (login/logout/session)
                   ├── Webhook receivers
                   └── Telegram bot callback

Key constraint: One FastAPI process on port 8000 handles all routes. Subdomain separation is cosmetic — the app routes internally.

2. Subdomain Map

🔧 Housekeeping Items

• blog.hoffdesk.com — either add DNS CNAME pointing to the tunnel or remove from ~/.cloudflared/config.yml. Currently a dead config entry.
• proto.hoffdesk.com — retire once family.hoffdesk.com is wired. The dev server needs manual startup and returns mock data; the real API has session auth and actual data now.
• api.hoffdesk.com — currently serves blog HTML at / alongside JSON. If we want a clean JSON-only gateway, route by subdomain header. If not, update the plan to match reality.

3. Route Hierarchy

hoffdesk-api
├── [PUBLIC]  /
│   └── Blog index, article pages, categories, tags
│
├── [PUBLIC]  /api/blog/
│   └── JSON API: posts, categories, tags, RSS, sitemap
│
├── [AUTH]    /admin/blog/
│   ├── Dashboard, post list, editor, images
│   └── Content pipeline (Magic Wand + Struggle v2)
│
├── [AUTH]    /api/v1/content/
│   └── Content pipeline v2 API (briefs CRUD, submit, approve, reject, output, score)
│
├── [AUTH]    /admin/family/
│   └── Family pipeline status, email webhook config
│
├── [AUTH]    /family/events/removed
│   └── Recently removed events (machine-to-machine via Bearer token)
│
├── [AUTH]    /auth/login, /auth/logout, /auth/me
│   └── Session auth (POST login sets cookie, GET me validates)
│
├── [INTERNAL] /health
│   └── Health check
│
├── [INTERNAL] /telegram/callback
│   └── Telegram bot webhook
│
└── [INTERNAL] /webhook
    └── Generic webhook receiver

4. Auth Model (Finalized 2026-04-24)

Session cookies for humans, Bearer tokens for machines. No exceptions.

Credentials

Auth Flow (Aundrea)

family.hoffdesk.com
  ↓ (no session cookie)
/auth/login?redirect=/family/dashboard/
  ↓ (enters credentials)
Session cookie set (HttpOnly, SameSite=Lax, 30 days)
  ↓
Redirect to /family/dashboard/
  ↓
HTMX polls /api/today (cookie automatic)

5. What Each Person Owns

Wadsworth 📋 — Chief of Staff & Coordination

Socrates 🧠 — Backend & Infrastructure

Daedalus 🎨 — Frontend & UX

6. Sprint Priorities

Now (unblocked)

1. Wire family.hoffdesk.com — add tunnel entry + DNS CNAME. Dashboard goes live.
2. Wire pipeline Phase 2 templates to backend routes. Content generation pipeline goes live.
3. Clean up blog.hoffdesk.com + proto.hoffdesk.com.

This Sprint

4. Build /api/today — aggregate endpoint returning real calendar + weather + system health. Dashboard becomes real.
5. Convert dashboard to Jinja2 — shared base layout, auth-aware nav, user greeting.
6. Build family dashboard login page — guest-friendly version of the admin login (Aundrea's first impression).

Next Sprint

7. Dashboard Week View — Family Assistant v1.5 UI mocks (conflict panel, undo toast, digest card).
8. Public landing page at hoffdesk.com.
9. API gateway pattern — if we want api.hoffdesk.com JSON-only.

7. Architecture Decisions Log

8. Pain Points

1. Monolith pressure. One FastAPI app handles blog, admin, content pipeline, family dashboard, webhooks, and bot callbacks. It works now but won't scale to multi-service gracefully. Not urgent, but worth noting.

2. Dashboard / blog / family admin all live in different template directories. My workspace templates, shared template symlinks, production template paths — it's easy to update the wrong copy. Need a single source of truth.

3. Three auth patterns existed for a week. We killed the tokens-in-URLs pattern, but the session middleware is brand new. Need a sprint of just watching auth logs to catch edge cases.

4. Dashboard is HTML+JS, not Jinja2. This means it doesn't inherit shared layouts or benefit from server-side rendering. Converting it matters most when Aundrea starts using it daily.