# mpoapostolis/vxlverse architecture

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

- Interactive diagram: https://gitdiagram.com/mpoapostolis/vxlverse
- Repository: https://github.com/mpoapostolis/vxlverse

## Overview

##### Project Type & Purpose
- VXLverse is a full-stack, browser-based game creation platform that targets both non-coders and experienced developers.
- Its main purpose is to allow users to create, play, and share immersive 3D voxel games easily. It features an advanced game editor, dynamic combat & quest systems, and natural language AI driven NPC interactions using Mistral AI.
- The README clarifies the separation of concerns between the editor environment (for game creation) and the game runtime (for playing the created games), with clear support systems such as state management (via Zustand), 3D rendering (using Three.js/React Three Fiber), authentication, and PWA support.

##### File Structure
- The top-level files like package.json, vite.config.ts, and tsconfig files reveal a modern React + TypeScript app built with Vite.
- The “src” folder is well structured, with separate directories for components (further divided into editor, game, auth, home, UI, etc.), pages, hooks, stores, and library utilities.
- There are also configuration files and build-related scripts that hint at a PWA setup and integration with various services (like PocketBase as evident in src/lib/pocketbase.ts).

##### Key Architectural Components
a. Frontend/UI:
- The Application view is split between the Editor (with components such as ScenePanel, PropertiesPanel, Toolbar, and various editor panels) and the Game (with HUD, combat components, inventory, dialogue modals).
- The UI components are organized into reusable pieces (as seen under src/components/UI) and pages are defined under src/pages (like Home, Editor, Game, Profile, etc.).

b. 3D Rendering Engine:
- Real-time 3D rendering using Three.js (and React Three Fiber is likely wrapped inside the Model, ModelViewer, and similar components).
- The platform uses 3D assets (e.g., player.glb in public) to render voxel environments.

c. AI Integration:
- AI-driven NPC conversation components (under src/components/auth and other areas) leverage Mistral AI, integrated with backend persistence using PocketBase.
- Components and services focus on dialogue management (such as ConversationManager and CharacterMemory as hinted in the README architecture).

d. State Management and Data Stores:
- Zustand state stores (from src/stores such as editorStore.ts, gameStore.ts, authStore.ts) are responsible for handling UI state and game state in a performant and persistent manner.

e. Backend & PWA Services:
- Although the code is primarily client-side, PocketBase is used for managing persistent data like user profiles, game state, and AI-driven conversations.
- Service-worker files (public/service-worker.js / sw.js) indicate PWA functionality enabling offline usage and enhanced performance.

##### Relationships & Interactions
- The “Game” module interacts with state (via Zustand), which is the runtime environment using components like GameHUD, CombatSystem, etc.
- External integrations such as Three.js for rendering, Tailwind CSS for UI styling, and Mistral AI for NPC conversations should be depicted as connected external services/libraries.

##### Architectural Patterns & Design Principles
- Component-Based Architecture: Highlight separation of concerns in components (editor vs. game vs. auth) and how reusability is maintained through the modular UI components.
- State Management using centralized stores (Zustand) and separation between UI (React components) and logic.
- Integration and abstraction layers for 3D rendering (abstracted behind Model, ModelViewer, etc.) and AI services.
- Emphasis on Progressive Web App principles—service workers, manifest, and responsive design.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend - Editor Module
    subgraph "Editor Module"
        Editor_Page["Editor Page"]:::ui
        Editor_Comp["Editor Components"]:::ui
    end

    %% Frontend - Game Module
    subgraph "Game Module"
        Game_Page["Game Page"]:::ui
        Game_Comp["Game Components"]:::ui
    end

    %% 3D Rendering Engine
    subgraph "3D Rendering Engine"
        Model["Model"]:::render
        ModelViewer["ModelViewer"]:::render
    end

    %% State Management
    subgraph "State Management"
        Zustand["Zustand Stores"]:::state
    end

    %% AI & Backend Integration
    subgraph "AI & Backend Integration"
        PocketBase["PocketBase Service"]:::backend
        Dialogue["Dialogue Modal"]:::backend
        Mistral["Mistral AI"]:::external
    end

    %% PWA Services
    subgraph "PWA Services"
        SW1["Service Worker (service-worker.js)"]:::pwa
        SW2["Service Worker (sw.js)"]:::pwa
        PWAComp["PWA Components"]:::pwa
    end

    %% Connections between modules
    Editor_Page -->|"updates"| Zustand
    Editor_Comp -->|"updatesUI"| Zustand
    Game_Page -->|"updates"| Zustand
    Game_Comp -->|"updatesUI"| Zustand

    Zustand -->|"syncs"| PocketBase
    Zustand -->|"triggers"| Dialogue

    Editor_Page -->|"renders"| Model
    Editor_Comp -->|"renders"| ModelViewer
    Game_Page -->|"renders"| Model
    Game_Comp -->|"renders"| ModelViewer

    Dialogue -->|"calls"| Mistral

    Editor_Page -->|"PWA"| SW1
    Editor_Page -->|"PWA"| PWAComp
    Game_Page -->|"PWA"| SW2
    Game_Page -->|"PWA"| PWAComp

    %% Click Events
    click Editor_Page "https://github.com/mpoapostolis/vxlverse/blob/main/src/pages/Editor.tsx"
    click Editor_Comp "https://github.com/mpoapostolis/vxlverse/tree/main/src/components/editor/"
    click Game_Page "https://github.com/mpoapostolis/vxlverse/blob/main/src/pages/Game.tsx"
    click Game_Comp "https://github.com/mpoapostolis/vxlverse/tree/main/src/components/game/"
    click Model "https://github.com/mpoapostolis/vxlverse/blob/main/src/components/Model.tsx"
    click ModelViewer "https://github.com/mpoapostolis/vxlverse/blob/main/src/components/ModelViewer.tsx"
    click PocketBase "https://github.com/mpoapostolis/vxlverse/blob/main/src/lib/pocketbase.ts"
    click Dialogue "https://github.com/mpoapostolis/vxlverse/blob/main/src/components/game/DialogueModal.tsx"
    click Zustand "https://github.com/mpoapostolis/vxlverse/tree/main/src/stores/"
    click SW1 "https://github.com/mpoapostolis/vxlverse/blob/main/public/service-worker.js"
    click SW2 "https://github.com/mpoapostolis/vxlverse/blob/main/public/sw.js"
    click PWAComp "https://github.com/mpoapostolis/vxlverse/tree/main/src/components/pwa/"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#1F618D,stroke-width:2px,color:#1F618D;
    classDef render fill:#ABEBC6,stroke:#27AE60,stroke-width:2px,color:#1E8449;
    classDef state fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px,color:#9A7D0A;
    classDef backend fill:#F5B7B1,stroke:#C0392B,stroke-width:2px,color:#922B21;
    classDef pwa fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px,color:#5B2C6F;
    classDef external fill:#D6EAF8,stroke:#2471A3,stroke-width:2px,color:#1A5276;
```
