# stellar-lua/stellar architecture

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

- Interactive diagram: https://gitdiagram.com/stellar-lua/stellar
- Repository: https://github.com/stellar-lua/stellar

## Overview

##### Project type and purpose
– Stellar is a lightweight, modular framework for Roblox games. It ships as a Rojo‐compatible library (managed by wally and aftman) providing Client, Server, and Shared utilities to accelerate game development.

##### File structure
Top‐level dev and config files
- .github/workflows/*.yaml → CI jobs for formatting, docs generation
- stylua.toml, selene.toml → code style and lint rules
- aftman.toml, wally.toml, moonwave.toml → package and site‐build config
Project sources in src/
- src/Core/Client – client‐side framework modules (e.g., ExampleClient.lua)
- src/Core/Server – server‐side modules (ExampleService.lua)
- src/Core/Shared – cross‐environment utilities (Network, Scheduler, SoundFX)
- src/Scripts/Client – entrypoint ClientCore.client.lua
- src/Scripts/Server – entrypoint ServerCore.server.lua
Documentation in docs/ and static assets in .moonwave/static

##### README for architectural hints
– Confirms it’s a framework plugged into Rojo, managed by aftman/wally
– Emphasizes simplicity and easy setup for both new and experienced developers

## Diagram (Mermaid)

```mermaid
graph TB
    %% Dev & CI Toolchain
    subgraph "Dev & CI Toolchain"
        direction TB
        GH_Docs["GitHub Actions (docs.yaml)"]:::dev
        GH_Format["GitHub Actions (format.yaml)"]:::dev
        Selene["selene.toml"]:::dev
        Stylua["stylua.toml"]:::dev
        WallyCFG["wally.toml"]:::dev
        AftmanCFG["aftman.toml"]:::dev
        Rojo["Rojo"]:::external
    end

    %% Documentation Site Generator
    subgraph "Documentation Site Generator"
        direction TB
        MoonwaveCFG["moonwave.toml"]:::dev
        StaticAssets[".moonwave/static"]:::dev
        DocsGetting["docs/gettingstarted.md"]:::dev
        DocsIntro["docs/intro.md"]:::dev
    end

    %% Core Library Modules
    subgraph "Core Library" 
        direction TB
        subgraph "Client Modules"
            direction TB
            ExampleClient["ExampleClient.lua"]:::code
        end
        subgraph "Server Modules"
            direction TB
            ExampleService["ExampleService.lua"]:::code
        end
        subgraph "Shared Utilities"
            direction TB
            StellarCore["Stellar.lua"]:::code
            subgraph "Utilities"
                direction TB
                Network["Network.lua"]:::code
                Scheduler["Scheduler.lua"]:::code
                SoundFX["SoundFX.lua"]:::code
            end
        end
    end

    %% Entrypoints
    subgraph "Entrypoint Scripts"
        direction TB
        ClientCore["ClientCore.client.lua"]:::entry
        ServerCore["ServerCore.server.lua"]:::entry
    end

    %% Roblox Runtime
    subgraph "Roblox Runtime"
        direction TB
        ClientVM["Client VM"]:::external
        ServerVM["Server VM"]:::external
    end

    %% Connections: CI to Configs
    GH_Docs -->|triggers docs build| MoonwaveCFG
    GH_Docs -->|uses| DocsGetting
    GH_Docs -->|uses| DocsIntro
    GH_Format -->|format rules| Stylua
    GH_Format -->|lint rules| Selene
    GH_Format -->|package deps| WallyCFG
    GH_Format -->|orchestrate| AftmanCFG
    WallyCFG -->|integrates with| Rojo
    AftmanCFG -->|build site| StaticAssets

    %% Build to Docs
    MoonwaveCFG --> StaticAssets

    %% Entrypoints import Core
    ClientCore -->|imports| ExampleClient
    ClientCore -->|imports| StellarCore
    ServerCore -->|imports| ExampleService
    ServerCore -->|imports| StellarCore

    %% Runtime flows
    ExampleClient -->|runs on| ClientVM
    ExampleService -->|runs on| ServerVM
    StellarCore -->|shared logic| ClientVM
    StellarCore -->|shared logic| ServerVM
    Network -->|Client↔Server communication| ClientVM
    Network -->|Client↔Server communication| ServerVM
    Scheduler -->|schedules tasks| ClientVM
    Scheduler -->|schedules tasks| ServerVM
    SoundFX -->|audio playback| ClientVM
    SoundFX -->|audio management| ServerVM
    ClientVM <-->|Network utility| ServerVM

    %% Deployment
    Rojo -->|deploys package to| ClientVM
    Rojo -->|deploys package to| ServerVM

    %% Click Events
    click GH_Docs "https://github.com/stellar-lua/stellar/blob/main/.github/workflows/docs.yaml"
    click GH_Format "https://github.com/stellar-lua/stellar/blob/main/.github/workflows/format.yaml"
    click Selene "https://github.com/stellar-lua/stellar/blob/main/selene.toml"
    click Stylua "https://github.com/stellar-lua/stellar/blob/main/stylua.toml"
    click WallyCFG "https://github.com/stellar-lua/stellar/blob/main/wally.toml"
    click AftmanCFG "https://github.com/stellar-lua/stellar/blob/main/aftman.toml"
    click MoonwaveCFG "https://github.com/stellar-lua/stellar/blob/main/moonwave.toml"
    click StaticAssets "https://github.com/stellar-lua/stellar/tree/main/.moonwave/static"
    click DocsGetting "https://github.com/stellar-lua/stellar/blob/main/docs/gettingstarted.md"
    click DocsIntro "https://github.com/stellar-lua/stellar/blob/main/docs/intro.md"
    click ExampleClient "https://github.com/stellar-lua/stellar/blob/main/src/Core/Client/ExampleClient.lua"
    click ExampleService "https://github.com/stellar-lua/stellar/blob/main/src/Core/Server/ExampleService.lua"
    click StellarCore "https://github.com/stellar-lua/stellar/blob/main/src/Core/Shared/Stellar.lua"
    click Network "https://github.com/stellar-lua/stellar/blob/main/src/Core/Shared/Utilities/Network.lua"
    click Scheduler "https://github.com/stellar-lua/stellar/blob/main/src/Core/Shared/Utilities/Scheduler.lua"
    click SoundFX "https://github.com/stellar-lua/stellar/blob/main/src/Core/Shared/Utilities/SoundFX.lua"
    click ClientCore "https://github.com/stellar-lua/stellar/blob/main/src/Scripts/Client/ClientCore.client.lua"
    click ServerCore "https://github.com/stellar-lua/stellar/blob/main/src/Scripts/Server/ServerCore.server.lua"
    click Rojo "https://github.com/stellar-lua/stellar/blob/main/default.project.json"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef dev fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef entry fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
