# aws-samples/fargate-serverless-platform-operator-kit architecture

> Architecture diagram of the GitHub repository aws-samples/fargate-serverless-platform-operator-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aws-samples/fargate-serverless-platform-operator-kit
- Repository: https://github.com/aws-samples/fargate-serverless-platform-operator-kit

## Overview

##### Project type and purpose
- This is an open-source Infrastructure-as-Code toolkit (“Serverless Platform Operator Kit” or SPOK) that bundles Terraform modules and reusable patterns to provision AWS ECS/Fargate, CI/CD pipelines, monitoring, and security integrations. It also includes a sample Python Flask application (ecsdemo-python) deployed on ECS-Fargate to demonstrate the stack in action.

##### File structure
- Top-level folders:
- application/ecsdemo-python: Sample Flask app, Dockerfile, templates/static assets, tests.
- modules: Reusable Terraform modules for AquaSec, Datadog, CodePipeline (GitHub/S3 backends).
- patterns: Opinionated Terraform patterns (e.g., fargate-cluster, aquasec-sidecar) that wire modules together into deployable blueprints.
- Key files:
- Terraform configurations (main.tf, variables.tf, outputs.tf, versions.tf) in modules/patterns.
- CI/CD pipeline definitions in modules/codepipeline.
- README.md describing overall architecture and workflow.

##### README for additional insights
- Architecture overview image (images/spok.png) shows Foundation Module relationships.
- Describes tools used: Terraform, AWS ECS/Fargate, CloudWatch, Secrets Manager, GitHub, Datadog, AquaSec.
- Workflow: terraform init/plan/apply on a selected pattern → ECS cluster + ALB + backend service → sample page served by ecsdemo-python.

##### Main components and relationships
a. Components
1. Developer workstation (Terraform CLI + Git)
2. GitHub repo (source of patterns, modules, application code)
3. CodePipeline (build/test/deploy pipeline)
4. Amazon ECR (container image registry)
5. Terraform (patterns invoking modules)
6. AWS resources:
- VPC & Networking (subnets, security groups)
- ECS Cluster (Serverless Fargate)
- ECS Service & Task Definition (runs ecsdemo-python container)
- Application Load Balancer (ALB)
- AWS Secrets Manager (store credentials)
- CloudWatch (logs/metrics)
- DynamoDB & S3 (Terraform state backend)
7. Integrations: Datadog for monitoring, AquaSec sidecar for security scanning
b. Relationships and interactions
- Developer pushes code/pattern selection to GitHub → triggers GitHub webhook → CodePipeline.
- CodePipeline pulls application code, builds Docker image, pushes to ECR.
- CodePipeline or Terraform runner provisions AWS infra: VPC → ECS Cluster → ALB → Secrets/CloudWatch → Deploys new Task Definition pointing to ECR image.
- ECS tasks run ecsdemo-python container behind ALB → serves web traffic.
- Datadog agent (sidecar or Fargate integration) collects metrics → Datadog.
- AquaSec sidecar (pattern) inspects images or runtime.
- Terraform state is stored in S3 with DynamoDB locking.
c. Architectural patterns and design principles
- Modular IaC: separate modules for each AWS service.
- Composition via patterns: higher-level blueprints that wire modules.
- Separation of concerns: application code vs infrastructure code.
- Immutable infrastructure: container images, versioned deployments.
- CI/CD integration for automated builds and deployments.
d. Key technologies
- Terraform (HCL)
- AWS ECS/Fargate, ALB, VPC, S3, DynamoDB, CloudWatch, Secrets Manager
- Docker (Dockerfile in ecsdemo-python)
- CodePipeline with GitHub source and S3/CodeBuild
- Python/Flask sample app
- Datadog, AquaSec

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer and Source Control
    Dev["Developer Workstation\n(Terraform CLI + Git)"]:::developer
    GH["GitHub Repo"]:::repo
    Dev -->|"git push triggers"| GH

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline" 
        direction TB
        CP["CodePipeline"]:::cicd
        ECR["Amazon ECR"]:::aws
    end
    GH -->|"GitHub webhook"| CP
    CP -->|"docker build & push"| ECR
    CP -->|"terraform apply"| TF

    %% Infrastructure as Code Layers
    subgraph "Infrastructure as Code" 
        direction TB
        TF["Terraform (Patterns)"]:::iac
        subgraph "Patterns"
            direction TB
            PC["Fargate Cluster Pattern"]:::iac
            PS["AquaSec Sidecar Pattern"]:::iac
        end
        subgraph "Modules"
            direction TB
            MA["AquaSec Module"]:::iac
            MD["Datadog Module"]:::iac
            MG["CodePipeline(GH) Module"]:::iac
            MS["CodePipeline(S3) Module"]:::iac
        end
        SB["State Backend\n(S3 & DynamoDB)"]:::aws
        TF --> PC
        TF --> PS
        TF --> MA
        TF --> MD
        TF --> MG
        TF --> MS
        TF --> SB
    end

    CP -->|"uses patterns"| TF

    %% AWS Runtime Services
    subgraph "AWS Runtime" 
        direction TB
        VPC["VPC & Networking"]:::aws
        ECSC["ECS Cluster"]:::aws
        ECSS["ECS Service & Task Definition"]:::aws
        ALB["Application Load Balancer"]:::aws
        Sec["Secrets Manager"]:::aws
        CW["CloudWatch Logs & Metrics"]:::aws
    end
    TF --> VPC
    VPC --> ECSC
    ECSC --> ECSS
    ALB -->|"HTTP request"| ECSS
    ECSS --> CW
    ECSS --> Datadog
    ECSS --> AquaSec

    %% Sample Application
    subgraph "Sample Application"
        direction TB
        App["ecsdemo-python Application"]:::app
        Dockerfile["Dockerfile"]:::app
    end
    ECR --> ECSS
    ECSS --> App
    App --> Dockerfile

    %% Third-Party Integrations
    Datadog["Datadog"]:::integration
    AquaSec["AquaSec"]:::integration
    MD --> Datadog
    MA --> AquaSec

    %% State Backend Components
    subgraph "Terraform State Backend"
        direction TB
        S3State["S3 (state files)"]:::aws
        DDB["DynamoDB (locking)"]:::aws
    end
    SB --> S3State
    SB --> DDB

    %% Click Events
    click App "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/tree/main/application/ecsdemo-python/"
    click Dockerfile "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/tree/main/application/ecsdemo-python/Dockerfile"
    click MA "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/blob/main/modules/aquasec/main.tf"
    click MD "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/blob/main/modules/datadog/main.tf"
    click MG "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/blob/main/modules/codepipeline/github/main.tf"
    click MS "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/blob/main/modules/codepipeline/github/s3/main.tf"
    click PC "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/blob/main/patterns/fargate-cluster/main.tf"
    click PS "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/tree/main/patterns/aquasec-sidecar/Dockerfile"
    click GH "https://github.com/aws-samples/fargate-serverless-platform-operator-kit/blob/main/README.md"

    %% Styles
    classDef developer fill:#f9f,stroke:#333,stroke-width:1px
    classDef repo fill:#ccf,stroke:#333,stroke-width:1px
    classDef cicd fill:#cfc,stroke:#333,stroke-width:1px
    classDef iac fill:#fcf,stroke:#333,stroke-width:1px
    classDef aws fill:#cff,stroke:#333,stroke-width:1px
    classDef app fill:#ffc,stroke:#333,stroke-width:1px
    classDef integration fill:#fcc,stroke:#333,stroke-width:1px
```
