Key Classes by Subsystem

This is the "where does X live" map. When you have a behavior and need the class that implements it — or a class name from a stack trace and need to know what subsystem owns it — start here. Each subsystem lists its key classes, a one-line role, and the chapter that explains it in full.

The classes span three roots: OpenSearch server (org.opensearch.*), Apache Lucene (org.apache.lucene.*), and the plugin ecosystems (org.opensearch.knn.*, org.opensearch.security.*). Package prefixes are given once per row where they aren't obvious.

Warning: Class names get refactored across versions — a class may move packages, split, or be renamed. Treat every name here as a starting point and grep to confirm in your checkout:

# Confirm a class exists and find its package:
grep -rn "class BalancedShardsAllocator" server/src/main/java/
# Find an interface's implementations:
grep -rln "implements AllocationDecider\|extends AllocationDecider" server/src/main/java/

Note: "cluster manager" (formerly "master") is the current term. The Java classes and methods were renamed (MasterService→ClusterManagerService, getMasterNode()→getClusterManagerNode()); only user-facing settings/REST params keep a deprecated master alias (e.g. master_timeout). When reading older blogs or 1.x/2.x code, mentally map every Master* symbol to its ClusterManager* name — and grep for both, since branches differ.

Jump to: Node & bootstrap · Cluster coordination · Cluster state · Transport · REST · Actions · Thread pools · Indexing & engine · Translog · Mapping & analysis · Search · Query & scoring · Aggregations · DocValues · Allocation · Recovery · Replication · Snapshots · Circuit breakers · Plugins · k-NN · Security · Telemetry

Node & bootstrap

The startup path: parse settings, build every service, wire them together.

Cluster coordination

Electing a cluster manager and agreeing on state — the Zen2 / Raft-like layer.

Cluster state

The immutable, versioned snapshot every node agrees on, and how updates apply.

Transport

The node-to-node RPC fabric (port 9300).

REST

The HTTP edge (port 9200): route → handler → client call.

Actions

Binding request types to handlers and intercepting them.

Thread pools

The bounded executors that run all work, and the context they carry.

Indexing & engine

The per-shard write path over Lucene.

Translog

The per-shard write-ahead log.

Mapping & analysis

Schema and the text-to-terms pipeline.

Search

Fanning a search across shards and reducing it.

Query & scoring

DSL → Lucene query → scored hits.

Aggregations

Building and reducing summaries.

DocValues

Columnar per-doc storage and its legacy heap cousin.

Allocation

Placing and balancing shards.

Recovery

Filling a placed shard.

Replication

Keeping copies in sync.

Snapshots

Backup/restore to a repository.

Circuit breakers

Memory safety.

Plugins

The extension model.

k-NN

Vector search (the k-NN plugin).

Security

The bundled security plugin (org.opensearch.security.*).

Telemetry

Tracing and metrics (org.opensearch.telemetry.*).

Using this map from a stack trace

The fastest path from a stack trace to understanding:

# 1. Take the most specific opensearch/lucene/knn/security frame, e.g.:
#    org.opensearch.cluster.routing.allocation.allocator.BalancedShardsAllocator.balance(...)

# 2. Find the subsystem in this doc (Allocation) and confirm the class:
grep -rn "class BalancedShardsAllocator" server/src/main/java/

# 3. Read the chapter the row points at, then return to the trace.

Note: A frame in org.apache.lucene.* means the failure is below OpenSearch — in storage/search primitives. Switch to the ../lucene/index.md chapters. A frame in org.opensearch.knn.* or org.opensearch.security.* means a plugin owns it — go to the k-NN or security material, which live in separate repos.