# vavr-io/vavr architecture

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

- Interactive diagram: https://gitdiagram.com/vavr-io/vavr
- Repository: https://github.com/vavr-io/vavr

## Overview

##### Project Type and Purpose
- Vavr is an open-source, multi-module Maven project that provides an object-functional extension for Java.
- It consists of a Scala-based code generator module plus a core library module delivering immutable collections, functional control structures, pattern matching, concurrency abstractions, etc.

##### High-Level File‐Structure Analysis
- Top-level:
– pom.xml (parent POM orchestrating modules)
– .github/ (CI/CD workflows: ci.yml, doclint-version.yml, release.yml)
– vavr/ (multi-module directory)
- vavr/generator (Scala module)
– Generator.scala: generates Java sources under vavr/src-gen
– Its own pom.xml, invoked during a Maven build
- vavr/src-gen (generated code)
– main/java/io/vavr: API.java, FunctionN, TupleN, etc.
– test/java/io/vavr: unit tests for generated code
- vavr/src/main/java (core library)
– io.vavr.collection, io.vavr.control, io.vavr.concurrent, value types, pattern-matching support
- vavr/src/test/java (core tests)
- .github/workflows (CI pipelines)

##### README Insights
- Describes library features, Maven/Gradle usage, and contributors’ branches.
- No runtime services or external dependencies beyond the JVM.

##### Main Components
A. Developer + GitHub Repository
- Source code (generator + core)
- GitHub Actions workflows (CI, doclint, release)
B. Build System (Maven)
- Parent POM orchestrates two child modules:
1. generator module (Scala) → produces vavr/src-gen
2. core library module (Java) → consumes both src/main and src-gen
- Lifecycle phases: generate-sources → compile → test → package → verify → deploy
C. Code Generator Module
- Reads configuration/templates → generates Java API/FunctionN/TupleN classes → writes to src-gen
D. Core Library Module
- Packages:
– io.vavr.collection (persistent collections)
– io.vavr.control (Either, Option, Try, Validation)
– io.vavr.concurrent (Future, Promise, Task)
– io.vavr (Lazy, PartialFunction, MatchError, etc.)
- Unit tests validate both handwritten and generated code
- Javadoc plugin for API docs
E. CI/CD Pipeline
- CI workflow: runs mvn clean test, jacoco, code coverage
- doclint workflow: generates Javadoc, checks doc style
- release workflow: on tag → mvn deploy → publish to Maven Central
F. Consumers
- Maven Central / Gradle users fetch io.vavr:vavr jar

##### Relationships and Data Flows
- Developer push → GitHub repo triggers CI workflows
- CI invokes Maven parent POM
→ generator module runs in generate-sources phase → outputs to vavr/src-gen
→ compiler compiles src/main + src-gen
→ tests run (on core + generated code)
→ package phase produces .jar, source.jar, javadoc.jar
- Release workflow pushes artifacts to Maven Central
- End users (Java developers) retrieve artifact as a dependency

