# bilibili/gengine architecture

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

- Interactive diagram: https://gitdiagram.com/bilibili/gengine
- Repository: https://github.com/bilibili/gengine

## Overview

##### Main Components
a. Rule Builder Module (Directory: builder)
- Component responsible for constructing rule definitions (e.g., rule_builder.go). It likely prepares the rules for parsing or execution.
b. Data Context Management (Directory: context)
- Handles the data (variables, contexts, etc.) passed to rules when they are executed (e.g., data_context.go).
c. Engine Module (Directory: engine)
- Contains the core execution logic (e.g., gengine.go and engine pool management in gengine_pool.go). It is the runtime that applies the loaded rules against the data context.
d. Internal AST & Rule Language Representation (Directory: internal)
- “base” subdirectory: Houses definitions for rule components (statements, expressions, function calls, variables, assignments, etc.). These represent the grammar and constructs of the user-defined rules.
- “core” subdirectory: Implements execution helpers (e.g., execute.go, math operations). Core runtime functions like execution control, nil checks, or math functions are added here.
- “iantlr” subdirectory: Provides integration with ANTLR, including parsers, lexers, and listeners (e.g., gengineLexer, gengineParser) for generating and processing the AST from rule definitions.
- “iparser” subdirectory: Additional parsing support that handles errors, listener logic, or visitor patterns in rule parsing.
- “iter” and “tool” subdirectories: Likely provide iteration helpers and utility functions that support the main components.
e. Testing & Validation:
- The “test” directory is comprehensive and covers unit, integration, concurrent, and complex scenarios – signifying a well-tested engine architecture.

##### Relationships and Data Flow
- A rule (written in a DSL or specific syntax) is input into the system.
- The Rule Builder takes the raw rule input and prepares it for parsing.
- The iantlr and iparser modules (with support from the “base” definitions) parse the input into an Abstract Syntax Tree (AST) that represents the rule.
- The Execution Engine (engine module) receives the AST along with a Data Context (from the context module) and then evaluates or ‘executes’ the rule.
- Core functions and additional utility functions from the “core”, “iter”, and “tool” modules support execution, error handling, and result aggregation.
- Optionally, results might be fed back to the application or be used in a pool to execute multiple rules concurrently (as supported by engine pool and test cases).

##### Architectural Patterns and Principles
- Modular Design:
– Separation of concerns is clear: rule building, parsing/AST construction, execution, and context management are separate.
- Extensibility:
– The integration with ANTLR demonstrates extensibility by allowing the engine to handle a complex grammar.
- Dynamic Code/Rules Loading:
– The design allows for rules to be loaded and interpreted at runtime without restarting the main application.
- Testing Coverage:
– The presence of diverse test directories underscores the importance of robustness and concurrent processing capabilities.
- Clear Separation of Parsing and Execution:
– The “base”, “iantlr”, and “iparser” directories suggest that the system explicitly distinguishes the parsing of rules from their execution.

##### Relevant Technologies & Frameworks
- Golang is the primary language.
- ANTLR is implied by the “iantlr” directory for parsing and lexing.
- Go modules (go.mod) manage project dependencies.
- Testing frameworks are used extensively in the “test” directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Rule Input"]:::input
    B["Rule Builder (rule_builder.go)"]:::builder

    subgraph "Parsing/AST Creation"
        C["AST Definitions (internal/base)"]:::parser
        D["ANTLR Integration (internal/iantlr)"]:::parser
        E["Additional Parsing Support (internal/iparser)"]:::parser
    end

    subgraph "Execution Engine"
        F1["Engine Core (gengine.go)"]:::engine
        F2["Engine Pool (gengine_pool.go)"]:::engine
    end

    G["Data Context Management (data_context.go)"]:::context

    subgraph "Support Utilities"
        H["Core Execution Helpers (internal/core)"]:::utilities
        I["Iteration (internal/iter/iter.go)"]:::utilities
        J["Utilities (internal/tool/tool.go)"]:::utilities
    end

    K["Testing & Validation (test)"]:::testing

    A --> B
    B --> C
    C --> D
    D --> E
    E --> F1
    H --> F1
    I --> F1
    J --> F1
    F1 --> F2
    F2 --> G
    G --> K

    click B "https://github.com/bilibili/gengine/blob/main/builder/rule_builder.go"
    click G "https://github.com/bilibili/gengine/blob/main/context/data_context.go"
    click F1 "https://github.com/bilibili/gengine/blob/main/engine/gengine.go"
    click F2 "https://github.com/bilibili/gengine/blob/main/engine/gengine_pool.go"
    click C "https://github.com/bilibili/gengine/tree/main/internal/base"
    click H "https://github.com/bilibili/gengine/tree/main/internal/core"
    click D "https://github.com/bilibili/gengine/tree/main/internal/iantlr"
    click E "https://github.com/bilibili/gengine/tree/main/internal/iparser"
    click I "https://github.com/bilibili/gengine/blob/main/internal/iter/iter.go"
    click J "https://github.com/bilibili/gengine/blob/main/internal/tool/tool.go"
    click K "https://github.com/bilibili/gengine/tree/main/test"

    classDef input fill:#B2EBF2,stroke:#006064,stroke-width:2px;
    classDef builder fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef parser fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef engine fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef context fill:#D1C4E9,stroke:#6A1B9A,stroke-width:2px;
    classDef utilities fill:#F8BBD0,stroke:#AD1457,stroke-width:2px;
    classDef testing fill:#CFD8DC,stroke:#455A64,stroke-width:2px;
```
