# nocoolusername/volatility-workbench architecture

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

- Interactive diagram: https://gitdiagram.com/nocoolusername/volatility-workbench
- Repository: https://github.com/nocoolusername/volatility-workbench

## Overview

Volatility Workbench is a local browser or native-desktop interface for memory-forensics cases; the separate volatility-mcp core performs forensic execution. Users register existing images, check readiness, run sequential report work and independent plugin batches, then revisit saved reports, evidence, citations, and coverage. The graph includes settings, plugin inspection, VolShell, AI assistance, and the optional Adventure game. Relationships for unsampled modules are included only where documented or listed in the source index; some internal wiring is therefore omitted.

Main entry points: [`src/volatility_workbench/app.py`](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/app.py) (Case controller), [`src/volatility_workbench/http.py`](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/http.py) (Local HTTP transport), [`src/volatility_workbench/settings.py`](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/settings.py) (Settings manager), [`src/volatility_workbench/storage.py`](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/storage.py) (Case and report storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_browser["Browser interface<br/>[app.js]"]
  node_http["Local HTTP transport<br/>[http.py]"]
  node_desktop["Native macOS shell<br/>[desktop.py]"]
end

subgraph group_cases["Cases and reports"]
  node_app["Case controller<br/>[app.py]"]
  node_storage[("Case and report storage<br/>[storage.py]")]
  node_report_plugins["Report plugin inventory<br/>[report_plugins.py]"]
  node_models["Case data models<br/>[models.py]"]
end

subgraph group_analysis["Analysis and assistance"]
  node_core["Volatility MCP core"]
  node_generation["Report generation<br/>[generation.py]"]
  node_providers["AI provider adapter<br/>[providers.py]"]
  node_codex["Codex connector<br/>[codex.py]"]
  node_coins["Report decorations<br/>[coins.py]"]
  node_volshell_ui["VolShell interface<br/>[volshell.js]"]
  node_volshell["VolShell process manager<br/>[volshell.py]"]
  node_volshell_agent["VolShell AI agent<br/>[volshell_agent.py]"]
  node_volshell_assist["AI command suggestions<br/>[volshell_assist.py]"]
  node_live_console["Live console transport<br/>[live_console.py]"]
end

subgraph group_admin["Configuration and extensions"]
  node_settings_ui["Settings interface<br/>[settings.js]"]
  node_settings["Settings manager<br/>[settings.py]"]
  node_symbols["Symbol import and checks<br/>[symbols.py]"]
  node_runtime["Analyzer maintenance"]
  node_themes["Theme catalog<br/>[themes.js]"]
  node_adventure["Adventure game<br/>[adventure.py]"]
  node_adventure_ui["Adventure interface<br/>[adventure.js]"]
end

node_user(("Workbench user"))

node_user -->|"uses"| node_browser
node_user -->|"opens"| node_desktop
node_browser -->|"requests"| node_http
node_desktop -->|"hosts"| node_http
node_http -->|"dispatches"| node_app
node_http -->|"routes settings"| node_settings
node_http -->|"serves status"| node_adventure
node_app -->|"persists cases"| node_storage
node_app -->|"uses models"| node_models
node_app -->|"generates reports"| node_generation
node_app -->|"uses providers"| node_providers
node_app -->|"manages sessions"| node_volshell
node_app -->|"uses agent"| node_volshell_agent
node_app -->|"packages inventory"| node_report_plugins
node_app -->|"uses decorations"| node_coins
node_app -->|"uses console"| node_live_console
node_app -->|"runs analysis"| node_core
node_storage -->|"packages saved runs"| node_report_plugins
node_storage -->|"loads coin data"| node_coins
node_providers -->|"connects Codex"| node_codex
node_volshell_agent -->|"uses sessions"| node_volshell
node_volshell_assist -->|"uses AI adapter"| node_providers
node_http -->|"serves console data"| node_volshell_ui
node_settings_ui -->|"submits settings"| node_http
node_settings -->|"imports symbols"| node_symbols
node_settings -->|"maintains analyzer"| node_runtime
node_settings -->|"stores preferences"| node_storage
node_user -->|"chooses theme"| node_themes
node_user -->|"plays"| node_adventure_ui
node_adventure_ui -->|"requests game"| node_http
node_http -->|"routes game"| node_adventure
node_browser -.->|"opens settings"| node_settings_ui
node_volshell_ui -.->|"requests suggestions"| node_volshell_assist

click node_browser "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/app.js"
click node_http "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/http.py"
click node_desktop "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/desktop.py"
click node_app "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/app.py"
click node_storage "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/storage.py"
click node_report_plugins "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/report_plugins.py"
click node_models "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/models.py"
click node_generation "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/generation.py"
click node_providers "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/providers.py"
click node_codex "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/codex.py"
click node_coins "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/coins.py"
click node_volshell_ui "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/volshell.js"
click node_volshell "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/volshell.py"
click node_volshell_agent "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/volshell_agent.py"
click node_volshell_assist "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/volshell_assist.py"
click node_live_console "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/live_console.py"
click node_settings_ui "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/settings.js"
click node_settings "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/settings.py"
click node_symbols "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/symbols.py"
click node_runtime "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/runtime_management.py"
click node_themes "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/themes.js"
click node_adventure "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/adventure.py"
click node_adventure_ui "https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/adventure.js"

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_browser,node_http,node_desktop,node_user toneBlue
class node_app,node_storage,node_report_plugins,node_models toneAmber
class node_core,node_generation,node_providers,node_codex,node_coins,node_volshell_ui,node_volshell,node_volshell_agent,node_volshell_assist,node_live_console toneMint
class node_settings_ui,node_settings,node_symbols,node_runtime,node_themes,node_adventure,node_adventure_ui toneRose
```

## Components

### User interfaces

- [Browser interface](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/app.js): `src/volatility_workbench/static/app.js`
- [Local HTTP transport](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/http.py): `src/volatility_workbench/http.py`
- [Native macOS shell](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/desktop.py): `src/volatility_workbench/desktop.py`

### Cases and reports

- [Case controller](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/app.py): `src/volatility_workbench/app.py`
- [Case and report storage](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/storage.py): `src/volatility_workbench/storage.py`
- [Report plugin inventory](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/report_plugins.py): `src/volatility_workbench/report_plugins.py`
- [Case data models](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/models.py): `src/volatility_workbench/models.py`

### Analysis and assistance

- **Volatility MCP core**
- [Report generation](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/generation.py): `src/volatility_workbench/generation.py`
- [AI provider adapter](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/providers.py): `src/volatility_workbench/providers.py`
- [Codex connector](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/codex.py): `src/volatility_workbench/codex.py`
- [Report decorations](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/coins.py): `src/volatility_workbench/coins.py`
- [VolShell interface](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/volshell.js): `src/volatility_workbench/static/volshell.js`
- [VolShell process manager](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/volshell.py): `src/volatility_workbench/volshell.py`
- [VolShell AI agent](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/volshell_agent.py): `src/volatility_workbench/volshell_agent.py`
- [AI command suggestions](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/volshell_assist.py): `src/volatility_workbench/volshell_assist.py`
- [Live console transport](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/live_console.py): `src/volatility_workbench/live_console.py`

### Configuration and extensions

- [Settings interface](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/settings.js): `src/volatility_workbench/static/settings.js`
- [Settings manager](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/settings.py): `src/volatility_workbench/settings.py`
- [Symbol import and checks](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/symbols.py): `src/volatility_workbench/symbols.py`
- [Analyzer maintenance](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/runtime_management.py): `src/volatility_workbench/runtime_management.py`
- [Theme catalog](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/themes.js): `src/volatility_workbench/static/themes.js`
- [Adventure game](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/adventure.py): `src/volatility_workbench/adventure.py`
- [Adventure interface](https://github.com/nocoolusername/volatility-workbench/blob/main/src/volatility_workbench/static/adventure.js): `src/volatility_workbench/static/adventure.js`

### Other components

- **Workbench user**

## Connections

- Workbench user → Browser interface: uses (evidence: `README.md`)
- Workbench user → Native macOS shell: opens (evidence: `README.md`)
- Browser interface → Local HTTP transport: requests (evidence: `README.md`)
- Native macOS shell → Local HTTP transport: hosts (evidence: `src/volatility_workbench/desktop.py`)
- Local HTTP transport → Case controller: dispatches (evidence: `src/volatility_workbench/http.py`)
- Local HTTP transport → Settings manager: routes settings (evidence: `src/volatility_workbench/http.py`)
- Local HTTP transport → Adventure game: serves status (evidence: `src/volatility_workbench/http.py`)
- Case controller → Case and report storage: persists cases (evidence: `src/volatility_workbench/app.py`)
- Case controller → Case data models: uses models (evidence: `src/volatility_workbench/app.py`)
- Case controller → Report generation: generates reports (evidence: `src/volatility_workbench/app.py`)
- Case controller → AI provider adapter: uses providers (evidence: `src/volatility_workbench/app.py`)
- Case controller → VolShell process manager: manages sessions (evidence: `src/volatility_workbench/app.py`)
- Case controller → VolShell AI agent: uses agent (evidence: `src/volatility_workbench/app.py`)
- Case controller → Report plugin inventory: packages inventory (evidence: `src/volatility_workbench/app.py`)
- Case controller → Report decorations: uses decorations (evidence: `src/volatility_workbench/app.py`)
- Case controller → Live console transport: uses console (evidence: `src/volatility_workbench/app.py`)
- Case controller → Volatility MCP core: runs analysis (evidence: `README.md`)
- Case and report storage → Report plugin inventory: packages saved runs (evidence: `src/volatility_workbench/storage.py`)
- Case and report storage → Report decorations: loads coin data (evidence: `src/volatility_workbench/coins.py`)
- AI provider adapter → Codex connector: connects Codex (evidence: `src/volatility_workbench/providers.py`)
- VolShell AI agent → VolShell process manager: uses sessions (evidence: `src/volatility_workbench/volshell_agent.py`)
- AI command suggestions → AI provider adapter: uses AI adapter (evidence: `src/volatility_workbench/volshell_assist.py`)
- Local HTTP transport → VolShell interface: serves console data (evidence: `README.md`)
- Settings interface → Local HTTP transport: submits settings (evidence: `README.md`)
- Settings manager → Symbol import and checks: imports symbols (evidence: `src/volatility_workbench/settings.py`)
- Settings manager → Analyzer maintenance: maintains analyzer (evidence: `src/volatility_workbench/settings.py`)
- Settings manager → Case and report storage: stores preferences (evidence: `src/volatility_workbench/settings.py`)
- Workbench user → Theme catalog: chooses theme (evidence: `README.md`)
- Workbench user → Adventure interface: plays (evidence: `README.md`)
- Adventure interface → Local HTTP transport: requests game (evidence: `README.md`)
- Local HTTP transport → Adventure game: routes game (evidence: `src/volatility_workbench/http.py`)
- Browser interface → Settings interface: opens settings
- VolShell interface → AI command suggestions: requests suggestions
