> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wolffi.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> How Wolffish's brain-inspired architecture works

# The Core Idea

Wolffish maps the human brain's architecture onto a deterministic software pipeline. Each of the 15 runtime modules handles exactly one function, and they communicate via a typed event bus (corpus).

## The Brain Metaphor

The module names aren't random — each maps to a real brain region that performs an analogous function:

| Module         | Brain Region                | Function                                  |
| -------------- | --------------------------- | ----------------------------------------- |
| `thalamus`     | Sensory gateway             | Routes input to LLM providers             |
| `prefrontal`   | Executive function          | Assembles context for the LLM             |
| `ras`          | Reticular Activating System | Filters relevant content by attention     |
| `cortex`       | Cerebral cortex             | Fast retrieval index (SQLite FTS5)        |
| `hippocampus`  | Memory center               | Stores and retrieves conversation history |
| `cerebellum`   | Motor coordination          | Discovers and loads capabilities          |
| `wernicke`     | Language comprehension      | Parses LLM output and extracts tool calls |
| `broca`        | Language production         | Streams responses to the UI               |
| `amygdala`     | Threat detection            | Safety gate for dangerous operations      |
| `motor`        | Motor cortex                | Executes tasks with retry and logging     |
| `basalganglia` | Reward/learning             | Records outcomes for feedback             |
| `hypothalamus` | Homeostasis                 | Monitors system health                    |
| `brainstem`    | Autonomic functions         | File watching, cron jobs, compaction      |
| `corpus`       | Corpus callosum             | Event bus connecting all modules          |
| `insula`       | Self-awareness              | Status and performance introspection      |

## The Key Insight

The pipeline is deterministic — the same input follows the same path through the same gates every time. The LLM adds creativity and intelligence at exactly one point (the `thalamus.stream()` call). Everything else is predictable TypeScript code that reads and writes markdown files.

## Module Communication

All modules communicate via `corpus` (the event bus), never by importing each other directly. This keeps dependencies clean and makes the system inspectable — every event is logged to daily markdown files.

```
corpus.emit('message.received', { content: '...' })
corpus.emit('context.built', { tokens: 8000 })
corpus.emit('tool.called', { name: 'shell_exec', args: {...} })
corpus.emit('safety.blocked', { reason: '...' })
```

## Tech Stack

Wolffish is built on Electron 39, React 19, TypeScript 5.9, and Vite 7. The event bus uses `mitt` for typed events. Memory indexing uses `better-sqlite3` with FTS5. All LLM communication is pure `fetch()` — no SDKs.

<Card title="See the Full Pipeline" icon="diagram-project" href="/architecture/pipeline">
  Follow a message from input to response, step by step.
</Card>