Family Dashboard Integration Guide

For Socrates (Backend)

This document outlines the integration points between the React frontend and the FastAPI backend.

API Endpoints Required

The dashboard expects these endpoints at /api/v1/:

1. GET /api/v1/briefing

Returns the daily briefing for the current user.

Query Parameters:
- date (optional): ISO date string for specific date
- member (optional): Filter by family member
- scope (optional): 'day', 'week', or 'month'

Response:

{
  "date": "2026-04-28T00:00:00Z",
  "sections": {
    "urgent": [/* Event[] - next 24h */],
    "today": [/* Event[] */],
    "coordination": [/* Event[] - needs confirmation */],
    "maintenance": [/* Event[] - due soon */],
    "documents": [/* Document[] - recent */]
  }
}

2. GET /api/v1/events

Returns filtered events.

Query Parameters:
- member (optional): Filter by member name
- type (optional): 'calendar', 'coordination', 'maintenance', 'document'
- date_range (optional): 'today', 'week', 'month'

Response: Event[]

3. GET /api/v1/events/{id}

Returns a single event.

Response: Event

4. PUT /api/v1/events/{id}

Updates an event.

Request Body: Partial<Event>

Response: Event

5. GET /api/v1/weather

Returns weather data (or proxy to wttr.in).

Response:

{
  "status": "ok",
  "current": {
    "temperatureF": 52,
    "feelsLikeF": 49,
    "condition": "Partly Cloudy",
    "humidityPct": 62,
    "windMph": 10
  },
  "forecast": [/* hourly forecast */]
}

6. GET /api/v1/health

Returns system health status.

Response:

{
  "overallStatus": "healthy",
  "components": {
    "openclaw_gateway": { "status": "ok", "latencyMs": 12 },
    "radicale_caldav": { "status": "ok", "latencyMs": 45 },
    "ollama_local": { "status": "ok", "latencyMs": 89 },
    "cloudflare_tunnel": { "status": "ok", "latencyMs": 23 }
  },
  "diskUsage": {
    "totalGb": 256,
    "usedGb": 168,
    "usagePct": 65.6
  }
}

7. GET /api/v1/maintenance

Returns upcoming maintenance items.

Response: MaintenanceItem[]

8. GET /api/v1/documents

Returns recent documents.

Query Parameters:
- limit (optional): Number of documents to return

Response:

[
  {
    "id": "doc-1",
    "title": "2024 School Calendar.pdf",
    "preview": "Important dates...",
    "url": "/documents/...",
    "processedAt": "2026-04-28T10:00:00Z",
    "type": "school"
  }
]

WebSocket Endpoint

/ws/events

Real-time event updates.

Client → Server:

{ "type": "subscribe", "channels": ["events", "documents"] }

Server → Client:

{ "type": "event_update", "data": { /* Event */ }, "timestamp": "..." }
{ "type": "document_update", "data": { /* Document */ }, "timestamp": "..." }
{ "type": "briefing_update", "data": { /* Briefing */ }, "timestamp": "..." }
{ "type": "ping" }

Authentication

The dashboard sends the session token in:
1. Cookie: session_token
2. Header: Authorization: Bearer <token>

The backend should:
1. Verify the session token
2. Return 401 if invalid (frontend will redirect to login)
3. Include user role in response headers or JWT

Data Types

See src/types/index.ts for complete TypeScript definitions.

Key types:
- Event - Calendar events, coordination items, maintenance
- Briefing - Daily summary with sections
- WeatherData - Weather current + forecast
- SystemHealth - Component health status
- MaintenanceItem - Maintenance tracking

CORS Configuration

The backend must allow requests from:
- https://family.hoffdesk.com (production)
- http://localhost:3000 (development)

Deployment

The dashboard builds to dist/ as static files. Serve from any static host or integrate into the existing FastAPI app.

Environment Variables

Frontend .env.local:

NEXT_PUBLIC_API_URL=https://family.hoffdesk.com/api/v1
NEXT_PUBLIC_USE_MOCK=false

For mock mode (development without backend):

NEXT_PUBLIC_USE_MOCK=true