# apache/opennlp architecture

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

- Interactive diagram: https://gitdiagram.com/apache/opennlp
- Repository: https://github.com/apache/opennlp

## Overview

##### Project Type and Purpose
- Apache OpenNLP is an open-source, Java-based NLP toolkit. It exposes a Java API (“opennlp-api”, “opennlp-tools”) and a CLI layer (“opennlp-cli”) to perform NLP tasks (tokenization, sentence detection, POS tagging, named-entity extraction, parsing, etc.).
- It is packaged as a multi-module Maven project, offering pluggable model loaders (“opennlp-models”), runtime implementations (“opennlp-runtime”), and extensions (UIMA, Morfologik, ONNX/DL backends).

##### Key Architectural Modules (top-level Maven modules)
- opennlp-api/opennlp-tools: core interfaces and abstractions.
- opennlp-runtime: reference implementations of tokenizers, taggers, parsers, chunkers, etc.
- opennlp-cli (under opennlp-core): command-line tools that wrap API calls.
- opennlp-models: utilities to locate and load prebuilt models from classpath or filesystem.
- opennlp-ml, opennlp-ml-commons, opennlp-ml-bayes, opennlp-ml-maxent, opennlp-ml-perceptron: algorithm modules (MaxEnt, Naive Bayes, Perceptron, DL).
- opennlp-extensions: optional add-ons (UIMA annotators, Morfologik lemmatizer, ONNX GPU support).
- opennlp-distr: distribution packaging (assembly scripts, Dockerfile).
- opennlp-docs: documentation source (DocBook).

##### Relationships and Data Flows
- End users invoke either:
- Java API → interfaces in opennlp-tools → implementations in opennlp-runtime or algorithm modules → model loaders → models → NLP output.
- CLI tool (“opennlp” shell script) → CLI wrappers in opennlp-cli → underlying API layers as above.
- All modules share common utilities (object streams, event streams, feature generators) in opennlp-tools/src/main/java/opennlp/tools/util.
- ML algorithm modules provide trainers and models to runtime. Extensions plug into API via SPI or direct dependency.

##### Architectural Patterns and Principles
- Layered architecture:
- API layer (interfaces)
- Implementation layer (runtime + algorithms)
- Presentation layer (CLI)
- Modularization via Maven: each concern is a separate artifact.
- Plug-in architecture for feature generators, model providers, and extensions (ExtensionLoader, ServiceKeys).
- Streaming data pattern: use of ObjectStream<T> for data ingestion.
- Build automation and CI via Maven, GitHub Actions.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Layers and modules
    subgraph "Presentation Layer (CLI)" 
        direction TB
        CLIJava["CLI Java Wrappers"]:::core
        CLIScript["CLI Shell Scripts"]:::core
    end

    subgraph "API Layer" 
        direction TB
        APILayer["opennlp-tools Interfaces\n(opennlp-api)"]:::core
    end

    subgraph "Runtime Layer" 
        direction TB
        Runtime["Reference Implementations\n(opennlp-runtime)"]:::core
        subgraph "ML Algorithm Modules"
            direction TB
            MLCommons["ML Commons\n(opennlp-ml-commons)"]:::algo
            MLBayes["Naive Bayes\n(opennlp-ml-bayes)"]:::algo
            MLMaxEnt["MaxEnt\n(opennlp-ml-maxent)"]:::algo
            MLPerceptron["Perceptron\n(opennlp-ml-perceptron)"]:::algo
            DLCPU["DL Backend CPU\n(opennlp-dl)"]:::algo
            DLGPU["DL Backend GPU\n(opennlp-dl-gpu)"]:::algo
        end
    end

    subgraph "Model Loader" 
        direction TB
        ModelLoader["Model Providers\n(opennlp-models)"]:::core
        ModelFiles["Prebuilt Models"]:::core
    end

    subgraph "Extensions" 
        direction TB
        ExtMorf["Morfologik Lemmatizer"]:::ext
        ExtUIMA["UIMA Annotators"]:::ext
    end

    subgraph "Distribution & Docs" 
        direction TB
        Distr["Distribution Packaging"]:::pkg
        Docs["Documentation (DocBook)"]:::doc
    end

    %% Dependencies and data flows
    CLIJava -->|"invokes"| APILayer
    CLIScript -->|"shell exec"| CLIJava
    APILayer -->|"calls"| Runtime
    Runtime -->|"loads via SPI"| ModelLoader
    ModelLoader -->|"provides"| ModelFiles
    Runtime -->|"uses trainers"| MLCommons
    Runtime -->|"uses trainers"| MLBayes
    Runtime -->|"uses trainers"| MLMaxEnt
    Runtime -->|"uses trainers"| MLPerceptron
    Runtime -->|"uses DL"| DLCPU
    Runtime -->|"uses DL GPU"| DLGPU
    Runtime -->|"extension point"| ExtMorf
    Runtime -->|"extension point"| ExtUIMA
    Distr ---|packaging| CLIJava
    Distr ---|includes| CLIScript
    Distr ---|Docker| Distr
    Docs ---|documents| APILayer

    %% Click Events
    click APILayer "https://github.com/apache/opennlp/tree/main/opennlp-api/src/main/java/opennlp/tools"
    click CLIJava "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-cli/src/main/java/opennlp/tools/cmdline"
    click CLIScript "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-cli/src/main/bin/opennlp*"
    click Runtime "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools"
    click ModelLoader "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-models/src/main/java/opennlp/tools/models"
    click MLCommons "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-ml/opennlp-ml-commons/src/main/java/opennlp/tools/ml"
    click MLBayes "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-ml/opennlp-ml-bayes/src/main/java/opennlp/tools/ml/naivebayes"
    click MLMaxEnt "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-ml/opennlp-ml-maxent/src/main/java/opennlp/tools/ml/maxent"
    click MLPerceptron "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-ml/opennlp-ml-perceptron/src/main/java/opennlp/tools/ml/perceptron"
    click DLCPU "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-ml/opennlp-dl/src/main/java/opennlp/dl"
    click DLGPU "https://github.com/apache/opennlp/tree/main/opennlp-core/opennlp-ml/opennlp-dl-gpu"
    click ExtMorf "https://github.com/apache/opennlp/tree/main/opennlp-extensions/opennlp-morfologik/src/main/java/opennlp/morfologik"
    click ExtUIMA "https://github.com/apache/opennlp/tree/main/opennlp-extensions/opennlp-uima/src/main/java/opennlp/uima"
    click Distr "https://github.com/apache/opennlp/tree/main/opennlp-distr/src/main/assembly"
    click Docs "https://github.com/apache/opennlp/tree/main/opennlp-docs/src/docbkx"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#006064
    classDef algo fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef ext fill:#fff3e0,stroke:#ef6c00,color:#ef6c00
    classDef pkg fill:#eceff1,stroke:#455a64,color:#455a64
    classDef doc fill:#f3e5f5,stroke:#6a1b9a,color:#6a1b9a
```
