# 1humza/evolve-framework architecture

> Architecture diagram of the GitHub repository 1humza/evolve-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/1humza/evolve-framework
- Repository: https://github.com/1humza/evolve-framework

## Overview

##### Project type and purpose
- This is an open-source Roblox Luau custom framework (not a full application), focused on providing an object-oriented API with classes, inheritance, event/stream systems, and a replication layer compatible with Streaming Enabled.
- Core goal: load and initialize the framework on both server and client, allow users to register custom classes, handle replication of those objects, and expose utility functions (Promise, Maid, Streamable, etc.).

##### File structure
- Top level:
- build.rbxlx, default.project.json – Roblox studio build and project settings
- src/EvolveLoader – loader entrypoints and the “Evolve” framework code
- src/Modules – placeholders for user-defined Classes, Client, Server, Shared scripts
- Inside src/EvolveLoader/Evolve:
- init.lua – main module entry
- _binder.lua, _classes.lua – internal class registration and binding logic
- CustomObjects/Utils – replicator, serialization, UUID utilities for object replication
- Events – Signal implementation and event dispatcher
- Maid.lua, Promise.lua, Streamable.lua, Table.lua, typeof.lua, wait.lua – helper libraries

##### Extract README insights
- Confirms framework nature, highlights Streaming Enabled compatibility.

a. Main components
- Loader Layer
– init.server.lua and client side loader (if any) that require EvolveLoader/Evolve/init.lua
- Core Framework Layer
– Evolve/init.lua (or main module)
– Internal Class Manager (_classes, _binder)
- Utilities Layer
– Events (Signal)
– Promise, Maid, Streamable, Table, typeof, wait
- Replication Layer
– CustomObjects
– Custom Objects Replicator.client.lua
– Serializer, Replicator, UUID
- User Modules Layer
– Modules/Classes, Modules/Server, Modules/Client, Modules/Shared

b. Relationships and interactions
- Loader → Core: loader scripts on server/client import the core init module
- Core ↔ Class Manager: main module registers classes via _classes.lua & _binder.lua
- Core ↔ Utilities: core functions call Promise, Events, Maid, etc., for async workflows
- Core → Replication: when a custom class is marked replicable, framework uses Serializer and Replicator to sync instances between server and client
- User Modules → Core: user-defined classes in Modules/Classes register themselves with the framework; Modules/Server & Modules/Client consume replicable objects and remote methods

c. Architectural patterns & design principles
- Layered architecture: loader → core → utilities → replication → user code
- Inversion of Control: user classes register themselves into the framework rather than the framework knowing them upfront
- Publish/Subscribe: Event Signals for decoupled event management
- Promise-based asynchronous flows instead of raw callbacks
- Resource management via Maid (cleanup pattern)

d. Key technologies & libraries
- Roblox Luau (language)
- Roblox’s networked environment: server & client runtimes
- Custom Promise, Maid, Streamable libraries (in-framework utilities)
- JSON (init.meta.json) for metadata

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Loader Layer
    subgraph "Loader Layer"
        LoaderServer["init.server.lua"]:::loader
    end

    %% Core Framework Layer
    subgraph "Core Framework Layer"
        MainCore["init.lua"]:::core
        Classes["_classes.lua"]:::core
        Binder["_binder.lua"]:::core
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        subgraph "Events"
            EventsInit["Events/init.lua"]:::util
            Signal["Signal.lua"]:::util
        end
        Promise["Promise.lua"]:::util
        Maid["Maid.lua"]:::util
        Streamable["Streamable.lua"]:::util
        Table["Table.lua"]:::util
        Typeof["typeof.lua"]:::util
        Wait["wait.lua"]:::util
    end

    %% Replication Layer
    subgraph "Replication Layer"
        CustomObjectsInit["CustomObjects/init.lua"]:::replication
        ReplicatorClient["Custom Objects Replicator.client.lua"]:::replication
        subgraph "Utils"
            Replicator["Replicator.lua"]:::replication
            Serialize["Serialize.lua"]:::replication
            UUID["UUID.lua"]:::replication
            CoreUtil["Core.lua"]:::replication
            Load["Load.lua"]:::replication
            Meta["init.meta.json"]:::replication
        end
    end

    %% User Modules Layer
    subgraph "User Modules Layer"
        ClassesUser["Modules/Classes"]:::user
        ClientUser["Modules/Client"]:::user
        ServerUser["Modules/Server"]:::user
        SharedUser["Modules/Shared"]:::user
    end

    %% Connections
    LoaderServer -->|loads| MainCore
    MainCore -->|uses| Classes
    MainCore -->|uses| Binder
    MainCore -->|calls| EventsInit
    EventsInit -->|provides| Signal
    MainCore -->|calls| Promise
    MainCore -->|calls| Maid
    MainCore -->|calls| Streamable
    MainCore -->|calls| Table
    MainCore -->|calls| Typeof
    MainCore -->|calls| Wait
    MainCore -->|initializes| CustomObjectsInit
    CustomObjectsInit -->|uses| ReplicatorClient
    CustomObjectsInit -->|uses| Replicator
    CustomObjectsInit -->|uses| Serialize
    CustomObjectsInit -->|uses| UUID
    CustomObjectsInit -->|uses| CoreUtil
    CustomObjectsInit -->|uses| Load
    CustomObjectsInit -->|reads| Meta
    CustomObjectsInit -->|"network"| ReplicatorClient
    ClassesUser -->|registers| MainCore
    ClientUser -->|interacts| MainCore
    ServerUser -->|interacts| MainCore
    SharedUser -->|interacts| MainCore

    %% Click Events
    click LoaderServer "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/init.server.lua"
    click MainCore "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/init.lua"
    click Classes "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/_classes.lua"
    click Binder "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/_binder.lua"
    click EventsInit "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/Events/init.lua"
    click Signal "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/Events/Signal.lua"
    click Promise "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/Promise.lua"
    click Maid "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/Maid.lua"
    click Streamable "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/Streamable.lua"
    click Table "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/Table.lua"
    click Typeof "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/typeof.lua"
    click Wait "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/wait.lua"
    click CustomObjectsInit "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/init.lua"
    click ReplicatorClient "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/Custom Objects Replicator.client.lua"
    click Replicator "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/Utils/Replicator.lua"
    click Serialize "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/Utils/Serialize.lua"
    click UUID "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/Utils/UUID.lua"
    click CoreUtil "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/Utils/Core.lua"
    click Load "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/Utils/Load.lua"
    click Meta "https://github.com/1humza/evolve-framework/blob/master/src/EvolveLoader/Evolve/CustomObjects/Utils/init.meta.json"
    click ClassesUser "https://github.com/1humza/evolve-framework/tree/master/src/Modules/Classes"
    click ClientUser "https://github.com/1humza/evolve-framework/tree/master/src/Modules/Client"
    click ServerUser "https://github.com/1humza/evolve-framework/tree/master/src/Modules/Server"
    click SharedUser "https://github.com/1humza/evolve-framework/tree/master/src/Modules/Shared"

    %% Styles
    classDef loader fill:#e0f7e9,stroke:#34a853,stroke-width:2px;
    classDef core fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px,stroke-dasharray: 5 2;
    classDef util fill:#fce8b2,stroke:#fbbc05,stroke-width:2px;
    classDef replication fill:#f3e8fd,stroke:#8e24aa,stroke-width:2px;
    classDef user fill:#f5f5f5,stroke:#9e9e9e,stroke-width:1px,stroke-dasharray: 4 2;
```
