# hadryan/maxkb architecture

> Architecture diagram of the GitHub repository hadryan/maxkb, 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/hadryan/maxkb
- Repository: https://github.com/hadryan/maxkb

## Overview

##### Main Components
- Frontend Interface: The “ui” directory shows a Vue.js application with views, components, routing, and state management. Represent it as the client layer that interacts (via HTTP/HTTPS API calls) with the backend.
- Backend Services: The “apps” directory is organized as multiple Django apps. Key ones include:
– “application”: Contains chat pipeline management (with multiple steps, such as “chat_step”, “generate_human_message_step”, etc.) and flow orchestration logic.
– “dataset”: Handles document ingestion, parsing, and dataset management.
– “embedding”: Manages text embedding and vector search (leveraging pgvector).
– “function_lib”: Contains additional AI function libraries.
– “setting”: Manages configuration for system settings and model provider integrations.
– “users” and “smartdoc”: Cover authentication/user management and additional document-based functionality.
- Workflow Engine / Chat Pipeline: Notice the detailed structure within “apps/application/chat_pipeline” and “apps/application/flow”, as well as multiple “step_node” directories; these represent the orchestration and execution of different AI/LLM steps.
- Model Providers & LLM Integrations: Under “apps/setting/models_provider”, numerous implementations for different model providers (e.g., OpenAI, Anthropic, Azure, etc.) show that MaxKB supports model-agnostic integration.
- Common Services: Directories like “apps/common” cover cross-cutting services (authentication, caching, logging, event handling, middleware, locks, and SQL queries). They are central to system reliability and performance.
- Infrastructure/Deployment: Supplementary files such as Dockerfiles (in “installer”), GitHub workflows, and CI/CD scripts indicate containerized deployment and automated build/deployment processes.

##### Relationships and Interactions
- Chat pipeline and flow engine as specialized subcomponents that orchestrate the conversation logic (including steps like generating human messages, resetting problems, and search dataset steps) via well-defined interfaces.
- If applicable, include a “Task/Job” component (visible in directories like “apps/common/task”, “apps/ops/celery”) to show asynchronous processing, scheduling, and background jobs.

##### Architectural Patterns & Design Principles
- Modular design with each Django “app” encapsulating a bounded context (e.g., dataset management, user management, embedding).
- Workflow orchestration pattern used in the “flow” directories. This demonstrates loosely coupled components following the command or pipeline pattern.
- Use of dependency injection and DRY principles in common modules, middleware, and handle/encoder/util packages.
- Containerization and automated CI/CD pipelines that ensure reproducible deployments.

##### Detailed Elements
- Modules/Clusters: Group related Django apps (e.g., all application-related components under one cluster, dataset/embedding under another).
- Additional Elements: Show deployment artifacts like Docker and installer setups lightly on the side to present the containerized deployment workflow.

- At the top level, separate “Frontend” from “Backend”.
- Under “Backend”, have clusters/blocks for:
– Core Business Logic (Application/Chat Pipeline & Workflow)
– Data Management (Dataset, Embedding, Function Library)
– Configuration & Model Settings (Setting/Models Provider)
– Supporting Infrastructure (Common utilities, auth, caching)
- These to the “Database” module.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level
    FE["Frontend (Vue.js)"]:::frontend
    BG["Django API Gateway"]:::backend
    DEP["CI/CD & Deployment"]:::infra
    DB["Database (PostgreSQL + pgvector)"]:::database
    EXT["External LLM Providers"]:::external

    %% Frontend to Gateway
    FE -->|"HTTP/HTTPS API"| BG

    %% Backend Modules Subgraph
    subgraph "Backend Modules"
        %% Core Business Logic Cluster
        subgraph "Core Business Logic"
            CP["Chat Pipeline"]:::backend_core
            FE2["Flow Engine"]:::backend_core
        end

        %% Data Management & AI Cluster
        subgraph "Data Management & AI"
            DS["Dataset Management"]:::backend_data
            EMB["Text Embedding & Vector Search"]:::backend_data
            FLIB["AI Function Libraries"]:::backend_data
        end

        %% Configuration & Model Integration Cluster
        subgraph "Configuration & Model Integration"
            SS["System Settings"]:::backend_config
            MPI["Models Provider Integrations"]:::backend_config
        end

        %% Supporting Services Cluster
        subgraph "Supporting Services"
            CS["Common Services"]:::backend_support
            subgraph "Task/Job Management"
                TM1["Task Manager (Common)"]:::backend_support
                TM2["Task Manager (Celery)"]:::backend_support
            end
        end
    end

    %% Connections from Django API Gateway to Backend Modules
    BG -->|"routes"| CP
    BG -->|"routes"| DS
    BG -->|"routes"| SS
    BG -->|"routes"| CS
    BG -->|"routes"| TM1
    BG -->|"routes"| TM2
    BG -->|"routes"| FLIB

    %% Internal Connections within Backend Modules
    CP -->|"orchestrates"| FE2
    FE2 -->|"invokes"| EMB
    EMB -->|"queries"| DB
    SS -->|"configures"| MPI
    MPI -->|"calls"| EXT

    %% Deployment affects the gateway (illustrating containerized deployment)
    DEP -->|"deploys"| BG

    %% Styles
    classDef frontend fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef backend fill:#87CEEB,stroke:#333,stroke-width:2px;
    classDef backend_core fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef backend_data fill:#B0E0E6,stroke:#333,stroke-width:2px;
    classDef backend_config fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef backend_support fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef database fill:#FFE4B5,stroke:#333,stroke-width:2px;
    classDef external fill:#F08080,stroke:#333,stroke-width:2px;
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/hadryan/maxkb/tree/main/ui/"
    click CP "https://github.com/hadryan/maxkb/tree/main/apps/application/chat_pipeline/"
    click FE2 "https://github.com/hadryan/maxkb/tree/main/apps/application/flow/"
    click DS "https://github.com/hadryan/maxkb/tree/main/apps/dataset/"
    click EMB "https://github.com/hadryan/maxkb/tree/main/apps/embedding/"
    click FLIB "https://github.com/hadryan/maxkb/tree/main/apps/function_lib/"
    click SS "https://github.com/hadryan/maxkb/tree/main/apps/setting/"
    click MPI "https://github.com/hadryan/maxkb/tree/main/apps/setting/models_provider/"
    click CS "https://github.com/hadryan/maxkb/tree/main/apps/common/"
    click TM1 "https://github.com/hadryan/maxkb/tree/main/apps/common/task/"
    click TM2 "https://github.com/hadryan/maxkb/tree/main/apps/ops/celery/"
    click DEP "https://github.com/hadryan/maxkb/tree/main/installer/"
    click DEP "https://github.com/hadryan/maxkb/tree/main/ .github/workflows/"
```
