# zalweny26/ts-cat architecture

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

- Interactive diagram: https://gitdiagram.com/zalweny26/ts-cat
- Repository: https://github.com/zalweny26/ts-cat

## Overview

##### Main Components

a) Core Components:
- Looking Glass (AI/LLM Integration Layer)
- CheshireCat (Main AI interaction handler)
- WhiteRabbit (Message processing)
- StrayCat (Auxiliary AI functions)
- AgentManager (AI agent management)

b) Plugin System:
- Mad Hatter (Plugin Management)
- Core Plugin Handler
- Forms Manager
- Hooks System
- Tools Manager

c) Memory System:
- Vector Memory
- Vector Memory Collections
- Database Integration (Qdrant)

d) API Layer:
- REST Endpoints
- WebSocket Server
- Rate Limiter

e) External Integrations:
- LLM Providers (OpenAI, Google, Ollama, HuggingFace)
- Embeddings Services
- Custom Services

##### Component Relationships

- Client Applications → API Layer (REST/WebSocket)
- API Layer → Looking Glass
- Looking Glass ↔ Mad Hatter (bidirectional for plugin interactions)
- Looking Glass ↔ Memory System
- Mad Hatter → Plugins
- Memory System ↔ Vector Database (Qdrant)
- Looking Glass ↔ External LLM Services

##### Specific Implementation Details

Technical annotations for:
- Docker container boundaries
- WebSocket streaming capabilities
- Cache layers for LLM and Embedder
- Rate limiting mechanism
- Plugin hook points
- Memory recall pathways

##### Data Flow Indicators

Specific flows for:
- User message processing
- Memory retrieval/storage
- Plugin execution
- LLM interactions
- Embedding processes

##### Architecture Patterns

Following patterns:
- Microservice architecture (Docker-based)
- Event-driven system (hooks and callbacks)
- Plugin-based extensibility
- Cache strategy
- API-first design

##### Technical Details to Note

- Built with TypeScript/Bun
- Docker-based deployment
- Qdrant vector database integration
- Multiple LLM provider support
- Real-time streaming capabilities
- Cache implementation
- Rate limiting

##### External service integration layer

This will create a comprehensive yet understandable representation of the system's architecture while maintaining the necessary level of detail for a principal software engineer to understand the complete system flow and component interactions.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        Client["Client Applications"]
    end

    subgraph "API Layer"
        REST["REST Endpoints"]:::api
        WS["WebSocket Server"]:::api
        RL["Rate Limiter"]:::api
    end

    subgraph "Looking Glass Layer"
        CC["CheshireCat"]:::core
        WR["WhiteRabbit"]:::core
        SC["StrayCat"]:::core
        AM["AgentManager"]:::core
    end

    subgraph "Mad Hatter Layer"
        MH["Mad Hatter"]:::plugin
        CPH["Core Plugin Handler"]:::plugin
        FM["Forms Manager"]:::plugin
        HS["Hooks System"]:::plugin
        TM["Tools Manager"]:::plugin
    end

    subgraph "Memory Layer"
        VM["Vector Memory"]:::memory
        VMC["Vector Memory Collections"]:::memory
        DB["Database Integration"]:::memory
    end

    subgraph "External Services"
        LLM["LLM Factory"]:::external
        EMB["Embeddings Factory"]:::external
        EXT["External LLM Services"]:::external
    end

    Client --> REST & WS
    REST & WS --> RL
    RL --> CC

    CC --> WR
    CC --> SC
    CC --> AM
    CC <--> MH
    CC <--> VM

    MH --> CPH
    MH --> FM
    MH --> HS
    MH --> TM

    VM <--> VMC
    VMC <--> DB

    CC <--> LLM
    CC <--> EMB
    LLM & EMB --> EXT

    %% Click Events
    click CC "https://github.com/zAlweNy26/ts-cat/blob/main/src/looking_glass/cheshire-cat.ts"
    click WR "https://github.com/zAlweNy26/ts-cat/blob/main/src/looking_glass/white-rabbit.ts"
    click SC "https://github.com/zAlweNy26/ts-cat/blob/main/src/looking_glass/stray-cat.ts"
    click AM "https://github.com/zAlweNy26/ts-cat/blob/main/src/looking_glass/agent-manager.ts"
    click MH "https://github.com/zAlweNy26/ts-cat/blob/main/src/mad_hatter/mad-hatter.ts"
    click FM "https://github.com/zAlweNy26/ts-cat/blob/main/src/mad_hatter/form.ts"
    click HS "https://github.com/zAlweNy26/ts-cat/blob/main/src/mad_hatter/hook.ts"
    click TM "https://github.com/zAlweNy26/ts-cat/blob/main/src/mad_hatter/tool.ts"
    click VM "https://github.com/zAlweNy26/ts-cat/blob/main/src/memory/vector-memory.ts"
    click VMC "https://github.com/zAlweNy26/ts-cat/blob/main/src/memory/vector-memory-collection.ts"
    click REST "https://github.com/zAlweNy26/ts-cat/tree/main/src/routes/"
    click RL "https://github.com/zAlweNy26/ts-cat/blob/main/src/looking_glass/callbacks.ts"
    click CPH "https://github.com/zAlweNy26/ts-cat/tree/main/src/mad_hatter/core_plugin/"
    click LLM "https://github.com/zAlweNy26/ts-cat/blob/main/src/factory/llm.ts"
    click EMB "https://github.com/zAlweNy26/ts-cat/blob/main/src/factory/embedder.ts"
    click DB "https://github.com/zAlweNy26/ts-cat/blob/main/src/database.ts"

    %% Styling
    classDef core fill:#2196F3,stroke:#1565C0,color:white
    classDef plugin fill:#4CAF50,stroke:#2E7D32,color:white
    classDef memory fill:#FFC107,stroke:#FFA000,color:black
    classDef api fill:#9C27B0,stroke:#7B1FA2,color:white
    classDef external fill:#757575,stroke:#616161,color:white

    %% Legend
    subgraph Legend
        L1["Core Components"]:::core
        L2["Plugin System"]:::plugin
        L3["Memory System"]:::memory
        L4["API Components"]:::api
        L5["External Services"]:::external
    end
```
