# formlio/forml architecture

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

- Interactive diagram: https://gitdiagram.com/formlio/forml
- Repository: https://github.com/formlio/forml

## Overview

##### Main Components
- Application and DSL Layer: This includes modules in forml/application and the DSL components under forml/io/dsl and the docs/dsl folder. This layer is responsible for accepting user-defined declarations, parsing the DSL (domain-specific language), and formally describing the ML problem.
- Evaluation and Metrics: The forml/evaluation modules deal with evaluation API, methods, metrics, and phases of the ML lifecycle. This shows a distinct component for evaluating model performance.
- Providers: The forml/provider package breaks further into several submodules (feed, gateway, inventory, registry, runner, sink). They are the glue between ForML and external systems, handling integrations (like REST API, Dask, Spark, file systems, MLflow, etc.).
- Runtime & Operational Services: The forml/runtime directory shows components like runtime agents, performance monitoring, and prediction services. This part represents the execution layer that manages the lifecycle and operational needs.
- Project & Setup: Managed under forml/project and forml/setup, these modules are responsible for configuring, packaging, and deploying a ForML project. They include templates, setuptools integration, and logging configurations.
- I/O Components: Located under forml/io, these modules manage data ingestion and output handling, along with asset management.
- Testing and Examples: The tests and tutorials directories provide examples and validate the integrations across different layers (useful for visualizing interactions between components).

##### Relationships and Data Flow
- User Interaction and DSL Processing: Start from the user input (the high-level problem description) which is parsed by the DSL parser (forml/io/dsl/*) and converted into a formal internal representation.
- Flow Compilation: The parsed operators feed into the flow and pipeline modules where the DAG is created. Include the flow compiler (located in forml/flow/_code/compiler.py) and the task assembly from forml/flow/_suite.
- Execution & Evaluation: After constructing the DAG, it is executed by the runtime services (forml/runtime) and dispatched to external providers (forml/provider/*). The evaluation module then collects metrics and applies methods spanning the ML lifecycle.
- Project Setup and Integration: The project configuration (forml/project and forml/setup) sets up the environment and integrates external libraries, ensuring the correct operational dependencies are injected.
- I/O Operations: Data access flows through the I/O handlers to supply and commit data before and after processing. This connection ensures that data assets (files, directories, etc.) are correctly handled by modules in forml/io/asset, _input, and _output.

##### Architectural Patterns and Design Principles
- Layered Architecture: The system cleanly separates the user’s problem definition (DSL, project specification) from the internal pipeline/DAG construction and from the runtime execution and external integrations.
- Use of a DAG for Workflow Execution: The “Not Just Another DAG” concept underlines that while a DAG is used at the core, the design is specialized for ML workflows through built-in operators.
- Extensibility and Modularity: With separate components for evaluation, provider integrations, and runtime, the framework can easily extend functionality by adding new modules or providers.

## Diagram (Mermaid)

```mermaid
flowchart TB

    %% User Input & DSL Layer
    subgraph "User Input & DSL Layer"
        DSLProblem["User Defined Problem (DSL)"]:::user
        DSLParser["DSL Parser"]:::dsl
        Application["Application Layer"]:::dsl
        DSLDoc["DSL Documentation"]:::dsl
    end

    %% Project Setup & I/O
    subgraph "Project Setup & I/O"
        ProjectSetup["Project Setup & Configuration"]:::setup
        IOManager["I/O Manager"]:::io
    end

    %% Flow & Pipeline Layer
    subgraph "Flow & Pipeline"
        FlowCompiler["Flow Compiler / DAG Creator"]:::flow
        PipelineManager["Pipeline Manager"]:::flow
    end

    %% Runtime & Providers Layer
    subgraph "Runtime & Operational Execution"
        RuntimeSrv["Runtime Services"]:::runtime
        Providers["Providers Integration"]:::provider
    end

    %% Evaluation Layer
    Eval["Evaluation & Metrics"]:::eval

    %% Testing & Examples Layer
    subgraph "Testing & Examples"
        Tests["Tests"]:::test
        Tutorials["Tutorials & Demos"]:::test
    end

    %% Connections
    DSLProblem -->|"parsedBy"| DSLParser
    DSLParser -->|"informs"| Application
    Application -->|"documents"| DSLDoc
    DSLParser -->|"feeds"| FlowCompiler
    ProjectSetup -->|"configures"| FlowCompiler
    IOManager -->|"suppliesData"| FlowCompiler
    FlowCompiler -->|"compilesTo"| PipelineManager
    PipelineManager -->|"executesOn"| RuntimeSrv
    RuntimeSrv -->|"integrates"| Providers
    RuntimeSrv -->|"reportsTo"| Eval
    Providers -->|"suppliesTo"| Eval
    Eval -->|"validatedBy"| Tests
    Eval -->|"validatedBy"| Tutorials

    %% Click Events for Application and DSL Layer
    click Application "https://github.com/formlio/forml/tree/main/forml/application"
    click DSLParser "https://github.com/formlio/forml/tree/main/forml/io/dsl"
    click DSLDoc "https://github.com/formlio/forml/tree/main/docs/dsl"

    %% Click Events for Flow and Pipeline
    click FlowCompiler "https://github.com/formlio/forml/blob/main/forml/flow/_code/compiler.py"
    click PipelineManager "https://github.com/formlio/forml/tree/main/forml/pipeline"

    %% Click Events for Providers and Runtime
    click Providers "https://github.com/formlio/forml/tree/main/forml/provider"
    click RuntimeSrv "https://github.com/formlio/forml/tree/main/forml/runtime"

    %% Click Events for Project & I/O Components
    click ProjectSetup "https://github.com/formlio/forml/tree/main/forml/project"
    click IOManager "https://github.com/formlio/forml/tree/main/forml/io"

    %% Click Event for Evaluation
    click Eval "https://github.com/formlio/forml/tree/main/forml/evaluation"

    %% Click Events for Testing and Examples
    click Tests "https://github.com/formlio/forml/tree/main/tests"
    click Tutorials "https://github.com/formlio/forml/tree/main/tutorials"

    %% Styles
    classDef user fill:#f9e79f,stroke:#d7bde2,stroke-width:2px;
    classDef dsl fill:#aed6f1,stroke:#5dade2,stroke-width:2px;
    classDef setup fill:#f5b7b1,stroke:#ec7063,stroke-width:2px;
    classDef io fill:#fad7a0,stroke:#f39c12,stroke-width:2px;
    classDef flow fill:#a3e4d7,stroke:#45b39d,stroke-width:2px;
    classDef runtime fill:#f7dc6f,stroke:#f1c40f,stroke-width:2px;
    classDef provider fill:#d2b4de,stroke:#af7ac5,stroke-width:2px;
    classDef eval fill:#d5f5e3,stroke:#58d68d,stroke-width:2px;
    classDef test fill:#f5eef8,stroke:#bb8fce,stroke-width:2px;
```
