# klavis-ai/klavis architecture

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

- Interactive diagram: https://gitdiagram.com/klavis-ai/klavis
- Repository: https://github.com/klavis-ai/klavis

## Overview

##### Project Type and Purpose
- Full-stack open-source integration platform (“Klavis AI”)
- Provides:
– Client SDKs (Python, TypeScript)
– Bot apps (Discord, Slack, Web, WhatsApp)
– Microservice MCP servers (100+ individual integrations)
– CI/CD pipelines and code generation (via Fern)
– Documentation & examples

##### Main Architectural Components
A. Client Layer
1. AI Agent / LLM or custom application
2. Klavis SDKs (Python `klavis` package, TS `klavis` npm module)
3. Bot Containers (Discord, Slack, Web, WhatsApp - in `mcp-clients/`)
B. API Layer
4. API Gateway or Router (generated via Fern, exposing REST/OpenAPI endpoints)
5. Authentication & OAuth endpoints
C. Microservices Layer
6. MCP Server Instances (each subfolder in `mcp_servers/` is a separate Dockerized microservice)
– Each runs its own HTTP server (Python, Node.js/TypeScript, Go)
– Implements a standardized MCP protocol (create instance, list tools, call tools)
D. External Services
7. Third-party APIs (Gmail, Google Drive, Airtable, GitHub, Slack, etc.)
8. OAuth providers (handle OAuth redirects, callbacks)
E. Infrastructure
9. Codegen & API definitions (Fern: `fern.config.json`, `generators.yml`)
10. CI/CD pipelines (GitHub Actions workflows for linting, SDK releases)
11. Documentation site & examples (Docs in `docs/`, Jupyter notebooks in `examples/`)

##### Relationships & Data Flows
– AI Agent → SDK calls → API Gateway → MCP Server microservice → External service
– SDK initiates OAuth flows: API Gateway returns `oauthUrl`, user redirects, callback → MCP Server stores tokens
– For function-calling: LLM <→> SDK <→> MCP Server tools API <→> External API
– Bots (Discord/Slack) receive webhooks/events → local Bot app → SDK → MCP Server → external API → Bot responds

##### Architectural Patterns & Principles
– Microservices per integration for isolation and scaling
– Monorepo for all servers+clients + codegen config
– Standardized MCP protocol across languages/platforms
– Separation of concerns:
- Clients (SDK & bots) vs API Gateway vs Server implementations
- Auth management centralized in MCP Servers
– Infrastructure as code: Dockerfiles in every service directory, GitHub Actions for CI/CD

##### Relevant Technologies
– Python (FastAPI or Flask) for Python-based MCP Servers & Python SDK
– TypeScript/Node.js (Express, Cloudflare Workers, GraphQL) for many servers & TS SDK
– Go (GitHub MCP server implementation)
– Docker for containerization
– Fern codegen for API definitions and documentation
– GitHub Actions for linting, releases
– OpenAPI/SSE for streaming responses

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        AIAgent["AI Agent / Custom App"]:::client
        PythonSDK["Python SDK"]:::client
        TSSDK["TypeScript SDK"]:::client
        DiscordBot["Discord Bot"]:::client
        SlackBot["Slack Bot"]:::client
        WebBot["Web Bot"]:::client
        WhatsAppBot["WhatsApp Bot"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIGateway["API Gateway / Router"]:::api
        Auth["Authentication & OAuth"]:::api
    end

    %% Microservices Layer
    subgraph "Microservices Layer"
        direction TB
        AffinityMS["Affinity MCP Server"]:::micro
        AirtableMS["Airtable MCP Server"]:::micro
        AsanaMS["Asana MCP Server"]:::micro
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Gmail["Gmail API"]:::external
        GoogleDrive["Google Drive API"]:::external
        GitHub["GitHub API"]:::external
        SlackAPI["Slack API"]:::external
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        subgraph "Codegen & API Definitions"
            FernConfig["fern.config.json"]:::infra
            Generators["generators.yml"]:::infra
        end
        subgraph "CI/CD Pipelines"
            LintClients["mcp_clients_lint.yml"]:::infra
            LintServers["mcp_servers_lint.yml"]:::infra
            SDKReleasePy["python-sdk-release.yml"]:::infra
            SDKReleaseTS["typescript-sdk-release.yml"]:::infra
        end
        Docs["Documentation Site (docs/)"]:::infra
        Examples["Examples & Notebooks (examples/)"]:::infra
    end

    %% Connections
    AIAgent --> PythonSDK
    AIAgent --> TSSDK
    DiscordBot --> PythonSDK
    SlackBot --> PythonSDK
    WebBot --> PythonSDK
    WhatsAppBot --> PythonSDK

    PythonSDK --> APIGateway
    TSSDK --> APIGateway

    APIGateway --> Auth
    Auth --> APIGateway

    APIGateway --> AffinityMS
    APIGateway --> AirtableMS
    APIGateway --> AsanaMS

    AffinityMS --> Gmail
    AirtableMS --> GoogleDrive
    AsanaMS --> GitHub
    SlackBot --> SlackAPI

    %% Codegen & CI/CD not connected to data flow but shown
    %% Click Events
    click DiscordBot "https://github.com/klavis-ai/klavis/blob/main/mcp-clients/src/mcp_clients/discord_bot.py"
    click SlackBot "https://github.com/klavis-ai/klavis/blob/main/mcp-clients/src/mcp_clients/slack_bot.py"
    click WebBot "https://github.com/klavis-ai/klavis/blob/main/mcp-clients/src/mcp_clients/web_bot.py"
    click WhatsAppBot "https://github.com/klavis-ai/klavis/blob/main/mcp-clients/src/mcp_clients/whatsapp_bot.py"
    click PythonSDK "https://github.com/klavis-ai/klavis/blob/main/mcp-clients/src/mcp_clients/mcp_client.py"
    click AffinityMS "https://github.com/klavis-ai/klavis/tree/main/mcp_servers/affinity/"
    click AirtableMS "https://github.com/klavis-ai/klavis/tree/main/mcp_servers/airtable/"
    click AsanaMS "https://github.com/klavis-ai/klavis/tree/main/mcp_servers/asana/"
    click FernConfig "https://github.com/klavis-ai/klavis/blob/main/fern/fern.config.json"
    click Generators "https://github.com/klavis-ai/klavis/blob/main/fern/generators.yml"
    click LintClients "https://github.com/klavis-ai/klavis/blob/main/.github/workflows/mcp_clients_lint.yml"
    click LintServers "https://github.com/klavis-ai/klavis/blob/main/.github/workflows/mcp_servers_lint.yml"
    click SDKReleasePy "https://github.com/klavis-ai/klavis/blob/main/.github/workflows/python-sdk-release.yml"
    click SDKReleaseTS "https://github.com/klavis-ai/klavis/blob/main/.github/workflows/typescript-sdk-release.yml"
    click Docs "https://github.com/klavis-ai/klavis/tree/main/docs/"
    click Examples "https://github.com/klavis-ai/klavis/tree/main/examples/"

    %% Styles
    classDef client fill:#e6ffe6,stroke:#2d662d,color:#2d662d
    classDef api fill:#e6f0ff,stroke:#1f4d79,color:#1f4d79
    classDef micro fill:#e0f7f7,stroke:#116466,color:#116466
    classDef external fill:#fff4e6,stroke:#b36003,color:#b36003
    classDef infra fill:#f0f0f0,stroke:#666666,color:#333333
```
