# sagary2j/python-flask-hello-world architecture

> Architecture diagram of the GitHub repository sagary2j/python-flask-hello-world, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sagary2j/python-flask-hello-world
- Repository: https://github.com/sagary2j/python-flask-hello-world

## Overview

##### Project type and purpose
- This is a small, containerized Flask-based HTTP API service (“Hello World”), which can run locally (using SQLite) or in AWS (using DynamoDB). It is deployed via a CI/CD pipeline (GitHub Actions) onto AWS ECS, with infrastructure managed by Terraform.

##### File structure
- Top-level files:
- app.py / applocal.py – two entrypoints: one for DynamoDB (prod), one for SQLite (local).
- requirements.txt – Python dependencies.
- Dockerfile – containerizes the Flask app.
- setup.sh – bootstraps ECR repo and pushes initial image.
- terraform/ – Terraform modules and configuration for provisioning AWS resources (ECR, ECS, ALB, DynamoDB, S3 state bucket).
- .github/workflows/deploy.yml – GitHub Actions defines the CI/CD pipeline.
- tests/ – unit test for the API.
- .gitignore – excludes local artifacts.

##### README
- Describes two HTTP endpoints (PUT/GET) for user birthday management.
- Enumerates AWS services in use: ECS (EC2 launch type), DynamoDB, S3 (terraform state), CloudWatch (logs/metrics), ECR (container registry).
- Outlines the CI/CD workflow and Terraform-based infrastructure provisioning.

##### Main components
a. Developer Workflow
- GitHub Repository
- GitHub Actions (CI/CD)
- Docker build & push to Amazon ECR
- Terraform apply (reads .tf in repo, stores state in S3)
b. AWS Infrastructure
- AWS S3 bucket (Terraform state)
- AWS ECR (container registry)
- AWS ECS Cluster (EC2 instances running the container task)
- Application Load Balancer (public entry point)
- AWS DynamoDB table
- AWS CloudWatch (log groups + metrics)
c. Runtime Application
- Flask microservice container
- HTTP endpoints: PUT /hello/<username>, GET /hello/<username>

##### Relationships and data flows
- Developer pushes code → GitHub Actions kicks off CI/CD.
- CI/CD:
1. Build Docker image → Tag & Push to ECR.
2. Run Terraform (init, plan, apply) → Provision or update ECS, ALB, DynamoDB, S3 bucket.
- At runtime:
- Client request → ALB → ECS task (Flask container).
- Flask service → DynamoDB (Read/Write).
- Logs → CloudWatch.

##### Architectural patterns and design principles
- Infrastructure-as-Code (Terraform) for reproducible environment.
- Containerization (Docker) + immutable deployments.
- CI/CD pipeline (GitHub Actions) that ties code changes to infra/app deployments.
- Separation of concerns: application logic vs infra provisioning vs CI/CD.
- Two execution modes (local vs cloud) following the 12-factor app principle (config via environment).

##### Technologies and frameworks
- Python 3.8+, Flask 2.x
- Docker
- Terraform
- AWS ECS (EC2), ECR, DynamoDB, S3, CloudWatch
- GitHub Actions

##### Putting it all together
- Split AWS Runtime into ALB → ECS Container → DynamoDB.
- CloudWatch adjacent to ECS to capture logs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workflow Layer
    subgraph "Developer Workflow" 
        direction TB
        GitHub["GitHub Repository"]:::dev
        Actions["GitHub Actions (CI/CD)"]:::dev
        GitHub -->|push code| Actions
        Actions -->|build image| DockerBuild["Docker Build"]:::dev
        DockerBuild -->|push to| ECR["Amazon ECR"]:::aws
        Actions -->|run Terraform| Terraform["Terraform"]:::dev
    end

    %% AWS Control Plane Layer
    subgraph "AWS Control Plane"
        direction TB
        S3["AWS S3 (Terraform State)"]:::aws
        Terraform -->|reads/writes state| S3
        Terraform -->|provision| ECR
        Terraform -->|provision| ECSCluster["AWS ECS Cluster"]:::aws
        Terraform -->|provision| ALB["Application Load Balancer"]:::aws
        Terraform -->|provision| DynamoDB["Amazon DynamoDB"]:::aws
        Terraform -->|provision| CloudWatch["AWS CloudWatch"]:::aws
    end

    %% AWS Runtime Layer
    subgraph "AWS Runtime"
        direction TB
        Client["Client"]:::external
        Client -->|HTTP PUT/GET| ALB
        ALB -->|routes request| ECSCluster
        ECSCluster -->|hosts| Container["Flask Container"]:::container
        Container -->|reads/writes| DynamoDB
        Container -->|sends logs| CloudWatch
    end

    %% Local Development Inset
    subgraph "Local Development" 
        direction TB
        DevMachine["Developer Machine"]:::dev
        DevMachine -->|run| LocalApp["applocal.py"]:::container
        LocalApp -->|uses| SQLite["SQLite Database"]:::aws
    end

    %% Component Mapping Click Events
    click appPy "https://github.com/sagary2j/python-flask-hello-world/blob/develop/app.py"
    click applocalPy "https://github.com/sagary2j/python-flask-hello-world/blob/develop/applocal.py"
    click requirements "https://github.com/sagary2j/python-flask-hello-world/blob/develop/requirements.txt"
    click dockerfile "https://github.com/sagary2j/python-flask-hello-world/tree/develop/Dockerfile"
    click setupsh "https://github.com/sagary2j/python-flask-hello-world/blob/develop/setup.sh"
    click deployyml "https://github.com/sagary2j/python-flask-hello-world/blob/develop/.github/workflows/deploy.yml"
    click providertf "https://github.com/sagary2j/python-flask-hello-world/blob/develop/terraform/provider.tf"
    click maintf "https://github.com/sagary2j/python-flask-hello-world/blob/develop/terraform/main.tf"
    click datatf "https://github.com/sagary2j/python-flask-hello-world/blob/develop/terraform/data.tf"
    click variablestf "https://github.com/sagary2j/python-flask-hello-world/blob/develop/terraform/variables.tf"
    click outputstf "https://github.com/sagary2j/python-flask-hello-world/blob/develop/terraform/outputs.tf"
    click testappt "https://github.com/sagary2j/python-flask-hello-world/blob/develop/tests/test_app.py"
    click gitignore "https://github.com/sagary2j/python-flask-hello-world/blob/develop/.gitignore"
    click readme "https://github.com/sagary2j/python-flask-hello-world/blob/develop/README.md"

    %% Styles
    classDef aws fill:#ADD8E6,stroke:#1E90FF,color:#000000
    classDef dev fill:#D3D3D3,stroke:#696969,color:#000000
    classDef container fill:#FFA500,stroke:#FF8C00,color:#000000
    classDef external fill:#FFFFFF,stroke:#000000,color:#000000
```
