How jack-samu/the-blog-backend works
Project Type and Purpose
• This is a Flask-based RESTful back-end for a blog application.
• It exposes HTTP API endpoints (grouped into auth, article, comment) to handle authentication, article management, commenting, and related business logic.
• Data persistence is in MySQL (initialized via init.sql and Flask-Migrate), and the service is containerized with Docker for easy deployment.
File Structure Analysis
Top-level
• run.py – entry point, loads app, runs Flask server
• init.sql – initial schema seed for MySQL
• requirements.txt – Python dependencies
app/
• config.py – application configuration (DB URI, mail, JWT, etc.)
• extensions.py – initializes extensions (SQLAlchemy, Migrate, JWT, Mail, CORS)
• hooks.py – request/response hooks or interceptors
• events.py – domain‐level events (e.g., email notifications)
• models/ – SQLAlchemy ORM models (Article, Comment, Auth/User, etc.)
• routes/ – Flask Blueprints (auth.py, article.py, comment.py) defining HTTP controllers
• services/ – business logic layer (article_services.py, etc.)
• utils/ – helper functions (validators, email templates, auth utils)
Insights from README
• Blueprint modularization into auth, article, comment modules.
• JWT-based auth with token refresh, three-stage password reset.
a. Main Components
1. Client(s): Web UI or mobile apps
2. API Gateway (Flask application)
– Blueprints: Auth, Article, Comment (controllers)
– Hooks/Interceptors (e.g., JWT verification, error handling)
– Extensions: SQLAlchemy, Flask-Migrate, Flask-Mail, JWT, CORS
3. Service Layer: article_services, auth workflows, comment_services
4. Data Layer: SQLAlchemy models → MySQL database
5. External Services:
– SMTP/email provider (for password reset)
– Dockerized MySQL instance
6. Optional Background/Event Processor: events.py triggers (e.g., email dispatch)
b. Relationships & Data Flow
• Clients → HTTP requests → Flask Blueprints (controllers)
• Controllers → call Services → perform business logic
• Services → interact with Models → ORM queries → MySQL
• Controllers/Services → trigger Events (e.g., send email) → External SMTP
• Hooks intercept incoming/outgoing requests (JWT refresh, error mapping)
c. Architectural Patterns & Principles
• Layered architecture:
• Presentation Layer (routes/controllers)
• Business Layer (services)
• Data Access Layer (models + ORM)
• Modularization via Blueprints for separation of concerns
• Event-driven notifications (events.py) for decoupling side effects
• Configuration & extensions centralized for easier testing and deployment
d. Key Technologies & Frameworks
• Flask & Flask-Blueprints
• SQLAlchemy + Flask-Migrate (DB migrations)
• PyJWT (JWT token handling)
• Flask-Mail (email)
• Docker (MySQL container)
• Python utilities: validators, util.py