# crescentschaos/crumbleai architecture

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

- Interactive diagram: https://gitdiagram.com/crescentschaos/crumbleai
- Repository: https://github.com/crescentschaos/crumbleai

## Overview

Crumble is a local browser-based character-chat and roleplay app backed by a user-loaded GGUF model. The main workflow is a browser chat request handled by the HTTP server, which assembles prompts and coordinates generation, memory, personality, and roleplay before returning a reply. Separate branches cover group turn-taking, roleplay resolution, and guest sharing. The README documents additional UI and chat capabilities; where their implementation or wiring was not sampled, relationships are omitted rather than inferred.

Main entry points: [`crumble/server.py`](https://github.com/crescentschaos/crumbleai/blob/main/crumble/server.py) (HTTP API), [`crumble/llm.py`](https://github.com/crescentschaos/crumbleai/blob/main/crumble/llm.py) (Reply generation), [`crumble/rp/resolve.py`](https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/resolve.py) (Action resolution), [`crumble/personality/engine.py`](https://github.com/crescentschaos/crumbleai/blob/main/crumble/personality/engine.py) (Personality engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat interface"]
  node_browser["Chat UI<br/>[06-generate.js]"]
  node_web["Page assets<br/>[web.py]"]
end

subgraph group_runtime["Chat runtime"]
  node_server["HTTP API<br/>[server.py]"]
  node_prompt["Prompt assembly<br/>[prompt.py]"]
  node_llm["Reply generation<br/>[llm.py]"]
  node_model["GGUF model"]
  node_text["Reply cleanup<br/>[textutil.py]"]
end

subgraph group_character["Character systems"]
  node_personality["Personality engine<br/>[engine.py]"]
  node_profile["Trait profiling<br/>[profile.py]"]
  node_memory["Memory workflow<br/>[memory.py]"]
  node_recall["Memory retrieval<br/>[retrieve.py]"]
  node_learning["Memory learning<br/>[learn.py]"]
  node_memstore[("Memory store<br/>[store.py]")]
end

subgraph group_roleplay["Roleplay systems"]
  node_director["Group director<br/>[director.py]"]
  node_resolution["Action resolution<br/>[resolve.py]"]
  node_combat["Combat rules<br/>[combat.py]"]
  node_romance["Romance rules<br/>[romance.py]"]
  node_intimacy["Intimacy rules<br/>[intimacy.py]"]
  node_ooc["Author channel<br/>[ooc.py]"]
end

subgraph group_persistence["State and sharing"]
  node_storage[("Chat and character files<br/>[storage.py]")]
  node_sharing["Guest sharing<br/>[sharing.py]"]
end

node_user(("Host or guest"))

node_user -->|"sends messages"| node_browser
node_browser -.->|"requests replies"| node_server
node_server -->|"serves pages"| node_web
node_server -->|"dispatches generation"| node_llm
node_server -->|"coordinates memory"| node_memory
node_server -->|"dispatches turns"| node_director
node_server -->|"dispatches actions"| node_resolution
node_server -->|"routes OOC"| node_ooc
node_server -->|"reads and writes"| node_storage
node_server -->|"checks sharing"| node_sharing
node_llm -->|"builds context"| node_prompt
node_llm -->|"prepares character"| node_personality
node_llm -->|"cleans replies"| node_text
node_llm -.->|"generates with"| node_model
node_prompt -->|"adds character block"| node_personality
node_prompt -->|"adds recalled memories"| node_recall
node_personality -->|"derives profile"| node_profile
node_memory -->|"retrieves memories"| node_recall
node_memory -->|"learns from turns"| node_learning
node_recall -->|"ranks stored items"| node_memstore
node_learning -->|"updates items"| node_memstore
node_director -->|"uses character profile"| node_personality
node_resolution -->|"resolves combat"| node_combat
node_resolution -->|"resolves romance"| node_romance
node_resolution -->|"resolves intimacy"| node_intimacy

click node_browser "https://github.com/crescentschaos/crumbleai/blob/main/crumble/web/js/06-generate.js"
click node_web "https://github.com/crescentschaos/crumbleai/blob/main/crumble/web.py"
click node_server "https://github.com/crescentschaos/crumbleai/blob/main/crumble/server.py"
click node_prompt "https://github.com/crescentschaos/crumbleai/blob/main/crumble/prompt.py"
click node_llm "https://github.com/crescentschaos/crumbleai/blob/main/crumble/llm.py"
click node_text "https://github.com/crescentschaos/crumbleai/blob/main/crumble/textutil.py"
click node_personality "https://github.com/crescentschaos/crumbleai/blob/main/crumble/personality/engine.py"
click node_profile "https://github.com/crescentschaos/crumbleai/blob/main/crumble/personality/profile.py"
click node_memory "https://github.com/crescentschaos/crumbleai/blob/main/crumble/memory.py"
click node_recall "https://github.com/crescentschaos/crumbleai/blob/main/crumble/recall/retrieve.py"
click node_learning "https://github.com/crescentschaos/crumbleai/blob/main/crumble/recall/learn.py"
click node_memstore "https://github.com/crescentschaos/crumbleai/blob/main/crumble/recall/store.py"
click node_director "https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/director.py"
click node_resolution "https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/resolve.py"
click node_combat "https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/combat.py"
click node_romance "https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/romance.py"
click node_intimacy "https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/intimacy.py"
click node_ooc "https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/ooc.py"
click node_storage "https://github.com/crescentschaos/crumbleai/blob/main/crumble/storage.py"
click node_sharing "https://github.com/crescentschaos/crumbleai/blob/main/crumble/sharing.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_browser,node_web toneBlue
class node_server,node_prompt,node_llm,node_model,node_text toneAmber
class node_personality,node_profile,node_memory,node_recall,node_learning,node_memstore toneMint
class node_director,node_resolution,node_combat,node_romance,node_intimacy,node_ooc toneRose
class node_storage,node_sharing,node_user toneIndigo
```

## Components

### Chat interface

- [Chat UI](https://github.com/crescentschaos/crumbleai/blob/main/crumble/web/js/06-generate.js): `crumble/web/js/06-generate.js`
- [Page assets](https://github.com/crescentschaos/crumbleai/blob/main/crumble/web.py): `crumble/web.py`

### Chat runtime

- [HTTP API](https://github.com/crescentschaos/crumbleai/blob/main/crumble/server.py): `crumble/server.py`
- [Prompt assembly](https://github.com/crescentschaos/crumbleai/blob/main/crumble/prompt.py): `crumble/prompt.py`
- [Reply generation](https://github.com/crescentschaos/crumbleai/blob/main/crumble/llm.py): `crumble/llm.py`
- **GGUF model**
- [Reply cleanup](https://github.com/crescentschaos/crumbleai/blob/main/crumble/textutil.py): `crumble/textutil.py`

### Character systems

- [Personality engine](https://github.com/crescentschaos/crumbleai/blob/main/crumble/personality/engine.py): `crumble/personality/engine.py`
- [Trait profiling](https://github.com/crescentschaos/crumbleai/blob/main/crumble/personality/profile.py): `crumble/personality/profile.py`
- [Memory workflow](https://github.com/crescentschaos/crumbleai/blob/main/crumble/memory.py): `crumble/memory.py`
- [Memory retrieval](https://github.com/crescentschaos/crumbleai/blob/main/crumble/recall/retrieve.py): `crumble/recall/retrieve.py`
- [Memory learning](https://github.com/crescentschaos/crumbleai/blob/main/crumble/recall/learn.py): `crumble/recall/learn.py`
- [Memory store](https://github.com/crescentschaos/crumbleai/blob/main/crumble/recall/store.py): `crumble/recall/store.py`

### Roleplay systems

- [Group director](https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/director.py): `crumble/rp/director.py`
- [Action resolution](https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/resolve.py): `crumble/rp/resolve.py`
- [Combat rules](https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/combat.py): `crumble/rp/combat.py`
- [Romance rules](https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/romance.py): `crumble/rp/romance.py`
- [Intimacy rules](https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/intimacy.py): `crumble/rp/intimacy.py`
- [Author channel](https://github.com/crescentschaos/crumbleai/blob/main/crumble/rp/ooc.py): `crumble/rp/ooc.py`

### State and sharing

- [Chat and character files](https://github.com/crescentschaos/crumbleai/blob/main/crumble/storage.py): `crumble/storage.py`
- [Guest sharing](https://github.com/crescentschaos/crumbleai/blob/main/crumble/sharing.py): `crumble/sharing.py`

### Other components

- **Host or guest**

## Connections

- Host or guest → Chat UI: sends messages
- Chat UI → HTTP API: requests replies
- HTTP API → Page assets: serves pages (evidence: `crumble/server.py`)
- HTTP API → Reply generation: dispatches generation (evidence: `crumble/server.py`)
- HTTP API → Memory workflow: coordinates memory (evidence: `crumble/server.py`)
- HTTP API → Group director: dispatches turns (evidence: `crumble/server.py`)
- HTTP API → Action resolution: dispatches actions (evidence: `crumble/server.py`)
- HTTP API → Author channel: routes OOC (evidence: `crumble/server.py`)
- HTTP API → Chat and character files: reads and writes (evidence: `crumble/server.py`)
- HTTP API → Guest sharing: checks sharing (evidence: `crumble/server.py`)
- Reply generation → Prompt assembly: builds context (evidence: `crumble/llm.py`)
- Reply generation → Personality engine: prepares character (evidence: `crumble/llm.py`)
- Reply generation → Reply cleanup: cleans replies (evidence: `crumble/llm.py`)
- Reply generation → GGUF model: generates with
- Prompt assembly → Personality engine: adds character block (evidence: `crumble/prompt.py`)
- Prompt assembly → Memory retrieval: adds recalled memories (evidence: `crumble/prompt.py`)
- Personality engine → Trait profiling: derives profile (evidence: `crumble/personality/engine.py`)
- Memory workflow → Memory retrieval: retrieves memories (evidence: `crumble/memory.py`)
- Memory workflow → Memory learning: learns from turns (evidence: `crumble/memory.py`)
- Memory retrieval → Memory store: ranks stored items (evidence: `crumble/recall/retrieve.py`)
- Memory learning → Memory store: updates items (evidence: `crumble/recall/learn.py`)
- Group director → Personality engine: uses character profile (evidence: `crumble/rp/director.py`)
- Action resolution → Combat rules: resolves combat (evidence: `crumble/rp/resolve.py`)
- Action resolution → Romance rules: resolves romance (evidence: `crumble/rp/resolve.py`)
- Action resolution → Intimacy rules: resolves intimacy (evidence: `crumble/rp/resolve.py`)
