# crescentschaos/cressyai architecture

> Architecture diagram of the GitHub repository crescentschaos/cressyai, 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/cressyai
- Repository: https://github.com/crescentschaos/cressyai

## Overview

CressyAI is a local-first GGUF chat application with a browser UI, server-side conversation and model handling, and optional research, memory, knowledge-base, and agent capabilities. The main workflow is a user sending a chat request through the UI to the server, which selects a model and may orchestrate tools before streaming a reply. The graph preserves the documented feature branches; some links are supported only by the README or SOURCE INDEX, since much of the server and UI source was not excerpted.

Main entry points: [`server.py`](https://github.com/crescentschaos/cressyai/blob/main/server.py) (Chat server), [`toolbox.py`](https://github.com/crescentschaos/cressyai/blob/main/toolbox.py) (Tool orchestration), [`geo.py`](https://github.com/crescentschaos/cressyai/blob/main/geo.py) (Places and weather), [`websearch.py`](https://github.com/crescentschaos/cressyai/blob/main/websearch.py) (Web search)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Chat application"]
  node_ui["Browser UI"]
  node_server["Chat server<br/>[server.py]"]
  node_chats[("Chat history<br/>[server.py]")]
end

subgraph group_models["Models and agent"]
  node_modelmgr["Model manager<br/>[modelmgr.py]"]
  node_agent["Agent mode<br/>[agent.py]"]
  node_agenttools["Agent tools<br/>[agenttools.py]"]
  node_toolbox["Tool orchestration<br/>[toolbox.py]"]
  node_files["Project files<br/>[fstools.py]"]
end

subgraph group_knowledge["Memory and knowledge"]
  node_memory[("Long-term memory<br/>[memory.py]")]
  node_embeddings["Semantic embeddings<br/>[embed.py]"]
  node_knowledgebase[("Knowledge base<br/>[rag.py]")]
end

subgraph group_research["Research tools"]
  node_web["Web search<br/>[websearch.py]"]
  node_wikipedia["Wikipedia lookup<br/>[wikipedia.py]"]
  node_github["GitHub lookup<br/>[github.py]"]
end

subgraph group_places["Places and nature"]
  node_animal["Animal lookup<br/>[animal.py]"]
  node_inat["iNaturalist<br/>[inaturalist.py]"]
  node_geo["Places and weather<br/>[geo.py]"]
  node_geomath["Geospatial math<br/>[geomath.py]"]
  node_openmeteo["Open-Meteo<br/>[openmeteo.py]"]
  node_osm["OpenStreetMap<br/>[openstreetmap.py]"]
end

node_user(("User"))
node_searxng{{"SearXNG"}}
node_externalapis{{"External APIs"}}

node_user -->|"uses"| node_ui
node_ui -->|"sends requests"| node_server
node_server -->|"streams replies"| node_ui
node_server -->|"saves chats"| node_chats
node_server -->|"loads models"| node_modelmgr
node_server -->|"orchestrates tools"| node_toolbox
node_server -->|"runs agent"| node_agent
node_agent -->|"uses actions"| node_agenttools
node_agenttools -.->|"confines file access"| node_files
node_toolbox -.->|"offers file tools"| node_files
node_server -->|"uses memory"| node_memory
node_memory -->|"embeds for recall"| node_embeddings
node_memory -->|"shares retrieval"| node_knowledgebase
node_server -->|"queries documents"| node_knowledgebase
node_toolbox -.->|"searches web"| node_web
node_toolbox -.->|"looks up articles"| node_wikipedia
node_toolbox -.->|"looks up repositories"| node_github
node_toolbox -.->|"queries nature"| node_inat
node_toolbox -.->|"queries places"| node_geo
node_animal -->|"uses search"| node_web
node_animal -->|"uses species data"| node_inat
node_animal -->|"uses summaries"| node_wikipedia
node_github -->|"uses web access"| node_web
node_geo -->|"uses calculations"| node_geomath
node_geo -->|"fetches weather"| node_openmeteo
node_geo -->|"fetches places"| node_osm
node_openmeteo -->|"validates coordinates"| node_geomath
node_osm -->|"uses calculations"| node_geomath
node_web -.->|"searches through"| node_searxng
node_inat -.->|"queries API"| node_externalapis
node_openmeteo -.->|"fetches forecasts"| node_externalapis
node_osm -.->|"queries map data"| node_externalapis

click node_ui "https://github.com/crescentschaos/cressyai/tree/main/js"
click node_server "https://github.com/crescentschaos/cressyai/blob/main/server.py"
click node_chats "https://github.com/crescentschaos/cressyai/blob/main/server.py"
click node_modelmgr "https://github.com/crescentschaos/cressyai/blob/main/modelmgr.py"
click node_agent "https://github.com/crescentschaos/cressyai/blob/main/agent.py"
click node_agenttools "https://github.com/crescentschaos/cressyai/blob/main/agenttools.py"
click node_toolbox "https://github.com/crescentschaos/cressyai/blob/main/toolbox.py"
click node_files "https://github.com/crescentschaos/cressyai/blob/main/fstools.py"
click node_memory "https://github.com/crescentschaos/cressyai/blob/main/memory.py"
click node_embeddings "https://github.com/crescentschaos/cressyai/blob/main/embed.py"
click node_knowledgebase "https://github.com/crescentschaos/cressyai/blob/main/rag.py"
click node_web "https://github.com/crescentschaos/cressyai/blob/main/websearch.py"
click node_wikipedia "https://github.com/crescentschaos/cressyai/blob/main/wikipedia.py"
click node_github "https://github.com/crescentschaos/cressyai/blob/main/github.py"
click node_animal "https://github.com/crescentschaos/cressyai/blob/main/animal.py"
click node_inat "https://github.com/crescentschaos/cressyai/blob/main/inaturalist.py"
click node_geo "https://github.com/crescentschaos/cressyai/blob/main/geo.py"
click node_geomath "https://github.com/crescentschaos/cressyai/blob/main/geomath.py"
click node_openmeteo "https://github.com/crescentschaos/cressyai/blob/main/openmeteo.py"
click node_osm "https://github.com/crescentschaos/cressyai/blob/main/openstreetmap.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_ui,node_server,node_chats,node_user toneBlue
class node_modelmgr,node_agent,node_agenttools,node_toolbox,node_files toneAmber
class node_memory,node_embeddings,node_knowledgebase,node_externalapis toneMint
class node_web,node_wikipedia,node_github toneRose
class node_animal,node_inat,node_geo,node_geomath,node_openmeteo,node_osm,node_searxng toneIndigo
```

## Components

### Chat application

- [Browser UI](https://github.com/crescentschaos/cressyai/tree/main/js): `js`
- [Chat server](https://github.com/crescentschaos/cressyai/blob/main/server.py): `server.py`
- [Chat history](https://github.com/crescentschaos/cressyai/blob/main/server.py): `server.py`

### Models and agent

- [Model manager](https://github.com/crescentschaos/cressyai/blob/main/modelmgr.py): `modelmgr.py`
- [Agent mode](https://github.com/crescentschaos/cressyai/blob/main/agent.py): `agent.py`
- [Agent tools](https://github.com/crescentschaos/cressyai/blob/main/agenttools.py): `agenttools.py`
- [Tool orchestration](https://github.com/crescentschaos/cressyai/blob/main/toolbox.py): `toolbox.py`
- [Project files](https://github.com/crescentschaos/cressyai/blob/main/fstools.py): `fstools.py`

### Memory and knowledge

- [Long-term memory](https://github.com/crescentschaos/cressyai/blob/main/memory.py): `memory.py`
- [Semantic embeddings](https://github.com/crescentschaos/cressyai/blob/main/embed.py): `embed.py`
- [Knowledge base](https://github.com/crescentschaos/cressyai/blob/main/rag.py): `rag.py`

### Research tools

- [Web search](https://github.com/crescentschaos/cressyai/blob/main/websearch.py): `websearch.py`
- [Wikipedia lookup](https://github.com/crescentschaos/cressyai/blob/main/wikipedia.py): `wikipedia.py`
- [GitHub lookup](https://github.com/crescentschaos/cressyai/blob/main/github.py): `github.py`

### Places and nature

- [Animal lookup](https://github.com/crescentschaos/cressyai/blob/main/animal.py): `animal.py`
- [iNaturalist](https://github.com/crescentschaos/cressyai/blob/main/inaturalist.py): `inaturalist.py`
- [Places and weather](https://github.com/crescentschaos/cressyai/blob/main/geo.py): `geo.py`
- [Geospatial math](https://github.com/crescentschaos/cressyai/blob/main/geomath.py): `geomath.py`
- [Open-Meteo](https://github.com/crescentschaos/cressyai/blob/main/openmeteo.py): `openmeteo.py`
- [OpenStreetMap](https://github.com/crescentschaos/cressyai/blob/main/openstreetmap.py): `openstreetmap.py`

### Other components

- **User**
- **SearXNG**
- **External APIs**

## Connections

- User → Browser UI: uses
- Browser UI → Chat server: sends requests
- Chat server → Browser UI: streams replies
- Chat server → Chat history: saves chats (evidence: `server.py`)
- Chat server → Model manager: loads models (evidence: `server.py`)
- Chat server → Tool orchestration: orchestrates tools (evidence: `server.py`)
- Chat server → Agent mode: runs agent (evidence: `server.py`)
- Agent mode → Agent tools: uses actions (evidence: `agent.py`)
- Agent tools → Project files: confines file access
- Tool orchestration → Project files: offers file tools (evidence: `toolbox.py`)
- Chat server → Long-term memory: uses memory (evidence: `server.py`)
- Long-term memory → Semantic embeddings: embeds for recall (evidence: `memory.py`)
- Long-term memory → Knowledge base: shares retrieval (evidence: `memory.py`)
- Chat server → Knowledge base: queries documents (evidence: `server.py`)
- Tool orchestration → Web search: searches web
- Tool orchestration → Wikipedia lookup: looks up articles
- Tool orchestration → GitHub lookup: looks up repositories
- Tool orchestration → iNaturalist: queries nature
- Tool orchestration → Places and weather: queries places
- Animal lookup → Web search: uses search (evidence: `animal.py`)
- Animal lookup → iNaturalist: uses species data (evidence: `animal.py`)
- Animal lookup → Wikipedia lookup: uses summaries (evidence: `animal.py`)
- GitHub lookup → Web search: uses web access (evidence: `github.py`)
- Places and weather → Geospatial math: uses calculations (evidence: `geo.py`)
- Places and weather → Open-Meteo: fetches weather (evidence: `geo.py`)
- Places and weather → OpenStreetMap: fetches places (evidence: `geo.py`)
- Open-Meteo → Geospatial math: validates coordinates (evidence: `openmeteo.py`)
- OpenStreetMap → Geospatial math: uses calculations (evidence: `openstreetmap.py`)
- Web search → SearXNG: searches through
- iNaturalist → External APIs: queries API
- Open-Meteo → External APIs: fetches forecasts
- OpenStreetMap → External APIs: queries map data
