# joaquinn6/habits-api architecture

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

- Interactive diagram: https://gitdiagram.com/joaquinn6/habits-api
- Repository: https://github.com/joaquinn6/habits-api

## Overview

##### Main Components
- API Server (FastAPI): This is the entry point (main.py) that initializes the server and connects all parts.
- Controllers: (Files in the “controllers” folder like habit_controller, mark_controller, stats_controller, and users_controller) manage the routing and incoming HTTP API requests.
- Services: (Inside the “services” folder) house the business logic for handling habits, marks, stats, and user-related operations.
- Repositories: (From the “repositories” folder) abstract the interactions with the database (MongoDB) and provide methods to perform CRUD operations.
- Models and Schemas: (Found in “models” and “schemas” folders) define the data structures for internal logic and input/output validations (e.g., using Pydantic).
- Core Module: (Contained in the “core” folder) manages essential functions such as authentication (JWT), database connection, environment variables, and helper utilities.
- External Systems:
- Database: MongoDB is used for data persistence.
- Frontend Client: A React application makes HTTP requests to the API endpoints.
- Infrastructure Scripts/Configs: Though not numerous here, files like Pipfile, requirements.txt, and start.sh indicate dependency management and startup configurations.

##### And Illustrate the Relationships
- The React Frontend sends API calls to the FastAPI server.
- FastAPI (in main.py) routes incoming requests to the appropriate controller based on URL endpoints.
- Controllers:
- Receive and validate requests.
- Invoke the corresponding Service functions (e.g., habit_service, mark_service, etc.).
- Services:
- Contain the business logic.
- Call repository functions to interact with the MongoDB database.
- Repositories:
- Encapsulate database queries and persistence logic.
- Use connection helpers and environment variables from the Core module.
- Core Utilities:
- Handle configurations, authentication (JWT handling with libraries like python-jose and password management via passlib), and maintenance of environment-related variables.
- Data Models/Schemas:

