# gelzy788/dnd-helper architecture

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

- Interactive diagram: https://gitdiagram.com/gelzy788/dnd-helper
- Repository: https://github.com/gelzy788/dnd-helper

## Overview

##### Project Type and Purpose
- This is a full-stack application: the backend is implemented as a Flask server (using SQLAlchemy for database interactions) and the frontend is built as a client application with UI defined in various .ui files.
- Its primary purpose is to facilitate online D&D game sessions, allowing users to create groups, manage profiles, register/log in, and maintain questionnaires associated with gameplay.

##### Analyzing the File Structure
- Top-Level Directories & Files:
- The root includes configuration files (e.g., .gitignore, requirements.txt) and a data directory.
- The data directory contains two highlighted sub-directories: one for the MySQL database ("DnD_Helper_db") and another ("ui_files") for the user interface definitions.
- The src directory is subdivided into two main parts:
a. server - Contains the Flask server’s main execution file (main.py), database interaction code (database.py), ORM models (models.py) for SQLAlchemy, and configuration constants (config.py).
b. client - Contains core files for launching the client (main.py), and other modules such as login_manager, register_manager, friend_manager, group_manager, profile_manager, and questionnaire_manager. Supporting files (like my_config.py and my_token.py for access token checks) ensure core client functionality.
- Additional archive directory indicates historical code versions (old_main.py, old_config.py) which are less central to the current architecture.

##### Insights from the README
- The README explicitly describes the division between "server" and "client" functionality, suggesting a clear separation of concerns.
- It confirms that the server uses Flask with SQLAlchemy for backend data management (likely interfacing with a MySQL database).
- The instructions given for launching the client (e.g., running "main.py" from the client folder) and setting up the virtual environment emphasize that both ends are developed to interact seamlessly.

a. Main Components:
- Client Application:
- UI Layer: Representing all .ui files that define screens (login, registration, main, profile, questionnaire, etc.).
- Business Logic: Modules such as friend_manager, group_manager, login_manager, register_manager, profile_manager, and questionnaire_manager.
- Authentication Utilities: Files like my_token.py to validate access tokens.
- Server Application:
- Web Server: The Flask-based server (main.py), responsible for routing and request handling.
- API Endpoints: Implied interfaces for handling client requests (login, registration, fetching/updating profiles, managing questionnaires, friend and group operations).
- Database Layer: Interfaced via database.py, with ORM models in models.py and configuration provided by config.py.
- Database:
- MySQL Database: Represented in the data/DnD_Helper_db directory. It contains tables (‘users’, ‘friends’, ‘groups_members’, ‘questionnaires’, ‘refresh_tokens’, ‘users_groups’).
- External Dependencies:
- Python Virtual Environment and related libraries as per requirements.txt.

b. Relationships and Interactions:
- The client communicates with the server via HTTP requests (likely through RESTful APIs provided by the Flask server).
- The server handles these incoming requests, processes business logic, and interacts with the database (using SQLAlchemy ORM).
- Data flows from the client (user-triggered events) to the server and then persists to the database, and vice versa for fetching updates.

c. Architectural Patterns and Design Principles:
- Client-server separation: Distinct boundaries between frontend (client) and backend (server).
- MVC/MVVM: The client side uses UI files (view) and corresponding managers (controller/business logic) to handle user interactions.
- Use of ORM (SQLAlchemy): Abstracting database interactions through model definitions.
- Token-Based Authentication: Use of my_token.py indicates use of access tokens for securing client-server communication.

d. Relevant Technologies:
- Flask for the server and API endpoints.
- SQLAlchemy to manage database schema and ORM.
- MySQL as the database management system.
- Python for both client and server logic.
- UI files (likely built via Qt Designer or similar) for the client application's graphical interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application Layer
    subgraph "Client Application"
        direction TB
        UI["UI Layer (Login, Registration, Profile, Questionnaire)"]:::client
        BL["Business Logic Modules (Managers)"]:::client
        AUTH["Authentication Utility (my_token.py)"]:::auth
    end

    %% Server Application Layer
    subgraph "Server Application"
        direction TB
        FS["Flask Server (main.py)"]:::server
        API["API Endpoints"]:::server
        DBI["Database Interaction (database.py)"]:::server
        ORM["ORM Models (models.py)"]:::server
        CFG["Configuration (config.py)"]:::server
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        DB["MySQL Database"]:::db
    end

    %% Client-side interactions
    UI -->|"sendsEvent"| BL
    BL -->|"validatesToken"| AUTH
    BL -->|"sendsHTTPRequest"| FS

    %% Server-side interactions
    FS -->|"routesTo"| API
    API -->|"queries"| DBI
    DBI -->|"mapsQueries"| ORM
    ORM -->|"performsCRUD"| DB
    DB -->|"returnsData"| ORM
    ORM -->|"sendsData"| DBI
    DBI -->|"deliversResults"| API
    API -->|"responds"| FS
    FS -->|"sendsHTTPResponse"| BL
    BL -->|"updatesUI"| UI

    %% Server configuration link
    FS -.->|"readsConfig"| CFG

    %% Click Events
    click UI "https://github.com/gelzy788/dnd-helper/tree/main/data/ui_files/"
    click BL "https://github.com/gelzy788/dnd-helper/tree/main/src/client/"
    click FS "https://github.com/gelzy788/dnd-helper/tree/main/src/server/"
    click DB "https://github.com/gelzy788/dnd-helper/tree/main/data/DnD_Helper_db/"
    click AUTH "https://github.com/gelzy788/dnd-helper/blob/main/src/archive/my_token.py"

    %% Styles
    classDef client fill:#ccf,stroke:#2a2,stroke-width:2px;
    classDef server fill:#cfc,stroke:#262,stroke-width:2px;
    classDef db fill:#fcc,stroke:#a22,stroke-width:2px;
    classDef auth fill:#fcf,stroke:#a2a,stroke-width:2px;
```
