app_flask_archetype

Objectives

• A Flask archetype with common patterns to enable focusing on the unique aspects of your application instead of setup ceremony.
• Features:
  • Project Conversion
  • HTTP REST API
    • Application Logic Resource
    • Health Check Resource
    • Input Validator
  • External API Gateway
  • Repository Pattern implemented with SQLAlchemy and Postgres
  • Alembic Migrations
  • Tests
  • GitHub Actions CI/CD

Project Structure

• docs: Project documentation lives in here.

• src: Production code lives in this folder and is divided in the modules below:

  • app_flask_archetype: Project package.
    • api:
      • The HTTP API to the application lives in this module.
      • The current implementation is a HTTP REST API, but a gRPC, CLI API, etc would be implemented in here.
    • config:
      • Configuration lives in here.
    • core:
      • the domain logic of the application lives in this module.
    • gateway:
      • Integration with external objects(e.g. files, external APIs etc) lives in here.
    • model:
      • The domain model lives in here.
    • repository:
      • Integration with internal data store (persistence and access) lives in here.
    • app.py:
      • The application factory to bootstrap the system lives in here.

• tests: Test code lives in here.

  • The tests are intentionally separated from production code.
    • Benefits of this structure:
      • Tests can run against an installed version of the app after using pip install ..
      • Tests can run against the local copy with an editable install after executing pip install --edit.
    • more in depth discussion here

• utilities: Ad-hoc utilities such as scripts, curl & postman requests, JSON payloads, software installations, etc live in here.

Dependencies

• Docker

Package Management

• Pipenv
  • Quick Reference

Setup Instructions

• The repository is configured to use devcontainers for development.
  • Developing inside a Container

Usage

• Project Conversion: Converts the project name to your desired name. This renames all import, configuration, etc.

  #target_app_name is desired project name
  ./convert_project.sh target_app_name

• Steps Executed:
  • Renames all occurrences of app_flask_archetype to target_app_name
  • Optional Step: Rename the project folder to user desired project name. This is a manual step, it is the folder you cloned this repository into.

Run Program

• The system automatically starts up as part of loading the project into an editor/IDE that supports devcontainers.

  • If you would like to run the prod image, change dockerfile: Dockerfile.dev to dockerfile: Dockerfile in docker-compose.

• Manual

  • Execute the required update detailed here: app_flask_archetype_postgres_service

  • Manually start

    ./start_system_development.sh

  • Manually stop

    ./stop_system_development.sh

• Invoke an endpoint

  # specifically imports malaria_annual_confirmed_cases from WHO API
  ./utilities/curl/computation/computation.sh

• Debugging

  • Debug with VSCode:

    • Open the "Run and Debug" view.
    • Execute the "Python Debugger: Remote Attach" task.
      
    • Allow debugging without frozen modules by clicking "Debug Anyway".
    • The server will inform you the host and port in the terminal output at the bottom.
      
    • Debug as you normally do(i.e. add break points, step into code definitions, evaluate code snippets, etc)
      

  • If you would like to debug the prod image, change dockerfile: Dockerfile.dev to dockerfile: Dockerfile in docker-compose.debug.

Testing

• Execute Unit Tests

  pytest

• Execute Integration Tests

  pytest tests/app_flask_archetype/integration

• Execute System Tests

  Not Implemented

• Execute Spellcheck

  pyspelling -c spellcheck.yaml

Database State Management

• The database state (i.e. tables, stored procedures, indexes, etc) are managed using Alembic.
  • Migrations location: src/app_flask_archetype/migrations
  • Migrations naming scheme: YYYY_MM_DD_HHMM_rev_name
    • uses alembic's full revision scheme defined in alembic.ini
    • example: 2025_02_10_1349-9e2772c6755f_create_schema_computation.py
  • Current database state can be queried with SELECT * FROM public.alembic_version;
• To upgrade the database to latest migrations:

  alembic upgrade head

• To downgrade the database to the base state:

  alembic downgrade base

Spell Check

pyspelling -c spellcheck.yaml

Git Conventions

• NB: The main is locked and all changes must come through a Pull Request.
• Commit Messages:
  • Provide concise commit messages that describe what you have done.

    # example:
    git commit -m "feat(core): algorithm" -m"implement my new shiny faster algorithm"

  • screen shot of GitHub view
  • references:
    • https://www.conventionalcommits.org/en/v1.0.0/
    • https://www.freecodecamp.org/news/how-to-write-better-git-commit-messages/

Disclaimer: This is still work in progress.