# simoneriggi92/breakthewall architecture

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

- Interactive diagram: https://gitdiagram.com/simoneriggi92/breakthewall
- Repository: https://github.com/simoneriggi92/breakthewall

## Overview

Break the Wall is a desktop app for turning text or Markdown into a source-grounded structure that readers can explore. The main loop is to provide a source, have a model generate and validate an exploration, then inspect its parts, links, and citations alongside the source. The README also documents disassemblies, prepared examples, local and ChatGPT providers, and Claude integrations. The graph combines documented capabilities with source-index relationships; unsampled UI and storage internals are represented conservatively.

Main entry points: [`src/desktop/generator.ts`](https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/generator.ts) (Generation coordinator), [`src/renderer/App.tsx`](https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/App.tsx) (App shell), [`src/core/disassembly-generation.ts`](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/disassembly-generation.ts) (Disassembly generation), [`src/mcp/server.ts`](https://github.com/simoneriggi92/breakthewall/blob/main/src/mcp/server.ts) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_input["Source and generation"]
  node_studio["Studio input<br/>[Studio.tsx]"]
  node_source["Source handling<br/>[source.ts]"]
  node_generator["Generation coordinator<br/>[generator.ts]"]
end

subgraph group_core["Structure and validation"]
  node_exploregen["Exploration generation"]
  node_exploration["Exploration model<br/>[exploration.ts]"]
  node_lesson["Lesson model<br/>[lesson.ts]"]
  node_disassemblygen["Disassembly generation"]
  node_disassembly["Disassembly model<br/>[disassembly.ts]"]
  node_layout["Disassembly layout<br/>[layout.ts]"]
  node_provider["Provider contracts<br/>[provider.ts]"]
end

subgraph group_experience["Desktop experience"]
  node_app["App shell<br/>[App.tsx]"]
  node_exploreview["Exploration view"]
  node_library["Exploration library<br/>[Library.tsx]"]
  node_desktop["Desktop runtime<br/>[main.ts]"]
  node_progress[("Progress storage<br/>[progress-store.ts]")]
end

subgraph group_integrations["Providers and assistants"]
  node_chatgpt["ChatGPT account<br/>[account.ts]"]
  node_local["Local runtimes<br/>[runtimes.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
  node_assistant["Claude assistant tools<br/>[assistant.ts]"]
end

node_reader(("Reader"))
node_claude(("Claude user"))

node_reader -->|"provides source"| node_studio
node_studio -->|"requests exploration"| node_generator
node_generator -->|"verifies selection"| node_source
node_generator -->|"generates structure"| node_exploregen
node_exploregen -->|"validates result"| node_exploration
node_exploregen -->|"uses lesson types"| node_lesson
node_generator -->|"uses provider API"| node_provider
node_app -->|"opens exploration"| node_exploreview
node_app -->|"loads library"| node_library
node_exploreview -->|"renders structure"| node_exploration
node_app -->|"uses desktop bridge"| node_desktop
node_app -->|"loads progress"| node_progress
node_generator -->|"generates disassembly"| node_disassemblygen
node_disassemblygen -->|"assembles and checks"| node_disassembly
node_disassemblygen -->|"computes layout"| node_layout
node_disassemblygen -->|"uses provider API"| node_provider
node_chatgpt -->|"implements provider"| node_provider
node_local -->|"implements provider"| node_provider
node_claude -->|"requests exploration"| node_mcp
node_mcp -->|"dispatches assistant tools"| node_assistant
node_mcp -->|"generates exploration"| node_exploregen
node_mcp -->|"handles disassembly"| node_disassembly

click node_studio "https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/Studio.tsx"
click node_source "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/source.ts"
click node_generator "https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/generator.ts"
click node_exploregen "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/exploration-generation.ts"
click node_exploration "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/exploration.ts"
click node_lesson "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/lesson.ts"
click node_disassemblygen "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/disassembly-generation.ts"
click node_disassembly "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/disassembly.ts"
click node_layout "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/layout.ts"
click node_provider "https://github.com/simoneriggi92/breakthewall/blob/main/src/core/provider.ts"
click node_app "https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/App.tsx"
click node_exploreview "https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/exploration/ExplorationView.tsx"
click node_library "https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/Library.tsx"
click node_desktop "https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/main.ts"
click node_progress "https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/progress-store.ts"
click node_chatgpt "https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/chatgpt/account.ts"
click node_local "https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/local/runtimes.ts"
click node_mcp "https://github.com/simoneriggi92/breakthewall/blob/main/src/mcp/server.ts"
click node_assistant "https://github.com/simoneriggi92/breakthewall/blob/main/src/mcp/assistant.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_studio,node_source,node_generator,node_claude toneBlue
class node_exploregen,node_exploration,node_lesson,node_disassemblygen,node_disassembly,node_layout,node_provider toneAmber
class node_app,node_exploreview,node_library,node_desktop,node_progress toneMint
class node_chatgpt,node_local,node_mcp,node_assistant toneRose
class node_reader toneIndigo
```

## Components

### Source and generation

- [Studio input](https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/Studio.tsx): `src/renderer/Studio.tsx`
- [Source handling](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/source.ts): `src/core/source.ts`
- [Generation coordinator](https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/generator.ts): `src/desktop/generator.ts`

### Structure and validation

- [Exploration generation](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/exploration-generation.ts): `src/core/exploration-generation.ts`
- [Exploration model](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/exploration.ts): `src/core/exploration.ts`
- [Lesson model](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/lesson.ts): `src/core/lesson.ts`
- [Disassembly generation](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/disassembly-generation.ts): `src/core/disassembly-generation.ts`
- [Disassembly model](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/disassembly.ts): `src/core/disassembly.ts`
- [Disassembly layout](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/layout.ts): `src/core/layout.ts`
- [Provider contracts](https://github.com/simoneriggi92/breakthewall/blob/main/src/core/provider.ts): `src/core/provider.ts`

### Desktop experience

- [App shell](https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/App.tsx): `src/renderer/App.tsx`
- [Exploration view](https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/exploration/ExplorationView.tsx): `src/renderer/exploration/ExplorationView.tsx`
- [Exploration library](https://github.com/simoneriggi92/breakthewall/blob/main/src/renderer/Library.tsx): `src/renderer/Library.tsx`
- [Desktop runtime](https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/main.ts): `src/desktop/main.ts`
- [Progress storage](https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/progress-store.ts): `src/desktop/progress-store.ts`

### Providers and assistants

- [ChatGPT account](https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/chatgpt/account.ts): `src/desktop/chatgpt/account.ts`
- [Local runtimes](https://github.com/simoneriggi92/breakthewall/blob/main/src/desktop/local/runtimes.ts): `src/desktop/local/runtimes.ts`
- [MCP server](https://github.com/simoneriggi92/breakthewall/blob/main/src/mcp/server.ts): `src/mcp/server.ts`
- [Claude assistant tools](https://github.com/simoneriggi92/breakthewall/blob/main/src/mcp/assistant.ts): `src/mcp/assistant.ts`

### Other components

- **Reader**
- **Claude user**

## Connections

- Reader → Studio input: provides source
- Studio input → Generation coordinator: requests exploration
- Generation coordinator → Source handling: verifies selection (evidence: `src/desktop/generator.ts`)
- Generation coordinator → Exploration generation: generates structure (evidence: `src/desktop/generator.ts`)
- Exploration generation → Exploration model: validates result (evidence: `src/core/exploration-generation.ts`)
- Exploration generation → Lesson model: uses lesson types (evidence: `src/core/exploration-generation.ts`)
- Generation coordinator → Provider contracts: uses provider API (evidence: `src/desktop/generator.ts`)
- App shell → Exploration view: opens exploration (evidence: `src/renderer/App.tsx`)
- App shell → Exploration library: loads library (evidence: `src/renderer/App.tsx`)
- Exploration view → Exploration model: renders structure (evidence: `src/renderer/exploration/ExplorationView.tsx`)
- App shell → Desktop runtime: uses desktop bridge (evidence: `src/renderer/App.tsx`)
- App shell → Progress storage: loads progress (evidence: `src/renderer/App.tsx`)
- Generation coordinator → Disassembly generation: generates disassembly (evidence: `src/desktop/generator.ts`)
- Disassembly generation → Disassembly model: assembles and checks (evidence: `src/core/disassembly-generation.ts`)
- Disassembly generation → Disassembly layout: computes layout (evidence: `src/core/disassembly-generation.ts`)
- Disassembly generation → Provider contracts: uses provider API (evidence: `src/core/disassembly-generation.ts`)
- ChatGPT account → Provider contracts: implements provider (evidence: `src/desktop/chatgpt/account.ts`)
- Local runtimes → Provider contracts: implements provider (evidence: `src/desktop/local/runtimes.ts`)
- Claude user → MCP server: requests exploration
- MCP server → Claude assistant tools: dispatches assistant tools (evidence: `src/mcp/server.ts`)
- MCP server → Exploration generation: generates exploration (evidence: `src/mcp/server.ts`)
- MCP server → Disassembly model: handles disassembly (evidence: `src/mcp/server.ts`)