# epochix-dev/epochix architecture

> Architecture diagram of the GitHub repository epochix-dev/epochix, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/epochix-dev/epochix
- Repository: https://github.com/epochix-dev/epochix

## Overview

Epochix turns existing or live training output into normalized metrics, an interpreted training story, and a dashboard/report. The primary path is input → parsing/normalization → story grading and phases → persisted run data → live delivery or export. The Python pipeline’s ownership is explicit in its module documentation; the README supplies the broader capabilities, while sampled sources confirm key server, frontend, and VS Code paths. Some integration wiring is documented but not sampled, so those links are omitted or marked optional.

Main entry points: [`src/epochix/pipeline.py`](https://github.com/epochix-dev/epochix/blob/main/src/epochix/pipeline.py) (Run pipeline), [`frontend/src/main.js`](https://github.com/epochix-dev/epochix/blob/main/frontend/src/main.js) (Web dashboard), [`src/epochix/server/routes_runs.py`](https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/routes_runs.py) (Run and snapshot routes), [`epochix-vscode/src/webview/StandaloneEngine.ts`](https://github.com/epochix-dev/epochix/blob/main/epochix-vscode/src/webview/StandaloneEngine.ts) (Standalone engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingest and analysis"]
  node_ingesters["Log ingesters"]
  node_parsers["Framework parsers"]
  node_normalizer["Metric normalization"]
end

subgraph group_interpret["Story interpretation"]
  node_story["Story and grading"]
end

subgraph group_runtime["Run delivery"]
  node_cli["CLI<br/>[cli.py]"]
  node_pipeline["Run pipeline<br/>[pipeline.py]"]
  node_store[("Run history<br/>[sqlite_store.py]")]
  node_hub["Live message hub<br/>[hub.py]"]
  node_server["HTTP and stream API<br/>[app.py]"]
  node_routes["Run and snapshot routes<br/>[routes_runs.py]"]
end

subgraph group_clients["Dashboards"]
  node_frontend["Web dashboard<br/>[main.js]"]
  node_liveclient["Live stream client<br/>[ws-client.js]"]
  node_compare["Run comparison<br/>[CompareView.js]"]
  node_vscode["VS Code extension<br/>[extension.ts]"]
  node_terminalwatch["Terminal detection<br/>[TerminalWatcher.ts]"]
  node_standalone["Standalone engine"]
end

subgraph group_outputs["Integrations and exports"]
  node_exportroutes["Export routes<br/>[routes_export.py]"]
  node_exporters["Report exporters"]
  node_integrations["Framework integrations"]
end

node_user(("ML engineer"))
node_training["Training output"]
node_llm(("LLM service"))

node_user -->|"runs command"| node_cli
node_training -->|"supplies logs"| node_ingesters
node_cli -->|"starts processing"| node_pipeline
node_ingesters -->|"yields lines"| node_pipeline
node_pipeline -->|"selects and parses"| node_parsers
node_parsers -->|"produces metrics"| node_normalizer
node_pipeline -->|"normalizes metrics"| node_normalizer
node_pipeline -->|"processes events"| node_story
node_pipeline -->|"writes run data"| node_store
node_pipeline -->|"publishes updates"| node_hub
node_user -->|"opens dashboard"| node_server
node_server -->|"dispatches requests"| node_routes
node_routes -->|"reads and updates"| node_store
node_frontend -->|"fetches run data"| node_routes
node_frontend -->|"starts live feed"| node_liveclient
node_liveclient -->|"opens WebSocket"| node_server
node_hub -->|"streams updates"| node_liveclient
node_frontend -->|"renders comparison"| node_compare
node_compare -->|"requests comparison"| node_routes
node_frontend -->|"requests exports"| node_exportroutes
node_exportroutes -->|"loads run data"| node_store
node_exportroutes -->|"generates reports"| node_exporters
node_user -->|"uses extension"| node_vscode
node_vscode -->|"watches terminal"| node_terminalwatch
node_terminalwatch -->|"feeds terminal text"| node_standalone
node_standalone -->|"parses framework logs"| node_parsers
node_standalone -->|"interprets metrics"| node_story
node_integrations -.->|"reports training metrics"| node_pipeline
node_pipeline -.->|"requests fallback extraction"| node_llm

click node_cli "https://github.com/epochix-dev/epochix/blob/main/src/epochix/cli.py"
click node_ingesters "https://github.com/epochix-dev/epochix/tree/main/src/epochix/ingester"
click node_parsers "https://github.com/epochix-dev/epochix/tree/main/src/epochix/parsers"
click node_normalizer "https://github.com/epochix-dev/epochix/tree/main/src/epochix/normalizer"
click node_pipeline "https://github.com/epochix-dev/epochix/blob/main/src/epochix/pipeline.py"
click node_story "https://github.com/epochix-dev/epochix/tree/main/src/epochix/story_engine"
click node_store "https://github.com/epochix-dev/epochix/blob/main/src/epochix/store/sqlite_store.py"
click node_hub "https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/hub.py"
click node_server "https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/app.py"
click node_routes "https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/routes_runs.py"
click node_exportroutes "https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/routes_export.py"
click node_frontend "https://github.com/epochix-dev/epochix/blob/main/frontend/src/main.js"
click node_liveclient "https://github.com/epochix-dev/epochix/blob/main/frontend/src/ws-client.js"
click node_compare "https://github.com/epochix-dev/epochix/blob/main/frontend/src/visualizations/CompareView.js"
click node_exporters "https://github.com/epochix-dev/epochix/tree/main/src/epochix/exporters"
click node_integrations "https://github.com/epochix-dev/epochix/tree/main/src/epochix/integrations"
click node_vscode "https://github.com/epochix-dev/epochix/blob/main/epochix-vscode/src/extension.ts"
click node_terminalwatch "https://github.com/epochix-dev/epochix/blob/main/epochix-vscode/src/terminal/TerminalWatcher.ts"
click node_standalone "https://github.com/epochix-dev/epochix/blob/main/epochix-vscode/src/webview/StandaloneEngine.ts"

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_ingesters,node_parsers,node_normalizer toneBlue
class node_story toneAmber
class node_cli,node_pipeline,node_store,node_hub,node_server,node_routes toneMint
class node_frontend,node_liveclient,node_compare,node_vscode,node_terminalwatch,node_standalone toneRose
class node_exportroutes,node_exporters,node_integrations,node_user,node_training,node_llm toneIndigo
```

## Components

### Ingest and analysis

- [Log ingesters](https://github.com/epochix-dev/epochix/tree/main/src/epochix/ingester): `src/epochix/ingester`
- [Framework parsers](https://github.com/epochix-dev/epochix/tree/main/src/epochix/parsers): `src/epochix/parsers`
- [Metric normalization](https://github.com/epochix-dev/epochix/tree/main/src/epochix/normalizer): `src/epochix/normalizer`

### Story interpretation

- [Story and grading](https://github.com/epochix-dev/epochix/tree/main/src/epochix/story_engine): `src/epochix/story_engine`

### Run delivery

- [CLI](https://github.com/epochix-dev/epochix/blob/main/src/epochix/cli.py): `src/epochix/cli.py`
- [Run pipeline](https://github.com/epochix-dev/epochix/blob/main/src/epochix/pipeline.py): `src/epochix/pipeline.py`
- [Run history](https://github.com/epochix-dev/epochix/blob/main/src/epochix/store/sqlite_store.py): `src/epochix/store/sqlite_store.py`
- [Live message hub](https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/hub.py): `src/epochix/server/hub.py`
- [HTTP and stream API](https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/app.py): `src/epochix/server/app.py`
- [Run and snapshot routes](https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/routes_runs.py): `src/epochix/server/routes_runs.py`

### Dashboards

- [Web dashboard](https://github.com/epochix-dev/epochix/blob/main/frontend/src/main.js): `frontend/src/main.js`
- [Live stream client](https://github.com/epochix-dev/epochix/blob/main/frontend/src/ws-client.js): `frontend/src/ws-client.js`
- [Run comparison](https://github.com/epochix-dev/epochix/blob/main/frontend/src/visualizations/CompareView.js): `frontend/src/visualizations/CompareView.js`
- [VS Code extension](https://github.com/epochix-dev/epochix/blob/main/epochix-vscode/src/extension.ts): `epochix-vscode/src/extension.ts`
- [Terminal detection](https://github.com/epochix-dev/epochix/blob/main/epochix-vscode/src/terminal/TerminalWatcher.ts): `epochix-vscode/src/terminal/TerminalWatcher.ts`
- [Standalone engine](https://github.com/epochix-dev/epochix/blob/main/epochix-vscode/src/webview/StandaloneEngine.ts): `epochix-vscode/src/webview/StandaloneEngine.ts`

### Integrations and exports

- [Export routes](https://github.com/epochix-dev/epochix/blob/main/src/epochix/server/routes_export.py): `src/epochix/server/routes_export.py`
- [Report exporters](https://github.com/epochix-dev/epochix/tree/main/src/epochix/exporters): `src/epochix/exporters`
- [Framework integrations](https://github.com/epochix-dev/epochix/tree/main/src/epochix/integrations): `src/epochix/integrations`

### Other components

- **ML engineer**
- **Training output**
- **LLM service**

## Connections

- ML engineer → CLI: runs command
- Training output → Log ingesters: supplies logs
- CLI → Run pipeline: starts processing
- Log ingesters → Run pipeline: yields lines
- Run pipeline → Framework parsers: selects and parses
- Framework parsers → Metric normalization: produces metrics
- Run pipeline → Metric normalization: normalizes metrics
- Run pipeline → Story and grading: processes events
- Run pipeline → Run history: writes run data
- Run pipeline → Live message hub: publishes updates
- ML engineer → HTTP and stream API: opens dashboard
- HTTP and stream API → Run and snapshot routes: dispatches requests
- Run and snapshot routes → Run history: reads and updates
- Web dashboard → Run and snapshot routes: fetches run data
- Web dashboard → Live stream client: starts live feed
- Live stream client → HTTP and stream API: opens WebSocket
- Live message hub → Live stream client: streams updates
- Web dashboard → Run comparison: renders comparison
- Run comparison → Run and snapshot routes: requests comparison
- Web dashboard → Export routes: requests exports
- Export routes → Run history: loads run data
- Export routes → Report exporters: generates reports
- ML engineer → VS Code extension: uses extension
- VS Code extension → Terminal detection: watches terminal
- Terminal detection → Standalone engine: feeds terminal text
- Standalone engine → Framework parsers: parses framework logs
- Standalone engine → Story and grading: interprets metrics
- Framework integrations → Run pipeline: reports training metrics
- Run pipeline → LLM service: requests fallback extraction