# focus-creative-games/luban architecture

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

- Interactive diagram: https://gitdiagram.com/focus-creative-games/luban
- Repository: https://github.com/focus-creative-games/luban

## Overview

Based on your project file tree and README, Luban is a highly modular game configuration solution that “generates” configuration assets and code based on various source data formats. It is not a traditional full-stack app but rather a code generation tool with a robust pipeline design that processes raw configuration data (from Excel, JSON, XML, YAML, Lua, etc.) and outputs configuration data in binary, JSON, BSON, and many other formats. It also generates code for multiple target languages (C#, C++, Java, Go, Dart, Python, TypeScript, Rust, PHP, etc.) using a templated approach.

##### Main Components
- Core Pipeline & Engine (Luban.Core): This is the heart of the generation system where the overall pipeline manages the flow.
- Data Loading & Parsing (DataLoader packages): Includes modules like Luban.DataLoader.Builtin and various raw definition loaders in Luban.Core/RawDefs and Luban.Schema.Builtin.
- Data Validation (DataValidator packages): Modules under Luban.DataValidator.Builtin that check ref integrity, path validations, range checks, etc.
- Schema/Definition Management: Components for loading and interpreting configurations (schema loader in Luban.Core/Schema, Def, and RawDefs).
- Code Generation Targets (CodeTarget modules): Language-specific modules such as Luban.CSharp, Luban.Cpp, Luban.Dart, Luban.Java, etc. Each language module contains both “CodeTarget” implementations (often found under CodeTarget folders) and template extensions for generating source code.
- Template Engine & Extensions: All the TemplateExtensions and Templates folders across modules, together with the Template Manager in Luban.Core/Tmpl, enable customization and extension.
- Data Output & Saving: Managed by the “OutputSaver” modules in Luban.Core/OutputSaver that abstract writing the generated code/data to files.
- Utility & Common Services: Includes a set of utility classes (under Luban.Core/Utils), custom behaviours, L10N support, type visitors, and other helper components.
- Pipeline Orchestration: The Pipeline folder in Luban.Core outlines the staged generation process with IPipeline and related managers.

##### Relationships and Interactions
- Next, the parsed data moves into the Schema/Definition Manager where it is structured as Beans, Enums, Tables, etc.
- Afterwards, the data is passed through Data Validator components that verify correctness.
- Then it enters the Core Generation Pipeline where the processing is orchestrated. Here, various “TypeVisitors” run to transform or inspect the definitions.
- From the pipeline, the flow branches into code generation via the CodeTarget modules. Each language-specific module (for C#, C++, Dart, Java, etc.) relies on its templates and template extensions to generate code.
- Finally, the generated outputs are handed to the OutputSaver modules that write files to disk.
- Additionally, plugin or custom behaviour modules can hook into various stages (as shown in CustomBehaviour folders) to customize the generation flow.

##### Architectural Patterns & Design Principles
- Modularity & Plugin Architecture: The system is divided into numerous independent modules (by language, data handling, validation, etc.), allowing easy extension. Emphasize the “plug-and-play” nature.
- Pipeline/Flow-based Processing: Highlight that the processing is conducted in defined stages (loading, validating, transforming, generating, saving), with each stage represented as a discrete component.
- Template Driven Code Generation: Stress the separation between the static template definitions (in Templates folders) and dynamic code generation logic (in CodeTarget and TemplateExtensions).

##### Relevant Technologies and Technologies
- That many directories contain .csproj files, indicating a .NET-based development environment for the core and most language support packages.
- That the system relies on configuration files (e.g., .editorconfig, .travis.yml, nlog.xml) to support building, formatting, and logging.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Input & Parsing
    subgraph "Data Input & Parsing"
        SD("Source Data (Excel,JSON,XML,YAML,Lua)"):::input
        DL("DataLoader Base"):::core
        BDL("Builtin Data Loaders"):::core
        RD("Raw Definitions"):::core
    end

    %% Schema/Definition Management
    subgraph "Schema/Definition Management"
        SL("Schema Loader/Manager"):::core
        DEF("Definitions"):::core
    end

    %% Data Validation
    subgraph "Data Validation"
        DV("Data Validator"):::core
    end

    %% Generation Pipeline
    subgraph "Generation Pipeline"
        CP("Core Pipeline & Engine"):::core
        PO("Pipeline Orchestration"):::core
        UT("Utility & Common Services"):::core
        CB("Custom Behaviour Modules"):::plugin
    end

    %% Template Engine & Extensions
    subgraph "Template Engine & Extensions"
        TM("Core Template Manager"):::template
        PT("Per-language Template Extensions"):::template
    end

    %% Code Generation Targets
    subgraph "Code Generation Targets"
        CS("C# CodeTarget"):::lang
        CPPC("C++ CodeTarget"):::lang
        DART("Dart CodeTarget"):::lang
        JAVA("Java CodeTarget"):::lang
        GO("Golang CodeTarget"):::lang
        GD("Gdscript CodeTarget"):::lang
        PHP("PHP CodeTarget"):::lang
        PB("Protobuf CodeTarget"):::lang
        PY("Python CodeTarget"):::lang
        RUST("Rust CodeTarget"):::lang
        TS("Typescript CodeTarget"):::lang
    end

    %% Data Output Generation
    subgraph "Data Output Generation"
        OUT("OutputSaver"):::output
    end

    %% Data Flow Connections
    SD -->|"loads"| DL
    SD -->|"loads"| BDL
    SD -->|"loads"| RD

    DL -->|"parses"| SL
    BDL -->|"parses"| SL
    RD -->|"contributes to"| SL
    DEF -->|"defines"| DV
    SL -->|"structures"| DV

    DV -->|"validated data"| CP

    CP -->|"orchestrates"| PO
    CP -->|"uses"| UT
    CP -->|"integrates"| CB
    CP -->|"triggers"| TM

    TM -->|"extends"| PT
    PT -->|"drives"| CS
    PT -->|"drives"| CPPC
    PT -->|"drives"| DART
    PT -->|"drives"| JAVA
    PT -->|"drives"| GO
    PT -->|"drives"| GD
    PT -->|"drives"| PHP
    PT -->|"drives"| PB
    PT -->|"drives"| PY
    PT -->|"drives"| RUST
    PT -->|"drives"| TS

    CS -->|"generates"| OUT
    CPPC -->|"generates"| OUT
    DART -->|"generates"| OUT
    JAVA -->|"generates"| OUT
    GO -->|"generates"| OUT
    GD -->|"generates"| OUT
    PHP -->|"generates"| OUT
    PB -->|"generates"| OUT
    PY -->|"generates"| OUT
    RUST -->|"generates"| OUT
    TS -->|"generates"| OUT

    %% Click Events
    click CP "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Core"
    click DL "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/DataLoader"
    click BDL "https://github.com/focus-creative-games/luban/blob/main/src/Luban.DataLoader.Builtin"
    click RD "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/RawDefs"
    click SL "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/Schema"
    click DEF "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/Defs"
    click DV "https://github.com/focus-creative-games/luban/blob/main/src/Luban.DataValidator.Builtin"
    click CS "https://github.com/focus-creative-games/luban/blob/main/src/Luban.CSharp"
    click CPPC "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Cpp"
    click DART "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Dart"
    click JAVA "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Java"
    click GO "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Golang"
    click GD "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Gdscript"
    click PHP "https://github.com/focus-creative-games/luban/blob/main/src/Luban.PHP"
    click PB "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Protobuf"
    click PY "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Python"
    click RUST "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Rust"
    click TS "https://github.com/focus-creative-games/luban/blob/main/src/Luban.Typescript"
    click TM "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/Tmpl"
    click OUT "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/OutputSaver"
    click UT "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/Utils"
    click PO "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/Pipeline"
    click CB "https://github.com/focus-creative-games/luban/tree/main/src/Luban.Core/CustomBehaviour"

    %% Styles
    classDef input fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef core fill:#FFF4C2,stroke:#333,stroke-width:2px;
    classDef plugin fill:#F7C2C2,stroke:#333,stroke-width:2px;
    classDef lang fill:#C2F7C9,stroke:#333,stroke-width:2px;
    classDef template fill:#E2C2F7,stroke:#333,stroke-width:2px;
    classDef output fill:#C2D1F7,stroke:#333,stroke-width:2px;
```
