# campfirein/cipher architecture

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

- Interactive diagram: https://gitdiagram.com/campfirein/cipher
- Repository: https://github.com/campfirein/cipher

## Overview

##### Project type and purpose
- Cipher is a full-stack AI agent framework providing:
- A CLI (cipher)
- An HTTP/WebSocket API server (mode=api)
- An MCP server (mode=mcp)
- A React/Next.js Web UI (mode=ui)
- All built around a core “brain” library offering memory, embedding, LLM orchestration, tools, event bus, and persistence.
- Purpose: expose AI-powered memory and context capabilities for coding agents, integrate via Model Context Protocol (MCP) or direct API/CLI/UI.

##### File structure
- Top-level folders:
- src/app – application entry points: api (HTTP+WS), cli, mcp, ui, web
- src/core – core brain modules: embedding, llm, memory, reasoning, tools, systemPrompt, mcp, events, session, storage, vector_storage, knowledge_graph, logger, utils
- examples – sample configurations for various clients
- Config/deployment: Dockerfile, docker-compose.yml, .env.example, GitHub workflows
- Tests scattered under core and api/cli to cover functionality

##### README for additional insights
- Defines modes (api, mcp, ui) and key features: dual memory layers, MCP integration, tool registry
- Lists built-in tools, catalog of supported LLM providers and vector stores
- Shows UI screenshot and CLI usage

