# josetorresmx/habit-tracking-api architecture

> Architecture diagram of the GitHub repository josetorresmx/habit-tracking-api, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josetorresmx/habit-tracking-api
- Repository: https://github.com/josetorresmx/habit-tracking-api

## Overview

##### Project type and purpose
- This is a backend-only RESTful web API (“web-api-habits”) built using Python and Flask.
- It exposes endpoints for habit-tracking features (CRUD operations on user habits) with JWT-based authentication and MySQL persistence.

##### File structure
- Top-level files:
– run.py – application entrypoint (initializes app, loads config, launches WSGI server)
– config.py – configuration (DB URIs, secret keys, JWT settings)
– requirements.txt – Python dependencies (Flask, Flask-JWT-Extended, SQLAlchemy, Flask-MySQL, etc.)
– db/htracker_backup.sql – database schema dump for MySQL
– gen_SK.py – utility to generate/rotate secret keys
- app/ directory: core Flask package
– __init__.py – creates Flask app instance, registers blueprints, sets up extensions
– auth.py – authentication blueprint: login, registration, token management (JWT, Bcrypt)
– models.py – ORM models (SQLAlchemy) for Users, Habits, etc.
– routes.py – resource-oriented API endpoints (habit CRUD, user profile)

##### README

a. Main components
– Clients (mobile apps or single-page web front-ends)
– API Layer (Flask application running under WSGI/Gunicorn)
– Authentication module (JWT issuance & verification, password hashing via Bcrypt)
– Business logic / Controllers (routes.py)
– Data layer (SQLAlchemy ORM + MySQL database)
– Utility services (secret key generator, database migrations via Flask-Migrate/Alembic)
– External integrations (optional e-mail service, 3rd-party analytics if used)
b. Relationships & interactions
– Clients → HTTP(S) requests → Flask API (routes)
– routes invoke auth module for protected endpoints → JWT validation → proceed
– routes interact with models via SQLAlchemy sessions → MySQL DB
– config.py injects environment-specific settings (DB URL, JWT secret, CORS policies)
– gen_SK.py is a one-off CLI utility (depicted as separate tool)
c. Architectural patterns & design principles
– MVC-like separation: models (ORM), controllers (routes), no server-side views
– RESTful resource design: clear URI patterns, HTTP verbs
– Layered architecture: Request handling → Business logic → Persistence
– Secure by design: JWT for stateless auth, Bcrypt for password hashing, CORS policy
d. Key technologies/frameworks
– Flask & Flask-Blueprints
– Flask-JWT-Extended for tokens
– Flask-Bcrypt for password hashing
– Flask-MySQL / PyMySQL for DB connectivity
– SQLAlchemy ORM
– Alembic/Flask-Migrate for migrations
– Python Decouple / python-dotenv for environment variables
– Gunicorn (or built-in Flask server in dev)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Clients["Clients (Mobile Apps / Web Front-Ends)"]:::external

    subgraph "API Container"
        run["run.py\n(Entrypoint & WSGI)"]:::compute
        config["config.py\n(Configuration)"]:::compute
        init["__init__.py\n(Flask App Init)"]:::compute
        auth["auth.py\n(Flask Auth Blueprint)"]:::compute
        routes["routes.py\n(Controllers)"]:::compute
        models["models.py\n(ORM Models)"]:::compute
    end

    db["MySQL Database"]:::db
    dbdump["htracker_backup.sql\n(DB Schema Dump)"]:::db
    sk["gen_SK.py\n(Secret Key Utility)"]:::dev
    mig["Flask-Migrate / Alembic\n(Database Migrations)"]:::dev
    req["requirements.txt"]:::docs
    readme["README.md\n(Project Intent)"]:::docs
    license["LICENSE"]:::docs
    email["Optional Email Service"]:::external
    analytics["3rd-Party Analytics"]:::external

    Clients -->|"HTTP(S) Requests"| run
    run --> init
    config --> run
    config --> init
    init --> auth
    init --> routes
    init --> models
    routes -->|"Protected Endpoints"| auth
    routes -->|"Uses ORM"| models
    models -->|"CRUD Operations"| db
    mig -.->|"Schema Changes"| db
    mig --> init
    routes -->|"Sends Notifications"| email
    routes -->|"Sends Metrics"| analytics

    subgraph "Dev / Docs"
        sk
        req
        readme
        license
    end

    dbdump --> db

    click run "https://github.com/josetorresmx/habit-tracking-api/blob/master/run.py"
    click config "https://github.com/josetorresmx/habit-tracking-api/blob/master/config.py"
    click init "https://github.com/josetorresmx/habit-tracking-api/blob/master/app/__init__.py"
    click auth "https://github.com/josetorresmx/habit-tracking-api/blob/master/app/auth.py"
    click routes "https://github.com/josetorresmx/habit-tracking-api/blob/master/app/routes.py"
    click models "https://github.com/josetorresmx/habit-tracking-api/blob/master/app/models.py"
    click dbdump "https://github.com/josetorresmx/habit-tracking-api/blob/master/db/htracker_backup.sql"
    click sk "https://github.com/josetorresmx/habit-tracking-api/blob/master/gen_SK.py"
    click req "https://github.com/josetorresmx/habit-tracking-api/blob/master/requirements.txt"
    click readme "https://github.com/josetorresmx/habit-tracking-api/blob/master/README.md"
    click license "https://github.com/josetorresmx/habit-tracking-api/tree/master/LICENSE"

    classDef compute fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef db fill:#D5F5E3,stroke:#27AE60,stroke-width:2px,stroke-dasharray: 0;
    classDef external fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
    classDef dev fill:#F8F9F9,stroke:#7F8C8D,stroke-width:2px,stroke-dasharray: 5 5;
    classDef docs fill:#F4F6F7,stroke:#95A5A6,stroke-width:2px;
```