##### Important Architectural Patterns
- Layered Architecture: Separation between controllers (API layer), services (business logic layer), and repositories (data access layer) ensures modularity.
- Security by Design: Authentication and authorization are implemented via JWT and password security libraries.
- Integration & Extensibility: The REST API is designed to be consumed by external clients (React App) and has clean separation of concerns that make extensions easier.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    ReactFrontend["React Frontend"]:::external

    %% API Server
    APIServer["API Server (FastAPI Entry Point)"]:::api

    %% Infrastructure Scripts/Configs
    subgraph "Infrastructure Scripts/Configs"
        P["Pipfile"]:::infra
        PL["Pipfile.lock"]:::infra
        RQ["Requirements.txt"]:::infra
        SScr["Start Script (start.sh)"]:::infra
    end

    %% Controllers Layer
    subgraph "Controllers"
        HTC["Habit Controller"]:::controller
        MTC["Mark Controller"]:::controller
        STC["Stats Controller"]:::controller
        UTC["Users Controller"]:::controller
        RTC["Routes"]:::controller
    end

    %% Services Layer
    subgraph "Services"
        HS["Habit Service"]:::service
        MS["Mark Service"]:::service
        SS["Stats Service"]:::service
        US["User Service"]:::service
    end

    %% Repositories Layer
    subgraph "Repositories"
        HR["Habit Repository"]:::repository
        MR["Mark Repository"]:::repository
        UR["User Repository"]:::repository
        R["Repository"]:::repository
    end

    %% Models
    subgraph "Models"
        HM["Habit Model"]:::model
        MM["Mark Model"]:::model
        TM["Token Model"]:::model
        UM["User Model"]:::model
        EN["Entity"]:::model
    end

    %% Schemas
    subgraph "Schemas"
        QMS["Query Marks Schema"]:::schema
        QSS["Query Stats Schema"]:::schema
        USch["User Schema"]:::schema
    end

    %% Core Module
    subgraph "Core Module"
        A["Auth"]:::core
        C["Connection"]:::core
        HAPI["Helpers API"]:::core
        U["Utils"]:::core
        VE["Var Env"]:::core
        VMP["Var Mongo Provider"]:::core
    end

    %% Database
    Database["MongoDB Database"]:::database

    %% Connections
    ReactFrontend -->|"makesAPICall"| APIServer
    APIServer -->|"startupConfig"| SScr
    APIServer -->|"dependencyMgmt"| P

    APIServer -->|"routes"| RTC
    RTC -->|"dispatches"| HTC
    RTC -->|"dispatches"| MTC
    RTC -->|"dispatches"| STC
    RTC -->|"dispatches"| UTC

    HTC -->|"calls"| HS
    MTC -->|"calls"| MS
    STC -->|"calls"| SS
    UTC -->|"calls"| US

    HS -->|"queries"| HR
    MS -->|"queries"| MR
    US -->|"queries"| UR
    SS -->|"queries"| R

    HR -->|"accesses"| Database
    MR -->|"accesses"| Database
    UR -->|"accesses"| Database
    R -->|"accesses"| Database

    %% Integration with Core Module
    APIServer -->|"authConfig"| A
    HS -->|"dbConnection"| C
    HR -->|"dbConnection"| C

    %% Data Mapping from Services to Models
    HS -->|"mapsData"| HM
    MS -->|"mapsData"| MM
    US -->|"mapsData"| UM
    SS -->|"mapsData"| EN

    %% Data Validation with Schemas from Controllers
    HTC -->|"validatesData"| USch
    MTC -->|"validatesData"| QMS
    STC -->|"validatesData"| QSS

    %% Styles & Classes
    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px
    classDef api fill:#fce5cd,stroke:#b8540f,stroke-width:2px
    classDef controller fill:#cfe2f3,stroke:#6fa8dc,stroke-width:2px
    classDef service fill:#d9ead3,stroke:#6aa84f,stroke-width:2px
    classDef repository fill:#ead1dc,stroke:#b45f06,stroke-width:2px
    classDef model fill:#fff2cc,stroke:#e69138,stroke-width:2px
    classDef schema fill:#d9d2e9,stroke:#8e7cc3,stroke-width:2px
    classDef core fill:#d0e0e3,stroke:#3d85c6,stroke-width:2px
    classDef database fill:#c9daf8,stroke:#1155cc,stroke-width:2px
    classDef infra fill:#ffe599,stroke:#bf9000,stroke-width:2px

    %% Click Events
    click APIServer "https://github.com/joaquinn6/habits-api/blob/master/main.py"
    click HTC "https://github.com/joaquinn6/habits-api/blob/master/controllers/habit_controller.py"
    click MTC "https://github.com/joaquinn6/habits-api/blob/master/controllers/mark_controller.py"
    click STC "https://github.com/joaquinn6/habits-api/blob/master/controllers/stats_controller.py"
    click UTC "https://github.com/joaquinn6/habits-api/blob/master/controllers/users_controller.py"
    click RTC "https://github.com/joaquinn6/habits-api/blob/master/controllers/routes.py"
    click HS "https://github.com/joaquinn6/habits-api/blob/master/services/habit_service.py"
    click MS "https://github.com/joaquinn6/habits-api/blob/master/services/mark_service.py"
    click SS "https://github.com/joaquinn6/habits-api/blob/master/services/stats_service.py"
    click US "https://github.com/joaquinn6/habits-api/blob/master/services/user_service.py"
    click HR "https://github.com/joaquinn6/habits-api/blob/master/repositories/habit_repository.py"
    click MR "https://github.com/joaquinn6/habits-api/blob/master/repositories/mark_repository.py"
    click UR "https://github.com/joaquinn6/habits-api/blob/master/repositories/user_repository.py"
    click R "https://github.com/joaquinn6/habits-api/blob/master/repositories/repository.py"
    click HM "https://github.com/joaquinn6/habits-api/blob/master/models/habit_model.py"
    click MM "https://github.com/joaquinn6/habits-api/blob/master/models/mark_model.py"
    click TM "https://github.com/joaquinn6/habits-api/blob/master/models/token_model.py"
    click UM "https://github.com/joaquinn6/habits-api/blob/master/models/user_model.py"
    click EN "https://github.com/joaquinn6/habits-api/blob/master/models/entity.py"
    click QMS "https://github.com/joaquinn6/habits-api/blob/master/schemas/query_marks.py"
    click QSS "https://github.com/joaquinn6/habits-api/blob/master/schemas/query_stats.py"
    click USch "https://github.com/joaquinn6/habits-api/blob/master/schemas/user_schema.py"
    click A "https://github.com/joaquinn6/habits-api/blob/master/core/auth.py"
    click C "https://github.com/joaquinn6/habits-api/blob/master/core/connection.py"
    click HAPI "https://github.com/joaquinn6/habits-api/blob/master/core/helpers_api.py"
    click U "https://github.com/joaquinn6/habits-api/blob/master/core/utils.py"
    click VE "https://github.com/joaquinn6/habits-api/blob/master/core/var_env.py"
    click VMP "https://github.com/joaquinn6/habits-api/blob/master/core/var_mongo_provider.py"
    click P "https://github.com/joaquinn6/habits-api/tree/master/Pipfile"
    click PL "https://github.com/joaquinn6/habits-api/blob/master/Pipfile.lock"
    click RQ "https://github.com/joaquinn6/habits-api/blob/master/requirements.txt"
    click SScr "https://github.com/joaquinn6/habits-api/blob/master/start.sh"
```
