# hrqneto/dramagotchi-terminal architecture

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

- Interactive diagram: https://gitdiagram.com/hrqneto/dramagotchi-terminal
- Repository: https://github.com/hrqneto/dramagotchi-terminal

## Overview

##### Project Type and Purpose
- This project is a terminal-based virtual pet game. It features dynamic emotional states, an interactive ASCII art terminal UI, and AI-powered conversations via the OpenAI API.
- The README highlights key features: dynamic emotions, conversational capabilities, personality traits, and emotion stat visualization. The tech stack includes Python 3.x, Rich for the terminal interface, OpenAI API for chat responses, and Matplotlib for generating emotion charts.

##### File Structure
- Top-level files include configuration (.gitignore, requirements.txt), README.md, and the main entry point (main.py).
- The “dramagotchi” directory acts as the core module, housing:
- __init__.py – to mark the package.
- constants.py – likely containing static configurations (pet states, thresholds, etc.).
- core.py – which probably has the core game logic (state updates, gameplay interactions, etc.).
- utils.py – providing utility/helper functions to support various operations.
- The compact structure suggests a tightly integrated design where the game logic and UI handling are coupled within a single module.

##### Key Components
- Entry Point (main.py): Initiates the game and orchestrates interactions.
- Core Module (dramagotchi):
- Core Component (core.py): Implements the main game engine responsible for managing pet states, dynamic updates, and processing player actions.
- Constants (constants.py): Contains configuration values used across the game.
- Utilities (utils.py): Supports common tasks (formatting, file operations for persistence, etc.).
- AI Conversation Module: While not a separate file, the integration with the OpenAI API is a vital part of the “chat” functionality. Represent this as an external service interacting with the core game engine.
- Terminal UI Component: Uses the Rich library to render ASCII art, display menus, and capture user inputs.
- Chart Generation Component: Uses Matplotlib to produce and update a PNG chart (e.g., “assets/emocao_grafico.png”) that visualizes emotion statistics.
- Persistence & State Management: Although not explicitly represented as a separate module, the description of “persistent state” implies the game saves and loads pet data automatically (likely embedded inside core.py or utils.py).

##### Relationships and Interactions
- The main.py file is the entry point that initializes the core game engine, loading constants and utilizing utilities.
- The core game component interacts with:
- The terminal UI for displaying pet states and receiving user input.
- The AI API (OpenAI) to facilitate conversations.
- The chart generator component for displaying emotional statistics.
- The persistence mechanism to save/load pet state.
- Data flow from user interactions (terminal input) to the game engine.
- Outgoing requests from the core engine to the external AI service.
- Flow from the game engine to the visualization component when generating charts.
- The update cycle of the pet’s dynamic emotions reflected back to the UI.

##### Architectural Patterns & Technology Stack
- Mention of relevant technologies:
- Python 3.x as the programming language.
- Rich for terminal UI and rendering.
- OpenAI API for conversational elements.
- Matplotlib for chart generation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Components
    subgraph "Core Components"
        A["Main Application (main.py)"]:::internal
        B["Game Engine (dramagotchi/core.py)"]:::internal
        C["Constants Config (dramagotchi/constants.py)"]:::internal
        D["Utility Functions (dramagotchi/utils.py)"]:::internal
    end

    %% External Components
    subgraph "External Services"
        E["Terminal UI (Rich)"]:::external
        F["AI Conversation Service (OpenAI API)"]:::external
        G["Emotion Chart Generator (Matplotlib)"]:::external
    end

    %% Relationships
    A -->|"initializes"| B
    B -->|"loads_config"| C
    B -->|"invokes_utilities"| D
    B -->|"updates_UI"| E
    B -->|"sends_request"| F
    F -->|"returns_response"| B
    B -->|"generates_chart"| G

    %% Click Events for Internal Components
    click A "https://github.com/hrqneto/dramagotchi-terminal/blob/main/main.py"
    click B "https://github.com/hrqneto/dramagotchi-terminal/blob/main/dramagotchi/core.py"
    click C "https://github.com/hrqneto/dramagotchi-terminal/blob/main/dramagotchi/constants.py"
    click D "https://github.com/hrqneto/dramagotchi-terminal/blob/main/dramagotchi/utils.py"

    %% Styles
    classDef internal fill:#CDE6FF,stroke:#000,stroke-width:1px;
    classDef external fill:#FFE6E6,stroke:#000,stroke-width:1px;
```