##### Architectural Patterns and Design Principles
- Multi-module Maven (separation of concerns: code generation vs. core logic)
- Code-generation pipeline (Scala → Java) to avoid boilerplate in API
- Clear package boundaries for functional domains (collection, control, concurrent)
- Immutable and persistent data structures throughout the library

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Developer["Developer"]:::external
    GitHubRepo["GitHub Repository"]:::external
    Consumers["Java Developers\n(Maven/Gradle)"]:::external

    %% CI/CD Workflows
    subgraph "CI/CD Pipeline" 
        direction TB
        CIWorkflow["CI Workflow\n(mvn clean test)"]:::ci
        DoclintWorkflow["Doclint Workflow\n(generate Javadoc)"]:::ci
        ReleaseWorkflow["Release Workflow\n(publish tag)"]:::ci
    end

    %% Build System
    subgraph "Maven Build" 
        direction TB
        ParentPOM["Parent POM\n(pom.xml)"]:::build
        GeneratorModule["Generator Module\n(vavr/generator)"]:::module
        GeneratedSources["Generated Sources\n(vavr/src-gen)"]:::module
        CoreModule["Core Library Module\n(vavr/src/main/java)"]:::module
        CoreTests["Core Module Tests\n(vavr/src/test/java)"]:::module
        Packaging["Packaging & Javadoc"]:::build
    end

    %% Publication & Consumption
    MavenCentral["Maven Central"]:::external

    %% Connections
    Developer -->|"push code"| GitHubRepo
    GitHubRepo -->|triggers| CIWorkflow
    GitHubRepo -->|triggers| DoclintWorkflow
    GitHubRepo -->|on tag triggers| ReleaseWorkflow

    CIWorkflow -->|invokes| ParentPOM
    ParentPOM -->|generate-sources phase| GeneratorModule
    GeneratorModule -->|writes to| GeneratedSources
    ParentPOM -->|compile phase| CoreModule
    GeneratedSources -->|compiled by| CoreModule
    ParentPOM -->|test phase| CoreTests
    ParentPOM -->|package phase| Packaging

    ReleaseWorkflow -->|runs| ParentPOM
    Packaging -->|deploy phase| MavenCentral
    MavenCentral -->|dependency| Consumers

    %% Click Events
    click ParentPOM "https://github.com/vavr-io/vavr/blob/main/pom.xml"
    click Developer "https://github.com/vavr-io/vavr/blob/main/README.md"
    click Developer "https://github.com/vavr-io/vavr/blob/main/CONTRIBUTING.md"
    click CIWorkflow "https://github.com/vavr-io/vavr/blob/main/.github/workflows/ci.yml"
    click DoclintWorkflow "https://github.com/vavr-io/vavr/blob/main/.github/workflows/doclint-version.yml"
    click ReleaseWorkflow "https://github.com/vavr-io/vavr/blob/main/.github/workflows/release.yml"
    click GeneratorModule "https://github.com/vavr-io/vavr/tree/main/vavr/generator"
    click GeneratorModule "https://github.com/vavr-io/vavr/blob/main/vavr/generator/Generator.scala"
    click ParentPOM "https://github.com/vavr-io/vavr/blob/main/vavr/pom.xml"
    click GeneratedSources "https://github.com/vavr-io/vavr/tree/main/vavr/src-gen/main/java/io/vavr"
    click GeneratedSources "https://github.com/vavr-io/vavr/blob/main/vavr/src-gen/main/java/io/vavr/API.java"
    click GeneratedSources "https://github.com/vavr-io/vavr/blob/main/vavr/src-gen/main/java/io/vavr/FunctionN.java"
    click GeneratedSources "https://github.com/vavr-io/vavr/blob/main/vavr/src-gen/main/java/io/vavr/TupleN.java"
    click GeneratedSources "https://github.com/vavr-io/vavr/blob/main/vavr/src-gen/main/java/io/vavr/collection/ArrayType.java"
    click GeneratedSources "https://github.com/vavr-io/vavr/tree/main/vavr/src-gen/test/java/io/vavr"
    click GeneratedSources "https://github.com/vavr-io/vavr/tree/main/vavr/src-gen/test/java/io/vavr/collection"
    click CoreModule "https://github.com/vavr-io/vavr/tree/main/vavr/src/main/java/io/vavr"
    click CoreModule "https://github.com/vavr-io/vavr/tree/main/vavr/src/main/java/io/vavr/collection"
    click CoreModule "https://github.com/vavr-io/vavr/tree/main/vavr/src/main/java/io/vavr/control"
    click CoreModule "https://github.com/vavr-io/vavr/tree/main/vavr/src/main/java/io/vavr/concurrent"
    click CoreModule "https://github.com/vavr-io/vavr/blob/main/vavr/src/main/javadoc/overview.html"
    click CoreTests "https://github.com/vavr-io/vavr/tree/main/vavr/src/test/java/io/vavr"
    click CoreTests "https://github.com/vavr-io/vavr/tree/main/vavr/src/test/java/io/vavr/collection"
    click CoreTests "https://github.com/vavr-io/vavr/tree/main/vavr/src/test/java/io/vavr/control"
    click CoreTests "https://github.com/vavr-io/vavr/tree/main/vavr/src/test/java/io/vavr/concurrent"

    %% Styles
    classDef external fill:#EEEEEE,stroke:#333,stroke-width:1px
    classDef build fill:#C1E1C1,stroke:#2E8B57,stroke-width:2px
    classDef module fill:#ADD8E6,stroke:#4682B4,stroke-width:2px
    classDef ci fill:#F0E68C,stroke:#DAA520,stroke-width:2px
```
