# beenycool/villagesreborn architecture

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

- Interactive diagram: https://gitdiagram.com/beenycool/villagesreborn
- Repository: https://github.com/beenycool/villagesreborn

## Overview

##### Project Type & Purpose
- This is a Minecraft mod built for the Fabric Loader targeting Minecraft version 1.21.4. Its purpose is to enhance village diversity by introducing culturally themed villages with intelligent AI-driven villagers, dynamic events, specialized crafting systems, and an immersive GUI experience.
- The mod leverages external AI (via LLMs) to simulate realistic villager behaviors, along with various cultural components like architecture, social interactions, and event systems.

##### Analyzing the File Structure
- Directories such as "src/main" and "src/client" hint at a separation between core mod functionality (server and common logic) and client-side components such as GUI interfaces and mixin modifications.
- The “src/main/java/com/beeny” folder organizes features into multiple sub-packages:
- AI components: “ai” folder, including classes like LLMImplementation, ModelChecker, various AI providers (OpenAIProvider, AzureOpenAIProvider, etc.) which handle API calls, model configurations, and error handling.
- API & Commands: “api” and “commands” directories manage mod-specific APIs (such as the VillageHudAPI) and mod commands.
- Configuration: The “config” package provides integration with Cloth Config and mod menu settings.
- Data, Events, & Network: Dedicated packages for data management, event handling, network synchronization, and client-server communications.
- GUI: Packages like “gui” and “client/java/com/beeny/gui” contain classes for user interfaces (setup screens, tutorials, settings, etc.).
- Mixin: Multiple mixin packages suggest the use of bytecode manipulation to inject mod behavior into Minecraft’s original code (both under client and main).
- Resource folders include assets (textures, GUI resources) and data (structure files, advancements, and templates) showing integration with Minecraft’s world generation and gameplay features.

##### Key Components
a. Main Mod Engine:
- Base classes: Villagesreborn.java and VillagesrebornClient.java serve as entry points for server and client initialization.
- Configuration & Setup: Use “LLMConfig”, “SystemSpecs”, “ClothConfigProvider”, etc., to manage mod settings.
b. AI Integration:
- Components in the “ai” sub-package and “provider” sub-package represent the interface with multiple LLM providers and error-handling (LLMErrorHandler). This is critical for AI-powered villager behavior.
c. User Interface & Client-side:
- Several GUI classes (SetupScreen, AISettingsScreen, TutorialScreen, etc.) in both “src/main/gui” and “src/client/java” highlight the client-specific components.
- Mixins here modify vanilla client behavior (e.g., ChatMessageMixin, OptionsScreenMixin) to integrate mod GUI elements.
d. Network & Synchronization:
- Packages under “network” manage the synchronization between client and server side for events like village crafting events and updating villager interactions.
e. Village & Cultural Systems:
- Packages such as “village”, “village/crafting”, “village/event”, and “village/artifacts” encapsulate the business logic for cultural crafting, evolution of village cultures, event scheduling, and social dynamics of villagers.
f. Data & Persistence:
- “data” packages and file resources (advancements, structure files) outline how the mod stores, loads, and manages cultural configurations and world generation templates.

##### Relationships & Interactions
- Communication flows between client and server via network components.
- Dependency between UI elements (like SetupScreen, TutorialScreen) and underlying business logic.
- Mixins as overlays on vanilla Minecraft functionality, indicating modification points.

##### Architectural Patterns & Design
- MVC-like separation where the "View" (GUI screens) is separate from the "Model" (village state, AI-led decision making) and "Controller" (event scheduling, command processing).
- Modular design: Individual packages for AI, networking, GUI, and events suggest modularity.
- Use of dependency injection (conceptually, if applicable) for AI providers configuration and modular provider selection.
- Dynamic configuration driven by external JSON files in the config directory, following a configuration-over-code approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Subgraph
    subgraph "Backend (Core Logic)"
        A["Villagesreborn (Server Entry)"]:::modEngine
        B["Configuration & Setup"]:::config
        subgraph "AI Integration Layer"
            C["AI Core Components"]:::ai
            D["AI Providers"]:::ai
        end
        subgraph "Village & Cultural Systems"
            E["Village Business Logic"]:::village
            F["Cultural Artifacts"]:::village
            G["Cultural Crafting"]:::village
            H["Cultural Events"]:::village
        end
        I["Network Communication"]:::network
        J["Data & Persistence"]:::data
        K["Fabric Loader (Mod Loader)"]:::external
    end

    %% Frontend Subgraph
    subgraph "Frontend (Client-Side)"
        L["VillagesrebornClient (Client Entry)"]:::modEngine
        M["GUI Components (Client & Server)"]:::client
        N["Client Mixins"]:::client
    end

    %% Connections for Backend
    K --> A
    A --> B
    B --> C
    B --> E
    C --> D
    A --> I
    I --> E
    E --> F
    E --> G
    E --> H
    B --> J
    I --> J

    %% Connections for Frontend and Interaction with Backend
    K --> L
    L --> M
    L --> N
    M --> I

    %% Styles
    classDef modEngine fill:#ffcccc,stroke:#000000,stroke-width:2px;
    classDef config fill:#ffe0b3,stroke:#000000,stroke-width:2px;
    classDef ai fill:#cce5ff,stroke:#000000,stroke-width:2px;
    classDef village fill:#ccffcc,stroke:#000000,stroke-width:2px;
    classDef network fill:#ffd699,stroke:#000000,stroke-width:2px;
    classDef client fill:#e0ccff,stroke:#000000,stroke-width:2px;
    classDef data fill:#d9d9d9,stroke:#000000,stroke-width:2px;
    classDef external fill:#fef2cc,stroke:#000000,stroke-width:2px;

    %% Additional Backend Subsystem Connections
    C --- D
    E --- F
    E --- G
    E --- H

    %% Click Events for Component Mapping
    click A "https://github.com/beenycool/villagesreborn/blob/main/src/main/java/com/beeny/Villagesreborn.java"
    click L "https://github.com/beenycool/villagesreborn/blob/main/src/main/java/com/beeny/VillagesrebornClient.java"
    click B "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/setup"
    click C "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/ai"
    click D "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/ai/provider"
    click M "https://github.com/beenycool/villagesreborn/tree/main/src/client/java/com/beeny/gui"
    click N "https://github.com/beenycool/villagesreborn/tree/main/src/client/java/com/beeny/mixin/client"
    click I "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/network"
    click E "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/village"
    click F "https://github.com/beenycool/villagesreborn/blob/main/src/main/java/com/beeny/village/artifacts/CulturalArtifactSystem.java"
    click G "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/village/crafting"
    click H "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/village/event"
    click J "https://github.com/beenycool/villagesreborn/tree/main/src/main/java/com/beeny/data"
    click K "https://github.com/beenycool/villagesreborn/tree/main/src/main/resources/data/villagesreborn"
```
