# realpython/discover-flask architecture

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

- Interactive diagram: https://gitdiagram.com/realpython/discover-flask
- Repository: https://github.com/realpython/discover-flask

## Overview

##### Project type and purpose
- This is a full‑stack Flask web application (a learning/tutorial “Discover Flask” app) that demonstrates building a small blog‐style site with user authentication, templates, static assets, database persistence, migrations, and unit tests.

##### File structure
- Top level:
- run.py / manage.py – application entry points
- config.py – configuration variables (e.g., database URL, secret key)
- db_create.py, db_create_users.py, sql.py – helper scripts for initializing the database
- Procfile, .travis.yml – deployment/CI configuration (Heroku, Travis CI)
- requirements.txt – Python dependencies
- “project/” package:
- project/home/ and project/users/ – two Flask Blueprints (views, forms, templates for public and user areas)
- project/models.py – SQLAlchemy model definitions
- project/static/ – CSS/JS/images served at /static
- project/templates/base.html – shared layout; blueprint templates extend this
- “migrations/” directory – Alembic configuration and versioned migration scripts
- “tests/” directory – unit tests for core functionality, blog posts, and user flows

##### README for additional insights
- Confirms a tutorial progression: static site → login/auth → databases → migrations → testing → deployment to Heroku.
- Tech stack: Python, Flask microframework, Jinja2 for templating, SQLAlchemy ORM, Flask‑Migrate/Alembic, unit tests with pytest or unittest, deployed on Heroku, CI via Travis.

##### Elements
- Labels: “Browser,” “Heroku Router,” “WSGI Server,” “Flask App,” “Home Blueprint,” “Users Blueprint,” “SQLAlchemy Models,” “PostgreSQL DB,” “Alembic Migrations,” “Travis CI.”
- Request flow (Browser → Router → WSGI → Flask → DB)
- Response flow (DB → Flask → Browser)
- Trigger flows (Git push → Travis → Heroku)
- Client vs server vs database vs CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Browser["Web Browser"]:::client
    %% Infrastructure
    Router["Heroku Router"]:::infra
    WSGI["WSGI Server\n(Gunicorn/Flask dev)"]:::server
    Git["Git Push"]:::infra
    TravisCI["Travis CI"]:::infra
    HerokuDyno["Heroku Dyno\n(Procfile)"]:::infra

    %% Application Entry Points
    subgraph "Entry Points"
        run_py["run.py"]:::code
        manage_py["manage.py"]:::code
    end

    %% Configuration & Dependencies
    config["config.py"]:::code
    req["requirements.txt"]:::code

    %% Helper Scripts
    subgraph "Local DB Scripts"
        db_create["db_create.py"]:::code
        db_create_users["db_create_users.py"]:::code
        sql_script["sql.py"]:::code
    end

    %% Migrations
    migrations["migrations/"]:::db

    %% Flask Application
    subgraph "Flask Application" 
        App["Flask App"]:::server
        subgraph "Blueprints"
            Home["Home Blueprint"]:::server
            Users["Users Blueprint"]:::server
        end
        Models["Models & ORM\n(project/models.py)"]:::server
        Templates["Shared Templates"]:::server
        Static["Static Assets"]:::server
    end

    %% Home Blueprint Details
    subgraph "Home Blueprint Files"
        home_views["views.py"]:::code
        home_forms["forms.py"]:::code
        home_index["index.html"]:::code
        home_welcome["welcome.html"]:::code
    end

    %% Users Blueprint Details
    subgraph "Users Blueprint Files"
        users_views["views.py"]:::code
        users_forms["forms.py"]:::code
        login_html["login.html"]:::code
        register_html["register.html"]:::code
    end

    %% Shared Template
    base_html["base.html"]:::code

    %% Static Directory
    static_dir["project/static/"]:::code

    %% Database
    DB["PostgreSQL / SQLite"]:::db

    %% Tests
    subgraph "Unit Tests"
        t_base["tests/base.py"]:::test
        t_basic["tests/test_basic.py"]:::test
        t_blog["tests/test_blog.py"]:::test
        t_users["tests/test_users.py"]:::test
    end

    %% Relationships
    Browser -->|"HTTP Request"| Router
    Router -->|"forwards"| WSGI
    WSGI -->|"invokes"| App
    App -->|"route to"| Home
    App -->|"route to"| Users
    Home -->|uses| Models
    Users -->|uses| Models
    Models -->|"queries"| DB
    DB -->|"results"| Models
    Models -->|"data to"| App
    App -->|"render with"| Templates
    Templates -->|"extends"| base_html
    App -->|"serves"| Static
    App -->|"runs migrations"| migrations
    Git -->|"push code"| TravisCI
    TravisCI -->|"on success deploy"| HerokuDyno
    HerokuDyno -->|"runs"| migrations
    HerokuDyno -->|"launches"| WSGI

    %% Files integration
    App --> run_py
    App --> manage_py
    App --> config
    App --> req
    App --> db_create
    App --> db_create_users
    App --> sql_script

    Home --> home_views
    Home --> home_forms
    Home --> home_index
    Home --> home_welcome

    Users --> users_views
    Users --> users_forms
    Users --> login_html
    Users --> register_html

    Templates --> base_html
    Static --> static_dir

    %% Click Events
    click run_py "https://github.com/realpython/discover-flask/blob/master/run.py"
    click manage_py "https://github.com/realpython/discover-flask/blob/master/manage.py"
    click config "https://github.com/realpython/discover-flask/blob/master/config.py"
    click req "https://github.com/realpython/discover-flask/blob/master/requirements.txt"
    click db_create "https://github.com/realpython/discover-flask/blob/master/db_create.py"
    click db_create_users "https://github.com/realpython/discover-flask/blob/master/db_create_users.py"
    click sql_script "https://github.com/realpython/discover-flask/blob/master/sql.py"
    click migrations "https://github.com/realpython/discover-flask/tree/master/migrations/"
    click home_views "https://github.com/realpython/discover-flask/blob/master/project/home/views.py"
    click home_forms "https://github.com/realpython/discover-flask/blob/master/project/home/forms.py"
    click home_index "https://github.com/realpython/discover-flask/blob/master/project/home/templates/index.html"
    click home_welcome "https://github.com/realpython/discover-flask/blob/master/project/home/templates/welcome.html"
    click users_views "https://github.com/realpython/discover-flask/blob/master/project/users/views.py"
    click users_forms "https://github.com/realpython/discover-flask/blob/master/project/users/forms.py"
    click login_html "https://github.com/realpython/discover-flask/blob/master/project/users/templates/login.html"
    click register_html "https://github.com/realpython/discover-flask/blob/master/project/users/templates/register.html"
    click base_html "https://github.com/realpython/discover-flask/blob/master/project/templates/base.html"
    click static_dir "https://github.com/realpython/discover-flask/tree/master/project/static/"
    click t_base "https://github.com/realpython/discover-flask/blob/master/tests/base.py"
    click t_basic "https://github.com/realpython/discover-flask/blob/master/tests/test_basic.py"
    click t_blog "https://github.com/realpython/discover-flask/blob/master/tests/test_blog.py"
    click t_users "https://github.com/realpython/discover-flask/blob/master/tests/test_users.py"

    %% Styles
    classDef client fill:#ffd,stroke:#333;
    classDef server fill:#bbf,stroke:#333;
    classDef infra fill:#fbf,stroke:#333;
    classDef db fill:#bfb,stroke:#333;
    classDef code fill:#ffe,stroke:#333;
    classDef test fill:#ffb,stroke:#333;
```