##### Elements
- Client→API/MCP server→core brain→external service
- Core brain→persistence→core brain→client

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        CLIInterface["CLI Interface"]:::clients
        WebUI["Web UI (Next.js)"]:::clients
        MCPClient["MCP-compatible Client"]:::clients
    end

    %% Transport Layer
    subgraph "Transport / API Layer"
        direction TB
        APIServer["HTTP / WebSocket API Server"]:::transport
        MCPServer["MCP Server"]:::transport
    end

    %% Core Brain Library
    subgraph "Core Brain Library" 
        direction TB
        EmbeddingManager["Embedding Manager"]:::core
        LLMManager["LLM Manager & Messaging"]:::core
        MemoryLayers["Memory Layers"]:::core
        Reasoning["Reasoning & Context Manager"]:::core
        SystemPrompt["System Prompt Modules"]:::core
        ToolsRegistry["Tools Registry & Execution"]:::core
        MemAgent["memAgent"]:::core
        EventBus["Event Bus & Webhooks"]:::core
        SessionManager["Session Management"]:::core
    end

    %% Persistence & Storage
    subgraph "Persistence & Storage"
        direction TB
        StorageManager["Storage Manager"]:::persistence
        VectorStorage["Vector Stores"]:::persistence
        KnowledgeGraph["Knowledge Graph"]:::persistence
    end

    %% Configuration & Entry
    subgraph "Config & Bootstrap"
        direction TB
        Config["Config & Env Loader"]:::core
        AppEntry["Application Entry Point"]:::transport
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProviders["LLM Provider Endpoints"]:::external
    end

    %% Relationships
    CLIInterface -->|uses REST/WebSocket| APIServer
    WebUI -->|uses REST/WebSocket| APIServer
    MCPClient -->|uses MCP protocol| MCPServer

    APIServer -->|routes to| EmbeddingManager
    APIServer -->|routes to| LLMManager
    APIServer -->|routes to| MemoryLayers
    APIServer -->|routes to| ToolsRegistry
    MCPServer -->|routes to| EmbeddingManager
    MCPServer -->|routes to| LLMManager
    MCPServer -->|routes to| MemoryLayers
    MCPServer -->|routes to| ToolsRegistry

    EmbeddingManager -->|stores/retrieves| VectorStorage
    MemoryLayers -->|persists| StorageManager
    SessionManager -->|persists| StorageManager
    ToolsRegistry -->|may update| KnowledgeGraph
    LLMManager -->|calls| LLMProviders
    ToolsRegistry -->|emits events| EventBus
    SessionManager -->|emits events| EventBus

    VectorStorage -->|provides context| EmbeddingManager
    StorageManager -->|loads session| SessionManager
    KnowledgeGraph -->|provides facts| MemoryLayers

    Config -->|configures| APIServer
    Config -->|configures| MCPServer
    Config -->|configures| EmbeddingManager
    AppEntry -->|bootstraps| APIServer
    AppEntry -->|bootstraps| MCPServer
    AppEntry -->|bootstraps| WebUI

    %% Click Events
    click CLIInterface "https://github.com/campfirein/cipher/blob/main/src/app/cli/cli.ts"
    click CLIInterface "https://github.com/campfirein/cipher/blob/main/src/app/cli/commands.ts"
    click CLIInterface "https://github.com/campfirein/cipher/blob/main/src/app/cli/parser.ts"
    click APIServer "https://github.com/campfirein/cipher/blob/main/src/app/api/server.ts"
    click APIServer "https://github.com/campfirein/cipher/tree/main/src/app/api/routes"
    click APIServer "https://github.com/campfirein/cipher/tree/main/src/app/api/middleware"
    click APIServer "https://github.com/campfirein/cipher/tree/main/src/app/api/websocket"
    click MCPServer "https://github.com/campfirein/cipher/blob/main/src/app/mcp/mcp_handler.ts"
    click MCPServer "https://github.com/campfirein/cipher/blob/main/src/app/mcp/mcp_sse_server.ts"
    click MCPServer "https://github.com/campfirein/cipher/blob/main/src/app/mcp/mcp_streamable_http_server.ts"
    click WebUI "https://github.com/campfirein/cipher/blob/main/src/app/ui/next.config.ts"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/public"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/src/app"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/src/components"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/src/hooks"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/src/contexts"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/src/stores"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/src/types"
    click WebUI "https://github.com/campfirein/cipher/tree/main/src/app/ui/src/lib"
    click EmbeddingManager "https://github.com/campfirein/cipher/blob/main/src/core/brain/embedding/manager.ts"
    click LLMManager "https://github.com/campfirein/cipher/tree/main/src/core/brain/llm/services"
    click LLMManager "https://github.com/campfirein/cipher/tree/main/src/core/brain/llm/messages"
    click LLMManager "https://github.com/campfirein/cipher/tree/main/src/core/brain/llm/compression"
    click LLMManager "https://github.com/campfirein/cipher/tree/main/src/core/brain/llm/tokenizer"
    click MemoryLayers "https://github.com/campfirein/cipher/tree/main/src/core/brain/memory"
    click Reasoning "https://github.com/campfirein/cipher/tree/main/src/core/brain/reasoning"
    click SystemPrompt "https://github.com/campfirein/cipher/tree/main/src/core/brain/systemPrompt"
    click ToolsRegistry "https://github.com/campfirein/cipher/blob/main/src/core/brain/tools/registry.ts"
    click ToolsRegistry "https://github.com/campfirein/cipher/blob/main/src/core/brain/tools/manager.ts"
    click ToolsRegistry "https://github.com/campfirein/cipher/tree/main/src/core/brain/tools/definitions"
    click MemAgent "https://github.com/campfirein/cipher/tree/main/src/core/brain/memAgent"
    click EventBus "https://github.com/campfirein/cipher/blob/main/src/core/events/event-manager.ts"
    click EventBus "https://github.com/campfirein/cipher/blob/main/src/core/events/event-types.ts"
    click EventBus "https://github.com/campfirein/cipher/blob/main/src/core/events/service-event-bus.ts"
    click EventBus "https://github.com/campfirein/cipher/blob/main/src/core/events/session-event-bus.ts"
    click EventBus "https://github.com/campfirein/cipher/blob/main/src/core/events/webhooks.ts"
    click SessionManager "https://github.com/campfirein/cipher/blob/main/src/core/session/session-manager.ts"
    click StorageManager "https://github.com/campfirein/cipher/blob/main/src/core/storage/manager.ts"
    click StorageManager "https://github.com/campfirein/cipher/tree/main/src/core/storage/backend"
    click VectorStorage "https://github.com/campfirein/cipher/blob/main/src/core/vector_storage/manager.ts"
    click VectorStorage "https://github.com/campfirein/cipher/tree/main/src/core/vector_storage/backend"
    click KnowledgeGraph "https://github.com/campfirein/cipher/blob/main/src/core/knowledge_graph/manager.ts"
    click KnowledgeGraph "https://github.com/campfirein/cipher/tree/main/src/core/knowledge_graph/backend"
    click Config "https://github.com/campfirein/cipher/tree/main/src/core/config"
    click Config "https://github.com/campfirein/cipher/blob/main/src/core/env.ts"
    click AppEntry "https://github.com/campfirein/cipher/blob/main/src/app/index.ts"
    click AppEntry "https://github.com/campfirein/cipher/blob/main/src/app/web/web-server.ts"

    %% Styles
    classDef clients fill:#ffe4e1,stroke:#d2691e,stroke-width:1px
    classDef transport fill:#e0ffff,stroke:#20b2aa,stroke-width:1px
    classDef core fill:#f0fff0,stroke:#32cd32,stroke-width:1px
    classDef persistence fill:#fffacd,stroke:#ffa500,stroke-width:1px
    classDef external fill:#ffe4b5,stroke:#cd5c5c,stroke-width:1px
```
