# fuzzylabs/sre-agent architecture

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

- Interactive diagram: https://gitdiagram.com/fuzzylabs/sre-agent
- Repository: https://github.com/fuzzylabs/sre-agent

## Overview

##### Project type and purpose
- This is an open-source AI-powered Site Reliability Engineer “Agent” built as a collection of small services (Python & Node.js) running in containers.
- It orchestrates LLM calls, queries Kubernetes and GitHub via MCP servers, and pushes notifications into Slack.
- Main use case: you POST a “diagnose” request and the agent runs root-cause analysis across infra, code, and logs.

##### File structure
- Top-level:
– compose.*.yaml & Dockerfiles → multicloud container orchestration (AWS EKS, GKE).
– sre_agent/
· client, firewall, llm, prompt_server → Python-based “orchestrator” services (FastAPI & MCP orchestrator).
· servers/… → standalone MCP “tool” servers implemented in Node/TypeScript (GitHub, Kubernetes, Slack).
· shared → common schemas, logging utilities.
- docs/agent-architecture.md hints at data flows and service relationships.
- .github/workflows & Makefile → CI/CD pipelines to build and push container images.

##### README for additional insights
- Orchestrator service listens on port 8003 (FastAPI).
- Kubernetes MCP server listens on port 3001 (SSE for streaming logs).
- The agent uses the Model Context Protocol (MCP) to glide between LLM and tool invocations.

a. Python Orchestrator Layer
– client.py: Entry point, accepts /diagnose and /health via FastAPI.
– llm/main.py: Wraps LLM provider calls (Anthropic, Gemini).
– firewall/firewall.py: (Optional layer for request filtering/security).
– prompt_server/server.py: Generates prompts, context enrichment for LLM.
b. MCP Tool Servers
– GitHub Server (Node/TS): handles repo queries, searches, issues, pulls.
– Kubernetes Server (Node/TS): SSE endpoint for logs, kubectl/helm operations.
– Slack Server (Node/TS): sends messages & updates into Slack channels.
c. Shared Components
– shared/logger.py, shared/schemas.py: type definitions & logging conventions.
d. External Dependencies
– LLM Providers (Anthropic, Gemini) – HTTP APIs.
– AWS EKS or GCP GKE cluster – Kubernetes API.
– GitHub REST/GQL API.
– Slack Webhooks/API.

##### Relationships & data flow
1. Developer or CI triggers a POST to Orchestrator (/diagnose).
2. Orchestrator calls prompt_server to build the LLM prompt.
3. Orchestrator calls llm service → speaks to LLM provider endpoint.
4. LLM response triggers calls to MCP Tool Servers:
- Kubernetes Server for logs/cluster state (SSE or REST).
- GitHub Server for code search.
- Slack Server to notify team.
5. Responses funnel back into Orchestrator → HTTP response to caller.
6. /health calls go directly to Orchestrator health check logic.

##### Architectural patterns & design principles
- Microservices: each tool server is independently deployable and containerized.
- Separation of concerns: Orchestrator (FastAPI) vs. prompt generation vs. LLM invocation vs. tool shims.
- Protocol-driven design: Model Context Protocol (MCP) for uniform tool invocation.
- Cloud-agnostic deployment (compose.aws.yaml, compose.gcp.yaml, ECR/GAR).
- CI/CD pipelines: GitHub Actions build & push container images.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Python Orchestrator Layer
    subgraph "Python Orchestrator Layer"
        direction TB
        Client["FastAPI Orchestrator\nPort:8003"]:::orchestrator
        Firewall["Firewall Service"]:::orchestrator
        Prompt["Prompt Generation Server"]:::orchestrator
        LLM["LLM Invocation Service"]:::orchestrator
    end

    %% MCP Tool Servers
    subgraph "MCP Tool Servers"
        direction TB
        GitHub["GitHub MCP Server"]:::tool
        Kubernetes["Kubernetes MCP Server"]:::tool
        Slack["Slack MCP Server"]:::tool
    end

    %% Shared Components
    subgraph "Shared Components"
        direction TB
        Logger["Shared Logging Utilities"]:::shared
        Schemas["Shared Schemas"]:::shared
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Anthropic["Anthropic API"]:::external
        Gemini["Gemini API"]:::external
        K8sCluster["AWS EKS / GCP GKE"]:::external
        GitHubAPI["GitHub REST/GQL API"]:::external
        SlackAPI["Slack API"]:::external
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        direction TB
        CI["GitHub Actions Workflows"]:::ci
        Compose["Docker Compose Definitions"]:::ci
    end

    %% Developer & CI trigger
    Developer["Developer / CI Trigger"]:::external
    Developer -->|"POST /diagnose"| Client
    Developer -->|"GET /health"| Client

    %% Orchestration flows
    Client -->|"validate request"| Firewall
    Firewall -->|"generate prompts"| Prompt
    Prompt -->|"invoke LLM"| LLM
    LLM -->|"HTTP"| Anthropic
    LLM -->|"HTTP"| Gemini

    %% LLM triggers MCP servers
    LLM -->|"MCP call"| GitHub
    LLM -->|"MCP call"| Kubernetes
    LLM -->|"MCP call"| Slack

    %% MCP servers to external
    GitHub -->|"REST/GQL"| GitHubAPI
    Kubernetes -->|"SSE / REST"| K8sCluster
    Slack -->|"Webhook/API"| SlackAPI

    %% Responses funnel back
    GitHub -->|"result"| Client
    Kubernetes -->|"logs/state"| Client
    Slack -->|"confirmation"| Client

    %% Shared utils usage
    Client --> Logger
    Client --> Schemas
    Firewall --> Logger
    Prompt --> Schemas
    LLM --> Logger
    GitHub --> Logger
    Kubernetes --> Logger
    Slack --> Logger

    %% CI/CD and Deployment dependencies
    CI --> Compose
    Compose --> Client
    Compose --> Firewall
    Compose --> Prompt
    Compose --> LLM
    Compose --> GitHub
    Compose --> Kubernetes
    Compose --> Slack

    %% Click Events
    click Client "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/client/client.py"
    click LLM "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/llm/main.py"
    click Firewall "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/firewall/firewall.py"
    click Prompt "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/servers/prompt_server/server.py"
    click GitHub "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/servers/github/index.ts"
    click Kubernetes "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/servers/mcp-server-kubernetes/src/index.ts"
    click Slack "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/servers/slack/index.ts"
    click Logger "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/shared/logger.py"
    click Schemas "https://github.com/fuzzylabs/sre-agent/blob/main/sre_agent/shared/schemas.py"
    click CI "https://github.com/fuzzylabs/sre-agent/blob/main/.github/workflows/build-push-images.yml"
    click CI "https://github.com/fuzzylabs/sre-agent/blob/main/.github/workflows/ci.yml"
    click Compose "https://github.com/fuzzylabs/sre-agent/blob/main/compose.aws.yaml"
    click Compose "https://github.com/fuzzylabs/sre-agent/blob/main/compose.gcp.yaml"
    click Compose "https://github.com/fuzzylabs/sre-agent/blob/main/compose.ecr.yaml"
    click Compose "https://github.com/fuzzylabs/sre-agent/blob/main/compose.gar.yaml"

    %% Styles
    classDef orchestrator fill:#ADD8E6,stroke:#000,width:1px
    classDef tool fill:#90EE90,stroke:#000,width:1px
    classDef shared fill:#FFFACD,stroke:#000,width:1px
    classDef external fill:#D3D3D3,stroke:#000,width:1px
    classDef ci fill:#F0E68C,stroke:#000,width:1px
```
