# lks-ai/deeper architecture

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

- Interactive diagram: https://gitdiagram.com/lks-ai/deeper
- Repository: https://github.com/lks-ai/deeper

## Overview

##### Major Components
- Frontend (User Interface):
– Located in the “web” directory with HTML, JavaScript, and CSS (theme folders).
– Responsible for presenting the tree visualization, node editing, navigation (hash-based), and interactive UI features (code block enhancements, context toolbar, etc.).
– It connects to backend endpoints (via HTTP or WebSockets) for dynamic data and collaborative functionality.

- Backend Server & API Layer:
– Built primarily using Python (see serve.py, ws.py, and util.py).
– Handles HTTP requests from the frontend and manages WebSocket connections for real-time updates.
– Manages session state, authentication (as indicated by JWT and Supabase configs in the README), and routing to various back-end services.

- LLM Integration Component:
– Uses prompt files (in the “prompts” folder) to communicate with external OpenAI-compatible LLM endpoints (like OpenRouter).
– Must load and manage a variety of context-specific prompts (for coding, roleplay, multimedia, etc.) and dispatch API requests.
– Acts as a middleware that processes tree-of-thought reasoning, auto-revisions, and branch rework.

- Data Persistence / Storage:
– The “data” directory contains JSON files supporting example knowledge trees (e.g., Dune-Butlerian.json).
– The system includes “Save & Load” functionality for tree structures, either using local file storage or possibly a lightweight database.
– Configuration files like defaults.yaml and placeholder.env help set up environment variables and defaults.

- Configuration & Deployment Artifacts:
– Dockerfile and docker-compose.yaml indicate containerization support.
– The .env setup (example in the README) and requirements.txt show dependencies and environment configuration.

##### Relationships and Interactions
- The Frontend UI sends HTTP/WebSocket requests to the Backend Server for tasks like saving trees, navigating nodes, and requesting LLM-based operations.
- The Backend receives these requests, orchestrates prompt management (loading the appropriate .prowl files from the “prompts” directory), and makes API calls to external LLM endpoints.
- The LLM Integration module then gets responses and passes them back to the Backend, which in turn updates or revises the tree structures.
- Data persistence is managed locally, with the server reading/writing from the “data” directory to load or persist state.
- External configurations and deployments are handled through Docker and environment variable setups.

##### Architectural Patterns and Technologies
- Full-stack separation between frontend and backend is evident with a clear API layer and dedicated web client.
- Real-time capabilities are supported through WebSockets (ws.py) for collaborative updates.
- Modularity is implemented via separate prompt files for various domain-specific tasks, which improves maintainability and extensibility.
- Containerization via Docker ensures a consistent deployment environment.
- Use of JWT and integration hints (Supabase, Firebase) indicate planned extensible user authentication and authorization modules.

##### Elements
- Frontend (Web UI): including themed views and JavaScript modules.
- Backend API Server: handling HTTP routes and WebSocket communications.
- LLM Integration Module: interacting with external LLM endpoints.
- Data Storage: local file system (data/ folder) for JSON-based knowledge trees.
- Configuration/Deployment: Docker, environment configuration, and build files.
- Requests from the UI to the backend (HTTP/WebSocket).
- Outbound API calls from the backend to the LLM endpoints.
- Data flows to/from the persistence layer.
- Annotations that highlight architectural patterns such as modular design, separation of concerns, and local execution for enhanced privacy.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Client/Frontend Layer"
        FE["Frontend (Web UI)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Server & API"
        BE["Backend Server & API"]:::backend
    end

    %% LLM Integration Module
    subgraph "LLM Integration"
        LLM["LLM Integration Module"]:::llm
    end

    %% Data Storage
    subgraph "Data Storage"
        DS["Local Data Store"]:::storage
    end

    %% Deployment & Configuration Artifacts
    subgraph "Deployment & Configuration"
        DC1["Dockerfile"]:::config
        DC2["docker-compose.yaml"]:::config
        DC3["defaults.yaml"]:::config
        DC4["placeholder.env"]:::config
        DC5["requirements.txt"]:::config
    end

    %% Data Flow Connections
    FE -->|"HTTP/WebSocket"| BE
    BE -->|"API_calls"| LLM
    BE -->|"Read/Write_Tree_Data"| DS

    %% Deployment/Configuration (dashed arrows representing containerization and config)
    DC1 -.->|"Deploy/Config"| FE
    DC1 -.->|"Deploy/Config"| BE
    DC1 -.->|"Deploy/Config"| LLM

    %% Click Events for Component Mapping
    click FE "https://github.com/lks-ai/deeper/tree/main/web/"
    click BE "https://github.com/lks-ai/deeper/blob/main/serve.py"
    click BE "https://github.com/lks-ai/deeper/blob/main/ws.py"
    click BE "https://github.com/lks-ai/deeper/blob/main/util.py"
    click LLM "https://github.com/lks-ai/deeper/tree/main/prompts/"
    click DS "https://github.com/lks-ai/deeper/tree/main/data/"
    click DC1 "https://github.com/lks-ai/deeper/tree/main/Dockerfile"
    click DC2 "https://github.com/lks-ai/deeper/blob/main/docker-compose.yaml"
    click DC3 "https://github.com/lks-ai/deeper/blob/main/defaults.yaml"
    click DC4 "https://github.com/lks-ai/deeper/blob/main/placeholder.env"
    click DC5 "https://github.com/lks-ai/deeper/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef llm fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef storage fill:#ffff99,stroke:#000,stroke-width:2px;
    classDef config fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
