# fureasu/simple-flask architecture

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

- Interactive diagram: https://gitdiagram.com/fureasu/simple-flask
- Repository: https://github.com/fureasu/simple-flask

## Overview

##### Project Type & Purpose
- This is a containerized, single‐service web application built in Flask and served by Gunicorn.
- It’s intended as a simple CI/CD demo: four endpoints (home, cookies, input, picture), writes to local files, sets cookies, and reports health.
- Supports local development via Docker Compose and production deployment via AWS ECS, with CI pipelines defined in GitHub Actions.

##### File‐Structure Analysis
- Top‐level:
- Dockerfile + docker‐compose.yml → container build & local orchestration
- ecs‐task‐definition‐template.json → AWS ECS service definition
- .github/workflows/…yml → CI/CD workflows (dev & staging)
- app/ → application code & config
- tests/ → pytest unit tests & fixtures
- app/simpleflask/ → Flask blueprints for each page (cookies, input, picture, health, home), plus templates & static assets.
- Configuration files: .env, gunicorn.conf.py, requirements.txt, pytest.ini.

##### Key Components to Render
a. Client / User’s Browser
b. CI/CD Pipeline
– GitHub Actions (simple‐flask‐dev.yml & simple‐flask‐stg.yml)
– Steps: code checkout → dependency install → pytest → Docker build → push to registry → deploy to ECS
c. Docker Registry (Docker Hub or ECR)
d. Deployment Targets
– Local: Docker Compose
– Staging/Production: AWS ECS Service & Task (ecs-task-definition-template.json) behind a Load Balancer
e. Containerized Service
– Gunicorn process
– Flask app modules (endpoints)
– Environment variables injected (APP_DATA_PATH, APP_LOG_PATH, APP_PORT)
– Mounted volumes for data & logs
f. Persistent Storage
– Docker volumes or host paths for /data and /log

##### Interactions & Data Flows
- User → HTTP Request → Load Balancer (ECS) → Container:Gunicorn → Flask route handler → possibly write/read a file on volume → render template or JSON → Response → User
- CI/CD: Git push → GitHub Actions → test/build/push → ECS deployment API → new task revision

