# skysingh04/dreamops architecture

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

- Interactive diagram: https://gitdiagram.com/skysingh04/dreamops
- Repository: https://github.com/skysingh04/dreamops

## Overview

##### Project type and purpose
- From the file tree (“backend/”, “frontend/”, “infrastructure/”) and README, we see this is a full-stack SaaS platform (“DreamOps” / “oncall-agent”) combining:
- A Python FastAPI backend AI-powered incident response agent
- A Next.js + React frontend dashboard
- Terraform & EKS/ECS infrastructure for AWS deployment
- External MCP servers (GitHub-MCP, Grafana-MCP)

##### File structure
- Top-level:
- backend/ – Python AI agent with FastAPI, CLI, examples, tests, Dockerfile
- frontend/ – Next.js app router, React components, Drizzle ORM, API routes, Dockerfile
- infrastructure/ – Terraform modules for ECS, CloudFront, EKS test cluster
- github-mcp-server/ & mcp-grafana/ – Go-based Model Context Protocol servers
- Patterns & config:
- Backend uses src/oncall_agent package, MVC-style routers under api/routers
- Frontend uses app/ and components/, plus client-side calls to backend via API routes and WebSocket
- CI/CD pipelines in .github/workflows for backend, frontend, security
- Docker-Compose for local dev and multiple microservices

##### README clues about architecture
- MCP integration block (Kubernetes, GitHub, Grafana, Notion)
- AWS infrastructure: VPC, ECS Fargate for backend, S3+CloudFront for frontend, ALB, ECR, CloudWatch, Secrets Manager
- Real-time flow via REST API, WebSockets, frontend dashboard

