# xiaokuntt/business-util architecture

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

- Interactive diagram: https://gitdiagram.com/xiaokuntt/business-util
- Repository: https://github.com/xiaokuntt/business-util

## Overview

##### Project Type and Purpose
- This is a Java/Maven-based open-source utility library (“business-util”) designed to simplify complex business-rule and configuration matching by providing a priority-based matching engine.
- There is no “frontend” or “backend” in the typical web-app sense. Instead, the key focus is on a reusable API and an internal matching engine.

a. API Layer
- PriorityAssembler<TSource, TConfig, TKey>
- PriorityFetcher<TSource, TConfig, TKey>
b. Matching Engine (Core Logic)
- PriorityMatchFunction – encapsulates a single matching rule
- PriorityMatchProcessor → orchestrates the sequential execution of functions
- PriorityMatchProcessorTree → optional tree-based processor for large rule sets
- PriorityHandler (and its two built-in implementations driven by PriorityMode)
c. Data Models / Value Objects
- PriorityMatchResult – holds matched configurations and metadata
- PriorityMatchType, PriorityMode – enums defining match types and handler modes

##### Relationships & Data Flow
- Client (your application) → calls PriorityAssembler.from(...) → obtains an assembler.
- Assembler
→ initConfig(configList) loads TConfig objects into an internal store
→ addPriorityMatchFunction(...) registers one or more PriorityMatchFunction instances
→ initPriorityHandler(PriorityMode) selects a PriorityHandler strategy
→ create() produces a PriorityFetcher instance
- PriorityFetcher
→ when match(source) is invoked, it instantiates either
- a flat list of PriorityMatchProcessor, or
- a PriorityMatchProcessorTree (if .tree() is called)
→ processes the input source through the chain/tree of PriorityMatchFunction nodes
→ applies the configured PriorityHandler (e.g., NUMBER_OF_MATCHES or ABSOLUTE_VALUE)
→ returns a PriorityMatchResult containing the best-match configuration(s)
- PriorityMatchResult flows back to the client

##### Architectural Patterns & Principles
- Builder/Fluent API: PriorityAssembler as a chained initializer for configuration, functions, and handler.
- Strategy Pattern: PriorityHandler is pluggable (two built-in strategies plus room for custom handlers).
- Chain of Responsibility / Tree Structure: sequential processors or a tree of processors for performance at scale.
- Separation of Concerns:
- Assembler – setup/configuration
- Fetcher/Processor – execution logic
- Handler – prioritization strategy
- Model – enums and result object

##### Technologies & Frameworks
- Java 8+ (lambdas for match functions)
- Maven for build and dependency management
- JUnit for tests (src/test)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Application"
        Client["Client"]:::client
    end

    subgraph "API Layer"
        Assembler["PriorityAssembler<TSource,TConfig,TKey>"]:::api
        Fetcher["PriorityFetcher<TSource,TConfig,TKey>"]:::api
    end

    subgraph "Core Engine"
        MatchFunction["PriorityMatchFunction"]:::engine
        Processor["PriorityMatchProcessor"]:::engine
        ProcessorTree["PriorityMatchProcessorTree"]:::engine
        Handler["PriorityHandler"]:::engine
    end

    subgraph "Models/Enums"
        MatchResult["PriorityMatchResult"]:::model
        MatchType["PriorityMatchType"]:::model
        Mode["PriorityMode"]:::model
    end

    Client -->|"PriorityAssembler.from(...)"| Assembler
    Assembler -->|"initConfig(list)"| Assembler
    Assembler -->|"addPriorityMatchFunction(fn)"| Assembler
    Assembler -->|"initPriorityHandler(mode)"| Assembler
    Assembler -->|"create()"| Fetcher

    Fetcher -->|"match(source)"| Processor
    Fetcher -.->|"tree()"| ProcessorTree

    Processor -->|"execute chain"| MatchFunction
    ProcessorTree -->|"execute tree"| MatchFunction

    MatchFunction -->|"produce matches"| Handler
    Handler -->|"apply strategy"| MatchFunction
    Handler -->|"return best-match"| MatchResult

    MatchResult -->|"return result"| Client

    click Assembler "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/PriorityAssembler.java"
    click Fetcher "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/PriorityFetcher.java"
    click MatchFunction "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/PriorityMatchFunction.java"
    click Processor "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/PriorityMatchProcessor.java"
    click ProcessorTree "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/PriorityMatchProcessorTree.java"
    click Handler "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/handler/PriorityHandler.java"
    click MatchType "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/handler/PriorityMatchType.java"
    click Mode "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/handler/PriorityMode.java"
    click MatchResult "https://github.com/xiaokuntt/business-util/blob/master/src/main/java/cn/ykccchen/businessutil/match/PriorityMatchResult.java"

    classDef client fill:#f2f2f2,stroke:#333;
    classDef api fill:#D6E4FB,stroke:#1E3A8A;
    classDef engine fill:#D1FAE5,stroke:#065F46;
    classDef model fill:#FEF3C7,stroke:#92400E;
```
