How ricardoqsx/playgrounds works
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)