# tw-haiven/haiven architecture

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

- Interactive diagram: https://gitdiagram.com/tw-haiven/haiven
- Repository: https://github.com/tw-haiven/haiven

## Overview

##### Main Components
- Backend API and Core Services (located in the “app” directory):
– This includes the central Python code (app/app.py, app/server.py, app/main.py) that handles incoming API requests.
– The components for LLM interactions are found in “app/llms”, while knowledge and embeddings management dwell in “app/knowledge” and “app/embeddings”.
– Other modules like configuration (app/config, app/config_service.py), prompts (app/prompts), and logging (app/logger.py) add to the backend’s functionality.
- Frontend UI (located in the “ui” directory):
– A Next.js/React application that communicates with the Python backend over HTTP.
– UI components, pages, and styles are housed here (e.g., in ui/src/pages, ui/src/app, and ui/src/styles).
- CLI Tool (found in the “cli” directory):
– A command-line interface for additional control of the system that replicates some functionality of the web app.
– It utilizes its own services and models (in cli/haiven_cli) and comes with its own tests.
- Knowledge Pack:
– This external, separately maintained data (or “knowledge pack”) is mounted as a volume during container runtime and contains prompts, guidelines, and related documentation.
- External LLM Providers:
– The system integrates with external AI model services—based on environment configuration via provided .env templates—with integration code spread across adaptive modules.

- The Backend API interacts with various core modules (such as API endpoints, embeddings logic, LLM client wrappers, and the knowledge manager) which should be depicted as internal subcomponents.
- CLI tool as a separate interface that also invokes backend services or interacts with the same set of modules.
- External integrations:

##### Architectural Patterns & Design Principles
- Single Container Deployment: The entire system (backend, frontend, CLI, and mounted knowledge pack) operates within one container.
- Modular Design: The project is organized into distinct modules (e.g., prompts, embeddings, knowledge management) to facilitate experimentation with AI, while customizability comes from swapping out knowledge packs.
- In-memory Operations & Configuration-Driven Behavior: Emphasize that persistence is limited mostly to logs and configuration is passed via environment variables and configuration files.
- Dependency & Integration Management: The use of a Dockerfile, multiple .env.template files, and configuration overrides (via config_override) reflects flexibility in how external AI models are integrated.

##### Relevant Technologies and Frameworks
- Backend: Python (with possibly Flask/FastAPI as the web server), configuration management (YAML, environment variable substitution) and modular Python scripts.
- Frontend: Next.js/React for user interfaces and Tailwind CSS for styling.
- CLI: Python-based CLI tool organized under cli/haiven_cli.
- Containerization: Docker for building and deploying a self-contained image.
- External Integrations: Azure, AWS, Google OpenAI endpoints, and Ollama for AI models.

– Between Frontend and Backend (showing HTTP REST or WebSocket communications).
– Between Backend and external services (including API calls to LLM providers and file system access for the knowledge pack).
– Between CLI and backend (if the CLI tool directly communicates with the backend).

##### Being Very Detailed
- Optionally, include smaller modules such as logging, configuration services, and the prompts factory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        FE["Frontend UI (Next.js/React)"]:::frontend
        CT["CLI Tool (haiven_cli)"]:::cli
    end

    subgraph "Application/API Layer"
        API["API Endpoints"]:::backend
        LLM["LLM Client"]:::backend
        KEM["Knowledge & Embeddings Manager"]:::backend
        PC["Prompts & Configuration"]:::backend
        LG["Logging"]:::backend
    end

    subgraph "External Systems"
        KPK["Knowledge Pack (mounted)"]:::external
        ELLM["External LLM Providers (Cloud&Local)"]:::external
    end

    FE -->|"HTTP"| API
    CT -->|"CLICommand"| API

    API -->|"callsLLM"| LLM
    API -->|"fetchesData"| KEM
    API -->|"retrievesInfo"| PC
    API -->|"logs"| LG

    LLM -->|"queries"| ELLM
    KEM -->|"loadsData"| KPK

    click FE "https://github.com/tw-haiven/haiven/tree/main/ui/src/pages"
    click FE "https://github.com/tw-haiven/haiven/tree/main/ui/src/app"
    click FE "https://github.com/tw-haiven/haiven/tree/main/ui/src/styles"
    click CT "https://github.com/tw-haiven/haiven/tree/main/cli/haiven_cli"
    click CT "https://github.com/tw-haiven/haiven/tree/main/cli/tests"
    click API "https://github.com/tw-haiven/haiven/blob/main/app/app.py"
    click API "https://github.com/tw-haiven/haiven/blob/main/app/server.py"
    click API "https://github.com/tw-haiven/haiven/blob/main/app/main.py"
    click LLM "https://github.com/tw-haiven/haiven/tree/main/app/llms"
    click KEM "https://github.com/tw-haiven/haiven/tree/main/app/knowledge"
    click KEM "https://github.com/tw-haiven/haiven/tree/main/app/embeddings"
    click PC "https://github.com/tw-haiven/haiven/tree/main/app/prompts"
    click PC "https://github.com/tw-haiven/haiven/tree/main/app/config"
    click LG "https://github.com/tw-haiven/haiven/blob/main/app/logger.py"
    click KPK "https://github.com/tw-haiven/haiven/tree/main/app/tests/test_data/test_knowledge_pack"
    click ELLM "https://github.com/tw-haiven/haiven/tree/main/app/llms"

    classDef frontend fill:#a2d2ff,stroke:#000,stroke-width:2px;
    classDef backend fill:#caffbf,stroke:#000,stroke-width:2px;
    classDef cli fill:#ffd6a5,stroke:#000,stroke-width:2px;
    classDef external fill:#ffadad,stroke:#000,stroke-width:2px;
```
