# rkumar70900/dungeons-and-dragons-game architecture

> Architecture diagram of the GitHub repository rkumar70900/dungeons-and-dragons-game, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rkumar70900/dungeons-and-dragons-game
- Repository: https://github.com/rkumar70900/dungeons-and-dragons-game

## Overview

##### Project Type and Purpose
- Type: Backend API service (FastAPI) orchestrating data ingestion, model training, inference, and logging.
- Purpose: Generate and manage D&D character attributes and context via REST endpoints, backed by various data pipelines and storage layers.

##### File Structure
Top-level:
– main.py (FastAPI app)
– logger.py (logging utility)
– pyproject.toml, test.py
Pipelines:
– feature-pipeline/ (data ingestion: CSV scrapers, cleaning, NoSQL + vector DB)
– training_pipeline/ (LLM-based training via ask_llm.py)
– inference_pipeline/ (core game logic, dice rolls, MongoDB connectors, DataFrame filters)
Data stores & config:
– Redis (caching via middleware in main.py)
– MongoDB (context_data collections)
– Vector database (feature-pipeline/vector_database.py)
– Local CSV sources (weapons.csv, armor.csv)

##### README for Insights
– FastAPI endpoints for each character attribute stage (race, class, abilities, etc.)
– Detailed list of inference methods (roll_dice, calculate_attack_modifier, etc.)
– Logging modules for success/failure
– Dependencies: FastAPI, Pydantic, Redis, uuid, inspect, pandas, logger, inference_pipeline

##### Main Components & Interactions
a. Components:
1. API Layer (FastAPI in main.py)
2. Inference Pipeline (inference_pipeline/dep.py)
3. Training Pipeline (training_pipeline/ask_llm.py)
4. Feature Pipeline (feature-pipeline scrapers, data_cleaning, vector_database)
5. Data Stores:
– Redis (cache/session)
– MongoDB (character context & raw data)
– Vector DB (embeddings or similarity search)
6. Logging (logger.py or logger/ modules)
7. External LLM (when training or inference uses LLM calls)
b. Relationships & Data Flow:
1. Offline Data Ingestion: feature-pipeline scrapes CSV → cleans → stores in MongoDB & vector DB.
2. Model Training: training_pipeline invokes ask_llm → generates embeddings or fine-tunes → updates vector DB.
3. API Request: client → FastAPI endpoints → middleware clears/reads Redis → calls inference_pipeline methods → reads/writes MongoDB → optionally queries vector DB → returns response → writes to Redis for caching.
4. Logging: each success/failure in any component → logger writes to logfile or stdout.
c. Architectural Patterns:
– Layered Architecture: API layer → Service layer (inference/training/feature) → Data layer
– Separation of Concerns: distinct pipelines for ingestion, training, inference
– Caching Pattern: Redis for repeat calls
– Adapter Pattern: dep.py adapts MongoDB, pandas, LLM calls into uniform service methods
d. Technologies & Frameworks:
– FastAPI (API layer)
– Pydantic (request/response models)
– Redis (cache)
– MongoDB & PyMongo (document store)
– Pandas (data transformations)
– Vector DB (similarity search)
– Python logging or custom logger modules
– External LLM APIs (e.g., OpenAI) used in training_pipeline

##### Final Checklist
– All major components distinctly labeled
– Separation between online (API & inference) and offline (feature, training) processes
– Callouts for caching, logging, external dependencies

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client to API
    Client["Client"]:::external
    subgraph "API Layer"
        API["FastAPI Service"]:::compute
    end
    Client -->|"HTTP Request"| API
    API -->|"Redis Cache Middleware"| Redis
    Redis["Redis Cache"]:::db
    API -->|"roll_dice(), calculate_attack_modifier()"| InferencePipeline

    subgraph "Inference Pipeline"
        direction TB
        Dep["dep.py"]:::compute
        Methods["inference_methods.py"]:::compute
    end
    API -->|"invoke inference methods"| Dep
    Dep -->|"uses methods"| Methods
    Dep -->|"reads/writes"| MongoDB
    Dep -->|"queries"| VectorDB

    subgraph "Data Stores & Adapters"
        direction TB
        MongoDB["MongoDB"]:::db
        VectorDB["Vector Database"]:::db
    end

    %% Logging
    Logger["logger.py"]:::logging
    API -->|"logs success/failure"| Logger
    Dep -->|"logs"| Logger

    %% External LLM
    ExternalLLM["External LLM API"]:::external
    TrainingPipeline -->|"ask_llm() calls"| ExternalLLM
    Dep -->|"may call LLM"| ExternalLLM

    %% Offline Pipelines
    subgraph "Feature Pipeline (Offline)" 
        direction TB
        Scrapers["scrapers/"]:::compute
        Cleaning["data_cleaning.py"]:::compute
        NoSQLIngest["nosql_conn.py"]:::compute
        VectorIngest["vector_database.py"]:::compute
        CSV1["armor.csv"]:::db
        CSV2["weapons.csv"]:::db
    end
    Scrapers --> Cleaning
    Cleaning --> NoSQLIngest
    Cleaning --> VectorIngest
    Cleaning --> CSV1
    Cleaning --> CSV2
    NoSQLIngest -->|"stores data"| MongoDB
    VectorIngest -->|"stores embeddings"| VectorDB
    NoSQLIngest -->|"logs"| Logger
    VectorIngest -->|"logs"| Logger

    subgraph "Training Pipeline (Offline)"
        direction TB
        AskLLM["ask_llm.py"]:::compute
    end
    AskLLM -->|"generates embeddings/fine-tunes"| VectorDB
    AskLLM -->|"logs"| Logger

    %% API to Data Stores
    API -->|"read/write context"| MongoDB
    API -->|"cache response"| Redis

    %% Offline triggers (dotted)
    Scrapers -.->|"scheduled job"| FeaturePipelineTrigger(( ))
    AskLLM -.->|"scheduled job"| TrainingPipelineTrigger(( ))

    %% Click Events
    click API "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/main.py"
    click Logger "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/logger.py"
    click Cleaning "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/feature-pipeline/data_cleaning.py"
    click NoSQLIngest "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/feature-pipeline/nosql_conn.py"
    click VectorIngest "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/feature-pipeline/vector_database.py"
    click Scrapers "https://github.com/rkumar70900/dungeons-and-dragons-game/tree/main/feature-pipeline/scrapers/"
    click CSV1 "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/feature-pipeline/armor.csv"
    click CSV2 "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/feature-pipeline/weapons.csv"
    click AskLLM "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/training_pipeline/ask_llm.py"
    click Dep "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/inference_pipeline/dep.py"
    click Methods "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/inference_pipeline/inference_methods.py"
    click TrainingPipelineTrigger "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/test.py"
    click FeaturePipelineTrigger "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/test.py"
    click Redis "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/main.py"
    click MongoDB "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/feature-pipeline/nosql_conn.py"
    click VectorDB "https://github.com/rkumar70900/dungeons-and-dragons-game/blob/main/feature-pipeline/vector_database.py"

    %% Styles
    classDef compute fill:#add8e6,stroke:#000,stroke-width:1px
    classDef db fill:#90ee90,stroke:#000,stroke-width:1px
    classDef external fill:#ffa500,stroke:#000,stroke-width:1px
    classDef logging fill:#d3d3d3,stroke:#000,stroke-width:1px
```
