# khoantd/haiven architecture

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

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

## Overview

##### Project’s Purpose and Type
- The README explains that Haiven is an “accelerator” for piloting AI assistance in software delivery teams. It is not a production-scale product but a sandbox with a “one-container” deployment strategy.
- Its core purpose is to integrate with popular cloud-based LLM providers (Azure OpenAI, AWS Bedrock, Google Gemini) or even local providers like Ollama to help codify and deliver team-specific practices and knowledge (via “knowledge packs”).
- The project includes multiple components: a Python-based backend (with modules for API endpoints, configuration, LLM and embeddings handling, knowledge management), a modern React/Next.js UI, and a CLI for additional integrations and scripting.

##### File Structure
- The top-level of the project contains several “policy and configuration” files (.dockerignore, .pre-commit-config.yaml, etc.) and directories for GitHub workflows, documentation, and licensing.
- Key top-level folders are:
- app: Contains the main backend code (the core API, integration with language models, embedding management, configuration, and business logic).
- ui: A Next.js/React frontend with dedicated pages, components, assets, and tests.
- cli: A command-line interface that mirrors some of the application’s functionality through a separate Python package.
- docs: Architectural decision records and design documentation that further explain deployment choices and knowledge pack integration.
- devscripts: Additional tooling scripts for development and testing.
- The backend is modularized into sub-folders like “api” for endpoints, “knowledge” and “embeddings” for handling various AI and data-specific functionalities, “llms” for model integration, and “config” for constants and config handling.
- Environment-specific configuration files (app/.env.*.template) stress that deployment requires plugging in provider-specific credentials.

- UI Frontend (located in the “ui” folder):
- Built with React/Next.js (including pages, components, styles, and hooks).
- Communicates with the backend (over REST or SSE as indicated by the presence of files like _fetch_sse.js).
- Backend/API (located in the “app” folder):
- Main entry point in app/app.py and/or app/server.py.
- API endpoints exposed via the “api” folder.
- Orchestrates business logic, configuration (app/config.yaml), and service invocations.
- Integrates with “knowledge_manager”, “embeddings”, “llms”, “prompts”, etc.
- Contains in-memory operations and logging for persistence.
- External Providers and LLM Integrations:
- External AI providers (Azure, AWS, Google, Ollama) as distinct components.
- The integration details are set in app/config.yaml and via environment variables.
- Knowledge Pack:
- Mounted externally (via Docker volume as shown in the “docker run” examples) so that the backend can load and work with team-specific prompts and guidance data.
- CLI Component:
- Resides in the “cli” folder and encapsulates similar functionality to the web app but provides another way to interact with the services.
- Development Scripts:
- For completeness, include a “devscripts” component for tasks like dependency updates and testing.

##### Architectural Patterns and Design Principles
- The design embraces modularity and a separation of concerns:
- Frontend vs. Backend separation.
- Logical separation within the backend (APIs, LLM functions, embeddings, configuration, and logging).
- External dependencies (cloud APIs, local model services) are clearly separated via environment configurations.

##### Final Recommendations for the Principal Software Engineer
- Drill down into the backend components (e.g., API endpoints, knowledge management, LLM integrations) if necessary.
- Refer to the configuration files (.env templates, app/config.yaml) and documentation (docs/design.md, docs/knowledge_packs.md) to capture any nuances of the runtime environment and customizations.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Haiven Container (One-Container Deployment)"
        direction TB
        UI["UI/Frontend (Next.js)"]:::frontend
        Backend["Backend/API Server (Python)"]:::backend

        subgraph "Backend Modules"
            direction TB
            API["API Endpoints (app/api)"]:::api
            LLM["LLM Integrations & External Provider Config"]:::llm
            Embedding["Embeddings & Knowledge Management"]:::knowledge
        end

        CLI["CLI Component (Python)"]:::cli
        DevScripts["Development Scripts (devscripts)"]:::dev
    end

    KP["Knowledge Pack Storage (Mounted Volume)"]:::storage
    Ext["External LLM Providers (Azure, AWS, GCP, Ollama)"]:::external

    UI -->|"REST_API"| Backend
    CLI -->|"CLI_Request"| Backend
    Backend -->|"Handles"| API
    Backend -->|"Executes"| LLM
    Backend -->|"Manages"| Embedding
    Backend <-->|"Volume_Mount"| KP
    Backend -->|"Calls"| Ext

    click UI "https://github.com/khoantd/haiven/tree/main/ui"
    click UI "https://github.com/khoantd/haiven/tree/main/ui/src"
    click UI "https://github.com/khoantd/haiven/blob/main/ui/next.config.js"
    click UI "https://github.com/khoantd/haiven/blob/main/ui/package.json"

    click Backend "https://github.com/khoantd/haiven/blob/main/app/app.py"
    click Backend "https://github.com/khoantd/haiven/blob/main/app/server.py"

    click API "https://github.com/khoantd/haiven/blob/main/app/api/api_basics.py"
    click API "https://github.com/khoantd/haiven/blob/main/app/api/api_creative_matrix.py"

    click LLM "https://github.com/khoantd/haiven/blob/main/app/llms/aws_chat.py"
    click LLM "https://github.com/khoantd/haiven/blob/main/app/llms/chats.py"
    click LLM "https://github.com/khoantd/haiven/blob/main/app/config.yaml"

    click Embedding "https://github.com/khoantd/haiven/blob/main/app/embeddings/client.py"
    click Embedding "https://github.com/khoantd/haiven/blob/main/app/knowledge/pack.py"
    click Embedding "https://github.com/khoantd/haiven/blob/main/app/knowledge_manager.py"

    click CLI "https://github.com/khoantd/haiven/tree/main/cli/haiven_cli"
    click CLI "https://github.com/khoantd/haiven/blob/main/cli/main.py"

    click DevScripts "https://github.com/khoantd/haiven/blob/main/devscripts/main.py"

    click KP "https://github.com/khoantd/haiven/tree/main/app/tests/test_data/test_knowledge_pack"

    classDef frontend fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
    classDef backend fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef api fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef llm fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef knowledge fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;
    classDef cli fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef dev fill:#D6DBDF,stroke:#7F8C8D,stroke-width:2px;
    classDef storage fill:#F5EEF8,stroke:#AF7AC5,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#BB8FCE,stroke-width:2px;
```
