# joejbaldwin/medra architecture

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

- Interactive diagram: https://gitdiagram.com/joejbaldwin/medra
- Repository: https://github.com/joejbaldwin/medra

## Overview

MeDRA streams model reasoning or supplied text into a live dashboard: a selected source yields chunks, the backend mines them into offset-aware metrics, presentation converts metrics into visual updates, and the browser renders text, concept, topic, and step views. The graph preserves documented source options and visualizations. Some subsystem links rely on the README because their implementation was not sampled; uncertain internal calls are omitted.

Main entry points: [`frontend/src/main.ts`](https://github.com/joejbaldwin/medra/blob/main/frontend/src/main.ts) (Dashboard app), [`backend/medra/server.py`](https://github.com/joejbaldwin/medra/blob/main/backend/medra/server.py) (Session API), [`backend/medra/mining/miner.py`](https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/miner.py) (Incremental miner), [`backend/medra/pipeline.py`](https://github.com/joejbaldwin/medra/blob/main/backend/medra/pipeline.py) (Stream pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Session runtime"]
  node_backend["Session API<br/>[server.py]"]
  node_pipeline["Stream pipeline<br/>[pipeline.py]"]
  node_contracts["Message contracts<br/>[contracts.py]"]
end

subgraph group_sources["Text sources"]
  node_replay["Trace replay<br/>[replay.py]"]
  node_samples["Sample traces<br/>[samples.py]"]
  node_paste["Pasted text<br/>[paste.py]"]
  node_deepseek["DeepSeek source<br/>[deepseek.py]"]
  node_ollama["Ollama source<br/>[ollama.py]"]
end

subgraph group_mining["Text mining"]
  node_miner["Incremental miner<br/>[miner.py]"]
  node_language["Language detection<br/>[language.py]"]
  node_clean["Text cleaning<br/>[clean.py]"]
  node_segment["Segmentation<br/>[segment.py]"]
  node_topics["Topic clustering<br/>[topics.py]"]
end

subgraph group_presentation["Presentation"]
  node_presenter["View presenter<br/>[presenter.py]"]
  node_selection["Bubble selection<br/>[select.py]"]
  node_topicview["Topic timeline<br/>[timeline.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_frontend["Dashboard app<br/>[main.ts]"]
  node_state["View state<br/>[state.ts]"]
  node_textpane["Stream text<br/>[textPane.ts]"]
  node_panels["Visualization panels<br/>[panels.ts]"]
  node_concept["Concept map<br/>[conceptMap.ts]"]
  node_timeline["Topic timeline<br/>[timeline.ts]"]
  node_stepgraph["Step graph<br/>[stepGraph.ts]"]
  node_layout["Window layout<br/>[layout.ts]"]
  node_picker["View picker<br/>[picker.ts]"]
end

node_user(("User"))
node_llm["Model service"]

node_user -->|"selects source"| node_frontend
node_frontend -->|"creates session"| node_backend
node_backend -->|"starts stream"| node_pipeline
node_backend -->|"loads trace"| node_replay
node_replay -->|"reads traces"| node_samples
node_backend -->|"selects source"| node_paste
node_backend -->|"selects source"| node_deepseek
node_backend -->|"selects source"| node_ollama
node_deepseek -->|"streams request"| node_llm
node_ollama -->|"uses local model"| node_llm
node_pipeline -->|"feeds chunks"| node_miner
node_pipeline -->|"presents metrics"| node_presenter
node_pipeline -->|"emits messages"| node_contracts
node_miner -->|"produces metrics"| node_contracts
node_miner -->|"detects language"| node_language
node_miner -->|"masks text"| node_clean
node_miner -->|"segments text"| node_segment
node_miner -->|"clusters topics"| node_topics
node_presenter -->|"selects bubbles"| node_selection
node_presenter -->|"builds timeline"| node_topicview
node_presenter -->|"produces views"| node_contracts
node_backend -->|"streams updates"| node_frontend
node_frontend -->|"updates state"| node_state
node_frontend -->|"renders text"| node_textpane
node_frontend -->|"opens views"| node_panels
node_frontend -->|"manages windows"| node_layout
node_frontend -->|"offers views"| node_picker
node_panels -->|"renders map"| node_concept
node_panels -->|"renders timeline"| node_timeline
node_panels -->|"renders steps"| node_stepgraph
node_state -->|"stores updates"| node_contracts

click node_backend "https://github.com/joejbaldwin/medra/blob/main/backend/medra/server.py"
click node_pipeline "https://github.com/joejbaldwin/medra/blob/main/backend/medra/pipeline.py"
click node_contracts "https://github.com/joejbaldwin/medra/blob/main/backend/medra/contracts.py"
click node_replay "https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/replay.py"
click node_samples "https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/samples.py"
click node_paste "https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/paste.py"
click node_deepseek "https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/deepseek.py"
click node_ollama "https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/ollama.py"
click node_miner "https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/miner.py"
click node_language "https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/language.py"
click node_clean "https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/clean.py"
click node_segment "https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/segment.py"
click node_topics "https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/topics.py"
click node_presenter "https://github.com/joejbaldwin/medra/blob/main/backend/medra/present/presenter.py"
click node_selection "https://github.com/joejbaldwin/medra/blob/main/backend/medra/present/select.py"
click node_topicview "https://github.com/joejbaldwin/medra/blob/main/backend/medra/present/timeline.py"
click node_frontend "https://github.com/joejbaldwin/medra/blob/main/frontend/src/main.ts"
click node_state "https://github.com/joejbaldwin/medra/blob/main/frontend/src/state.ts"
click node_textpane "https://github.com/joejbaldwin/medra/blob/main/frontend/src/textPane.ts"
click node_panels "https://github.com/joejbaldwin/medra/blob/main/frontend/src/panels.ts"
click node_concept "https://github.com/joejbaldwin/medra/blob/main/frontend/src/conceptMap.ts"
click node_timeline "https://github.com/joejbaldwin/medra/blob/main/frontend/src/timeline.ts"
click node_stepgraph "https://github.com/joejbaldwin/medra/blob/main/frontend/src/stepGraph.ts"
click node_layout "https://github.com/joejbaldwin/medra/blob/main/frontend/src/layout.ts"
click node_picker "https://github.com/joejbaldwin/medra/blob/main/frontend/src/picker.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_backend,node_pipeline,node_contracts,node_user toneBlue
class node_replay,node_samples,node_paste,node_deepseek,node_ollama toneAmber
class node_miner,node_language,node_clean,node_segment,node_topics toneMint
class node_presenter,node_selection,node_topicview toneRose
class node_frontend,node_state,node_textpane,node_panels,node_concept,node_timeline,node_stepgraph,node_layout,node_picker,node_llm toneIndigo
```

## Components

### Session runtime

- [Session API](https://github.com/joejbaldwin/medra/blob/main/backend/medra/server.py): `backend/medra/server.py`
- [Stream pipeline](https://github.com/joejbaldwin/medra/blob/main/backend/medra/pipeline.py): `backend/medra/pipeline.py`
- [Message contracts](https://github.com/joejbaldwin/medra/blob/main/backend/medra/contracts.py): `backend/medra/contracts.py`

### Text sources

- [Trace replay](https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/replay.py): `backend/medra/sources/replay.py`
- [Sample traces](https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/samples.py): `backend/medra/sources/samples.py`
- [Pasted text](https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/paste.py): `backend/medra/sources/paste.py`
- [DeepSeek source](https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/deepseek.py): `backend/medra/sources/deepseek.py`
- [Ollama source](https://github.com/joejbaldwin/medra/blob/main/backend/medra/sources/ollama.py): `backend/medra/sources/ollama.py`

### Text mining

- [Incremental miner](https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/miner.py): `backend/medra/mining/miner.py`
- [Language detection](https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/language.py): `backend/medra/mining/language.py`
- [Text cleaning](https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/clean.py): `backend/medra/mining/clean.py`
- [Segmentation](https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/segment.py): `backend/medra/mining/segment.py`
- [Topic clustering](https://github.com/joejbaldwin/medra/blob/main/backend/medra/mining/topics.py): `backend/medra/mining/topics.py`

### Presentation

- [View presenter](https://github.com/joejbaldwin/medra/blob/main/backend/medra/present/presenter.py): `backend/medra/present/presenter.py`
- [Bubble selection](https://github.com/joejbaldwin/medra/blob/main/backend/medra/present/select.py): `backend/medra/present/select.py`
- [Topic timeline](https://github.com/joejbaldwin/medra/blob/main/backend/medra/present/timeline.py): `backend/medra/present/timeline.py`

### Dashboard

- [Dashboard app](https://github.com/joejbaldwin/medra/blob/main/frontend/src/main.ts): `frontend/src/main.ts`
- [View state](https://github.com/joejbaldwin/medra/blob/main/frontend/src/state.ts): `frontend/src/state.ts`
- [Stream text](https://github.com/joejbaldwin/medra/blob/main/frontend/src/textPane.ts): `frontend/src/textPane.ts`
- [Visualization panels](https://github.com/joejbaldwin/medra/blob/main/frontend/src/panels.ts): `frontend/src/panels.ts`
- [Concept map](https://github.com/joejbaldwin/medra/blob/main/frontend/src/conceptMap.ts): `frontend/src/conceptMap.ts`
- [Topic timeline](https://github.com/joejbaldwin/medra/blob/main/frontend/src/timeline.ts): `frontend/src/timeline.ts`
- [Step graph](https://github.com/joejbaldwin/medra/blob/main/frontend/src/stepGraph.ts): `frontend/src/stepGraph.ts`
- [Window layout](https://github.com/joejbaldwin/medra/blob/main/frontend/src/layout.ts): `frontend/src/layout.ts`
- [View picker](https://github.com/joejbaldwin/medra/blob/main/frontend/src/picker.ts): `frontend/src/picker.ts`

### Other components

- **User**
- **Model service**

## Connections

- User → Dashboard app: selects source
- Dashboard app → Session API: creates session
- Session API → Stream pipeline: starts stream (evidence: `backend/medra/server.py`)
- Session API → Trace replay: loads trace (evidence: `backend/medra/server.py`)
- Trace replay → Sample traces: reads traces (evidence: `backend/medra/sources/replay.py`)
- Session API → Pasted text: selects source
- Session API → DeepSeek source: selects source (evidence: `backend/medra/server.py`)
- Session API → Ollama source: selects source (evidence: `backend/medra/server.py`)
- DeepSeek source → Model service: streams request (evidence: `backend/medra/sources/deepseek.py`)
- Ollama source → Model service: uses local model
- Stream pipeline → Incremental miner: feeds chunks (evidence: `backend/medra/pipeline.py`)
- Stream pipeline → View presenter: presents metrics (evidence: `backend/medra/pipeline.py`)
- Stream pipeline → Message contracts: emits messages (evidence: `backend/medra/pipeline.py`)
- Incremental miner → Message contracts: produces metrics (evidence: `backend/medra/mining/miner.py`)
- Incremental miner → Language detection: detects language (evidence: `backend/medra/mining/miner.py`)
- Incremental miner → Text cleaning: masks text (evidence: `backend/medra/mining/miner.py`)
- Incremental miner → Segmentation: segments text (evidence: `backend/medra/mining/miner.py`)
- Incremental miner → Topic clustering: clusters topics (evidence: `backend/medra/mining/miner.py`)
- View presenter → Bubble selection: selects bubbles (evidence: `backend/medra/present/presenter.py`)
- View presenter → Topic timeline: builds timeline (evidence: `backend/medra/present/presenter.py`)
- View presenter → Message contracts: produces views (evidence: `backend/medra/present/presenter.py`)
- Session API → Dashboard app: streams updates
- Dashboard app → View state: updates state (evidence: `frontend/src/main.ts`)
- Dashboard app → Stream text: renders text (evidence: `frontend/src/main.ts`)
- Dashboard app → Visualization panels: opens views (evidence: `frontend/src/main.ts`)
- Dashboard app → Window layout: manages windows (evidence: `frontend/src/main.ts`)
- Dashboard app → View picker: offers views (evidence: `frontend/src/main.ts`)
- Visualization panels → Concept map: renders map (evidence: `frontend/src/panels.ts`)
- Visualization panels → Topic timeline: renders timeline (evidence: `frontend/src/panels.ts`)
- Visualization panels → Step graph: renders steps (evidence: `frontend/src/panels.ts`)
- View state → Message contracts: stores updates (evidence: `frontend/src/state.ts`)
