# ricardoqsx/playgrounds architecture

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

- Interactive diagram: https://gitdiagram.com/ricardoqsx/playgrounds
- Repository: https://github.com/ricardoqsx/playgrounds

## Overview

##### Project type and purpose
- This is a full-stack web application built with Flask (Python) that serves as a CMS/blog playground. It exposes CRUD operations for users and articles, organized via Flask blueprints, and is packaged for deployment with Docker and Docker Compose.

##### File structure
- Top-level deployment artifacts:
- Dockerfile (builds the container image)
- compose.yaml (defines services and volumes for deployment)
- restart.sh (helper script to rebuild/restart the container)
- Source code under src/:
- run.py – application entry point, creates and runs the Flask app
- app/__init__.py – initializes the Flask app, registers blueprints
- app/models/ – data-access layer (blog_db.py, queries_db.py, admin_db.py)
- app/routes/ – controller layer, six blueprints handling admin, auth, home, debug, testing, users
- app/static/ – client-side assets (CSS, JS, images)
- app/templates/ – Jinja2 HTML templates for all views
- Configuration/dependencies: requirements.txt

##### Key insights from README
- The application uses Flask blueprints to modularize routes.
- Persistence is via a lightweight database (blog.db or CSV for demos), with potential to swap in MySQL.
- Docker Compose mounts the src folder into the container and abstracts the build/run cycle.
- Objectives include two CRUD domains (users, articles) with differing permission levels.

##### Components
a. External Actor
- User’s Browser (mobile/desktop client)
b. Infrastructure / Deployment
- Docker Engine & Compose
- Web App Container (built from Dockerfile)
- (Optional) External Database Service container (MySQL) if in production
- Host Volume mount for code and persistent DB file
c. Application Layers (inside Web App container)
- run.py & app factory – bootstraps the Flask application
- Blueprint registry (controllers) – admin_bp, auth_bp, home_bp, debug_bp, testing_bp, users_bp
- Models layer – admin_db, queries_db, users; data-access abstractions
- Templates – Jinja2 layouts and views
- Static assets – CSS, JS, images
d. Data Store
- SQLite file (blog.db) or MySQL database
e. (Optional) External Services
- CDN for static assets (future)
- Authentication provider or email service (future)

##### Relationships and data flow
1. Browser sends HTTP request → Docker host → Flask WSGI server
2. run.py routes request to registered Blueprint (controller)
3. Controller calls Models layer to perform CRUD on DB
4. Models layer issues SQL (to SQLite or MySQL via connector)
5. DB responds → Models return data to controller
6. Controller selects a Jinja2 template and static assets → generates HTML response
7. Flask serves rendered HTML/CSS/JS back to browser

##### Architectural patterns and principles
- Layered (MVC-like) separation: Models, Views (templates & static), Controllers (blueprints)
- Modularization via Flask Blueprints
- Infrastructure as code: Dockerfile + Compose for consistent environments
- Single container vs. multi-service (if DB is also containerized)

