# oracle/opengrok architecture

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

- Interactive diagram: https://gitdiagram.com/oracle/opengrok
- Repository: https://github.com/oracle/opengrok

## Overview

##### Main modules (nodes)
- opengrok-indexer
- opengrok-web
- suggester
- plugins
- tools
- distribution (assembly, Docker)
- Third-party libraries (Lucene, Jersey/JAX-RS, JFlex, ChronicleMap, various SCM client libs)
- Runtime environment (JVM, Python runtime for tools, Docker container)

##### Dependencies (directed edges)
- opengrok-web → opengrok-indexer (uses indexer’s search API and configuration classes)
- opengrok-web → plugins (loads authorization plugins at startup)
- opengrok-web → suggester (optional: web’s API/v1/suggester controllers call suggester library)
- suggester → opengrok-indexer (reads Lucene index files produced by indexer)
- plugins → opengrok-web (plugins implement IAuthorizationPlugin interfaces used by web)
- tools → opengrok-indexer (calls Java indexer CLI or REST API to perform indexing)
- tools → opengrok-web (deploys or configures webapp via REST)
- distribution → all Java modules (bundles .war/.jar artifacts into one distribution)
- Docker container (docker/*) → distribution artifacts + Python tools (requires Python runtime)
- All Java modules → JFlex (code generation for analyzers), Lucene (index persistence), SLF4J/log4j (logging)

##### Architectural patterns and principles
- Maven multi-module project — each subdirectory (opengrok-indexer, opengrok-web, suggester, plugins, tools) is a separate artifact.
- Separation of concerns — indexer (backend indexing/search core), web (REST/UI layer), suggester (suggestion engine), tools (administration scripts).
- Plugin framework — indexer and web load plugins via a classloader; show “plugins” node pointing into both indexer and web.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Distribution & Docker"
        DIST["distribution"]:::dist
        DOCKER["Docker Container"]:::dist
    end

    subgraph "UI/API Layer"
        WEB["opengrok-web"]:::ui
    end

    subgraph "Core Modules"
        INDEX["opengrok-indexer"]:::core
        SUG["suggester"]:::core
        PLUG["plugins"]:::ext
    end

    ANAL["JFlex Analyzers"]:::core

    subgraph "Libraries"
        LIB["Lucene / SLF4J / JAX-RS / ChronicleMap / Others"]:::lib
    end

    subgraph "Runtimes"
        JVM["JVM Runtime"]:::runtime
        PY["Python Runtime"]:::runtime
    end

    subgraph "Tools"
        TOOLS["tools"]:::tools
    end

    DIST -->|bundles artifacts| WEB
    DIST -->|bundles artifacts| INDEX
    DIST -->|bundles artifacts| SUG
    DIST -->|bundles artifacts| PLUG
    DIST -->|bundles artifacts| TOOLS
    DOCKER -->|runs distribution| DIST
    DOCKER -->|requires Python Runtime| PY

    WEB -->|uses search API| INDEX
    WEB -->|loads plugins| PLUG
    WEB -->|optional suggests| SUG
    WEB -->|depends on Libraries| LIB
    WEB -->|runs on JVM| JVM

    INDEX -->|generates analyzers| ANAL
    INDEX -->|depends on Libraries| LIB
    INDEX -->|runs on JVM| JVM

    SUG -->|reads Lucene index| INDEX
    SUG -->|depends on Libraries| LIB
    SUG -->|runs on JVM| JVM

    PLUG -->|implements IAuthorizationPlugin| WEB
    PLUG -->|depends on Libraries| LIB
    PLUG -->|runs on JVM| JVM

    TOOLS -.->|calls indexer CLI| INDEX
    TOOLS -.->|deploys web via REST| WEB
    TOOLS -->|depends on Python Runtime| PY

    LIB -->|runs on JVM| JVM

    click INDEX "https://github.com/oracle/opengrok/tree/master/opengrok-indexer/"
    click WEB "https://github.com/oracle/opengrok/tree/master/opengrok-web/"
    click SUG "https://github.com/oracle/opengrok/tree/master/suggester/"
    click PLUG "https://github.com/oracle/opengrok/tree/master/plugins/"
    click TOOLS "https://github.com/oracle/opengrok/tree/master/tools/"
    click DIST "https://github.com/oracle/opengrok/blob/master/distribution/assembly.xml"
    click DIST "https://github.com/oracle/opengrok/blob/master/distribution/pom.xml"
    click DOCKER "https://github.com/oracle/opengrok/tree/master/docker/"
    click ANAL "https://github.com/oracle/opengrok/tree/master/opengrok-indexer/src/main/jflex/analysis/"
    click PY "https://github.com/oracle/opengrok/tree/master/tools/src/main/python/"

    classDef core fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef ui fill:#ABEBC6,stroke:#239B56,color:#239B56;
    classDef ext fill:#FAD7A0,stroke:#B9770E,color:#B9770E;
    classDef tools fill:#D2B4DE,stroke:#7D3C98,color:#7D3C98;
    classDef dist fill:#D5DBDB,stroke:#566573,color:#566573;
    classDef lib fill:#E5E7E9,stroke:#A6ACAF,color:#566573;
    classDef runtime fill:#EBF5FB,stroke:#5DADE2,color:#1B4F72;
```
