# uber/nullaway architecture

> Architecture diagram of the GitHub repository uber/nullaway, 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/uber/nullaway
- Repository: https://github.com/uber/nullaway

## Overview

This project is a multi-module, Gradle-based tool designed to work as an Error Prone plugin for annotation-based null checking in Java. In other words, NullAway is a tool that integrates into the Java compilation process (via Error Prone) to catch potential null pointer dereferences by using annotations like @Nullable. Along with its core checking functionality, the project includes ancillary modules for generating library models, automatically inferring annotations (via jar-infer), performance benchmarks (via JMH), and example/sample applications/libraries for demonstration and integration testing.

##### Main Components
- NullAway Core – This is the heart of the tool. It is implemented under the “nullaway” module and includes the dataflow analysis, error reporting, and integration with Error Prone.
- Annotation API – Found in the “annotations” directory, this module defines the custom annotations (e.g., @EnsuresNonNull, @RequiresNonNull) used by NullAway.
- Jar Infer Modules – Located under the “jar-infer” directory, these provide automatic inference of nullability for compiled libraries. This component includes separate submodules for different Android SDK versions as well as the CLI and core library.
- Library Model Generator – Under “library-model”, this component generates models representing library APIs and their nullability behavior.
- Benchmarking and Testing – The “jmh” module contains benchmarks to measure the performance overhead of NullAway, while there are several test directories (e.g., “guava-recent-unit-tests”, “jdk-recent-unit-tests”, “nullaway/src/test/”, etc.) for integration and unit testing.
- Sample Applications and Libraries – Modules like “sample-app”, “sample-library-model”, “sample” provide sample usage, illustrating how end users integrate NullAway into their projects.
- Build and Configuration Infrastructure – Includes Gradle scripts, settings (build.gradle, settings.gradle), and CI/CD configurations (GitHub workflows) that orchestrate builds, tests, code coverage, and releases.

##### Relationships and Data/Control Flows
- How “NullAway Core” integrates with the Error Prone framework (marked as an external component) to intercept the compilation process and analyze code.
- Interaction between the “Jar Infer” modules and “NullAway Core”: inferred nullability models from jar-infer can be fed into the NullAway pipeline.
- “Library Model Generator” with both “NullAway Core” and sample/library modules to demonstrate how library nullability models are integrated into static analysis.
- A block for “Configuration & Build Scripts” to indicate that these files set up options (such as -Xep:NullAway:ERROR, options.errorprone, etc.) for processing by the NullAway tool during builds.

##### Architectural Patterns and Design Principles
- Modular Design – Each primary functionality is isolated in its own module (e.g., core analysis, annotation definitions, model generation) to allow for independent development, testing, and reuse.
- Plugin Architecture – NullAway works as a plugin to Error Prone, leveraging existing compiler checking capabilities while extending its functionality.
- Testability and Performance – Multiple test modules and the inclusion of benchmarking (via JMH) emphasize the importance of verifying behavior and ensuring performance remains acceptable.

- Main modules: NullAway core, annotations, jar-infer (with its submodules such as android-jarinfer-models for various SDKs, CLI, and lib), library-model generator, benchmarking (jmh), sample apps/libraries, and test suites.
- Clearly distinguish external dependencies (Error Prone, Gradle, third-party annotations like JSpecify or AndroidX) from in-house components.
- Build orchestration and CI/CD (from the .github folder configurations and Gradle scripts) which manage tests, benchmarks, and releases.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    subgraph "Core Modules"
        A["Annotations API"]:::core
        B["NullAway Core"]:::core
        C["Jar Infer Modules"]:::core
        D["Library Model Generator"]:::core
    end

    %% Testing and Samples
    subgraph "Testing and Samples"
        E["Benchmarking and Testing"]:::test
        subgraph "Sample Applications and Libraries"
            F["Sample App"]:::sample
            G["Sample Library Model"]:::sample
            H["Sample"]:::sample
        end
    end

    %% Build and Configuration Infrastructure
    subgraph "Build and Configuration Infrastructure"
        I["Build Gradle"]:::build
        J["Settings Gradle"]:::build
        K["CI/CD"]:::build
    end

    %% External Component
    L["Error Prone"]:::external

    %% Relationships between Core Modules
    A -->|"UsesAnnotations"| B
    C -->|"FeedsInferredNullability"| B
    D -->|"GeneratesLibraryModels"| B
    B -->|"Integrates"| L

    %% Relationships involving Library Model and Samples
    D -->|"SuppliesModels"| F
    D -->|"SuppliesModels"| G
    D -->|"SuppliesModels"| H

    %% Testing and Usage Flows
    B -->|"TestedBy"| E
    F -->|"Uses"| B
    G -->|"Uses"| B
    H -->|"Uses"| B

    %% Build and Configuration Flows
    I -->|"Configures"| B
    J -->|"Configures"| B
    K -->|"Orchestrates"| E
    K -->|"Orchestrates"| F
    K -->|"Orchestrates"| G
    K -->|"Orchestrates"| H
    K -->|"Orchestrates"| C
    K -->|"Orchestrates"| D

    %% Click Events
    click A "https://github.com/uber/nullaway/tree/master/annotations/"
    click B "https://github.com/uber/nullaway/tree/master/nullaway/"
    click C "https://github.com/uber/nullaway/tree/master/jar-infer/"
    click D "https://github.com/uber/nullaway/tree/master/library-model/"
    click E "https://github.com/uber/nullaway/tree/master/jmh/"
    click F "https://github.com/uber/nullaway/tree/master/sample-app/"
    click G "https://github.com/uber/nullaway/tree/master/sample-library-model/"
    click H "https://github.com/uber/nullaway/tree/master/sample/"
    click I "https://github.com/uber/nullaway/blob/master/build.gradle"
    click J "https://github.com/uber/nullaway/blob/master/settings.gradle"
    click K "https://github.com/uber/nullaway/tree/master/.github/"

    %% Style Definitions
    classDef core fill:#f9e79f,stroke:#d35400,stroke-width:2px;
    classDef test fill:#aed6f1,stroke:#2e86c1,stroke-width:2px;
    classDef sample fill:#abebc6,stroke:#229954,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#c0392b,stroke-width:2px,stroke-dasharray:5 5;
    classDef build fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
```
