# HoffDesk Web — Project Plan

**Date:** 2026-04-19
**Status:** Approved by Director Matt on 2026-04-19
**Owner:** Matt (Director), Wadsworth (Coordinator)

---

## Objective

Build and deploy a web presence at **hoffdesk.com** — starting with a family dashboard that surfaces calendar, weather, and household status in a fast, zero-cloud-dependency, mobile-first experience.

## Architecture Decisions (Pre-established)

| Decision | Choice | Rationale |
|---|---|---|
| Hosting | **Cloudflare Pages** | Git-push deploys, free tier, already on CF DNS |
| Frontend | **HTMX + Tailwind CSS** | Sovereign stack per Daedalus charter; no SPA frameworks |
| Backend API | **FastAPI** on Beelink | Existing infra, zero-trust, localhost/Tailscale |
| Auth | **Cloudflare Access** (public pages) + **Tailscale** (admin) | Zero-trust, no OAuth complexity |
| Dark mode | **"Functional Luxury" aesthetic** — default, not a toggle | Daedalus doctrine |
| Mobile-first | Primary device = phone | High-WAF design principle |

## Subdomain Architecture

| Subdomain | Purpose | Deployment |
|---|---|---|
| `hoffdesk.com` | Public landing / family dashboard | Cloudflare Pages |
| `cal.hoffdesk.com` | CalDAV (existing) | Beelink, Tailscale-only |
| `hook.hoffdesk.com` | Webhook receiver (existing) | Beelink, Tailscale-only |
| `api.hoffdesk.com` | REST API for dashboard data | Beelink → Cloudflare Tunnel or Tailscale Funnel |

---

**Socrates Day 1 Priority:** Stand up Cloudflare Tunnel + CF Access (Email OTP). Proof of life required before API spec.

## Sprint 1 — Family Dashboard MVP

**Goal:** A live dashboard at `hoffdesk.com` showing today's calendar, current weather, and household status. One glance. Phone-sized. Done fast.

### Socrates Deliverables (Backend)

| # | Deliverable | Description | Depends On | Status |
|---|---|---|---|---|
| S1 | API spec: `GET /api/today` | **AGGREGATE endpoint** — single payload: calendar + weather + health | — | **P2 — WAIT for tunnel** |
| S2 | API spec: `GET /api/calendar/upcoming` | Structured calendar events with time, title, location | S1 approved | — |
| S3 | API spec: `GET /api/weather` | Current conditions + 24h forecast for Green Bay, WI | S1 approved | — |
| S4 | API spec: `GET /api/health` | Gateway status, Ollama status, disk usage | S1 approved | — |
| S5 | FastAPI endpoints wired to real data | Implement all Sprint 1 endpoints with live data | S1–S4 specs approved | — |
| S6 | API deployed on Beelink | Bound to localhost, exposed via **Cloudflare Tunnel + CF Access (Email OTP)** | S5 complete | — |

**Socrates note:** All API specs go in `shared/api-specs/sprint-1/` as OpenAPI YAML. Daedalus builds against these contracts.

### Daedalus Deliverables (Frontend)

| # | Deliverable | Description | Depends On |
|---|---|---|---|
| D1 | Design system foundation | Color palette, typography scale, spacing tokens, dark mode palette in `shared/design-tokens/` | — |
| D2 | Component library | Calendar card, weather card, health status card — Tailwind + HTMX | D1 |
| D3 | Dashboard layout | Mobile-first single-page, sections: calendar (top), weather (middle), health (bottom) | D2 |
| D4 | Static mock with API contracts | Deploy to Cloudflare Pages, HTMX pulls from API endpoints | **S1 spec approved** |
| D5 | Connected dashboard | Real data flowing, auto-refresh via HTMX polling (30s) | **D4 + S5 + S6** |

**Daedalus note:** Start D1 (design tokens) immediately — unblocked. Wait for S1 spec approval before D4 integration.

### Wadsworth Deliverables (Coordination)

| # | Deliverable | Description |
|---|---|---|
| W1 | Cloudflare Pages project setup | Create project, connect to Git repo, configure builds |
| W2 | Cloudflare Tunnel for API | Route `api.hoffdesk.com` → Beelink localhost FastAPI |
| W3 | CI/CD pipeline | Git push → Cloudflare Pages auto-deploy |
| W4 | Sprint tracking & blocker resolution | Keep the board informed, escalate blockers |

---

## Definition of Done — Sprint 1

- [ ] `hoffdesk.com` loads in <2s on mobile
- [ ] Calendar shows next 24h of events, auto-refreshes
- [ ] Weather shows current + forecast for Green Bay
- [ ] Health section shows gateway + Ollama + disk status
- [ ] All behind Cloudflare, zero-trust on admin routes
- [ ] No third-party JS, no CDN dependencies
- [ ] Dark mode default, mobile-first layout

---

## Out of Scope — Sprint 1

- User authentication / login flow
- Multi-family support
- Push notifications
- Calendar event creation via web UI
- Historical data / analytics
- Desktop-first layout refinements

---

## Risks

| Risk | Mitigation |
|---|---|
| Cloudflare Tunnel latency | Test early; fall back to Tailscale Funnel |
| CalDAV API response time | Cache aggressively, 5-min TTL |
| HTMX polling overhead | 30s interval, lightweight payloads |
| Both specialists blocked on each other | Contract-first: specs before implementation |

---

## Approval

**Director Matt:** Approve / Modify / Reject → tag @hoffmann_butler_bot in The Hoffmann Board

---

_This document is the source of truth for Sprint 1. Updates go here first, then propagate to specialist workspaces._