# Family Brain — Live Network Visualization

**Status:** ✅ Implemented & live at `https://hoffdesk.com/api/system/brain/svg`  
**Preview:** `https://hoffdesk.com/blog/static/brain-live.html`  
**Stats JSON:** `https://hoffdesk.com/api/system/brain/stats`

## Overview

A live-rendered SVG network visualization of the Beelink's data constellation. Each node represents a data store, auto-scaling with live record counts. Connections pulse with animated data packets. No manual SVG editing — the server generates it from real queries.

## Nodes

| Node | Data Source | Auto-scales With |
|------|-------------|-----------------|
| BEELINK | — | Static hub (r=58) |
| CALENDAR | Radicale systemctl status | Status text |
| MEMORY | ChromaDB chunk count + file size | Chunk count → radius 36-48 |
| BLOG | SQLite post count | Published + total → radius 36-48 |
| LLM | Ollama API model count | Model count → radius 36-48 |
| ONTOLOGY | Entity count | Entity count → radius 34-42 |
| RECIPES | Ontology recipe-type entities | Stub (0 now, grows as recipes added) |

## Endpoints

### `GET /api/system/brain/svg` → `image/svg+xml`
Renders full network SVG with live data. No auth required. Used on dashboard as `<img>` or `<object>`.

### `GET /api/system/brain/stats` → JSON
Returns raw stats for each data store. Useful for debugging or embedding in other dashboards.

## How to Add a New Node

1. Add a query to `_get_db_stats()` in `/home/hoffmann_admin/.openclaw/workspace-socrates/hoffdesk-api/family/brain.py`
2. Add a color entry in `COLORS` dict (use one of the 7 existing palette colors)
3. Add a slot in `_build_nodes()` with position and detail text
4. Restart uvicorn — the SVG auto-generates

## Deployment

The endpoint is mounted on:
- `family_app` (family.hoffdesk.com) — with session auth exempt prefix
- `blog_app` (hoffdesk.com) — fully public  
- `dev_app` (local testing) — fully public

Auth exemption added to `EXEMPT_PREFIXES` in `/api/system/`.

## Files

| File | Purpose |
|------|---------|
| `family/brain.py` | Stats collection + SVG generator |
| `blog/templates/brain_svg.svg.j2` | Jinja2 SVG template |
| `hoffdesk/blog/static/brain-live.html` | Preview page with HTMX auto-refresh |
| `shared/project-docs/family-brain-spec.md` | This spec |

## Phase 2 Ideas (Socrates)

- Add `query_count` tracking to each service (read from FastAPI access logs or middleware)
- Add `last_activity` timestamps for stores that don't track them
- Add health check per store (ping port, check process)
- Add cross-connections between satellites (e.g. Blog → Memory for vector search)