# delee03/aws-audit-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/delee03/aws-audit-mcp-server
- Repository: https://github.com/delee03/aws-audit-mcp-server

## Overview

##### Project Type and Purpose
- This is a specialized full-stack microservice project comprising:
– mcp_client: a TypeScript library / client for consuming the MCP Server via Server-Sent Events (SSE).
– mcp_server: a Python-based SSE API that fetches and serves AWS documentation.
- It ships with local‐development (Docker), production deployment (Nginx + Docker), GitHub Actions CI/CD, and Terraform for AWS infra.

##### Main Components
a. MCP Client (TypeScript)
– Packaged via npm (`mcp_client/src/index.ts`)
– Used by third-party tools (n8n, VS Code Copilot)
– Establishes an SSE connection to the server.
b. Edge Proxy / Ingress
– Nginx (with Let’s Encrypt SSL)
– Terminates HTTPS, forwards plain HTTP to the container.
c. MCP Server (Docker Container)
– Python application (`mcp_server/src`) exposing `/sse` endpoints.
– Implements three MCP tools: search_documentation, read_documentation, recommend.
– Optionally packaged as an AWS Lambda (scripts/build_lambda.sh, lambda_handler_sse.py).
d. External Service
– AWS Documentation API (external HTTP)
e. Infrastructure as Code
– Terraform (mcp_server/terraform/*.tf) provisions any AWS resources needed.
f. CI/CD Pipelines
– GitHub Actions workflows under `.github/workflows/ci-cd.yml` (client)
– `.github/workflows/deploy-workers.yml` (server)
g. Local Dev / Testing
– Docker Compose (`docker-compose.yml`)
– Utility scripts (run-docker.sh, get-aws-info.sh)

##### Relationships & Data Flow
1. MCP Client → (HTTPS/SSE) → Nginx
2. Nginx → (HTTP) → Docker Container (MCP Server)
3. MCP Server → (HTTP) → AWS Documentation API
4. Terraform → AWS (infra provisioning)
5. GitHub Actions → (build & deploy) → Docker registry / AWS / Cloudflare Workers / Lambda

##### Architectural Patterns & Design Principles
- Microservice / API-Gateway pattern (server behind Nginx)
- Client-Server SSE transport (unidirectional stream)
- Containerization (Docker), with optional serverless Lambda target
- Infrastructure-as-Code (Terraform)
- CI/CD-driven deployments (GitHub Actions)

##### Technologies & Frameworks
- Frontend/Client: Node.js, TypeScript, npm
- Backend: Python 3.x, FastAPI/Starlette (or similar) under SSE
- Proxy: Nginx + Let’s Encrypt
- Containerization: Docker, Docker Compose
- Cloud Infra: AWS (Terraform), optional Lambda
- CI/CD: GitHub Actions

##### What
– e.g., Client → HTTPS/SSE → Nginx → HTTP → MCP Server → HTTPS → AWS Docs API
– Green for user-facing components
– Blue for internal services
– Gray for external dependencies
– Orange for CI/CD/IaC pipelines
- Notes or annotations for:
– Ports (8000), endpoints (`/sse`)
– File tree pointers (e.g., `mcp_server/src`, `mcp_client/src`)
– Build/deploy scripts

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client & 3rd-party Tools"
        CLIENT["MCP Client"]:::frontend
        PKG["package.json"]:::frontend
        TSC["tsconfig.json"]:::frontend
        TOOLS["n8n / VSCode Copilot"]:::frontend
    end

    subgraph "Gateway"
        NGINX["Nginx + SSL Termination"]:::gateway
    end

    subgraph "MCP Server (Docker Container)"
        subgraph "App (Python SSE API)"
            SSE["server_sse.py"]:::backend
            AWSLOGIC["server_aws.py"]:::backend
            MODELS["models.py"]:::backend
            SUTIL["server_utils.py"]:::backend
            UTIL["utils.py"]:::backend
        end
    end

    AWS_API["AWS Documentation API"]:::external

    subgraph "Containerization & Local Dev"
        DOCKERFILE["Dockerfile"]:::infra
        COMPOSE["docker-compose.yml"]:::infra
        RUNDOCK["run-docker.sh"]:::infra
        AWSINFO["get-aws-info.sh"]:::infra
    end

    subgraph "Serverless (Optional)"
        LAMBDA["lambda_handler_sse.py"]:::backend
        BLDSCRIPT["build_lambda.sh"]:::infra
    end

    subgraph "CI/CD & IaC"
        CICLIENT[".github/workflows/ci-cd.yml"]:::pipeline
        CISERVER["mcp_server/.github/workflows/deploy-workers.yml"]:::pipeline
        subgraph "Terraform"
            TF1["provider.tf"]:::pipeline
            TF2["variables.tf"]:::pipeline
            TF3["mcp_server.tf"]:::pipeline
            TF4["outputs.tf"]:::pipeline
            TFPLAN["tfplan"]:::pipeline
        end
    end

    CLIENT -->|HTTPS/SSE| NGINX
    TOOLS -->|uses| CLIENT
    NGINX -->|HTTP| SSE
    SSE -->|HTTP| AWS_API
    CICLIENT -->|build & test| CLIENT
    CISERVER -->|deploy| SSE
    CISERVER -->|deploy| LAMBDA
    TF1 -->|provision| AWS_API
    TF2 -->|provision| AWS_API
    TF3 -->|provision| AWS_API
    TF4 -->|provision| AWS_API
    TFPLAN -->|plan| AWS_API

    click CLIENT "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_client/src/index.ts"
    click PKG "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_client/package.json"
    click TSC "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_client/tsconfig.json"
    click SSE "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/src/server_sse.py"
    click AWSLOGIC "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/src/server_aws.py"
    click MODELS "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/src/models.py"
    click SUTIL "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/src/server_utils.py"
    click UTIL "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/src/utils.py"
    click DOCKERFILE "https://github.com/delee03/aws-audit-mcp-server/tree/main/mcp_server/Dockerfile"
    click COMPOSE "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/docker-compose.yml"
    click RUNDOCK "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/scripts/run-docker.sh"
    click AWSINFO "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/scripts/get-aws-info.sh"
    click LAMBDA "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/lambda_handler_sse.py"
    click BLDSCRIPT "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/scripts/build_lambda.sh"
    click CICLIENT "https://github.com/delee03/aws-audit-mcp-server/blob/main/.github/workflows/ci-cd.yml"
    click CISERVER "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/.github/workflows/deploy-workers.yml"
    click TF1 "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/terraform/provider.tf"
    click TF2 "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/terraform/variables.tf"
    click TF3 "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/terraform/mcp_server.tf"
    click TF4 "https://github.com/delee03/aws-audit-mcp-server/blob/main/mcp_server/terraform/outputs.tf"
    click TFPLAN "https://github.com/delee03/aws-audit-mcp-server/tree/main/mcp_server/terraform/tfplan"

    classDef frontend fill:#ccffcc,stroke:#2d572c,color:#2d572c;
    classDef gateway fill:#cce5ff,stroke:#1a5276,color:#1a5276;
    classDef backend fill:#e6e6ff,stroke:#4a235a,color:#4a235a;
    classDef infra fill:#ffe6cc,stroke:#a04000,color:#a04000;
    classDef external fill:#f2f2f2,stroke:#808080,color:#808080;
    classDef pipeline fill:#ffd1dc,stroke:#a40e4c,color:#a40e4c;
```
