Frontend-Backend Contract — HoffDesk Dashboard

Version: 1.0
Date: 2026-04-29
Status: Active

1. Philosophy

• Python-first appliance. No React, Vue, or build steps.
• HTMX for interactivity. Backend renders, frontend swaps.
• Jinja2 for templating. No inline HTML generation in Python.
• Explicit contracts. JSON and HTML never mix.

2. Endpoint Namespaces

Rule: If HTMX calls it, it MUST be /ui/* and return HTML.

3. Directory Structure

icarus/templates/
├── base.html.j2              # Base layout (if needed)
├── dashboard/
│   ├── index.html            # Dashboard shell
│   ├── login.html            # Family login
│   └── components/
│       ├── weather_card.html.j2
│       ├── health_card.html.j2
│       ├── events_list.html.j2
│       ├── events_week.html.j2
│       └── event_detail.html.j2
└── shared/
    └── macros.j2             # Shared Jinja2 macros

Rule: Daedalus writes templates here. Socrates references these exact paths in FastAPI routes. No copies, no drift.

4. HTMX Endpoint Contract

4.1 Weather Card

Endpoint: GET /ui/weather-card

Response: HTML fragment (not JSON)

Template: dashboard/components/weather_card.html.j2

Example Response:

<div class="weather-summary">
  <span class="temp">44°F</span>
  <span class="condition">Rain</span>
  <span class="feels-like">Feels like 43°F</span>
</div>

4.2 Health Card

Endpoint: GET /ui/health-card

Response: HTML fragment

Template: dashboard/components/health_card.html.j2

4.3 Events List

Endpoint: GET /ui/events-list

Response: HTML fragment

Template: dashboard/components/events_list.html.j2

4.4 Events Week

Endpoint: GET /ui/events-week?start=YYYY-MM-DD

Response: HTML fragment

Template: dashboard/components/events_week.html.j2

5. JSON API Contract (for external consumers)

Endpoint: GET /api/today

Response: JSON (unchanged — for external apps, not HTMX)

Note: Dashboard does NOT call this via HTMX.

6. Template Ownership

Rule: Socrates NEVER modifies templates. If data structure changes, he notifies Daedalus to update templates.

7. Current Refactor Tasks

7.1 Socrates Tasks

1. Create /ui/weather-card endpoint — returns HTML using weather_card.html.j2
2. Create /ui/health-card endpoint — returns HTML using health_card.html.j2
3. Move /api/events-list → /ui/events-list
4. Move /api/events-week → /ui/events-week
5. Update dashboard router to import and use templates from icarus/templates/

7.2 Daedalus Tasks

1. Create icarus/templates/dashboard/components/weather_card.html.j2
2. Create icarus/templates/dashboard/components/health_card.html.j2
3. Update dashboard/index.html HTMX calls to use /ui/* endpoints
4. Ensure CSS classes match between templates and static/style.css

7.3 Wadsworth Tasks

1. Verify both specialists have access to icarus/templates/
2. Check endpoints return correct response types
3. Validate on iPad/iPhone

8. Validation Checklist

• [ ] /ui/weather-card returns HTML, not JSON
• [ ] /ui/health-card returns HTML, not JSON
• [ ] /ui/events-list returns HTML (moved from /api/)
• [ ] /ui/events-week returns HTML (moved from /api/)
• [ ] Dashboard loads weather card with styled data
• [ ] Dashboard loads health card with styled data
• [ ] Events list/week work as before
• [ ] iPhone Safari renders correctly

9. Anti-Patterns (Forbidden)

• ❌ Returning JSON from /ui/* endpoints
• ❌ Generating HTML inline in Python (use Jinja2 templates)
• ❌ Copying templates between directories (use single source)
• ❌ HTMX calling /api/* endpoints
• ❌ Modifying templates without updating corresponding endpoint

10. Version History

Approved by: Matt Hoffmann (Director)
Enforced by: Wadsworth (Chief of Staff)