# g9000/animaos architecture

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

- Interactive diagram: https://gitdiagram.com/g9000/animaos
- Repository: https://github.com/g9000/animaos

## Overview

AnimaOS is a desktop-centered personal AI system: a user interacts through the desktop, which exposes conversation and persistent personal-data features backed by a server and local runtime components. The documented conversation model uses tool calls for internal thought and response, with local or hosted inference providers. The graph emphasizes documented capabilities and sampled wiring; some desktop-to-server and server-to-runtime relationships are conventional but unsampled, so those links are marked unverified.

Main entry points: [`apps/server/src/anima_server/main.py`](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/main.py) (HTTP server), [`apps/desktop/src/App.tsx`](https://github.com/g9000/animaos/blob/main/apps/desktop/src/App.tsx) (Desktop app), [`packages/api-client/src/client.ts`](https://github.com/g9000/animaos/blob/main/packages/api-client/src/client.ts) (API client), [`apps/server/src/anima_server/api/routes/chat.py`](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/api/routes/chat.py) (Chat API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Desktop experience"]
  node_desktop["Desktop app<br/>[App.tsx]"]
  node_chat["Chat interface<br/>[Chat.tsx]"]
  node_personal_data["Personal data views<br/>[Memory.tsx]"]
  node_database_ui["Database browser<br/>[Database.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_server["Application server"]
  node_server_app["HTTP server<br/>[main.py]"]
  node_chat_route["Chat API<br/>[chat.py]"]
  node_consciousness_route["Consciousness API<br/>[consciousness.py]"]
  node_knowledge_route["Knowledge API<br/>[knowledge.py]"]
  node_runtime_models[("Runtime state<br/>[runtime.py]")]
end

subgraph group_mind["Memory and cognition"]
  node_thread_manager["Thread lifecycle<br/>[thread_manager.py]"]
  node_retrieval["Memory retrieval"]
  node_corefs_authority["Content authority"]
  node_core_engine["Memory engine<br/>[engine.rs]"]
  node_path_engine["Persistent path engine<br/>[path_engine.rs]"]
  node_knowledge_cards["Knowledge cards<br/>[cards.rs]"]
  node_knowledge_graph["Knowledge graph<br/>[graph.rs]"]
end

subgraph group_integrations["Runtime integrations"]
  node_animus["Animus terminal<br/>[main.rs]"]
  node_animus_app["Terminal session<br/>[app.rs]"]
  node_mod_server["Mod server<br/>[server.ts]"]
  node_mod_management["Mod management<br/>[router.ts]"]
  node_mod_registry["Mod registry<br/>[registry.ts]"]
end

node_user(("User"))
node_inference{{"Model provider"}}
node_database[("Database")]

node_user -->|"uses"| node_desktop
node_desktop -->|"routes to"| node_chat
node_desktop -->|"routes to"| node_personal_data
node_desktop -->|"routes to"| node_database_ui
node_chat -.->|"requests"| node_api_client
node_personal_data -.->|"requests"| node_api_client
node_database_ui -->|"requests"| node_api_client
node_api_client -.->|"calls"| node_server_app
node_server_app -->|"mounts"| node_chat_route
node_server_app -->|"mounts"| node_consciousness_route
node_server_app -->|"mounts"| node_knowledge_route
node_chat_route -.->|"manages threads"| node_thread_manager
node_thread_manager -->|"reads and writes"| node_runtime_models
node_thread_manager -->|"uses"| node_corefs_authority
node_retrieval -.->|"retrieves"| node_knowledge_cards
node_core_engine -->|"serializes"| node_knowledge_cards
node_core_engine -->|"serializes"| node_knowledge_graph
node_path_engine -.->|"persists"| node_core_engine
node_server_app -.->|"initializes storage"| node_database
node_user -->|"uses"| node_animus
node_animus -->|"starts session"| node_animus_app
node_animus_app -.->|"connects"| node_server_app
node_mod_server -->|"loads modules"| node_mod_registry
node_mod_server -->|"mounts routes"| node_mod_management
node_mod_management -->|"installs and controls"| node_mod_registry
node_chat_route -.->|"tool-call loop"| node_inference

click node_desktop "https://github.com/g9000/animaos/blob/main/apps/desktop/src/App.tsx"
click node_chat "https://github.com/g9000/animaos/blob/main/apps/desktop/src/pages/chat/Chat.tsx"
click node_personal_data "https://github.com/g9000/animaos/blob/main/apps/desktop/src/pages/memory/Memory.tsx"
click node_database_ui "https://github.com/g9000/animaos/blob/main/apps/desktop/src/pages/Database.tsx"
click node_api_client "https://github.com/g9000/animaos/blob/main/packages/api-client/src/client.ts"
click node_server_app "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/main.py"
click node_chat_route "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/api/routes/chat.py"
click node_consciousness_route "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/api/routes/consciousness.py"
click node_knowledge_route "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/api/routes/knowledge.py"
click node_runtime_models "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/models/runtime.py"
click node_thread_manager "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/services/agent/thread_manager.py"
click node_retrieval "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/services/memory/retrieval_router.py"
click node_corefs_authority "https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/services/corefs/content_authority.py"
click node_core_engine "https://github.com/g9000/animaos/blob/main/packages/anima-core/src/engine.rs"
click node_path_engine "https://github.com/g9000/animaos/blob/main/packages/anima-core/src/path_engine.rs"
click node_knowledge_cards "https://github.com/g9000/animaos/blob/main/packages/anima-core/src/cards.rs"
click node_knowledge_graph "https://github.com/g9000/animaos/blob/main/packages/anima-core/src/graph.rs"
click node_animus "https://github.com/g9000/animaos/blob/main/apps/animus/src/main.rs"
click node_animus_app "https://github.com/g9000/animaos/blob/main/apps/animus/src/app.rs"
click node_mod_server "https://github.com/g9000/animaos/blob/main/apps/anima-mod/src/server.ts"
click node_mod_management "https://github.com/g9000/animaos/blob/main/apps/anima-mod/src/management/router.ts"
click node_mod_registry "https://github.com/g9000/animaos/blob/main/apps/anima-mod/src/core/registry.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_desktop,node_chat,node_personal_data,node_database_ui,node_api_client,node_user toneBlue
class node_server_app,node_chat_route,node_consciousness_route,node_knowledge_route,node_runtime_models,node_database toneAmber
class node_thread_manager,node_retrieval,node_corefs_authority,node_core_engine,node_path_engine,node_knowledge_cards,node_knowledge_graph toneMint
class node_animus,node_animus_app,node_mod_server,node_mod_management,node_mod_registry toneRose
class node_inference toneIndigo
```

## Components

### Desktop experience

- [Desktop app](https://github.com/g9000/animaos/blob/main/apps/desktop/src/App.tsx): `apps/desktop/src/App.tsx`
- [Chat interface](https://github.com/g9000/animaos/blob/main/apps/desktop/src/pages/chat/Chat.tsx): `apps/desktop/src/pages/chat/Chat.tsx`
- [Personal data views](https://github.com/g9000/animaos/blob/main/apps/desktop/src/pages/memory/Memory.tsx): `apps/desktop/src/pages/memory/Memory.tsx`
- [Database browser](https://github.com/g9000/animaos/blob/main/apps/desktop/src/pages/Database.tsx): `apps/desktop/src/pages/Database.tsx`
- [API client](https://github.com/g9000/animaos/blob/main/packages/api-client/src/client.ts): `packages/api-client/src/client.ts`

### Application server

- [HTTP server](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/main.py): `apps/server/src/anima_server/main.py`
- [Chat API](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/api/routes/chat.py): `apps/server/src/anima_server/api/routes/chat.py`
- [Consciousness API](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/api/routes/consciousness.py): `apps/server/src/anima_server/api/routes/consciousness.py`
- [Knowledge API](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/api/routes/knowledge.py): `apps/server/src/anima_server/api/routes/knowledge.py`
- [Runtime state](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/models/runtime.py): `apps/server/src/anima_server/models/runtime.py`

### Memory and cognition

- [Thread lifecycle](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/services/agent/thread_manager.py): `apps/server/src/anima_server/services/agent/thread_manager.py`
- [Memory retrieval](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/services/memory/retrieval_router.py): `apps/server/src/anima_server/services/memory/retrieval_router.py`
- [Content authority](https://github.com/g9000/animaos/blob/main/apps/server/src/anima_server/services/corefs/content_authority.py): `apps/server/src/anima_server/services/corefs/content_authority.py`
- [Memory engine](https://github.com/g9000/animaos/blob/main/packages/anima-core/src/engine.rs): `packages/anima-core/src/engine.rs`
- [Persistent path engine](https://github.com/g9000/animaos/blob/main/packages/anima-core/src/path_engine.rs): `packages/anima-core/src/path_engine.rs`
- [Knowledge cards](https://github.com/g9000/animaos/blob/main/packages/anima-core/src/cards.rs): `packages/anima-core/src/cards.rs`
- [Knowledge graph](https://github.com/g9000/animaos/blob/main/packages/anima-core/src/graph.rs): `packages/anima-core/src/graph.rs`

### Runtime integrations

- [Animus terminal](https://github.com/g9000/animaos/blob/main/apps/animus/src/main.rs): `apps/animus/src/main.rs`
- [Terminal session](https://github.com/g9000/animaos/blob/main/apps/animus/src/app.rs): `apps/animus/src/app.rs`
- [Mod server](https://github.com/g9000/animaos/blob/main/apps/anima-mod/src/server.ts): `apps/anima-mod/src/server.ts`
- [Mod management](https://github.com/g9000/animaos/blob/main/apps/anima-mod/src/management/router.ts): `apps/anima-mod/src/management/router.ts`
- [Mod registry](https://github.com/g9000/animaos/blob/main/apps/anima-mod/src/core/registry.ts): `apps/anima-mod/src/core/registry.ts`

### Other components

- **User**
- **Model provider**
- **Database**

## Connections

- User → Desktop app: uses (evidence: `apps/desktop/src/App.tsx`)
- Desktop app → Chat interface: routes to (evidence: `apps/desktop/src/App.tsx`)
- Desktop app → Personal data views: routes to (evidence: `apps/desktop/src/App.tsx`)
- Desktop app → Database browser: routes to (evidence: `apps/desktop/src/App.tsx`)
- Chat interface → API client: requests
- Personal data views → API client: requests
- Database browser → API client: requests (evidence: `apps/desktop/src/pages/Database.tsx`)
- API client → HTTP server: calls
- HTTP server → Chat API: mounts (evidence: `apps/server/src/anima_server/main.py`)
- HTTP server → Consciousness API: mounts (evidence: `apps/server/src/anima_server/main.py`)
- HTTP server → Knowledge API: mounts (evidence: `apps/server/src/anima_server/main.py`)
- Chat API → Thread lifecycle: manages threads
- Thread lifecycle → Runtime state: reads and writes (evidence: `apps/server/src/anima_server/services/agent/thread_manager.py`)
- Thread lifecycle → Content authority: uses (evidence: `apps/server/src/anima_server/services/agent/thread_manager.py`)
- Memory retrieval → Knowledge cards: retrieves
- Memory engine → Knowledge cards: serializes (evidence: `packages/anima-core/src/engine.rs`)
- Memory engine → Knowledge graph: serializes (evidence: `packages/anima-core/src/engine.rs`)
- Persistent path engine → Memory engine: persists (evidence: `packages/anima-core/src/path_engine.rs`)
- HTTP server → Database: initializes storage
- User → Animus terminal: uses (evidence: `apps/animus/src/main.rs`)
- Animus terminal → Terminal session: starts session (evidence: `apps/animus/src/main.rs`)
- Terminal session → HTTP server: connects
- Mod server → Mod registry: loads modules (evidence: `apps/anima-mod/src/server.ts`)
- Mod server → Mod management: mounts routes (evidence: `apps/anima-mod/src/server.ts`)
- Mod management → Mod registry: installs and controls (evidence: `apps/anima-mod/src/server.ts`)
- Chat API → Model provider: tool-call loop
