# brainarts-lab/hebe-longevity architecture

> Architecture diagram of the GitHub repository brainarts-lab/hebe-longevity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brainarts-lab/hebe-longevity
- Repository: https://github.com/brainarts-lab/hebe-longevity

## Overview

Hebe is a Hermes longevity plugin for recording blood panels, calculating and explaining Blood PhenoAge, and preparing screened research plans. The main workflow begins with a user-confirmed blood draw in the Desktop page or chat command; Hebe validates and saves it, computes a report and trend, and can use the resulting PLSI state to draft, screen, challenge, and—only after user approval—start a plan. The graph separates interfaces, core workflows, calculation/reporting, planning, and persistence. Some UI-to-API wiring is not shown in the excerpts, so that link is marked unverified.

Main entry points: [`hebe/commands.py`](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/commands.py) (Chat Commands), [`hebe/service.py`](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/service.py) (Import & Results), [`hebe/plans.py`](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plans.py) (Plan Lifecycle), [`__init__.py`](https://github.com/brainarts-lab/hebe-longevity/blob/main/__init__.py) (Plugin Registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Hermes Interfaces"]
  node_desktop["Hebe Desktop Page<br/>[plugin.js]"]
  node_plugin["Plugin Registration<br/>[__init__.py]"]
  node_commands["Chat Commands<br/>[commands.py]"]
  node_agent_tools["Agent Tools<br/>[agent_tools.py]"]
  node_api["Desktop API<br/>[api.py]"]
end

subgraph group_workflow["Blood Workflow"]
  node_service["Import &amp; Results<br/>[service.py]"]
end

subgraph group_calculation["Calculation &amp; Reports"]
  node_drivers["Trend Drivers<br/>[drivers.py]"]
  node_kernel["PhenoAge Formula<br/>[plsi_kernel.py]"]
  node_units["Unit Conversion<br/>[plsi_units.py]"]
  node_report["Report Rendering<br/>[report.py]"]
end

subgraph group_planning["Research Planning"]
  node_plans["Plan Lifecycle<br/>[plans.py]"]
  node_challenger["Challenger Model"]
end

subgraph group_storage["State &amp; PLSI"]
  node_plsi_bridge["PLSI Bridge<br/>[plsi_bridge.py]"]
  node_plsi["PLSI Toolbelt"]
  node_database[("Local Results DB<br/>[service.py]")]
end

node_user(("User"))
node_hermes["Hermes Host"]

node_user -->|"uses page"| node_desktop
node_user -->|"enters command"| node_commands
node_desktop -.->|"calls routes"| node_api
node_hermes -->|"loads plugin"| node_plugin
node_plugin -->|"registers command"| node_commands
node_plugin -->|"registers tools"| node_agent_tools
node_plugin -->|"registers challenger"| node_hermes
node_commands -->|"validates and saves"| node_service
node_api -->|"reads and changes"| node_service
node_commands -->|"renders report"| node_report
node_api -->|"serves report"| node_report
node_service -->|"converts values"| node_units
node_service -->|"calculates age"| node_kernel
node_report -->|"renders trend effects"| node_drivers
node_drivers -->|"recalculates formula"| node_kernel
node_service -->|"reads and writes"| node_database
node_commands -->|"starts plans"| node_plans
node_agent_tools -->|"runs planning tools"| node_plans
node_plans -->|"syncs person state"| node_service
node_plans -->|"screens and checks"| node_plsi_bridge
node_agent_tools -->|"searches and calculates"| node_plsi_bridge
node_plsi_bridge -->|"runs commands"| node_plsi
node_plans -.->|"requests challenge"| node_challenger
node_user -->|"approves start"| node_commands

click node_desktop "https://github.com/brainarts-lab/hebe-longevity/blob/main/desktop/plugin.js"
click node_plugin "https://github.com/brainarts-lab/hebe-longevity/blob/main/__init__.py"
click node_commands "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/commands.py"
click node_agent_tools "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/agent_tools.py"
click node_api "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/api.py"
click node_service "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/service.py"
click node_drivers "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/drivers.py"
click node_kernel "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plsi_kernel.py"
click node_units "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plsi_units.py"
click node_report "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/report.py"
click node_plans "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plans.py"
click node_plsi_bridge "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plsi_bridge.py"
click node_database "https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_desktop,node_plugin,node_commands,node_agent_tools,node_api,node_user toneBlue
class node_service toneAmber
class node_drivers,node_kernel,node_units,node_report toneMint
class node_plans,node_challenger toneRose
class node_plsi_bridge,node_plsi,node_database,node_hermes toneIndigo
```

## Components

### Hermes Interfaces

- [Hebe Desktop Page](https://github.com/brainarts-lab/hebe-longevity/blob/main/desktop/plugin.js): `desktop/plugin.js`
- [Plugin Registration](https://github.com/brainarts-lab/hebe-longevity/blob/main/__init__.py): `__init__.py`
- [Chat Commands](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/commands.py): `hebe/commands.py`
- [Agent Tools](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/agent_tools.py): `hebe/agent_tools.py`
- [Desktop API](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/api.py): `hebe/api.py`

### Blood Workflow

- [Import & Results](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/service.py): `hebe/service.py`

### Calculation & Reports

- [Trend Drivers](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/drivers.py): `hebe/drivers.py`
- [PhenoAge Formula](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plsi_kernel.py): `hebe/plsi_kernel.py`
- [Unit Conversion](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plsi_units.py): `hebe/plsi_units.py`
- [Report Rendering](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/report.py): `hebe/report.py`

### Research Planning

- [Plan Lifecycle](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plans.py): `hebe/plans.py`
- **Challenger Model**

### State & PLSI

- [PLSI Bridge](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/plsi_bridge.py): `hebe/plsi_bridge.py`
- **PLSI Toolbelt**
- [Local Results DB](https://github.com/brainarts-lab/hebe-longevity/blob/main/hebe/service.py): `hebe/service.py`

### Other components

- **User**
- **Hermes Host**

## Connections

- User → Hebe Desktop Page: uses page (evidence: `README.md`)
- User → Chat Commands: enters command (evidence: `README.md`)
- Hebe Desktop Page → Desktop API: calls routes
- Hermes Host → Plugin Registration: loads plugin (evidence: `__init__.py`)
- Plugin Registration → Chat Commands: registers command (evidence: `__init__.py`)
- Plugin Registration → Agent Tools: registers tools (evidence: `__init__.py`)
- Plugin Registration → Hermes Host: registers challenger (evidence: `__init__.py`)
- Chat Commands → Import & Results: validates and saves (evidence: `hebe/commands.py`)
- Desktop API → Import & Results: reads and changes (evidence: `hebe/api.py`)
- Chat Commands → Report Rendering: renders report (evidence: `hebe/commands.py`)
- Desktop API → Report Rendering: serves report (evidence: `hebe/api.py`)
- Import & Results → Unit Conversion: converts values (evidence: `hebe/service.py`)
- Import & Results → PhenoAge Formula: calculates age (evidence: `hebe/service.py`)
- Report Rendering → Trend Drivers: renders trend effects (evidence: `hebe/report.py`)
- Trend Drivers → PhenoAge Formula: recalculates formula (evidence: `hebe/drivers.py`)
- Import & Results → Local Results DB: reads and writes (evidence: `hebe/service.py`)
- Chat Commands → Plan Lifecycle: starts plans (evidence: `hebe/commands.py`)
- Agent Tools → Plan Lifecycle: runs planning tools (evidence: `hebe/agent_tools.py`)
- Plan Lifecycle → Import & Results: syncs person state (evidence: `hebe/plans.py`)
- Plan Lifecycle → PLSI Bridge: screens and checks (evidence: `hebe/plans.py`)
- Agent Tools → PLSI Bridge: searches and calculates (evidence: `hebe/agent_tools.py`)
- PLSI Bridge → PLSI Toolbelt: runs commands (evidence: `hebe/plsi_bridge.py`)
- Plan Lifecycle → Challenger Model: requests challenge
- User → Chat Commands: approves start (evidence: `README.md`)