##### Essential details to capture
- Docker Compose service definitions (app, optional db) and their relationship
- The Flask application factory pattern in run.py registering blueprints
- Blueprint modules as separate controller components
- Models classes/files as data-access components
- The template folder and static folder served by Flask’s built-in server
- Persistence mechanism (file-based DB vs. external RDBMS)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Actor
    Browser["User Browser (Mobile/Desktop)"]:::external

    %% Infrastructure Layer
    subgraph "Infrastructure"  
        direction TB
        DockerHost["Docker Host OS"]:::infra
        Compose["Docker Compose"]:::infra
        DockerfileNode["Dockerfile"]:::infra
        RestartScript["restart.sh"]:::infra
        Compose -->|orchestrates| DockerfileNode
        Compose -->|orchestrates| RestartScript
    end

    Browser -->|HTTP Request| DockerHost

    DockerHost -->|runs| Compose

    %% Containers
    subgraph "Containers"
        direction TB
        WebAppContainer["Web App Container"]:::infra
        DBContainer["MySQL DB Service (optional)"]:::data
        Volume["Host Volume Mount\n(src/ & blog.db)"]:::infra
        Compose -->|spins up| WebAppContainer
        Compose -->|spins up| DBContainer
        DBContainer -->|data store| Volume
        WebAppContainer -->|mounts| Volume
    end

    %% Application Inside WebAppContainer
    subgraph "Web App Container"
        direction TB
        RunPy["run.py\n(Flask App Entry)"]:::app
        InitApp["app/__init__.py\n(App Factory)"]:::app

        subgraph "Controllers (Flask Blueprints)"
            direction TB
            AdminBP["admin_bp"]:::app
            AuthBP["auth_bp"]:::app
            HomeBP["home_bp"]:::app
            DebugBP["debug_bp"]:::app
            TestingBP["testing_bp"]:::app
            UsersBP["users_bp"]:::app
        end

        subgraph "Models (Data Access)"
            direction TB
            AdminDB["admin_db.py"]:::app
            QueriesDB["queries_db.py"]:::app
            UsersModel["users.py"]:::app
            BlogCSV["blog.csv"]:::data
        end

        subgraph "Views"
            direction TB
            Templates["Templates (Jinja2)"]:::view
            StaticAssets["Static Assets"]:::asset
        end

        RunPy -->|bootstraps| InitApp
        InitApp -->|registers| AdminBP
        InitApp -->|registers| AuthBP
        InitApp -->|registers| HomeBP
        InitApp -->|registers| DebugBP
        InitApp -->|registers| TestingBP
        InitApp -->|registers| UsersBP

        AdminBP -->|uses| AdminDB
        AuthBP -->|uses| QueriesDB
        HomeBP -->|uses| QueriesDB
        DebugBP -->|uses| QueriesDB
        TestingBP -->|uses| QueriesDB
        UsersBP -->|uses| UsersModel

        AdminDB -->|reads/writes| Volume
        QueriesDB -->|executes SQL| Volume
        UsersModel -->|reads/writes| Volume
        BlogCSV -->|demo persistence| Volume

        AdminBP -->|renders| Templates
        AuthBP -->|renders| Templates
        HomeBP -->|renders| Templates
        DebugBP -->|renders| Templates
        TestingBP -->|renders| Templates
        UsersBP -->|renders| Templates

        Templates -->|served via| StaticAssets
    end

    WebAppContainer -->|HTTP Response| Browser

    %% Click Events
    click DockerfileNode "https://github.com/ricardoqsx/playgrounds/tree/master/Dockerfile"
    click Compose "https://github.com/ricardoqsx/playgrounds/blob/master/compose.yaml"
    click RestartScript "https://github.com/ricardoqsx/playgrounds/blob/master/restart.sh"
    click RunPy "https://github.com/ricardoqsx/playgrounds/blob/master/src/run.py"
    click InitApp "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/__init__.py"
    click AdminBP "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/routes/admin_bp.py"
    click AuthBP "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/routes/auth_bp.py"
    click HomeBP "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/routes/home_bp.py"
    click DebugBP "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/routes/debug_bp.py"
    click TestingBP "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/routes/testing_bp.py"
    click UsersBP "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/routes/users_bp.py"
    click AdminDB "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/models/admin_db.py"
    click QueriesDB "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/models/queries_db.py"
    click UsersModel "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/models/users.py"
    click BlogCSV "https://github.com/ricardoqsx/playgrounds/blob/master/src/app/models/blog.csv"
    click Templates "https://github.com/ricardoqsx/playgrounds/tree/master/src/app/templates/"
    click StaticAssets "https://github.com/ricardoqsx/playgrounds/tree/master/src/app/static/"

    %% Styles
    classDef infra fill:#d4f1be,stroke:#2d572c,color:#2d572c;
    classDef app fill:#cfe2f3,stroke:#084298,color:#084298;
    classDef data fill:#fff3cd,stroke:#664d03,color:#664d03;
    classDef view fill:#fce5cd,stroke:#a64d14,color:#a64d14;
    classDef asset fill:#fde2e2,stroke:#b02a37,color:#b02a37;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
