# goldmansachs/jdmn-python-runtime architecture

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

- Interactive diagram: https://gitdiagram.com/goldmansachs/jdmn-python-runtime
- Repository: https://github.com/goldmansachs/jdmn-python-runtime

## Overview

##### Project Type and Purpose
- This project is a runtime library for processing DMN (Decision Model and Notation) and evaluating FEEL (Friendly Enough Expression Language). Its purpose is to serve as a lightweight engine to interpret and execute decision tables and expressions defined in DMN models.
- The README confirms it’s meant for installation via pip, and the file tree shows a modular, well-organized library structure with clearly separated functional areas, unit tests, CI scripts, and configuration files.

##### Analyzing the File Structure
- Top-level directories and files such as src/, tests/, and CI-related files indicate that the project is built around a clear separation of concerns (core runtime vs. FEEL language processing vs. testing).
- The src/jdmn directory is the core of the library and is split into subdirectories:
- src/jdmn/feel: Houses the FEEL implementation. The lib/ folder further breaks down into modules for base logic, standard libraries, and type-specific libraries (e.g., for booleans, numeric values, strings, dates/times, lists, ranges).
- src/jdmn/runtime: Contains classes for executing decisions (like DMNDecision, ExecutionContext, and DMNRuntimeException), along with utility modules such as caching, discovery, external execution, annotations, and event listeners.
- This level of granularity (e.g., type-specific comparators and libraries) points to a design that lends itself to modularization and possibly plug-and-play extensibility of individual FEEL type implementations.

##### Components
- Core DMN Runtime Engine:
- Central DMN engine that manages the execution context, decision processing, and exception handling.
- Classes like DMNDecision, ExecutionContext, and DMNRuntimeException.
- FEEL Evaluation Engine:
- Base and Standard FEEL Libraries (BaseFEELLib, BaseStandardFEELLib, DefaultStandardFEELLib)
- Specialized libraries for handling different types: Boolean, Numeric, List, Context, Range, String, and Temporal types.
- Type comparator modules for ordering and equality (such as ComparableComparator, EqualityComparator, etc.)
- Supporting Subsystems:
- External Function Executor: Outline the module that allows for external function execution (DefaultExternalFunctionExecutor), which likely integrates with external systems or libraries.
- Cache: Highlight the caching layer (DefaultCache) that supports runtime optimization.
- Event Listener Subsystem: Include modules from the listener directory (e.g., LoggingEventListener, NopEventListener) that handle events, rules, and annotations during DMN execution.
- Discovery and Registry: Briefly note modules such as ModelElementRegistry for discovery of model elements.
- Annotations: Represent how annotations (Annotation, AnnotationSet) are used to add metadata or runtime instrumentation.
- Infrastructure and CI/CD:

##### Relationships and Interactions
- The DMN Runtime Engine calls into the FEEL Evaluation Engine to perform its expression evaluations.
- The FEEL Engine, in turn, uses type-specific libraries to execute operations based on operand types.
- External function calls route through the External Function Executor, feeding back into the core execution context.
- The caching and event listener subsystems interact with the runtime to optimize performance and log/monitor decision executions.
- Data flow from input (decision context) to processing layers (FEEL library evaluation, decision resolution) and then to output (decision results).

##### Architectural Patterns and Design Principles
- Modular design: Each major domain (FEEL evaluation, DMN runtime, type libraries) is encapsulated within its own module and likely communicates via well-defined interfaces.
- Separation of concerns: Different components (e.g., evaluators vs. execution context) perform distinct roles, making the system easier to maintain and extend.
- Extensibility: The presence of multiple “Default” implementations (e.g., DefaultStandardFEELLib, DefaultCache) indicates an architecture built to allow alternative implementations or plugging in additional features if needed.

##### Relevant Technologies, Frameworks, and Libraries
- Python is the central language.
- Testing is handled by pytest and tox (as seen in the README and tests/ directory).
- CI/CD integration is managed via GitHub workflows and additional scripts in the ci/ directory.
- Static analysis and quality assurance are ensured by tools (pylint, flake8) as referenced in the configuration files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% DMN Execution Core Subgraph
    subgraph "DMN Execution Core"
        DMN_Runtime["DMN Runtime Engine"]:::runtime
        External_Fn["External Function Executor"]:::external
        Cache["Cache Subsystem"]:::cache
        Event_Listeners["Event Listener Subsystem"]:::event
        Model_Registry["Model Discovery/Registry"]:::discovery
        Annotations["Annotations Support"]:::annotation
    end

    %% FEEL Evaluation Core Subgraph
    subgraph "FEEL Evaluation Core"
        FEEL_Eval["FEEL Evaluation Engine"]:::feel
        Type_Libs["Type-Specific FEEL Libraries"]:::type
    end

    %% Infrastructure and Testing Subgraph
    subgraph "Infrastructure and Testing"
        CI_Infra["CI/CD Infrastructure"]:::infra
        Tests["Testing Modules"]:::infra
    end

    %% Relationships
    DMN_Runtime -->|"callsFEEL"| FEEL_Eval
    FEEL_Eval -->|"usesTypes"| Type_Libs
    DMN_Runtime -->|"executesExternal"| External_Fn
    DMN_Runtime -->|"appliesCache"| Cache
    DMN_Runtime -->|"logsEvents"| Event_Listeners
    DMN_Runtime -->|"discoversModels"| Model_Registry
    DMN_Runtime -->|"appliesAnnotations"| Annotations
    CI_Infra -->|"builds"| DMN_Runtime
    Tests -->|"validates"| DMN_Runtime

    %% Click Events
    click DMN_Runtime "https://github.com/goldmansachs/jdmn-python-runtime/tree/main/src/jdmn/runtime"
    click FEEL_Eval "https://github.com/goldmansachs/jdmn-python-runtime/tree/main/src/jdmn/feel/lib"
    click Type_Libs "https://github.com/goldmansachs/jdmn-python-runtime/tree/main/src/jdmn/feel/lib/type"
    click External_Fn "https://github.com/goldmansachs/jdmn-python-runtime/blob/main/src/jdmn/runtime/external/DefaultExternalFunctionExecutor.py"
    click Cache "https://github.com/goldmansachs/jdmn-python-runtime/blob/main/src/jdmn/runtime/cache/DefaultCache.py"
    click Event_Listeners "https://github.com/goldmansachs/jdmn-python-runtime/tree/main/src/jdmn/runtime/listener"
    click Model_Registry "https://github.com/goldmansachs/jdmn-python-runtime/blob/main/src/jdmn/runtime/discovery/ModelElementRegistry.py"
    click Annotations "https://github.com/goldmansachs/jdmn-python-runtime/tree/main/src/jdmn/runtime/annotation"
    click CI_Infra "https://github.com/goldmansachs/jdmn-python-runtime/tree/main/ci/"
    click Tests "https://github.com/goldmansachs/jdmn-python-runtime/tree/main/tests/"

    %% Styles
    classDef runtime fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef cache fill:#FAD7A0,stroke:#D68910,stroke-width:2px;
    classDef event fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef discovery fill:#D2B4DE,stroke:#7D3C98,stroke-width:2px;
    classDef annotation fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef feel fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef type fill:#D4EFDF,stroke:#239B56,stroke-width:2px;
    classDef infra fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
```
