How lks-ai/deeper works
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.