backend-architecture

Backend Architecture Rules

Overview

This document defines the coding standards and architectural patterns for the Flask backend. These rules MUST be followed to maintain consistency, security, and code quality.

Authentication Standards

Protected Routes

• MUST use @require_authenticated_user decorator for all protected routes
• MUST NOT use @login_required or current_user from Flask-Login
• MUST NOT manually call get_current_user() in route functions
• MUST accept user as the first parameter in decorated route functions

Agent Routes

• MUST use @require_agent_access decorator for agent-only routes
• MUST NOT manually check user.is_agent in route functions — use user_is_agent(user) or @require_agent_access
• MUST use @require_agent_access instead of manual agent authorization checks

Examples

# ✅ CORRECT: Using decorator
from ..utils.common_patterns import require_authenticated_user

@user_bp.route('/profile', methods=['GET'])
@require_authenticated_user
def get_user_profile(user):
    from app.dtos.user import UserDTO
    return jsonify({'success': True, 'data': UserDTO.to_response(user)})

# ❌ WRONG: Manual authentication
from ..services.auth.current_user import get_current_user

@user_bp.route('/profile', methods=['GET'])
def get_user_profile():
    try:
        user = get_current_user()
        if not user:
            return jsonify({'error': 'Unauthorized'}), 401
        # ...
    except Exception as e:
        # ...

# ✅ CORRECT: Agent route
from ..utils.common_patterns import require_agent_access

@agent_bp.route('/clients', methods=['GET'])
@require_agent_access
def get_clients(user):
    # user is guaranteed to be an agent
    return jsonify({'success': True, 'clients': get_agent_clients(user.id)})

# ❌ WRONG: Manual agent check
@agent_bp.route('/clients', methods=['GET'])
def get_clients():
    user = get_current_user()
    if not user.is_agent:
        return jsonify({'error': 'Only agents can access this'}), 403
    # ...