# vasiniks/lobotomy architecture

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

- Interactive diagram: https://gitdiagram.com/vasiniks/lobotomy
- Repository: https://github.com/vasiniks/lobotomy

## Overview

lobotomy is a local model-inspection and intervention app. A user chats through the browser; the server streams a reply from the loaded model, records internal activations, and serves those recordings to visualizations and analysis tools. Users can inspect the 3D layer stack, individual layers and tokens, compare answers, scan or explain predictions, and apply reversible edits before asking again. The README documents both MLX and PyTorch runtimes; sampled code confirms the engine/backend boundary, while several feature-specific routes were not excerpted, so their internal links are omitted where unverified.

Main entry points: [`src/lobotomy/engine.py`](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/engine.py) (Chat engine), [`src/lobotomy/web/js/main.js`](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/main.js) (App routing), [`src/lobotomy/backends/base.py`](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/base.py) (Backend contract), [`src/lobotomy/web/js/components.js`](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/components.js) (Shared controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser interface"]
  node_boot["App routing<br/>[main.js]"]
  node_chatview["Chat view<br/>[chat.js]"]
  node_stack["3D layer stack<br/>[stack3d.js]"]
  node_layerview["Layer view<br/>[layer.js]"]
  node_tokenview["Token view<br/>[token.js]"]
  node_compareview["Compare view<br/>[compare.js]"]
  node_components["Shared controls<br/>[components.js]"]
  node_store["App state<br/>[store.js]"]
  node_api["API client<br/>[api.js]"]
end

subgraph group_service["Local API"]
  node_server["HTTP and streaming API<br/>[server.py]"]
end

subgraph group_runtime["Model runtime"]
  node_engine["Chat engine<br/>[engine.py]"]
  node_loader["GGUF loader<br/>[gguf_loader.py]"]
  node_tokenizer["Tokenizer<br/>[tokenizer.py]"]
  node_config["Model configuration<br/>[config.py]"]
  node_contract["Backend contract<br/>[base.py]"]
  node_mlx["MLX backend<br/>[backend.py]"]
  node_torch["PyTorch backend<br/>[backend.py]"]
  node_sampling["Text sampling<br/>[sampling.py]"]
end

subgraph group_inspection["Inspection and edits"]
  node_recording[("Activation recordings<br/>[base.py]")]
  node_analysis["Activation analysis<br/>[analysis.py]"]
  node_edits["Reversible edits<br/>[edits.py]"]
  node_presets["Edit presets<br/>[presets.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_boot
node_boot -->|"routes to"| node_chatview
node_boot -->|"routes to"| node_layerview
node_boot -->|"routes to"| node_tokenview
node_boot -->|"routes to"| node_compareview
node_chatview -->|"renders"| node_stack
node_chatview -->|"uses"| node_components
node_layerview -->|"uses"| node_components
node_tokenview -->|"uses"| node_components
node_compareview -->|"uses"| node_components
node_store -->|"requests"| node_api
node_boot -->|"loads state"| node_store
node_api -->|"HTTP requests"| node_server
node_server -->|"dispatches chat"| node_engine
node_engine -->|"opens weights"| node_loader
node_engine -->|"uses"| node_tokenizer
node_engine -->|"uses"| node_config
node_engine -->|"calls backend"| node_contract
node_contract -->|"implemented by"| node_mlx
node_contract -.->|"implemented by"| node_torch
node_engine -->|"samples replies"| node_sampling
node_contract -->|"produces"| node_recording
node_engine -->|"applies and undoes"| node_edits
node_edits -->|"maps to weight ops"| node_contract
node_server -->|"computes insights"| node_analysis
node_server -->|"lists presets"| node_presets
node_user -.->|"asks and edits"| node_engine
node_recording -.->|"visualized as activity"| node_stack
node_analysis -.->|"supports inspection"| node_layerview
node_presets -->|"shown as recipes"| node_components

click node_boot "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/main.js"
click node_chatview "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/chat.js"
click node_stack "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/stack3d.js"
click node_layerview "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/layer.js"
click node_tokenview "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/token.js"
click node_compareview "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/compare.js"
click node_components "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/components.js"
click node_store "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/store.js"
click node_api "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/api.js"
click node_server "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/server.py"
click node_engine "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/engine.py"
click node_loader "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/gguf_loader.py"
click node_tokenizer "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/tokenizer.py"
click node_config "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/config.py"
click node_contract "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/base.py"
click node_mlx "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/mlx/backend.py"
click node_torch "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/pytorch/backend.py"
click node_recording "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/base.py"
click node_analysis "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/analysis.py"
click node_edits "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/edits.py"
click node_sampling "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/sampling.py"
click node_presets "https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/presets.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_boot,node_chatview,node_stack,node_layerview,node_tokenview,node_compareview,node_components,node_store,node_api,node_user toneBlue
class node_server toneAmber
class node_engine,node_loader,node_tokenizer,node_config,node_contract,node_mlx,node_torch,node_sampling toneMint
class node_recording,node_analysis,node_edits,node_presets toneRose
```

## Components

### Browser interface

- [App routing](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/main.js): `src/lobotomy/web/js/main.js`
- [Chat view](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/chat.js): `src/lobotomy/web/js/views/chat.js`
- [3D layer stack](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/stack3d.js): `src/lobotomy/web/js/views/stack3d.js`
- [Layer view](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/layer.js): `src/lobotomy/web/js/views/layer.js`
- [Token view](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/token.js): `src/lobotomy/web/js/views/token.js`
- [Compare view](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/views/compare.js): `src/lobotomy/web/js/views/compare.js`
- [Shared controls](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/components.js): `src/lobotomy/web/js/components.js`
- [App state](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/store.js): `src/lobotomy/web/js/store.js`
- [API client](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/web/js/api.js): `src/lobotomy/web/js/api.js`

### Local API

- [HTTP and streaming API](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/server.py): `src/lobotomy/server.py`

### Model runtime

- [Chat engine](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/engine.py): `src/lobotomy/engine.py`
- [GGUF loader](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/gguf_loader.py): `src/lobotomy/gguf_loader.py`
- [Tokenizer](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/tokenizer.py): `src/lobotomy/tokenizer.py`
- [Model configuration](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/config.py): `src/lobotomy/config.py`
- [Backend contract](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/base.py): `src/lobotomy/backends/base.py`
- [MLX backend](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/mlx/backend.py): `src/lobotomy/backends/mlx/backend.py`
- [PyTorch backend](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/pytorch/backend.py): `src/lobotomy/backends/pytorch/backend.py`
- [Text sampling](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/sampling.py): `src/lobotomy/sampling.py`

### Inspection and edits

- [Activation recordings](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/backends/base.py): `src/lobotomy/backends/base.py`
- [Activation analysis](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/analysis.py): `src/lobotomy/analysis.py`
- [Reversible edits](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/edits.py): `src/lobotomy/edits.py`
- [Edit presets](https://github.com/vasiniks/lobotomy/blob/main/src/lobotomy/presets.py): `src/lobotomy/presets.py`

### Other components

- **User**

## Connections

- User → App routing: uses (evidence: `README.md`)
- App routing → Chat view: routes to (evidence: `src/lobotomy/web/js/main.js`)
- App routing → Layer view: routes to (evidence: `src/lobotomy/web/js/main.js`)
- App routing → Token view: routes to (evidence: `src/lobotomy/web/js/main.js`)
- App routing → Compare view: routes to (evidence: `src/lobotomy/web/js/main.js`)
- Chat view → 3D layer stack: renders (evidence: `src/lobotomy/web/js/views/chat.js`)
- Chat view → Shared controls: uses (evidence: `src/lobotomy/web/js/views/chat.js`)
- Layer view → Shared controls: uses (evidence: `src/lobotomy/web/js/views/layer.js`)
- Token view → Shared controls: uses (evidence: `src/lobotomy/web/js/views/token.js`)
- Compare view → Shared controls: uses (evidence: `src/lobotomy/web/js/views/compare.js`)
- App state → API client: requests (evidence: `src/lobotomy/web/js/store.js`)
- App routing → App state: loads state (evidence: `src/lobotomy/web/js/main.js`)
- API client → HTTP and streaming API: HTTP requests (evidence: `src/lobotomy/web/js/api.js`)
- HTTP and streaming API → Chat engine: dispatches chat (evidence: `src/lobotomy/server.py`)
- Chat engine → GGUF loader: opens weights (evidence: `src/lobotomy/engine.py`)
- Chat engine → Tokenizer: uses (evidence: `src/lobotomy/engine.py`)
- Chat engine → Model configuration: uses (evidence: `src/lobotomy/engine.py`)
- Chat engine → Backend contract: calls backend (evidence: `src/lobotomy/engine.py`)
- Backend contract → MLX backend: implemented by (evidence: `src/lobotomy/backends/mlx/backend.py`)
- Backend contract → PyTorch backend: implemented by (evidence: `README.md`)
- Chat engine → Text sampling: samples replies (evidence: `src/lobotomy/engine.py`)
- Backend contract → Activation recordings: produces (evidence: `src/lobotomy/backends/base.py`)
- Chat engine → Reversible edits: applies and undoes (evidence: `src/lobotomy/engine.py`)
- Reversible edits → Backend contract: maps to weight ops (evidence: `src/lobotomy/edits.py`)
- HTTP and streaming API → Activation analysis: computes insights (evidence: `src/lobotomy/server.py`)
- HTTP and streaming API → Edit presets: lists presets (evidence: `src/lobotomy/server.py`)
- User → Chat engine: asks and edits (evidence: `README.md`)
- Activation recordings → 3D layer stack: visualized as activity (evidence: `README.md`)
- Activation analysis → Layer view: supports inspection (evidence: `README.md`)
- Edit presets → Shared controls: shown as recipes (evidence: `src/lobotomy/web/js/components.js`)