# charnyanton/rulesengine architecture

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

- Interactive diagram: https://gitdiagram.com/charnyanton/rulesengine
- Repository: https://github.com/charnyanton/rulesengine

## Overview

##### Project type and purpose
- This is an actor-based, rule-evaluation Swift library (not a full-stack app).
- Its purpose is to provide a generic, priority-based decision-making engine that evaluates a set of independent rules against a mutable context.

##### File structure
- Top-level files:
- Package.swift – Swift Package Manager manifest
- README.md, LICENSE, .gitignore
- Sources/RulesEngine
- Core types: AnyRule.swift, EvaluationResult.swift
- Protocols: ApplicationContextProtocol, RuleProtocol, RulesEngineProtocol
- Implementation: RulesEngine.swift
- Tests/RulesEngineTests

##### Key points from README
- Engine accepts:
- A list of main rules (type-erased to AnyRule)
- A list of override rules
- A fallback EvaluationResult
- A default context
- It sorts rules by priority, applies them against the context, handles overrides, returns a final decision.

##### Main components
a. Protocol layer
- ApplicationContextProtocol
- RuleProtocol<Context,Outcome>
- RulesEngineProtocol
b. Core data structures
- AnyRule (type erasure wrapper)
- EvaluationResult (decision + reason)
c. Engine implementation
- RulesEngine (actor)
d. Client code (example)
- Concrete Context (e.g., MyContext)
- Concrete Rules (e.g., AdminRule)
e. External boundaries
- Consumer application calling engine.makeOutcome()

##### Relationships and data flow
- Consumer → initializes RulesEngine with:
– [AnyRule<ConcreteRule>] (main rules)
– [AnyRule<OverrideRule>]
– fallback EvaluationResult
– default Context
- RulesEngine actor
↓ (await)
- sorts rules by priority
- for each rule: rule.evaluate(context) → optional Outcome
- applies override logic
- if no rule matches, uses fallback
↓
returns EvaluationResult to consumer

##### Architectural patterns & principles
- Protocol-oriented design (Protocols folder)
- Type erasure (AnyRule) to store heterogeneous RuleProtocol implementations
- Actor isolation for thread safety
- Priority queue pattern for rule ordering
- Context-driven mutable state passed to rules

##### Detailed component breakdown
- ApplicationContextProtocol
- RuleProtocol (generic interface)
- AnyRule (type erasure)
- RulesEngineProtocol (engine interface)
- RulesEngine (actor implementation)
- EvaluationResult (decision + reason)
- Concrete rule implementations (e.g., AdminRule)
- Consumer context (e.g., MyContext)

##### Putting it all together
- Inside RulesEngine:

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Protocols"
        ACP["ApplicationContextProtocol"]:::protocols
        RP["RuleProtocol<Context,Outcome>"]:::protocols
        REP["RulesEngineProtocol"]:::protocols
    end

    subgraph "Core Types"
        AR["AnyRule"]:::core
        ER["EvaluationResult"]:::core
    end

    subgraph "Engine Implementation"
        RE["RulesEngine (actor)"]:::engine
        subgraph "Processing Flow"
            S1["Sort rules by priority"]:::engine
            S2["Evaluate each rule\nrule.evaluate(context)"]:::engine
            S3["Apply override logic"]:::engine
            S4["Return EvaluationResult"]:::engine
        end
    end

    subgraph "Consumer / Example"
        ConsumerApp["Consumer App"]:::consumer
        CC["MyContext"]:::consumer
        CR["AdminRule (ConcreteRule)"]:::consumer
    end

    ConsumerApp -->|"initialize(rules, overrideRules, fallback, defaultContext)"| RE
    RE --> S1
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S2 -->|uses| AR
    S2 -->|conforms to| RP
    RE -->|returns| ER
    ConsumerApp -->|"calls makeOutcome()"| RE
    CR -->|wrapped by| AR
    ConsumerApp --> CC

    click ACP "https://github.com/charnyanton/rulesengine/blob/main/Sources/RulesEngine/Protocols/ApplicationContextProtocol.swift"
    click RP "https://github.com/charnyanton/rulesengine/blob/main/Sources/RulesEngine/Protocols/RuleProtocol.swift"
    click REP "https://github.com/charnyanton/rulesengine/blob/main/Sources/RulesEngine/Protocols/RulesEngineProtocol.swift"
    click AR "https://github.com/charnyanton/rulesengine/blob/main/Sources/RulesEngine/AnyRule.swift"
    click ER "https://github.com/charnyanton/rulesengine/blob/main/Sources/RulesEngine/EvaluationResult.swift"
    click RE "https://github.com/charnyanton/rulesengine/blob/main/Sources/RulesEngine/RulesEngine.swift"

    classDef protocols fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef core fill:#90EE90,stroke:#000,stroke-width:1px
    classDef engine fill:#FFA500,stroke:#000,stroke-width:1px
    classDef consumer fill:#D3D3D3,stroke:#000,stroke-width:1px
```
