Contract Refactor Summary — UI Namespace Implementation

Completed: 2026-04-29
Task: Implement /ui/ namespace per CONTRACT.md specification

Files Created

1. UI Router

• Path: workspace-socrates/hoffdesk-api/dashboard/ui_router.py
• Description: New FastAPI router with /ui/* endpoints
• Routes:
• GET /ui/weather-card — Returns HTML fragment using Jinja2 template
• GET /ui/health-card — Returns HTML fragment using Jinja2 template
• GET /ui/events-list — Returns HTML fragment using Jinja2 template (moved from /api/events-list)
• GET /ui/events-week — Returns HTML fragment using Jinja2 template (moved from /api/events-week)

2. Jinja2 Templates (Icarus Templates Directory)

• icarus/templates/dashboard/components/weather_card.html.j2
• icarus/templates/dashboard/components/health_card.html.j2
• icarus/templates/dashboard/components/events_list.html.j2
• icarus/templates/dashboard/components/events_week.html.j2

3. Updated Main Router

• Path: workspace-socrates/hoffdesk-api/main.py
• Changes:
• Added import: from dashboard.ui_router import router as ui_router
• Added to family_app: family_app.include_router(ui_router, tags=["ui"])
• Added to dev_app: dev_app.include_router(ui_router, prefix="/family/ui", tags=["ui"])

4. Updated Dashboard Router

• Path: workspace-socrates/hoffdesk-api/dashboard/router.py
• Changes:
• Added Jinja2Templates initialization pointing to icarus/templates/
• Converted /api/events-list to JSON response (deprecated, recommends /ui/events-list)
• Converted /api/events-week to JSON response (deprecated, recommends /ui/events-week)
• Note: Functions _format_event_for_list, _get_day_label, _get_week_start are now shared helpers

Endpoint Mapping

Validation Checklist (from CONTRACT.md)

• [x] /ui/weather-card returns HTML, not JSON
• [x] /ui/health-card returns HTML, not JSON
• [x] /ui/events-list returns HTML (moved)
• [x] /ui/events-week returns HTML (moved)
• [ ] Dashboard template HTMX calls work — REQUIRES Daedalus to update templates

Next Steps (Daedalus)

Daedalus must update the dashboard HTML templates to use the new /ui/* endpoints:

File to update: icarus/templates/dashboard/index.html

Current HTMX calls (using /api/today):

<section class="card" id="weather-card" ... hx-get="/api/today" ...>
<section class="card" id="health-card" ... hx-get="/api/today" ...>
<section class="card" id="calendar-card" ... hx-get="/api/today" ...>

Should change to:

<section class="card" id="weather-card" ... hx-get="/ui/weather-card" ...>
<section class="card" id="health-card" ... hx-get="/ui/health-card" ...>
<section class="card" id="events-card" ... hx-get="/ui/events-list" ...>

Contract Compliance

Per CONTRACT.md Section 2: If HTMX calls it, it MUST be /ui/* and return HTML.

Testing

To test the new endpoints:

# Test weather card (returns HTML)
curl http://family.hoffdesk.com/ui/weather-card

# Test health card (returns HTML)
curl http://family.hoffdesk.com/ui/health-card

# Test events list (returns HTML)
curl http://family.hoffdesk.com/ui/events-list

# Test events week (returns HTML)
curl http://family.hoffdesk.com/ui/events-week?start=2026-04-28

# Test deprecated endpoints (return JSON)
curl http://family.hoffdesk.com/api/events-list
curl http://family.hoffdesk.com/api/events-week

API Response Examples

/ui/weather-card (HTML)

<div class="weather-card-content">
  <div class="weather-current">
    <div class="weather-temp temp-mild">52°</div>
    <div class="weather-details">
      <div class="weather-condition">Partly cloudy</div>
      <div class="weather-meta text-body-sm text-text-secondary">
        Feels like 49° · 62% humidity · 10 mph wind
      </div>
    </div>
  </div>
  ...
</div>

/api/events-list (deprecated, JSON)

{
  "events": [...],
  "meta": {
    "note": "This endpoint is deprecated. Use /ui/events-list for HTML fragments.",
    "count": 5
  }
}

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