# 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
[
  {
    "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:**
```json
{ "type": "subscribe", "channels": ["events", "documents"] }
```

**Server → Client:**
```json
{ "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
```