# gimhandissanayake/flask-todo-app architecture

> Architecture diagram of the GitHub repository gimhandissanayake/flask-todo-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gimhandissanayake/flask-todo-app
- Repository: https://github.com/gimhandissanayake/flask-todo-app

## Overview

##### What this project is (type + purpose)
This is a small **server-rendered Flask web application** (“flask-todo-app”) that provides a **To‑Do UI** and persists data in a **PostgreSQL** backend. It also includes **database setup/migrations** (via SQL files and likely Flyway through `docker-compose.yml`).

From the repo layout and README:
- **Web tier:** `app.py` (Flask entrypoint) + `templates/index.html` (Jinja template)
- **Data tier:** PostgreSQL (run locally via Docker, plus provisioning scripts)
- **Schema management:** `migrations/V*.sql` and `docker-compose.yml` (commonly used to run Flyway migrations)
- **Containerization:** `Dockerfile`, `docker-compose.yml`

**Browser → Flask App → PostgreSQL**, with an additional **Migration/Provisioning lane**.

##### File tree signals (how to map code to components)
Use the file tree as a “component inventory”:

##### Runtime / application layer
- `app.py`
Main Flask app: routes, request handling, DB connection usage, CRUD for todos (implied).
- `templates/index.html`
Server-side rendered UI template. Indicates “HTML rendered by Flask”, not a SPA.

##### Database / schema layer
- `migrations/V1__create_database.sql`
- `migrations/V2__create_user.sql`
- `migrations/V3__grant_privilleges.sql`
- `db_setup/setup_database.sh` + `db_setup/README.md`
Manual/automated DB bootstrapping scripts. Represent as “DB bootstrap (optional/manual)”.

##### Packaging / deployment layer
- `docker-compose.yml`
Orchestrates multiple services (at least Postgres; possibly Flyway). Treat as “local orchestration / deployment topology”.
- `Dockerfile`
Container image for Flask app (or for something else if configured that way; usually the app).
- `.dockerignore`, `requirements.txt`
Build/runtime dependencies.

##### Configuration
- `.env` described in README: `DATABASE_URL`, plus `DB_PASSWORD`, `TODO_PASSWORD` (for compose/migrations). Represent as “Environment Config / Secrets”.

##### Client Browser
- Sends HTTP requests to Flask (GET `/`, POST to create, etc.).
##### Flask App (app.py)
- Renders HTML via Jinja (`templates/index.html`)
- Executes SQL queries (directly or via a driver) against Postgres using `DATABASE_URL`
##### PostgreSQL
- Stores todo items (tables implied)

- Browser → Flask: HTTP (request)
- Flask → Browser: HTML (response)
- Flask ↔ Postgres: SQL over TCP 5432 (queries/results)

##### Schema / provisioning flow (ops/deploy-facing)
1. **Flyway (or migration runner)** uses `migrations/V*.sql` to apply schema changes to Postgres.
2. **db_setup/setup_database.sh** may create DB/user/privileges (especially for local/dev), or migrations do this (your SQL files suggest DB/user/grants are managed via migrations).

- Migration tool / script → Postgres: “apply migrations / create roles / grants”
- `.env`/compose variables → migration tool + Flask app (configuration input)

This separation is important: runtime path vs lifecycle path.

##### Architectural patterns to call out explicitly
- **Server-side rendered MVC-ish Flask**: routes/controllers in `app.py`, views in `templates/`.
- **Single service + single database** (monolith web app).
- **Versioned migrations** (`migrations/V*__*.sql`) as the canonical schema evolution mechanism.
- **Containerized local deployment** via Docker / Compose.

##### Flask Web App Container
- sub-label: “Jinja templates – templates/index.html”
- sub-label: “Dependencies – requirements.txt”
##### Config/Secrets

