# kmesiab/go-policy-enforcer architecture

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

- Interactive diagram: https://gitdiagram.com/kmesiab/go-policy-enforcer
- Repository: https://github.com/kmesiab/go-policy-enforcer

## Overview

##### Project type and purpose
- This is a Go-based library (not a standalone app) whose sole purpose is to let other Go programs apply “policies” (sets of field-based rules) to arbitrary Go structs at runtime. It is packaged for reuse, extensibility (custom operators), and reflection-driven evaluation.

##### File structure
- Top level:
- core API files: policy.go, rule.go, policy_enforcer.go, evaluator.go
- operator definitions: operators.go, operators_map.go
- custom extensions: custom_operators/
- internal utilities: internal/utils/
- examples: examples/* (show usage scenarios)
- CI/CD: .github/workflows/*.yml
- Patterns and choices:
- Registry pattern for operators (operators_map.go)
- Reflection (evaluator.go) to walk dot-notation fields
- Extensibility via pluggable operator implementations
- Example JSON policy files (examples/json_policy_example/)

##### README for additional insights
- Confirms: dynamic enforcement, reflection, custom operators, JSON policy file support, Enforce vs. Match APIs, nested struct support.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    ClientApp["Client Application"]:::client

    %% Public API Layer
    subgraph "Public API" 
        PolicyEnforcer["PolicyEnforcer\n(NewPolicyEnforcer, Enforce/Match)"]:::publicAPI
        Policy["Policy\n(Name, []Rule)"]:::publicAPI
        Rule["Rule\n(FieldPath, Operator, Value)"]:::publicAPI
    end

    %% Core Engine Layer
    subgraph "Core Engine"
        Evaluator["Evaluator Engine"]:::coreEngine
        Reflection["Reflection Subsystem"]:::coreEngine
    end

    %% Extension Layer
    subgraph "Extensibility"
        OperatorRegistry["Operator Registry\nMap[string]OperatorFunc"]:::extension
        CustomOps["Custom Operators"]:::extension
    end

    %% Examples & Support Layer
    subgraph "Examples & Support"
        JSONLoader["JSON Policy Loader\n(main.go, JSON policies)"]:::support
        AuthExample["Authentication Example"]:::support
        InternalUtils["Internal Utilities"]:::support
        CICDPipelines["CI/CD Pipelines"]:::support
    end

    %% Relationships
    ClientApp -->|"calls Enforce/Match"| PolicyEnforcer
    PolicyEnforcer -->|"holds []*Policy"| Policy
    Policy -->|"contains []Rule"| Rule
    PolicyEnforcer -->|"for each Rule & Resource"| Evaluator
    Evaluator -->|"uses reflection"| Reflection
    Evaluator -->|"looks up operator"| OperatorRegistry
    Reflection -->|"field value"| Evaluator
    OperatorRegistry -->|"OperatorFunc"| Evaluator
    Evaluator -->|"bool result"| PolicyEnforcer
    PolicyEnforcer -->|"final outcome"| ClientApp

    %% Extensibility flow
    CustomOps -->|"registers in"| OperatorRegistry
    JSONLoader -->|"builds []Policy"| PolicyEnforcer
    AuthExample -->|"demo usage"| PolicyEnforcer
    InternalUtils --> Reflection
    CICDPipelines -.-> PolicyEnforcer

    %% Click Events
    click PolicyEnforcer "https://github.com/kmesiab/go-policy-enforcer/blob/main/policy_enforcer.go"
    click Policy "https://github.com/kmesiab/go-policy-enforcer/blob/main/policy.go"
    click Rule "https://github.com/kmesiab/go-policy-enforcer/blob/main/rule.go"
    click Evaluator "https://github.com/kmesiab/go-policy-enforcer/blob/main/evaluator.go"
    click OperatorRegistry "https://github.com/kmesiab/go-policy-enforcer/blob/main/operators_map.go"
    click OperatorRegistry "https://github.com/kmesiab/go-policy-enforcer/blob/main/operators.go"
    click Reflection "https://github.com/kmesiab/go-policy-enforcer/blob/main/internal/utils/helpers.go"
    click CustomOps "https://github.com/kmesiab/go-policy-enforcer/blob/main/custom_operators/deep_equals_slice_operator.go"
    click CustomOps "https://github.com/kmesiab/go-policy-enforcer/tree/main/custom_operators/"
    click JSONLoader "https://github.com/kmesiab/go-policy-enforcer/blob/main/examples/json_policy_example/main.go"
    click JSONLoader "https://github.com/kmesiab/go-policy-enforcer/tree/main/examples/json_policy_example/policies/"
    click AuthExample "https://github.com/kmesiab/go-policy-enforcer/blob/main/examples/authentication/main.go"
    click InternalUtils "https://github.com/kmesiab/go-policy-enforcer/blob/main/internal/utils/helpers.go"
    click CICDPipelines "https://github.com/kmesiab/go-policy-enforcer/blob/main/.github/workflows/go-build.yml"
    click CICDPipelines "https://github.com/kmesiab/go-policy-enforcer/blob/main/.github/workflows/go-lint.yml"
    click CICDPipelines "https://github.com/kmesiab/go-policy-enforcer/blob/main/.github/workflows/go-test.yml"

    %% Styles
    classDef publicAPI fill:#E3F2FD,stroke:#1E88E5,color:#0D47A1;
    classDef coreEngine fill:#FCE4EC,stroke:#C2185B,color:#880E4F;
    classDef extension fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef client fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef support fill:#ECEFF1,stroke:#546E7A,color:#263238;
```
