# zeeeepa/mcp-aas architecture

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

- Interactive diagram: https://gitdiagram.com/zeeeepa/mcp-aas
- Repository: https://github.com/zeeeepa/mcp-aas

## Overview

##### Main Components
- Frontend: Built with React. Responsible for presenting the user interface and integrating with AWS Amplify for Cognito-based authentication.
- Backend: A Node.js/Express service that handles core API functionalities (user management, tool launching, routing) including authentication logic with AWS Cognito.
- Infrastructure: Contains AWS CDK (and Terraform) code for deploying resources such as AWS Cognito, AWS ECS, Lambda functions, and other cloud services.
- Shared Libraries/Utilities: Found in the “shared” directory and reused by both frontend and backend.
- Specialized Python Service: The “mcp-tool-crawler-py” module, which appears to handle crawling and source management tasks. This service involves CLI scripts, lambda functions, and integrates with AWS step-functions.
- Testing/CI Components: End-to-end tests (in folder “e2e”), unit tests (in __tests__ directories), and GitHub Actions workflows (.github/workflows) for CI/CD processes.

##### Relationships & Data Flow
- Users (clients) interact with the Frontend (React app) via browsers.
- The Frontend communicates with the Backend via RESTful APIs. This layer could include sessions, JWT tokens, and WebSocket connections to tools.
- The Backend directly interacts with AWS Cognito for authentication (user registration, authentication, and profile management).
- Infrastructure components (AWS CDK/Terraform scripts) are responsible for provisioning services like Cognito, ECS containers (hosting both the frontend and backend docker images), Lambda functions, and event handling services.
- The Python-based “mcp-tool-crawler-py” service likely operates as an independent microservice, which might be triggered by events (possibly managed through AWS Step Functions) to crawl sources and manage tool packaging.
- Shared utility modules ensure consistent behavior across different services.

##### Architectural Patterns & Design Principles
- Microservice components: The separation between the frontend, backend, and the independent Python crawler service illustrates a microservice-oriented approach.
- Separation of Concerns: Frontend logic remains within the “frontend” folder, backend API handling in “backend”, and infrastructure orchestration is managed separately.
- Infrastructure as Code (IaC): Using AWS CDK (and Terraform) for automated deployment ensures reproducible cloud configurations.
- Testing: A robust test suite including unit tests (under __tests__) and end-to-end tests (in “e2e”) is in place.

##### Technologies
- Frontend: React, AWS Amplify
- Backend: Node.js, Express, AWS SDK for integrating with Cognito
- Infrastructure: AWS CDK, AWS ECS, AWS Cognito, Terraform modules
- Python Service: Python scripts, AWS Lambda integrations, AWS Step Functions (via the provided JSON definition)
- Containerization: Docker (both for frontend and backend) and Docker Compose for local testing.
- CI/CD: GitHub Actions to manage build and deployment pipelines.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    subgraph "User Interaction"
        U["User (Browser)"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        F["React Frontend - AWS Amplify Integration"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B["Node.js Backend - API & Cognito Integration"]:::backend
        C["AWS Cognito (Auth Service)"]:::infra
        S["Shared Utilities"]:::shared
    end

    %% Python Service
    subgraph "Python Service"
        P["Python Tool Crawler"]:::python
        SF["AWS Step Functions"]:::infra
    end

    %% Infrastructure Deployment
    subgraph "Infrastructure Deployment"
        D["Containerization (Docker/ECS)"]:::infra
        A1["AWS CDK Deployment"]:::infra
        T["Terraform Deployment"]:::infra
        GA["GitHub Actions CI/CD"]:::testing
    end

    %% Testing / CI Components
    subgraph "Testing/CI"
        E2E["End-to-End Tests"]:::testing
    end

    %% Connections
    U -->|"HTTP_Request"| F
    F -->|"API_Call"| B
    B -->|"Auth_Flow"| C
    B ---|"Uses"| S
    GA -->|"Deploys_to"| D
    A1 -->|"Provisions"| D
    T -->|"Provisions"| D
    D -->|"Hosts"| F
    D -->|"Hosts"| B
    P -->|"Triggers"| SF

    %% Click Events
    click F "https://github.com/zeeeepa/mcp-aas/tree/main/frontend/"
    click B "https://github.com/zeeeepa/mcp-aas/tree/main/backend/"
    click A1 "https://github.com/zeeeepa/mcp-aas/tree/main/infrastructure/cdk/"
    click T "https://github.com/zeeeepa/mcp-aas/tree/main/infrastructure/terraform/"
    click S "https://github.com/zeeeepa/mcp-aas/tree/main/shared/"
    click P "https://github.com/zeeeepa/mcp-aas/tree/main/mcp-tool-crawler-py/"
    click E2E "https://github.com/zeeeepa/mcp-aas/tree/main/e2e/"
    click GA "https://github.com/zeeeepa/mcp-aas/tree/main/.github/workflows/"

    %% Styles
    classDef frontend fill:#B3E5FC,stroke:#01579B,stroke-width:2px;
    classDef backend fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef infra fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef python fill:#FFECB3,stroke:#FF9800,stroke-width:2px;
    classDef shared fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px;
    classDef testing fill:#DCEDC8,stroke:#7CB342,stroke-width:2px;
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:2px;
```
