# apache/lucene architecture

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

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

## Overview

Apache Lucene is a Java text-search library. A representative workflow accepts query text, parses it into a query representation, searches an index, and collects matching results; Lucene also provides analysis, facets, monitoring, highlighting, spatial search, suggestions, and related modules. The graph reflects documented capabilities and sampled implementation references; several subsystem connections remain unverified because their source was not sampled.

Main entry points: [`lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java`](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java) (Search execution), [`lucene/core/src/java/org/apache/lucene/search/Query.java`](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/Query.java) (Query model), [`lucene/monitor/src/java/org/apache/lucene/monitor/CustomQueryHandler.java`](https://github.com/apache/lucene/blob/main/lucene/monitor/src/java/org/apache/lucene/monitor/CustomQueryHandler.java) (Query monitoring), [`lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/standard/processors/StandardQueryNodeProcessorPipeline.java`](https://github.com/apache/lucene/blob/main/lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/standard/processors/StandardQueryNodeProcessorPipeline.java) (Query parsing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_querying["Querying and Search"]
  node_queryparser["Query parsing"]
  node_query["Query model<br/>[Query.java]"]
  node_searcher["Search execution<br/>[IndexSearcher.java]"]
  node_collectors["Result collection"]
  node_booleanquery["Boolean queries<br/>[BooleanQuery.java]"]
  node_termquery["Term queries<br/>[TermQuery.java]"]
end

subgraph group_indexing["Indexing and Analysis"]
  node_indexwriter["Index writing<br/>[IndexWriter.java]"]
  node_reader["Index readers<br/>[IndexReader.java]"]
  node_terms["Term access<br/>[TermsEnum.java]"]
  node_bytes["Term bytes<br/>[BytesRef.java]"]
  node_analysis["Text analysis"]
  node_hunspell["Hunspell storage<br/>[WordStorage.java]"]
end

subgraph group_extensions["Search Extensions"]
  node_facets["Faceted search"]
  node_monitor["Query monitoring"]
  node_highlight["Result highlighting<br/>[QueryScorer.java]"]
  node_spatial["Spatial search"]
  node_suggest["Search suggestions<br/>[ContextQuery.java]"]
  node_grouping["Result grouping"]
  node_querytree["Query tree<br/>[QueryTree.java]"]
end

node_developer(("Library user"))

node_developer -.->|"provides text"| node_queryparser
node_queryparser -->|"builds query"| node_query
node_searcher -->|"rewrites and weighs"| node_query
node_searcher -->|"uses reader"| node_reader
node_searcher -->|"reduces results"| node_collectors
node_query -->|"specialized by"| node_booleanquery
node_query -->|"specialized by"| node_termquery
node_facets -->|"uses for collection"| node_searcher
node_monitor -->|"handles queries"| node_query
node_monitor -->|"uses tree"| node_querytree
node_indexwriter -.->|"index lifecycle"| node_reader
node_analysis -.->|"prepares indexed text"| node_indexwriter
node_highlight -.->|"uses search results"| node_searcher
node_spatial -.->|"adds query types"| node_query
node_suggest -.->|"supports suggestions"| node_searcher
node_grouping -.->|"collects groups"| node_searcher
node_terms -.->|"seeks terms"| node_bytes
node_hunspell -.->|"supports analysis"| node_analysis

click node_queryparser "https://github.com/apache/lucene/blob/main/lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/standard/processors/StandardQueryNodeProcessorPipeline.java"
click node_query "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/Query.java"
click node_searcher "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java"
click node_collectors "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/CollectorManager.java"
click node_booleanquery "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/BooleanQuery.java"
click node_termquery "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/TermQuery.java"
click node_indexwriter "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java"
click node_reader "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/index/IndexReader.java"
click node_terms "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/index/TermsEnum.java"
click node_bytes "https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/util/BytesRef.java"
click node_analysis "https://github.com/apache/lucene/tree/main/lucene/analysis/common/src/java/org/apache/lucene/analysis"
click node_hunspell "https://github.com/apache/lucene/blob/main/lucene/analysis/common/src/java/org/apache/lucene/analysis/hunspell/WordStorage.java"
click node_facets "https://github.com/apache/lucene/blob/main/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollectorManager.java"
click node_monitor "https://github.com/apache/lucene/blob/main/lucene/monitor/src/java/org/apache/lucene/monitor/CustomQueryHandler.java"
click node_highlight "https://github.com/apache/lucene/blob/main/lucene/highlighter/src/java/org/apache/lucene/search/highlight/QueryScorer.java"
click node_spatial "https://github.com/apache/lucene/blob/main/lucene/spatial-extras/src/java/org/apache/lucene/spatial/composite/CompositeVerifyQuery.java"
click node_suggest "https://github.com/apache/lucene/blob/main/lucene/suggest/src/java/org/apache/lucene/search/suggest/document/ContextQuery.java"
click node_grouping "https://github.com/apache/lucene/blob/main/lucene/grouping/src/java/org/apache/lucene/search/grouping/AllGroupHeadsCollectorManager.java"
click node_querytree "https://github.com/apache/lucene/blob/main/lucene/monitor/src/java/org/apache/lucene/monitor/QueryTree.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_queryparser,node_query,node_searcher,node_collectors,node_booleanquery,node_termquery,node_developer toneBlue
class node_indexwriter,node_reader,node_terms,node_bytes,node_analysis,node_hunspell toneAmber
class node_facets,node_monitor,node_highlight,node_spatial,node_suggest,node_grouping,node_querytree toneMint
```

## Components

### Querying and Search

- [Query parsing](https://github.com/apache/lucene/blob/main/lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/standard/processors/StandardQueryNodeProcessorPipeline.java): `lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/standard/processors/StandardQueryNodeProcessorPipeline.java`
- [Query model](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/Query.java): `lucene/core/src/java/org/apache/lucene/search/Query.java`
- [Search execution](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java): `lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java`
- [Result collection](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/CollectorManager.java): `lucene/core/src/java/org/apache/lucene/search/CollectorManager.java`
- [Boolean queries](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/BooleanQuery.java): `lucene/core/src/java/org/apache/lucene/search/BooleanQuery.java`
- [Term queries](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/search/TermQuery.java): `lucene/core/src/java/org/apache/lucene/search/TermQuery.java`

### Indexing and Analysis

- [Index writing](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/index/IndexWriter.java): `lucene/core/src/java/org/apache/lucene/index/IndexWriter.java`
- [Index readers](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/index/IndexReader.java): `lucene/core/src/java/org/apache/lucene/index/IndexReader.java`
- [Term access](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/index/TermsEnum.java): `lucene/core/src/java/org/apache/lucene/index/TermsEnum.java`
- [Term bytes](https://github.com/apache/lucene/blob/main/lucene/core/src/java/org/apache/lucene/util/BytesRef.java): `lucene/core/src/java/org/apache/lucene/util/BytesRef.java`
- [Text analysis](https://github.com/apache/lucene/tree/main/lucene/analysis/common/src/java/org/apache/lucene/analysis): `lucene/analysis/common/src/java/org/apache/lucene/analysis`
- [Hunspell storage](https://github.com/apache/lucene/blob/main/lucene/analysis/common/src/java/org/apache/lucene/analysis/hunspell/WordStorage.java): `lucene/analysis/common/src/java/org/apache/lucene/analysis/hunspell/WordStorage.java`

### Search Extensions

- [Faceted search](https://github.com/apache/lucene/blob/main/lucene/facet/src/java/org/apache/lucene/facet/FacetsCollectorManager.java): `lucene/facet/src/java/org/apache/lucene/facet/FacetsCollectorManager.java`
- [Query monitoring](https://github.com/apache/lucene/blob/main/lucene/monitor/src/java/org/apache/lucene/monitor/CustomQueryHandler.java): `lucene/monitor/src/java/org/apache/lucene/monitor/CustomQueryHandler.java`
- [Result highlighting](https://github.com/apache/lucene/blob/main/lucene/highlighter/src/java/org/apache/lucene/search/highlight/QueryScorer.java): `lucene/highlighter/src/java/org/apache/lucene/search/highlight/QueryScorer.java`
- [Spatial search](https://github.com/apache/lucene/blob/main/lucene/spatial-extras/src/java/org/apache/lucene/spatial/composite/CompositeVerifyQuery.java): `lucene/spatial-extras/src/java/org/apache/lucene/spatial/composite/CompositeVerifyQuery.java`
- [Search suggestions](https://github.com/apache/lucene/blob/main/lucene/suggest/src/java/org/apache/lucene/search/suggest/document/ContextQuery.java): `lucene/suggest/src/java/org/apache/lucene/search/suggest/document/ContextQuery.java`
- [Result grouping](https://github.com/apache/lucene/blob/main/lucene/grouping/src/java/org/apache/lucene/search/grouping/AllGroupHeadsCollectorManager.java): `lucene/grouping/src/java/org/apache/lucene/search/grouping/AllGroupHeadsCollectorManager.java`
- [Query tree](https://github.com/apache/lucene/blob/main/lucene/monitor/src/java/org/apache/lucene/monitor/QueryTree.java): `lucene/monitor/src/java/org/apache/lucene/monitor/QueryTree.java`

### Other components

- **Library user**

## Connections

- Library user → Query parsing: provides text
- Query parsing → Query model: builds query (evidence: `lucene/queryparser/src/java/org/apache/lucene/queryparser/flexible/standard/processors/StandardQueryNodeProcessorPipeline.java`)
- Search execution → Query model: rewrites and weighs (evidence: `lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java`)
- Search execution → Index readers: uses reader (evidence: `lucene/core/src/java/org/apache/lucene/search/IndexSearcher.java`)
- Search execution → Result collection: reduces results (evidence: `lucene/core/src/java/org/apache/lucene/search/CollectorManager.java`)
- Query model → Boolean queries: specialized by (evidence: `lucene/core/src/java/org/apache/lucene/search/Query.java`)
- Query model → Term queries: specialized by (evidence: `lucene/core/src/java/org/apache/lucene/search/Query.java`)
- Faceted search → Search execution: uses for collection (evidence: `lucene/facet/src/java/org/apache/lucene/facet/FacetsCollectorManager.java`)
- Query monitoring → Query model: handles queries (evidence: `lucene/monitor/src/java/org/apache/lucene/monitor/CustomQueryHandler.java`)
- Query monitoring → Query tree: uses tree (evidence: `lucene/monitor/src/java/org/apache/lucene/monitor/CustomQueryHandler.java`)
- Index writing → Index readers: index lifecycle
- Text analysis → Index writing: prepares indexed text
- Result highlighting → Search execution: uses search results
- Spatial search → Query model: adds query types
- Search suggestions → Search execution: supports suggestions (evidence: `lucene/suggest/src/java/org/apache/lucene/search/suggest/document/ContextQuery.java`)
- Result grouping → Search execution: collects groups
- Term access → Term bytes: seeks terms (evidence: `lucene/core/src/java/org/apache/lucene/index/TermsEnum.java`)
- Hunspell storage → Text analysis: supports analysis (evidence: `lucene/analysis/common/src/java/org/apache/lucene/analysis/hunspell/WordStorage.java`)