Milestone [4] Integration, Testing, and Documentation

[mcode-app]

View Milestone

---

Table of Contents

• Status
• Feature Overview
• Testing
• Architecture
• Suggested Order of Review

---

Status

All tasks in the milestone were successfully completed.

This milestone comprised 3 tasks:

1. Task 1: Flask application foundation and infrastructure
2. Task 2: SQLAlchemy models and Alembic migration scripts
3. Task 3: Users module with registration endpoint

---

Feature Overview

This milestone establishes the foundational infrastructure for migrating the Task Management REST API from TypeScript/NestJS to Python/Flask. It delivers:

• Flask Application Factory with environment-based configuration supporting development, testing, and production environments
• Database Connectivity via SQLAlchemy with PostgreSQL, including Alembic migrations for schema management
• User Registration Endpoint (POST /users) with bcrypt password hashing (10 rounds)
• Swagger Documentation via Flask-RESTX at /docs

After this milestone, developers can:

• Start the Flask application connected to PostgreSQL
• Register new users via POST /users with {"username": "...", "password": "..."}
• Access auto-generated Swagger documentation at /docs
• Run database migrations via flask db upgrade

---

Testing

Automated Testing

No automated tests were included in this milestone. Test infrastructure (pytest, pytest-flask) is specified in requirements.txt for future milestones.

Manual Testing

1. Environment Setup

   cd /l2l/dst/task-management-api
   cp .env.example .env
   # Edit .env with PostgreSQL credentials
   pip install -r requirements.txt

2. Run Migrations

   export FLASK_APP=src/app.py
   flask db upgrade

3. Start Application

   python src/app.py
   # Or: flask run --port 3000

4. Test User Registration

   curl -X POST http://localhost:3000/users/ \
     -H "Content-Type: application/json" \
     -d '{"username": "testuser", "password": "testpass123"}'

   Expected response (201):

   {"id": "<uuid>", "username": "testuser"}

5. Test Duplicate User (409 Conflict)

   curl -X POST http://localhost:3000/users/ \
     -H "Content-Type: application/json" \
     -d '{"username": "testuser", "password": "testpass123"}'

   Expected: 409 with {"message": "User 'testuser' already registered"}

6. Swagger Documentation
   Navigate to http://localhost:3000/docs to view API documentation.

---

Architecture

Overview

flowchart TD
    subgraph Client
        C[HTTP Client]
    end

    subgraph Flask Application
        AF[App Factory<br/>src/app.py]
        CFG[Config<br/>src/config.py]
        EXT[Extensions<br/>src/extensions.py]
        ERR[Error Handlers<br/>src/errors.py]
    end

    subgraph Users Module
        UC[Users Controller<br/>users_controller.py]
        US[Users Service<br/>users_service.py]
        UD[Users DTOs<br/>users_dto.py]
    end

    subgraph Database Layer
        UM[User Model<br/>users_model.py]
        TM[Task Model<br/>task_model.py]
        MIG[Alembic Migrations<br/>migrations/]
    end

    subgraph PostgreSQL
        DB[(PostgreSQL)]
    end

    C --> UC
    AF --> CFG
    AF --> EXT
    AF --> ERR
    AF --> UC
    UC --> US
    US --> UM
    UM --> DB
    TM --> DB
    MIG --> DB

    classDef new fill:#90EE90,stroke:#333
    classDef modified fill:#FFD700,stroke:#333
    
    class AF,CFG,EXT,ERR,UC,US,UD,UM,TM,MIG new

Loading

Legend: Green = New

Changes

Application Foundation (src/app.py, src/config.py, src/extensions.py)

• Application Factory Pattern: create_app(config_class) enables multiple configurations for testing and different environments
• Configuration Classes: Base Config, DevelopmentConfig, TestingConfig, ProductionConfig with environment variable loading via python-dotenv
• Extension Initialization: Flask-SQLAlchemy, Flask-Migrate, Flask-JWT-Extended, Flask-RESTX, Flask-Marshmallow instantiated in extensions.py and initialized in the factory

Error Handling (src/errors.py)

• Centralized error handlers for BadRequest, NotFound, Unauthorized, Conflict, and Marshmallow ValidationError
• Consistent JSON response format: {"message": "..."}
• Production-safe generic exception handler that logs errors without leaking details

Database Layer (src/db/, migrations/)

• User Model (src/users/users_model.py): UUID PK, username (unique), password_hash
• Task Model (src/task/task_model.py): UUID PK, title, description, status (default TO_DO), expiration_date (timestamptz)
• Alembic Migrations: 20170126_task_table.py creates task table with uuid-ossp extension; 20170131_user_table.py creates user table

Users Module (src/users/)

• Controller (users_controller.py): Flask-RESTX namespace at /users with POST / endpoint, Swagger models for documentation
• Service (users_service.py): create_user() with bcrypt hashing (10 rounds), duplicate detection; find_by_username() for auth module use
• DTOs (users_dto.py): UserCreateSchema for input validation, UserResponseSchema for output (excludes password_hash)

Design Decisions

Decision	Description	Justification
Application Factory Pattern	Use create_app(config_class) to instantiate Flask app	Enables different configurations for testing/production; standard Flask pattern matching NestJS module system
Werkzeug Exceptions + Centralized Handlers	Services raise Werkzeug HTTP exceptions (Conflict, BadRequest); handlers in errors.py convert to JSON	Maintains separation between business logic and HTTP concerns while ensuring consistent error formatting
Explicit Namespace Registration	Register Flask-RESTX namespaces centrally in create_app()	Provides clear visibility of all routes; matches NestJS pattern of explicit module imports in AppModule
Marshmallow for Validation	Use Marshmallow schemas instead of Flask-RESTX built-in validation	Provides richer validation capabilities (length constraints, custom error messages) matching class-validator behavior in source
SQLAlchemy with Direct Session Access	Services use db.session directly rather than a repository abstraction	Keeps architecture simple while maintaining service layer separation; appropriate for this API's complexity

---

Suggested Order of Review

1. requirements.txt - Dependencies and versions
2. src/config.py - Environment configuration and config classes
3. src/extensions.py - Flask extension instantiation
4. src/app.py - Application factory and namespace registration
5. src/errors.py - Centralized error handling
6. migrations/versions/20170126_task_table.py - Task table migration
7. migrations/versions/20170131_user_table.py - User table migration
8. src/task/task_model.py - Task SQLAlchemy model
9. src/users/users_model.py - User SQLAlchemy model
10. src/users/users_dto.py - Marshmallow validation schemas
11. src/users/users_service.py - Business logic and bcrypt hashing
12. src/users/users_controller.py - REST endpoint and Swagger documentation
13. .env.example - Environment variable template