# thehapyone/sage architecture

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

- Interactive diagram: https://gitdiagram.com/thehapyone/sage
- Repository: https://github.com/thehapyone/sage

## Overview

- Frontend/UI:
- Chainlit Integration – Represent components from the “.chainlit” directory and related Chainlit configuration (chainlit.md).
- Sage Chat Interface – Indicate the user’s conversational screen as shown in the README (Sage Chat overview and starter modes).
- Backend/Application Core:
- Sage Application – Highlight “sage/app.py” as the main entry point.
- Chat Processing Module – Include “sage/chat.py” and “sage/models/chat_prompt.py” that process conversation inputs and format prompts.
- Agent & Crew Management – Represent modules under “sage/agent” (crew.py, memory.py, tools_finder.py) and related agent-mode configurations shown in the README.
- Data Source Module – Detail “sage/sources” (loaders.py, retrievers.py, source_manager.py, etc.) which handle integration with multiple data sources (Confluence, web, etc.).
- Tools & Utilities – Outline components in “sage/tools” and “sage/utils” that support extended functionalities, integrations (like GitLab and Jira), logging, and validations (“sage/validators”).
- Configuration & Initialization:
- Configuration Files – Show how “sage/config.toml”, “.env.sample”, and other TOML/YAML configuration files (used for starters, data sources, and agents) determine the system’s behavior.
- Deployment & Infrastructure:
- Docker Environment – Include the Dockerfile and docker-compose.yml to indicate containerization.
- CI/CD & Testing – Reference “.github” workflows, Makefile, and the “tests” directory to show continuous integration and testing infrastructure.
- External Services & APIs:

##### Relationships and Data Flow
- The LLM components (for generating chat responses)
- The Data Source Interface (for retrieving or manipulating configured data)
- Agent execution modules (for autonomous tasks in Agent Mode)
- Configuration files influencing system behavior at initialization. Connect the configuration to the data source, tool, and agent modules.
- How the Docker container encapsulates the overall application, and denote the CI/CD pipeline using GitHub workflows.

##### Architectural Patterns and Principles
- Modular and Layered Design: Emphasize the clean separation between the UI (Chainlit/Sage Chat) and the backend (processing, agents, data source handling).
- Extensibility: Note how the use of configuration files allows for quick customization (starters, tool integrations, data source updates).
- Containerization: Reflect the Docker / docker-compose setup that enables easy deployment.
- Dependency Injection/Loose Coupling: Show how agents, data loaders, and utilities are organized in separate modules to allow independent testing and updates (as evidenced by the separate “tests” directory).

##### Technology & Framework Details
- Out references to Python (with modules in “sage/”), Chainlit (in the “.chainlit” folder), CrewAI (for agent mode), and external LLM and embedding models.
- Integration with external APIs/services like Confluence, web sources, Jira, and GitLab.
- CI/CD context provided by GitHub Actions workflows for maintaining quality and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    User("User"):::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        CI["Chainlit Integration"]:::frontend
        SCI["Sage Chat Interface"]:::frontend
    end

    %% Application Core
    subgraph "Application Core"
        SA["Sage App (Entry Point)"]:::backend
        CPM["Chat Processing Module"]:::backend
        ACM["Agent & Crew Module"]:::backend
        DSM["Data Source Module"]:::backend
        TUT["Tools & Utilities"]:::backend
    end

    %% Configuration & Initialization
    subgraph "Configuration & Initialization"
        CF["Configuration Files"]:::config
    end

    %% Infrastructure Layer
    subgraph "Infrastructure"
        DE["Docker Environment"]:::infra
        CICD["CI/CD & Testing"]:::infra
        DOC["Documentation"]:::infra
    end

    %% External Services
    subgraph "External Services"
        ECS["LLM & CrewAI Services"]:::external
    end

    %% Connections
    User -->|"starts"| SCI
    CI -->|"assists"| SCI
    SCI -->|"routes input to"| SA

    SA -->|"processes chat"| CPM
    SA -->|"triggers agents"| ACM
    SA -->|"queries data"| DSM
    SA -->|"utilizes utilities"| TUT

    CF -->|"configures"| SA
    CF -->|"configures"| CPM
    CF -->|"configures"| ACM
    CF -->|"configures"| DSM
    CF -->|"configures"| TUT

    DE -->|"encapsulates"| SA
    CICD -->|"validates"| SA

    SA -->|"uses"| ECS

    %% Click Events - Frontend/UI
    click CI "https://github.com/thehapyone/sage/blob/main/.chainlit"
    click SCI "https://github.com/thehapyone/sage/blob/main/README.md"

    %% Click Events - Backend/Application Core
    click SA "https://github.com/thehapyone/sage/blob/main/sage/app.py"
    click CPM "https://github.com/thehapyone/sage/blob/main/sage/chat.py"
    click ACM "https://github.com/thehapyone/sage/tree/main/sage/agent"
    click DSM "https://github.com/thehapyone/sage/tree/main/sage/sources"
    click TUT "https://github.com/thehapyone/sage/tree/main/sage/tools"

    %% Click Events - Configuration & Initialization
    click CF "https://github.com/thehapyone/sage/blob/main/sage/config.toml"

    %% Click Events - Deployment & Infrastructure
    click DE "https://github.com/thehapyone/sage/tree/main/Dockerfile"
    click CICD "https://github.com/thehapyone/sage/blob/main/.github"
    click DOC "https://github.com/thehapyone/sage/tree/main/docs"

    %% Extra Click Events from component mapping
    %% Chainlit additional configuration file
    click CI "https://github.com/thehapyone/sage/blob/main/chainlit.md"
    %% Sage Chat additional documentation
    click SCI "https://github.com/thehapyone/sage/blob/main/docs/chat_overview.md"
    %% For Agent Mode configuration
    click ACM "https://github.com/thehapyone/sage/tree/main/examples/agents"
    
    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef config fill:#D5F5E3,stroke:#1E8449,stroke-width:2px;
    classDef infra fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#E8DAEF,stroke:#7D3C98,stroke-width:2px;
```
