# pluvium27/heurams architecture

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

- Interactive diagram: https://gitdiagram.com/pluvium27/heurams
- Repository: https://github.com/pluvium27/heurams

## Overview

HeurAMS is a heuristic spaced-repetition scheduler and TUI learning tool. The documented user path is to launch the TUI, navigate memory repositories, work through scheduled review and new-memory stages, and complete recall puzzles; the kernel routes review sessions and applies scheduling algorithms. The interface also exposes repository synchronization, settings, favorites, and audio precaching. Several screen implementations and repository-loading paths were not excerpted, so those links are omitted or marked unverified rather than inferred.

Main entry points: [`src/heurams/kernel/reactor/router.py`](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/router.py) (Stage router), [`src/heurams/interface/screens/dashboard.py`](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/dashboard.py) (Dashboard), [`src/heurams/kernel/repolib/repo.py`](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/repolib/repo.py) (Memory repositories), [`src/heurams/kernel/reactor/procession.py`](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/procession.py) (Review procession)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application interface"]
  node_cli["CLI entry<br/>[__main__.py]"]
  node_tui["TUI app<br/>[__init__.py]"]
  node_dashboard["Dashboard<br/>[dashboard.py]"]
  node_navigation["Repository navigation<br/>[navigator.py]"]
  node_preparation["Session preparation<br/>[preparation.py]"]
  node_memoqueue["Review queue<br/>[memoqueue.py]"]
  node_puzzle_ui["Puzzle widgets"]
  node_sync["Repository sync<br/>[synctool.py]"]
  node_settings["Settings<br/>[setting.py]"]
  node_precache["Audio precaching<br/>[precache.py]"]
end

subgraph group_content["Memory content"]
  node_repo[("Memory repositories<br/>[repo.py]")]
  node_particles["Memory records<br/>[atom.py]"]
  node_puzzles["Recall puzzles<br/>[mcq.py]"]
  node_electron["Review state<br/>[electron.py]"]
end

subgraph group_schedule["Review engine"]
  node_router["Stage router<br/>[router.py]"]
  node_procession["Review procession<br/>[procession.py]"]
  node_expander["Prompt expansion<br/>[expander.py]"]
  node_states["Session states<br/>[states.py]"]
  node_algorithms["Scheduling algorithms<br/>[base.py]"]
end

