# hloc26/homequest architecture

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

- Interactive diagram: https://gitdiagram.com/hloc26/homequest
- Repository: https://github.com/hloc26/homequest

## Overview

##### Main Components
- Backend API Service: Built with Express.js, organized into controllers, models, services, middleware, and routes. It handles business logic, authentication (JWT), and database interactions (using Sequelize with MySQL).
- Frontend UI: Developed with React (and Vite) that features components, pages, and state management. It communicates with the API to display tasks, manage user sessions, and handle the gamified task interactions.
- Database: A MySQL instance which is coordinated via Docker Compose with the backend. The API’s configuration files and Sequelize models (e.g., Task, User, Achievement) indicate the database’s central role.
- Containerization & Orchestration: Docker is used for containerizing both the API and UI, and docker-compose.yml ties everything together (including the MySQL database service).

##### Relationships and Interactions
- Users interact with the UI, which makes HTTP calls (via Axios in the UI’s API folder) to the backend endpoints defined in the API’s routes.
- The API controllers process these requests by leveraging business logic from the services and by reading/updating data via Sequelize models.
- Authentication flows (login, registration) follow JWT-based protocols.
- The database is the persistent store for tasks, users, achievements, and other game-task data.
- Docker Compose ties these components together by exposing front-end ports (e.g., 5173) and back-end ports (e.g., 3000), making sure containerized services can communicate.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clear segregation between UI and API.
- MVC-like structure on the backend (with controllers, models, and services).
- Use of middleware for common tasks (e.g., authentication).
- Containerization promotes environment consistency across development and deployment.
- RESTful API design: The API endpoints are structured to manage tasks, users, etc.

##### Relevant Technologies and Their Roles
- Frontend: React, Vite, Bootstrap contribute to a responsive and interactive UI.
- Backend: Express.js facilitates HTTP request handling; Sequelize abstracts database operations; JWT secures authentication.
- Database: MySQL serves as the relational database.
- Docker and Docker Compose: Containerize and orchestrate the services making the development and deployment pipelines consistent.

##### Important Details to Capture
- Separate areas for the backend’s structure (showing controllers, models, services, and middleware).
- The API layer’s reliance on the configuration files (like db.js, multer.js, etc.) that set up database connections and request handling.
- The front-end structure, showing components (like DescriptionBoard, TaskList, ProfileButton) and pages (Dashboard, Login, Profile).
- Container boundaries with ports as defined in the docker-compose file.
- Special utilities (e.g., JWT utilities in API/src/utils) to reinforce security flows.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level external entity
    User("User"):::user

    %% Container nodes
    UIContainer("UI Container"):::container
    APIContainer("API Container"):::container
    DatabaseContainer("Database Container"):::container
    DockerCompose("Docker Compose"):::container

    %% Connections from Docker Compose to container nodes (dotted lines)
    DockerCompose --- UIContainer
    DockerCompose --- APIContainer
    DockerCompose --- DatabaseContainer

    %% Flow from User to Frontend UI container
    User -->|"interacts"| UIContainer

    %% Frontend Subgraph (inside UI Container)
    subgraph "Frontend"
        UI1("React Frontend UI"):::frontend
        UI2("API Communication (Axios)"):::frontend
        UI3("Components"):::frontend
        UI4("Pages"):::frontend
        UI5("State Management"):::frontend
    end
    UIContainer -->|"hosts"| UI1
    UI1 -->|"triggers"| UI2

    %% Flow from Frontend to Backend container
    UI2 -->|"HTTP Request"| APIContainer

    %% Backend Subgraph (inside API Container)
    subgraph "Backend"
        API1("Express API"):::backend
        API2("Routes"):::backend
        API3("Controllers"):::backend
        API4("Services"):::backend
        API5("Middleware"):::backend
        API6("Models (Sequelize)"):::backend
        API7("Configuration"):::backend
        %% Utilities subgraph
        subgraph "Utilities"
            U1("decodeJwt"):::utility
            U2("handleRequest"):::utility
        end
    end
    APIContainer -->|"hosts"| API1

    %% Internal Backend Flow
    API1 -->|"uses"| API2
    API1 -->|"configures"| API7
    API2 -->|"invokes"| API3
    API3 -->|"calls"| API4
    API4 -->|"manipulates"| API6
    API1 -->|"applies"| API5
    API1 -->|"utilizes"| U1
    API1 -->|"utilizes"| U2

    %% Flow from API to Database container
    API6 -->|"queries"| DatabaseContainer

    %% Database Subgraph (inside Database Container)
    subgraph "Database"
        DB("MySQL Database"):::database
        DBConfig("Database Config"):::database
    end
    DatabaseContainer -->|"contains"| DB
    DBConfig -->|"sets up"| DB

    %% Connection from API Container to Frontend (response flow)
    API1 ---|"responds"| UI1

    %% Docker Compose connects containers (already defined above)

    %% Click Events for Frontend
    click UI1 "https://github.com/hloc26/homequest/tree/master/UI/src"
    click UI2 "https://github.com/hloc26/homequest/blob/master/UI/src/api/axios.js"
    click UI3 "https://github.com/hloc26/homequest/tree/master/UI/src/components"
    click UI4 "https://github.com/hloc26/homequest/tree/master/UI/src/pages"
    click UI5 "https://github.com/hloc26/homequest/tree/master/UI/src/store"

    %% Click Events for API Backend
    click API1 "https://github.com/hloc26/homequest/tree/master/API/src"
    click API2 "https://github.com/hloc26/homequest/tree/master/API/src/routes"
    click API3 "https://github.com/hloc26/homequest/tree/master/API/src/controllers"
    click API4 "https://github.com/hloc26/homequest/tree/master/API/src/services"
    click API5 "https://github.com/hloc26/homequest/tree/master/API/src/middlewares"
    click API6 "https://github.com/hloc26/homequest/tree/master/API/src/models"
    click API7 "https://github.com/hloc26/homequest/tree/master/API/src/config"
    click U1 "https://github.com/hloc26/homequest/blob/master/API/src/utils/decodeJwt.js"
    click U2 "https://github.com/hloc26/homequest/blob/master/API/src/utils/handleRequest.js"

    %% Click Event for Database Config
    click DBConfig "https://github.com/hloc26/homequest/blob/master/API/src/config/db.js"

    %% Click Events for Containerization & Orchestration
    click UIContainer "https://github.com/hloc26/homequest/tree/master/UI/Dockerfile"
    click APIContainer "https://github.com/hloc26/homequest/tree/master/API/Dockerfile"
    click DockerCompose "https://github.com/hloc26/homequest/blob/master/docker-compose.yml"

    %% Styles
    classDef user fill:#ffe0b2,stroke:#fb8c00,stroke-width:2px;
    classDef frontend fill:#bbdefb,stroke:#1976d2,stroke-width:2px;
    classDef backend fill:#c8e6c9,stroke:#388e3c,stroke-width:2px;
    classDef database fill:#fff9c4,stroke:#fbc02d,stroke-width:2px;
    classDef container fill:#d7ccc8,stroke:#795548,stroke-width:2px;
    classDef utility fill:#d1c4e9,stroke:#673ab7,stroke-width:2px;
```