##### Main components
a. Alert Source layer
- PagerDuty SNS webhooks
- (Test scripts, “fuck_kubernetes.sh”)
b. Oncall AI Agent (Backend)
- FastAPI REST API & WebSocket server
- Core agent logic (oncall_agent.agent, remediation_pipeline)
- MCP plugin loader (mcp_integrations/*)
c. External AI Service
- Claude AI API
d. MCP Integration Services
- Kubernetes cluster (EKS or local kind)
- GitHub-MCP server
- Grafana-MCP server
- Optional: Notion, PagerDuty, Slack
e. Frontend SaaS UI
- Next.js app with API routes and real-time updates
- Drizzle ORM + SQLite/Postgres for session & dashboard data
f. AWS Infrastructure
- ECS Fargate backend behind ALB
- S3 + CloudFront hosting frontend
- EKS cluster for testing & debug integration
- CloudWatch + SNS → PagerDuty
- Terraform modules (networking, monitoring, backend, frontend)

##### Architectural patterns & design principles
- Microservices / plugin architecture for MCP integrations
- Async event-driven processing (async/await in Python, background tasks)
- Clear separation:
- API layer (FastAPI)
- Core logic & strategies
- Integrations as interchangeable plugins
- Frontend SSR/CSR hybrid (Next.js / App Router) with real-time WebSocket feeds
- Infrastructure as code (Terraform) with separate modules for networking, compute, monitoring

##### Technologies & frameworks
- Backend: Python 3.11, FastAPI, Uvicorn, Pydantic, pytest, mypy, ruff
- Frontend: Next.js 13+, React, TypeScript, Drizzle ORM, Stripe, WebSocket
- External MCP: Go, Gorilla Mux, Go-GitHub-SDK, EasyJSON
- Infra: Terraform, AWS (ECS Fargate, EKS, CloudFront, S3, ALB, CloudWatch, SNS, Secrets Manager)
- CI/CD: GitHub Actions, Docker, Docker-Compose, Amplify

##### Be detailed but not overwhelming
- Every essential moving piece: alert ingress, AI call, integration calls, front-end updates, infra components
- Avoid unnecessary low-level file paths—focus on logical components

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Alert Source Layer
    subgraph "Alert Source Layer"
        PD["PagerDuty SNS Webhooks"]:::external
    end

    %% Backend (Oncall AI Agent)
    subgraph "Backend (Oncall AI Agent)"
        API["FastAPI REST & WebSocket Server"]:::backend
        Core["Agent Core Logic"]:::backend
        CLI["CLI & Examples"]:::backend
        PluginLoader["MCP Plugin Loader"]:::backend
    end

    %% MCP Integrations
    subgraph "MCP Integrations"
        KubePlugin["Kubernetes Plugin"]:::integration
        GHPlugin["GitHub Plugin"]:::integration
        GrafPlugin["Grafana Plugin"]:::integration
        NotionPlugin["Notion Plugins"]:::integration
    end

    %% Frontend SaaS UI
    subgraph "Frontend SaaS UI"
        NextApp["Next.js App Router"]:::frontend
        APIRoutes["API & WebSocket Routes"]:::frontend
        UIComponents["React Components & UI"]:::frontend
        Drizzle["Drizzle ORM & DB Setup"]:::frontend
        WSClient["WebSocket Client"]:::frontend
    end

    %% AWS Infrastructure
    subgraph "AWS Infrastructure"
        SNS["SNS (CloudWatch Alarms)"]:::infra
        ALB["Application Load Balancer"]:::infra
        ECS["ECS Fargate (Backend)"]:::infra
        S3["S3 + CloudFront (Frontend)"]:::infra
        EKS["EKS Test Cluster"]:::infra
    end

    %% External Services
    subgraph "External Services"
        Claude["Claude AI"]:::external
        GH_MCP["GitHub-MCP Server"]:::external
        Graf_MCP["Grafana-MCP Server"]:::external
        K8sCluster["Kubernetes Cluster"]:::external
    end

    %% Data Flows
    SNS -->|"1. Alert Event"| PD
    PD -->|"2. HTTP POST webhook"| API
    API -->|"3. Pass context"| Core
    Core -->|"Claude AI call"| Claude
    Core -->|"4. Load plugins"| PluginLoader
    PluginLoader -->|"kubectl / REST"| KubePlugin
    KubePlugin -->|"Manage resources"| K8sCluster
    PluginLoader -->|"REST"| GHPlugin
    GHPlugin -->|"Operate repos"| GH_MCP
    PluginLoader -->|"REST"| GrafPlugin
    GrafPlugin -->|"Query metrics"| Graf_MCP
    PluginLoader -->|"Interact"| NotionPlugin
    Core -->|"5. Respond ack/resolve"| API
    API -->|"HTTP response"| PD
    NextApp -->|"uses"| APIRoutes
    APIRoutes -->|"REST & WS"| API
    API -->|"WebSocket events"| WSClient
    WSClient -->|"subscribe"| API
    APIRoutes -->|"DB read/write"| Drizzle
    %% Infrastructure Connections
    ALB -->|"Route traffic"| ECS
    ECS -->|"Hosts API & Core"| API
    S3 -->|"Hosts frontend"| NextApp
    EKS -->|"Test integration"| K8sCluster
    %% Click Events
    click PD "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/api/webhooks.py"
    click API "https://github.com/skysingh04/dreamops/blob/main/backend/api_server.py"
    click API "https://github.com/skysingh04/dreamops/blob/main/backend/main.py"
    click Core "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/agent.py"
    click Core "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/agent_enhanced.py"
    click Core "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/remediation_pipeline.py"
    click CLI "https://github.com/skysingh04/dreamops/tree/main/backend/examples/"
    click CLI "https://github.com/skysingh04/dreamops/blob/main/backend/demo_github_mcp.py"
    click PluginLoader "https://github.com/skysingh04/dreamops/tree/main/backend/src/oncall_agent/mcp_integrations/"
    click KubePlugin "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/mcp_integrations/kubernetes.py"
    click KubePlugin "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/mcp_integrations/kubernetes_mcp.py"
    click GHPlugin "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/mcp_integrations/github_mcp.py"
    click GrafPlugin "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/mcp_integrations/grafana_mcp.py"
    click NotionPlugin "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/mcp_integrations/notion.py"
    click NotionPlugin "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/mcp_integrations/notion_direct.py"
    click NotionPlugin "https://github.com/skysingh04/dreamops/blob/main/backend/src/oncall_agent/mcp_integrations/notion_real.py"
    click GH_MCP "https://github.com/skysingh04/dreamops/tree/main/github-mcp-server/"
    click Graf_MCP "https://github.com/skysingh04/dreamops/tree/main/mcp-grafana/"
    click NextApp "https://github.com/skysingh04/dreamops/tree/main/frontend/app/"
    click APIRoutes "https://github.com/skysingh04/dreamops/tree/main/frontend/app/api/"
    click APIRoutes "https://github.com/skysingh04/dreamops/blob/main/frontend/app/api/socketio/route.ts"
    click UIComponents "https://github.com/skysingh04/dreamops/tree/main/frontend/components/"
    click UIComponents "https://github.com/skysingh04/dreamops/tree/main/frontend/components/ui/"
    click Drizzle "https://github.com/skysingh04/dreamops/tree/main/frontend/lib/db/"
    click Drizzle "https://github.com/skysingh04/dreamops/blob/main/frontend/drizzle.config.ts"
    click WSClient "https://github.com/skysingh04/dreamops/blob/main/frontend/lib/websocket.ts"
    click WSClient "https://github.com/skysingh04/dreamops/blob/main/frontend/lib/hooks/use-websocket.ts"
    click SNS "https://github.com/skysingh04/dreamops/blob/main/infrastructure/terraform/main.tf"
    click ECS "https://github.com/skysingh04/dreamops/tree/main/infrastructure/terraform/modules/backend/"
    click S3 "https://github.com/skysingh04/dreamops/tree/main/infrastructure/terraform/modules/frontend/"
    click ALB "https://github.com/skysingh04/dreamops/tree/main/infrastructure/terraform/modules/networking/"
    click SNS "https://github.com/skysingh04/dreamops/tree/main/infrastructure/terraform/modules/monitoring/"
    click EKS "https://github.com/skysingh04/dreamops/blob/main/infrastructure/eks/main.tf"

    %% Styles
    classDef backend fill:#f9f,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef integration fill:#fbf,stroke:#333,stroke-width:1px
    classDef infra fill:#bfb,stroke:#333,stroke-width:1px
    classDef external fill:#ffe,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef default stroke:#333,stroke-width:1px,fill:#fff
```
