Fullstack Blueprint Engineering
Comprehensive architectural guidance for Flask web applications, covering backend API design, database modeling, and frontend integration patterns.
Overview
This skill provides end-to-end technical guidance for Flask application development, from initial blueprint structure through production deployment. Whether you're designing RESTful APIs, modeling complex database relationships, or integrating modern frontend frameworks, this skill delivers proven architectural patterns and implementation strategies.
Core Capabilities
- Blueprint Architecture: Modular application structure with feature-based organization
- Database Design: SQLAlchemy ORM patterns, migration strategies, and query optimization
- API Development: RESTful endpoint design, versioning, authentication, and documentation
- Frontend Integration: Vue.js, React, and other SPA framework integration patterns
- Authentication & Security: Flask-Security, JWT tokens, role-based access control
- Testing Strategies: Unit testing, integration testing, and API contract validation
Blueprint Organization
Organize features as self-contained modules with clear boundaries:
application/
├── core/
│ ├── __init__.py
│ ├── models.py # Core domain models
│ ├── views.py # Main routes
│ └── services.py # Business logic
├── auth/
│ ├── __init__.py
│ ├── models.py # User, Role models
│ ├── views.py # Login, register endpoints
│ └── decorators.py # Auth decorators
├── api/
│ └── v1/
│ ├── products.py
│ ├── orders.py
│ └── users.py
Each blueprint should be independently testable and loosely coupled from other modules.
Database Modeling Patterns
Use declarative base models with relationship mapping:
from flask_sqlalchemy import SQLAlchemy
from datetime import datetime
db = SQLAlchemy()
class BaseModel:
"""Base mixin for common columns"""
id = db.Column(db.Integer, primary_key=True)
created_at = db.Column(db.DateTime, default=datetime.utcnow, nullable=False)
updated_at = db.Column(db.DateTime, default=datetime.utcnow,
def to_dict(self):
"""Serialize model to dictionary"""
raise NotImplementedError
def from_dict(self, data):
"""Populate model from dictionary"""
raise NotImplementedError
class Product(db.Model, BaseModel):
__tablename__ = 'products'
name = db.Column(db.String(200), nullable=False, index=True)
description = db.Column(db.Text)
price = db.Column(db.Numeric(10, 2), nullable=False)
category_id = db.Column(db.Integer, db.ForeignKey('categories.id'))
category = db.relationship('Category', backref='products', lazy='joined')
def to_dict(self):
return {
'id': self.id,
'name': self.name,
'description': self.description,
'price': str(self.price),
'category': self.category.name if self.category else None,
'created_at': self.created_at.isoformat()
}
RESTful API Design
Structure endpoints with consistent patterns:
from flask import Blueprint, request, jsonify
from flask_jwt_extended import jwt_required, get_jwt_identity
from marshmallow import ValidationError
api_bp = Blueprint('api', __name__, url_prefix='/api/v1')
@api_bp.route('/products', methods=['GET'])
def list_products():
"""List products with pagination and filtering"""
page = request.args.get('page', 1, type=int)
per_page = request.args.get('per_page', 20, type=int)
category = request.args.get('category', type=str)
query = Product.query
if category:
query = query.join(Category).filter(Category.name == category)
pagination = query.paginate(page=page, per_page=per_page, error_out=False)
return jsonify({
'items': [p.to_dict() for p in pagination.items],
'total': pagination.total,
'page': page,
'pages': pagination.pages
})
@api_bp.route('/products', methods=['POST'])
@jwt_required()
def create_product():
"""Create new product"""
try:
data = request.get_json()
product = Product()
product.from_dict(data)
db.session.add(product)
db.session.commit()
return jsonify(product.to_dict()), 201
except ValidationError as e:
return jsonify({'errors': e.messages}), 400
@api_bp.route('/products/<int:product_id>', methods=['PUT'])
@jwt_required()
def update_product(product_id):
"""Update existing product"""
product = Product.query.get_or_404(product_id)
product.from_dict(request.get_json())
db.session.commit()
return jsonify(product.to_dict())
@api_bp.route('/products/<int:product_id>', methods=['DELETE'])
@jwt_required()
def delete_product(product_id):
"""Delete product"""
product = Product.query.get_or_404(product_id)
db.session.delete(product)
db.session.commit()
return '', 204
Authentication Patterns
Implement JWT-based authentication for API endpoints:
from flask_jwt_extended import JWTManager, create_access_token
from werkzeug.security import check_password_hash
jwt = JWTManager()
@api_bp.route('/auth/login', methods=['POST'])
def login():
"""Authenticate user and return JWT token"""
data = request.get_json()
user = User.query.filter_by(email=data.get('email')).first()
if user and check_password_hash(user.password_hash, data.get('password')):
access_token = create_access_token(identity=user.id)
return jsonify({
'access_token': access_token,
'user': user.to_dict()
})
return jsonify({'error': 'Invalid credentials'}), 401
Frontend Integration
Serve single-page applications alongside API endpoints:
from flask import send_from_directory
import os
@app.route('/', defaults={'path': ''})
@app.route('/<path:path>')
def serve_spa(path):
"""Serve React/Vue build"""
static_folder = os.path.join(app.root_path, 'static', 'dist')
if path and os.path.exists(os.path.join(static_folder, path)):
return send_from_directory(static_folder, path)
return send_from_directory(static_folder, 'index.html')
Testing Strategies
Write comprehensive tests for all API endpoints:
import pytest
from application import create_app, db
from application.models import Product
@pytest.fixture
def client():
app = create_app('testing')
with app.test_client() as client:
with app.app_context():
db.create_all()
yield client
db.drop_all()
def test_create_product(client):
"""Test product creation endpoint"""
response = client.post('/api/v1/products', json={
'name': 'Test Product',
'price': '29.99',
'category_id': 1
})
assert response.status_code == 201
data = response.get_json()
assert data['name'] == 'Test Product'
def test_list_products_pagination(client):
"""Test product listing with pagination"""
response = client.get('/api/v1/products?page=1&per_page=10')
assert response.status_code == 200
data = response.get_json()
assert 'items' in data
assert 'total' in data
Production Considerations
- Database Connection Pooling: Configure SQLAlchemy pool size based on expected load
- Caching Strategy: Implement Redis/Memcached for frequently accessed data
- Error Handling: Use application-wide error handlers with structured logging
- Rate Limiting: Apply Flask-Limiter to prevent API abuse
- CORS Configuration: Configure allowed origins for cross-domain requests
- Environment Configuration: Use environment-specific config classes
- Migration Management: Use Alembic for database schema versioning
Common Patterns
Service Layer Pattern
Separate business logic from route handlers:
class ProductService:
@staticmethod
def create_product(data):
"""Create product with validation"""
product = Product()
product.from_dict(data)
db.session.add(product)
db.session.commit()
return product
@staticmethod
def get_products_by_category(category_name, page=1):
"""Retrieve paginated products by category"""
return Product.query.join(Category)\
.filter(Category.name == category_name)\
.paginate(page=page, per_page=20)
Repository Pattern
Encapsulate data access logic:
class ProductRepository:
def find_by_id(self, product_id):
return Product.query.get(product_id)
def find_all(self, filters=None):
query = Product.query
if filters:
query = self._apply_filters(query, filters)
return query.all()
def save(self, product):
db.session.add(product)
db.session.commit()
return product
Best Practices
- Versioning: Always version APIs (e.g.,
/api/v1/) - Serialization: Use Marshmallow schemas for consistent data validation
- Logging: Log all database operations and API requests
- Documentation: Generate OpenAPI specs with Flask-RESTX or similar
- Security Headers: Enable HTTPS, HSTS, and CSP headers
- Input Validation: Validate and sanitize all user inputs
- Dependency Injection: Use application factory pattern for testability