# trailblazelabs/fca-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/trailblazelabs/fca-mcp
- Repository: https://github.com/trailblazelabs/fca-mcp

## Overview

##### Project Type and Purpose
- This is a backend-focused, AI-powered regulatory intelligence service (“FCA MCP Server”) that continuously ingests live FCA data, processes and embeds it for semantic search (via Azure OpenAI), indexes it into Elasticsearch, and exposes a conversational API (FastAPI) that AI assistants (e.g., Claude Desktop) call.
- It includes a CLI for data loading and infrastructure as code (Terraform) for deployment to AWS (ECS, Lambda, S3, IAM, Load Balancer).

##### File Structure Analysis
- Top level:
- fca_mcp/          → Python package with modules:
– cli.py           (entry point for data loading & server serve)
– data_loaders.py  (FCA API fetchers)
– elasticsearch_helpers.py (ES index utilities)
– lambda_handler.py (AWS Lambda ingestion entry)
– mcp_server/     (FastAPI application: main.py, api.py, handlers.py, utils.py)
– models.py, settings.py, shared_utils/ (auth, etc.)
- Dockerfile.mcp-server, Dockerfile.lambda → container definitions for server and Lambda ingestion
- docker-compose.yaml → local orchestration (MCP server + Elasticsearch)
- terraform/        → IaC for AWS: ECS cluster (ecs.tf), Lambda (lambda.tf), S3 (s3.tf), IAM (iam.tf), Load Balancer (load_balancer.tf), secrets, variables, plus a small diagram_script.py.
- tests/            → pytest suite for data loaders, server handlers, models.
- Key patterns:
- CLI + Lambda for batch/daily ingestion
- FastAPI microservice for real-time query
- Elasticsearch as search backend
- Terraform-managed AWS infra
- Dockerized components for local/dev and production

##### README Insights
- Architecture call-out: “FastMCP server → Elasticsearch with semantic search → Azure OpenAI embeddings → Live FCA APIs”
- Describes continuous ingestion, transformation, embedding, indexing, and conversational query.

##### Detail Level
- Essential components (CLI, Lambda, FastAPI, ES, embeddings, external APIs, infra)
- Drill into sub-components if needed (e.g., in FastAPI: api.py vs. handlers.py)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Services
    subgraph "External Services"
        FCA["FCA REST APIs"]:::external
        Azure["Azure OpenAI Embeddings"]:::external
        Claude["Claude Desktop (Client)"]:::external
    end

    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        CLI["CLI Runner"]:::compute
        Lambda["AWS Lambda Handler"]:::compute
    end

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        Loader["Data Loader"]:::compute
        Transformer["Transformer"]:::compute
        Indexer["ES Indexer"]:::compute
    end

    %% Search Backend
    Elasticsearch["Elasticsearch Cluster"]:::db

    %% API Layer
    subgraph "API Layer"
        LoadBalancer["Load Balancer"]:::compute
        MCP["FastAPI MCP Server"]:::compute
        API["API Definitions"]:::compute
        Handlers["Handlers"]:::compute
        Utils["Utils"]:::compute
        Models["Domain Models"]:::compute
        Settings["Settings"]:::compute
        Auth["Shared Auth Utilities"]:::compute
    end

    %% Infrastructure as Code
    subgraph "Infrastructure as Code (Terraform)"
        ECSInfra["ECS Cluster\n(ecs.tf)"]:::iac
        LambdaInfra["Lambda Configuration\n(lambda.tf)"]:::iac
        S3Infra["S3 Buckets\n(s3.tf)"]:::iac
        IAMInfra["IAM Roles & Policies\n(iam.tf)"]:::iac
        LBInfra["Load Balancer\n(load_balancer.tf)"]:::iac
        ProviderInfra["Provider & Backend\n(provider.tf)"]:::iac
        VarsInfra["Variables & Overrides\n(variables/*.tfvars)"]:::iac
        DiagramScript["Diagram Script\n(diagram_script.py)"]:::iac
    end

    %% Local Development
    subgraph "Local Development"
        Compose["Docker Compose"]:::compute
        DockerMCP["Dockerfile.mcp-server"]:::compute
        DockerLambda["Dockerfile.lambda"]:::compute
    end

    %% Developer
    Dev["Developer"]:::external

    %% Data Ingestion Flow
    FCA --> CLI
    FCA --> Lambda
    CLI --> Loader
    Lambda --> Loader
    Loader --> Transformer
    Transformer --> Azure
    Azure --> Indexer
    Indexer --> Elasticsearch

    %% Query Flow
    Claude --> LoadBalancer
    LoadBalancer --> MCP
    MCP --> API
    API --> Handlers
    Handlers --> Elasticsearch
    Handlers --> Utils
    MCP --> Models
    MCP --> Settings
    MCP --> Auth

    %% Local Dev Flow
    Compose --> MCP
    Compose --> Elasticsearch
    DockerMCP --> MCP
    DockerLambda --> Lambda

    %% Infra Provisioning
    Dev -->|provisions| ECSInfra
    Dev -->|provisions| LambdaInfra
    Dev -->|provisions| S3Infra
    Dev -->|provisions| IAMInfra
    Dev -->|provisions| LBInfra
    Dev -->|provisions| ProviderInfra
    Dev -->|provisions| VarsInfra
    Dev -->|provisions| DiagramScript

    ECSInfra -.-> MCP
    LambdaInfra -.-> Lambda
    LBInfra -.-> LoadBalancer
    S3Infra -.-> Loader
    IAMInfra -.-> Dev

    %% Click Events
    click CLI "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/cli.py"
    click Lambda "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/lambda_handler.py"
    click Loader "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/data_loaders.py"
    click Indexer "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/elasticsearch_helpers.py"
    click MCP "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/mcp_server/main.py"
    click API "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/mcp_server/api.py"
    click Handlers "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/mcp_server/handlers.py"
    click Utils "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/mcp_server/utils.py"
    click Models "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/models.py"
    click Settings "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/settings.py"
    click Auth "https://github.com/trailblazelabs/fca-mcp/blob/main/fca_mcp/shared_utils/auth.py"
    click DockerMCP "https://github.com/trailblazelabs/fca-mcp/blob/main/Dockerfile.mcp-server"
    click DockerLambda "https://github.com/trailblazelabs/fca-mcp/blob/main/Dockerfile.lambda"
    click Compose "https://github.com/trailblazelabs/fca-mcp/blob/main/docker-compose.yaml"
    click ECSInfra "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/ecs.tf"
    click LambdaInfra "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/lambda.tf"
    click S3Infra "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/s3.tf"
    click IAMInfra "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/iam.tf"
    click LBInfra "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/load_balancer.tf"
    click ProviderInfra "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/provider.tf"
    click VarsInfra "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/variables/variables.tfvars"
    click DiagramScript "https://github.com/trailblazelabs/fca-mcp/blob/main/terraform/diagram_script.py"

    %% Styles
    classDef compute fill:#cce5ff,stroke:#0366d6,color:#0366d6
    classDef db fill:#ffe5b4,stroke:#d58512,color:#8a6d3b
    classDef external fill:#d4edda,stroke:#28a745,color:#155724
    classDef iac fill:#e2e3e5,stroke:#6c757d,color:#343a40
```
