# vespperhq/vespper architecture

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

- Interactive diagram: https://gitdiagram.com/vespperhq/vespper
- Repository: https://github.com/vespperhq/vespper

## Overview

##### Main System Components

a. Frontend Layer:
- Dashboard service (React-based web application)
- Slackbot service (Slack integration interface)

b. Backend Services:
- API Service (Main application logic)
- Data Processor (Document processing)
- Doc Indexer (Vector database management)
- Log Parser (Log analysis service)

c. Infrastructure Components:
- Database (PostgreSQL)
- Vector Store (ChromaDB)
- Message Queue/Event Bus
- LiteLLM Proxy (LLM interface)
- Authentication (Ory Kratos)
- Reverse Proxy (Envoy)

##### External Integrations Layer

Connections to:
- Slack
- OpenAI
- Monitoring tools (Datadog, Coralogix)
- Incident Management (PagerDuty, Opsgenie)
- Knowledge Base sources (GitHub, Notion, Confluence)

##### Data Flow Representation

- User interactions through Slack and Dashboard
- Alert flow from monitoring systems
- Document ingestion pipeline
- Authentication flow
- LLM interaction pattern

##### Component Details

For each major component, include:
- Service name
- Primary responsibility
- Key technologies used
- Internal service dependencies

##### Specific Implementation Notes

- Microservices architecture (evident from the services directory)
- Event-driven patterns (shown in events directories)
- Integration patterns with various tools
- Security boundaries and authentication flow

##### Additional Elements

Include:
- Version information
- Key deployment requirements
- Security boundaries
- Scaling points

##### Technical Details to Highlight

Specific technical implementations:
- Docker containerization
- NX monorepo structure
- TypeScript/Python service split
- Vector store implementation
- Authentication flow with Ory

##### Scaling and Redundancy

Indicate:
- Stateless vs. stateful services
- Database replication possibilities
- Cache layers
- Load balancing points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph UI["User Interface Layer"]
        DASH["Dashboard Service"]
        SLACK["Slackbot Service"]
    end

    subgraph AS["Application Services Layer"]
        API["API Service"]
        DP["Data Processor"]
        DI["Doc Indexer"]
        LP["Log Parser"]
    end

    subgraph DS["Data Storage Layer"]
        DB[(PostgreSQL)]
        VS[(ChromaDB Vector Store)]
        MQ[("Message Queue")]
    end

    subgraph INF["Infrastructure"]
        PROXY["Envoy Reverse Proxy"]
        AUTH["Ory Kratos Auth"]
        LLMP["LiteLLM Proxy"]
    end

    subgraph EXT["External Services"]
        direction TB
        OPENAI["OpenAI"]
        MON["Monitoring Tools"]
        INC["Incident Management"]
        KB["Knowledge Base Sources"]
    end

    %% Connections
    PROXY --> DASH
    PROXY --> SLACK
    PROXY --> API
    
    API --> AUTH
    API --> MQ
    API --> DB
    API --> VS
    API --> LLMP
    
    DP --> DB
    DP --> VS
    DP --> MQ
    
    DI --> DB
    DI --> VS
    DI --> MQ
    
    LP --> DB
    LP --> MQ
    
    LLMP --> OPENAI
    
    API --> MON
    API --> INC
    API --> KB

    %% Click Events
    click DASH "https://github.com/vespperhq/vespper/tree/main/services/dashboard"
    click SLACK "https://github.com/vespperhq/vespper/tree/main/services/slackbot"
    click API "https://github.com/vespperhq/vespper/tree/main/services/api"
    click DP "https://github.com/vespperhq/vespper/tree/main/services/data-processor"
    click DI "https://github.com/vespperhq/vespper/tree/main/services/doc-indexer"
    click LP "https://github.com/vespperhq/vespper/tree/main/services/log-parser"
    click VS "https://github.com/vespperhq/vespper/tree/main/services/api/src/agent/rag"
    click AUTH "https://github.com/vespperhq/vespper/tree/main/config/kratos"
    click PROXY "https://github.com/vespperhq/vespper/tree/main/config/envoy"
    click LLMP "https://github.com/vespperhq/vespper/tree/main/config/litellm"
    click DB "https://github.com/vespperhq/vespper/tree/main/packages/db"

    %% Styling
    classDef ui fill:#e1f5fe,stroke:#01579b
    classDef service fill:#e8f5e9,stroke:#2e7d32
    classDef storage fill:#fff3e0,stroke:#ef6c00
    classDef infra fill:#f3e5f5,stroke:#7b1fa2
    classDef external fill:#fbe9e7,stroke:#d84315

    class DASH,SLACK ui
    class API,DP,DI,LP service
    class DB,VS,MQ storage
    class PROXY,AUTH,LLMP infra
    class OPENAI,MON,INC,KB external
```
