# hyperfy-xyz/hyperfy architecture

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

- Interactive diagram: https://gitdiagram.com/hyperfy-xyz/hyperfy
- Repository: https://github.com/hyperfy-xyz/hyperfy

## Overview

##### Main System Components

a) Client-Side Layer
- Following sub-components:
- UI Components (from src/client/components)
- Graphics Engine (Three.js integration)
- Physics Engine (PhysX client integration)
- VRM Avatar System
- Client Systems (Graphics, Controls, Network, etc.)

b) Core Layer (Middle)
- This in the center as it's shared between client and server
- Include:
- World Management
- Entity System
- Node System
- Asset Management
- Networking Protocol

c) Server-Side Layer
- At the bottom
- Include:
- Physics Server (PhysX)
- Network Handler
- Database Integration
- Server Systems

##### Component Relationships

- Double lines: Data synchronization

##### Specific Implementation Details

Key architectural elements:
- Entity-Component System (ECS)
- Relationship between Entities, Components, and Systems
- Node Hierarchy
- Demonstrate the relationship between different node types (Mesh, Group, RigidBody, etc.)
- Network Architecture
- WebSocket connections
- State synchronization flow
- Physics Integration
- PhysX integration points
- Collision system

##### System Interactions

Critical flows:
- Client-server communication
- Physics synchronization
- Asset loading pipeline
- User interaction handling
- World state management

##### Technical Stack Indicators

Technologies:
- Three.js
- PhysX
- WebSocket
- VRM
- Node.js

Remember to emphasize the real-time nature of the system and how different components work together to create the persistent virtual world experience.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        UI["UI Components"]:::ui
        GFX["Graphics Engine (Three.js)"]:::graphics
        PHX["Physics Engine (PhysX)"]:::physics
        VRM["VRM Avatar System"]:::avatar
        
        subgraph ClientSystems
            CGfx["Client Graphics"]:::system
            CCtrl["Client Controls"]:::system
            CNet["Client Network"]:::system
            CEd["Client Editor"]:::system
        end
    end

    subgraph Core
        World["World Management"]:::core
        
        subgraph EntitySystem
            Ent["Entity System"]:::entity
            Nodes["Node System"]:::entity
        end
        
        subgraph CoreSystems
            Events["Events System"]:::system
            Physics["Physics System"]:::system
            Scripts["Scripts System"]:::system
            Stage["Stage System"]:::system
        end
        
        Assets["Asset Management"]:::core
        Network["Network Protocol"]:::network
    end

    subgraph Server
        PhysServer["Physics Server"]:::physics
        DB["Database"]:::database
        NetHandler["Network Handler"]:::network
        SrvLoader["Server Loader"]:::system
    end

    %% Client Relationships
    UI --> CGfx
    GFX --> CGfx
    PHX --> Physics
    VRM --> CGfx
    
    %% Core Relationships
    World --> EntitySystem
    World --> CoreSystems
    World --> Assets
    World --> Network
    
    %% Server Relationships
    Network --> NetHandler
    Physics --> PhysServer
    NetHandler --> DB
    SrvLoader --> Assets

    %% Cross-layer Communication
    CNet <-.-> Network
    Network <-.-> NetHandler
    Physics <-.-> PhysServer

    %% Component Mappings
    click UI "https://github.com/hyperfy-xyz/hyperfy/tree/main/src/client/components/"
    click PHX "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/client/loadPhysX.js"
    click CGfx "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/ClientGraphics.js"
    click CCtrl "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/ClientControls.js"
    click CNet "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/ClientNetwork.js"
    click CEd "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/ClientEditor.js"
    click World "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/World.js"
    click Ent "https://github.com/hyperfy-xyz/hyperfy/tree/main/src/core/entities/"
    click Nodes "https://github.com/hyperfy-xyz/hyperfy/tree/main/src/core/nodes/"
    click Assets "https://github.com/hyperfy-xyz/hyperfy/tree/main/src/core/assets/"
    click Network "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/Socket.js"
    click PhysServer "https://github.com/hyperfy-xyz/hyperfy/tree/main/src/server/physx/"
    click DB "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/server/db.js"
    click NetHandler "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/ServerNetwork.js"
    click SrvLoader "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/ServerLoader.js"
    click VRM "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/nodes/VRM.js"
    click Physics "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/Physics.js"
    click Events "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/Events.js"
    click Scripts "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/Scripts.js"
    click Stage "https://github.com/hyperfy-xyz/hyperfy/blob/main/src/core/systems/Stage.js"

    %% Styling
    classDef ui fill:#FFA500
    classDef graphics fill:#4169E1
    classDef physics fill:#32CD32
    classDef avatar fill:#9370DB
    classDef system fill:#A9A9A9
    classDef core fill:#4682B4
    classDef entity fill:#20B2AA
    classDef network fill:#8A2BE2
    classDef database fill:#696969
```