subgraph group_services["Supporting services"]
  node_context["Runtime context<br/>[context.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_favorites[("Favorites")]
  node_tts["Text-to-speech service<br/>[tts_service.py]"]
  node_tts_provider["TTS providers<br/>[edge_tts.py]"]
end

node_user(("Learner"))

node_user -->|"runs"| node_cli
node_cli -->|"launches"| node_tui
node_tui -->|"opens"| node_dashboard
node_dashboard -->|"opens"| node_navigation
node_dashboard -->|"opens"| node_preparation
node_navigation -.->|"browses"| node_repo
node_preparation -.->|"starts session"| node_router
node_memoqueue -.->|"requests stage"| node_router
node_router -->|"creates queues"| node_procession
node_router -->|"sets state"| node_states
node_procession -->|"calls"| node_expander
node_procession -->|"reads state"| node_states
node_expander -->|"uses records"| node_particles
node_expander -->|"creates puzzles"| node_puzzles
node_puzzle_ui -->|"renders"| node_puzzles
node_router -->|"routes records"| node_particles
node_particles -.->|"contains state"| node_electron
node_electron -->|"uses algorithms"| node_algorithms
node_dashboard -->|"loads repositories"| node_repo
node_sync -.->|"synchronizes"| node_repo
node_settings -->|"reads context"| node_context
node_context -->|"initializes"| node_config
node_precache -->|"reads content"| node_repo
node_precache -->|"requests speech"| node_tts
node_tts -->|"selects provider"| node_tts_provider

click node_cli "https://github.com/pluvium27/heurams/blob/dev/src/heurams/__main__.py"
click node_tui "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/__init__.py"
click node_dashboard "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/dashboard.py"
click node_navigation "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/navigator.py"
click node_preparation "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/preparation.py"
click node_memoqueue "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/memoqueue.py"
click node_puzzle_ui "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/widgets/base_puzzle_widget.py"
click node_sync "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/synctool.py"
click node_settings "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/setting.py"
click node_precache "https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/precache.py"
click node_repo "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/repolib/repo.py"
click node_particles "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/particles/atom.py"
click node_puzzles "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/puzzles/mcq.py"
click node_router "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/router.py"
click node_procession "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/procession.py"
click node_expander "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/expander.py"
click node_states "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/states.py"
click node_algorithms "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/algorithms/base.py"
click node_electron "https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/particles/electron.py"
click node_context "https://github.com/pluvium27/heurams/blob/dev/src/heurams/context.py"
click node_config "https://github.com/pluvium27/heurams/blob/dev/src/heurams/services/config.py"
click node_favorites "https://github.com/pluvium27/heurams/blob/dev/src/heurams/services/favorite_service.py"
click node_tts "https://github.com/pluvium27/heurams/blob/dev/src/heurams/services/tts_service.py"
click node_tts_provider "https://github.com/pluvium27/heurams/blob/dev/src/heurams/providers/tts/edge_tts.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_cli,node_tui,node_dashboard,node_navigation,node_preparation,node_memoqueue,node_puzzle_ui,node_sync,node_settings,node_precache toneBlue
class node_repo,node_particles,node_puzzles,node_electron toneAmber
class node_router,node_procession,node_expander,node_states,node_algorithms toneMint
class node_context,node_config,node_favorites,node_tts,node_tts_provider toneRose
class node_user toneIndigo
```

## Components

### Application interface

- [CLI entry](https://github.com/pluvium27/heurams/blob/dev/src/heurams/__main__.py): `src/heurams/__main__.py`
- [TUI app](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/__init__.py): `src/heurams/interface/__init__.py`
- [Dashboard](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/dashboard.py): `src/heurams/interface/screens/dashboard.py`
- [Repository navigation](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/navigator.py): `src/heurams/interface/screens/navigator.py`
- [Session preparation](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/preparation.py): `src/heurams/interface/screens/preparation.py`
- [Review queue](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/memoqueue.py): `src/heurams/interface/screens/memoqueue.py`
- [Puzzle widgets](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/widgets/base_puzzle_widget.py): `src/heurams/interface/widgets/base_puzzle_widget.py`
- [Repository sync](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/synctool.py): `src/heurams/interface/screens/synctool.py`
- [Settings](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/setting.py): `src/heurams/interface/screens/setting.py`
- [Audio precaching](https://github.com/pluvium27/heurams/blob/dev/src/heurams/interface/screens/precache.py): `src/heurams/interface/screens/precache.py`

### Memory content

- [Memory repositories](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/repolib/repo.py): `src/heurams/kernel/repolib/repo.py`
- [Memory records](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/particles/atom.py): `src/heurams/kernel/particles/atom.py`
- [Recall puzzles](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/puzzles/mcq.py): `src/heurams/kernel/puzzles/mcq.py`
- [Review state](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/particles/electron.py): `src/heurams/kernel/particles/electron.py`

### Review engine

- [Stage router](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/router.py): `src/heurams/kernel/reactor/router.py`
- [Review procession](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/procession.py): `src/heurams/kernel/reactor/procession.py`
- [Prompt expansion](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/expander.py): `src/heurams/kernel/reactor/expander.py`
- [Session states](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/reactor/states.py): `src/heurams/kernel/reactor/states.py`
- [Scheduling algorithms](https://github.com/pluvium27/heurams/blob/dev/src/heurams/kernel/algorithms/base.py): `src/heurams/kernel/algorithms/base.py`

### Supporting services

- [Runtime context](https://github.com/pluvium27/heurams/blob/dev/src/heurams/context.py): `src/heurams/context.py`
- [Configuration](https://github.com/pluvium27/heurams/blob/dev/src/heurams/services/config.py): `src/heurams/services/config.py`
- [Favorites](https://github.com/pluvium27/heurams/blob/dev/src/heurams/services/favorite_service.py): `src/heurams/services/favorite_service.py`
- [Text-to-speech service](https://github.com/pluvium27/heurams/blob/dev/src/heurams/services/tts_service.py): `src/heurams/services/tts_service.py`
- [TTS providers](https://github.com/pluvium27/heurams/blob/dev/src/heurams/providers/tts/edge_tts.py): `src/heurams/providers/tts/edge_tts.py`

### Other components

- **Learner**

## Connections

- Learner → CLI entry: runs (evidence: `README.md`)
- CLI entry → TUI app: launches (evidence: `src/heurams/__main__.py`)
- TUI app → Dashboard: opens (evidence: `src/heurams/interface/__init__.py`)
- Dashboard → Repository navigation: opens (evidence: `src/heurams/interface/screens/dashboard.py`)
- Dashboard → Session preparation: opens (evidence: `src/heurams/interface/screens/dashboard.py`)
- Repository navigation → Memory repositories: browses
- Session preparation → Stage router: starts session
- Review queue → Stage router: requests stage
- Stage router → Review procession: creates queues (evidence: `src/heurams/kernel/reactor/router.py`)
- Stage router → Session states: sets state (evidence: `src/heurams/kernel/reactor/router.py`)
- Review procession → Prompt expansion: calls (evidence: `src/heurams/kernel/reactor/procession.py`)
- Review procession → Session states: reads state (evidence: `src/heurams/kernel/reactor/procession.py`)
- Prompt expansion → Memory records: uses records (evidence: `src/heurams/kernel/reactor/expander.py`)
- Prompt expansion → Recall puzzles: creates puzzles (evidence: `src/heurams/kernel/reactor/expander.py`)
- Puzzle widgets → Recall puzzles: renders
- Stage router → Memory records: routes records (evidence: `src/heurams/kernel/reactor/router.py`)
- Memory records → Review state: contains state
- Review state → Scheduling algorithms: uses algorithms (evidence: `src/heurams/kernel/particles/electron.py`)
- Dashboard → Memory repositories: loads repositories (evidence: `src/heurams/interface/screens/dashboard.py`)
- Repository sync → Memory repositories: synchronizes
- Settings → Runtime context: reads context (evidence: `src/heurams/interface/screens/setting.py`)
- Runtime context → Configuration: initializes (evidence: `src/heurams/context.py`)
- Audio precaching → Memory repositories: reads content (evidence: `src/heurams/interface/screens/precache.py`)
- Audio precaching → Text-to-speech service: requests speech (evidence: `src/heurams/interface/screens/precache.py`)
- Text-to-speech service → TTS providers: selects provider (evidence: `src/heurams/services/tts_service.py`)