##### Architectural Patterns & Principles
- Twelve-factor app: stateless container, config via env vars, port binding.
- Single‐responsibility microservice: each endpoint in its own module.
- Infrastructure as code: ECS task template + Docker Compose for dev parity.
- Automated CI/CD promoting build→test→deploy in one flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes/Zones
    subgraph "Development Environment"
        direction TB
        Developer["Developer"]:::compute
        DockerCompose["Docker Compose"]:::compute
        Developer -->|uses| DockerCompose
        DockerCompose -->|starts| Container
    end

    subgraph "CI/CD Pipeline"
        direction TB
        Developer -.->|push code| GitHubActions["GitHub Actions Runner"]:::compute
        GitHubActions -->|Docker build & push| Registry["Docker Registry"]:::cloud
        GitHubActions -->|ECS Deploy API| ECSService["AWS ECS Service"]:::cloud
    end

    subgraph "Production Environment"
        direction TB
        LoadBalancer["Load Balancer"]:::cloud
        ECSService -->|serves via| LoadBalancer
        LoadBalancer -->|HTTP/HTTPS| Container
    end

    %% Runtime User Flow
    User["User (Browser)"]:::external
    User -->|HTTP request| LoadBalancer
    Container -->|HTTP response| User

    %% Container and Internals
    subgraph "Container (Gunicorn + Flask)" 
        direction TB
        AppEntry["app/app.py"]:::compute
        GunicornConf["app/gunicorn.conf.py"]:::compute
        EnvVars["app/.env"]:::compute
        Requirements["requirements.txt"]:::compute
        subgraph "Flask Endpoints"
            direction TB
            HomeEP["home.py"]:::compute
            CookiesEP["cookies.py"]:::compute
            InputEP["input.py"]:::compute
            PictureEP["picture.py"]:::compute
            HealthEP["health.py"]:::compute
        end
        subgraph "Assets & Templates"
            direction TB
            Templates["app/simpleflask/templates/"]:::compute
            Static["app/simpleflask/static/"]:::compute
        end
        AppEntry -->|imports| HomeEP
        AppEntry -->|imports| CookiesEP
        AppEntry -->|imports| InputEP
        AppEntry -->|imports| PictureEP
        AppEntry -->|imports| HealthEP
        AppEntry -->|loads| Templates
        AppEntry -->|serves| Static
    end

    %% Volumes
    DataVol["/data Volume"]:::storage
    LogVol["/log Volume"]:::storage
    Container -->|mount| DataVol
    Container -->|mount| LogVol

    %% Persistent Storage
    subgraph "Persistent Storage"
        DataVol
        LogVol
    end

    %% CI/CD Registry Flow
    Registry -->|pull image| ECSService

    %% Click Events
    click DockerCompose "https://github.com/fureasu/simple-flask/blob/main/docker-compose.yml"
    click Dockerfile "https://github.com/fureasu/simple-flask/tree/main/Dockerfile"
    click ECSService "https://github.com/fureasu/simple-flask/blob/main/ecs-task-definition-template.json"
    click GitHubActions "https://github.com/fureasu/simple-flask/blob/main/.github/workflows/simple-flask-dev.yml"
    click GitHubActions "https://github.com/fureasu/simple-flask/blob/main/.github/workflows/simple-flask-stg.yml"
    click AppEntry "https://github.com/fureasu/simple-flask/blob/main/app/app.py"
    click GunicornConf "https://github.com/fureasu/simple-flask/blob/main/app/gunicorn.conf.py"
    click EnvVars "https://github.com/fureasu/simple-flask/blob/main/app/.env"
    click Requirements "https://github.com/fureasu/simple-flask/blob/main/requirements.txt"
    click pytest "https://github.com/fureasu/simple-flask/blob/main/pytest.ini"
    click TestsDir "https://github.com/fureasu/simple-flask/tree/main/tests/"
    click Conftest "https://github.com/fureasu/simple-flask/blob/main/tests/conftest.py"
    click TestClear "https://github.com/fureasu/simple-flask/blob/main/tests/test_clear_input.py"
    click TestCookies "https://github.com/fureasu/simple-flask/blob/main/tests/test_cookies.py"
    click TestHealth "https://github.com/fureasu/simple-flask/blob/main/tests/test_health.py"
    click TestInput "https://github.com/fureasu/simple-flask/blob/main/tests/test_input.py"
    click TestLog "https://github.com/fureasu/simple-flask/blob/main/tests/test_log.py"
    click TestPicture "https://github.com/fureasu/simple-flask/blob/main/tests/test_picture.py"
    click HomeEP "https://github.com/fureasu/simple-flask/blob/main/app/simpleflask/home.py"
    click CookiesEP "https://github.com/fureasu/simple-flask/blob/main/app/simpleflask/cookies.py"
    click InputEP "https://github.com/fureasu/simple-flask/blob/main/app/simpleflask/input.py"
    click PictureEP "https://github.com/fureasu/simple-flask/blob/main/app/simpleflask/picture.py"
    click HealthEP "https://github.com/fureasu/simple-flask/blob/main/app/simpleflask/health.py"
    click Templates "https://github.com/fureasu/simple-flask/tree/main/app/simpleflask/templates/"
    click Static "https://github.com/fureasu/simple-flask/tree/main/app/simpleflask/static/"

    %% Styles
    classDef compute fill:#D6EAF8,stroke:#2E86C1,stroke-width:1px
    classDef storage fill:#D5F5E3,stroke:#28B463,stroke-width:1px
    classDef cloud fill:#F9E79F,stroke:#D68910,stroke-width:1px
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:1px
```