- Browser → Flask: HTTP :5000
- Flask → Postgres: SQL/TCP :5432 using DATABASE_URL
- Flyway/Setup → Postgres: migration DDL / role creation / grants
- Config → Flask and Config → Migration Tool: env injection

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% External actors
  U["User / Browser"]:::external

  %% Host machine boundary
  subgraph Host["Host Machine"]
    HPorts["Published Ports\n- HTTP :5000\n- Postgres :5432 (optional for tools)"]:::infra
    Env["Environment Config / Secrets\n(.env)\n- DATABASE_URL\n- DB_PASSWORD\n- TODO_PASSWORD"]:::config
    Compose["Local Orchestration\nDocker Compose"]:::infra
  end

  %% Deployment boundary (vertical layout)
  subgraph Net["Docker Compose Network (local)"]
    subgraph WebTier["Web Tier (Runtime)"]
      Flask["Flask Web App (Python)\nRoutes/Controllers\nSSR HTML"]:::runtime
      AppPy["app.py"]:::code
      TemplatesDir["templates/"]:::code
      IndexHtml["templates/index.html\n(Jinja Template)"]:::artifact
      Req["requirements.txt\n(Python deps)"]:::artifact
    end

    subgraph DataTier["Data Tier"]
      PG[("PostgreSQL\n(todo_db)\nTCP :5432")]:::database
    end

    subgraph SchemaTier["Schema / Provisioning (Lifecycle)"]
      Flyway["Migration Runner\n(e.g., Flyway via Compose)"]:::ops
      MigrationsDir["migrations/"]:::ops
      V1["V1__create_database.sql"]:::artifact
      V2["V2__create_user.sql"]:::artifact
      V3["V3__grant_privilleges.sql"]:::artifact
      DBSetupDir["db_setup/"]:::ops
      SetupSh["setup_database.sh\n(optional/manual bootstrap)"]:::ops
      SetupReadme["README.md\n(DB setup docs)"]:::artifact
    end

    DockerfileN["Dockerfile\n(App image build)"]:::infra
  end

  %% Runtime request flow
  U -->|"HTTP :5000 (request)"| Flask
  Flask -->|"HTML (Jinja) (response)"| U
  Flask <-->|"SQL/TCP :5432\nuses DATABASE_URL"| PG

  %% SSR composition / dependencies
  AppPy -->|"defines_routes/templates"| Flask
  TemplatesDir -->|"view_layer"| Flask
  IndexHtml -->|"rendered_by"| Flask
  Req -->|"installs_deps_for"| Flask

  %% Lifecycle / migration flow
  Compose -->|"orchestrates_services"| Flask
  Compose -->|"orchestrates_services"| PG
  Compose -->|"orchestrates_services"| Flyway

  MigrationsDir -->|"contains"| V1
  MigrationsDir -->|"contains"| V2
  MigrationsDir -->|"contains"| V3
  MigrationsDir -->|"fed_to"| Flyway
  Flyway -->|"apply_migrations (DDL/roles/grants)"| PG

  DBSetupDir -->|"contains"| SetupSh
  DBSetupDir -->|"contains"| SetupReadme
  SetupSh -->|"bootstrap_db/users (optional)"| PG

  %% Config injection
  Env -->|"env_injection"| Flask
  Env -->|"env_injection"| Flyway

  %% Build/packaging
  DockerfileN -->|"builds_image_for"| Flask
  Compose -->|"reads_env"| Env
  Compose -->|"publishes_ports"| HPorts

  %% Click events (paths only; not visible)
  click AppPy "https://github.com/gimhandissanayake/flask-todo-app/blob/main/app.py"
  click IndexHtml "https://github.com/gimhandissanayake/flask-todo-app/blob/main/templates/index.html"
  click TemplatesDir "https://github.com/gimhandissanayake/flask-todo-app/tree/main/templates/"
  click V1 "https://github.com/gimhandissanayake/flask-todo-app/blob/main/migrations/V1__create_database.sql"
  click V2 "https://github.com/gimhandissanayake/flask-todo-app/blob/main/migrations/V2__create_user.sql"
  click V3 "https://github.com/gimhandissanayake/flask-todo-app/blob/main/migrations/V3__grant_privilleges.sql"
  click MigrationsDir "https://github.com/gimhandissanayake/flask-todo-app/tree/main/migrations/"
  click SetupSh "https://github.com/gimhandissanayake/flask-todo-app/blob/main/db_setup/setup_database.sh"
  click SetupReadme "https://github.com/gimhandissanayake/flask-todo-app/blob/main/db_setup/README.md"
  click DBSetupDir "https://github.com/gimhandissanayake/flask-todo-app/tree/main/db_setup/"
  click Compose "https://github.com/gimhandissanayake/flask-todo-app/blob/main/docker-compose.yml"
  click DockerfileN "https://github.com/gimhandissanayake/flask-todo-app/tree/main/Dockerfile"
  click Req "https://github.com/gimhandissanayake/flask-todo-app/blob/main/requirements.txt"

  %% Styles
  classDef external fill:#ffffff,stroke:#334155,stroke-width:1.5px,color:#0f172a
  classDef runtime fill:#dbeafe,stroke:#1d4ed8,stroke-width:1.5px,color:#0b1b3a
  classDef database fill:#dcfce7,stroke:#166534,stroke-width:1.5px,color:#052e16
  classDef ops fill:#ffedd5,stroke:#c2410c,stroke-width:1.5px,color:#3b1406
  classDef config fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
  classDef infra fill:#ede9fe,stroke:#5b21b6,stroke-width:1.5px,color:#1f1147
  classDef artifact fill:#fff7ed,stroke:#9a3412,stroke-width:1.2px,color:#2b1208
  classDef code fill:#e0f2fe,stroke:#0369a1,stroke-width:1.2px,color:#0c2a3a
```
