# opensearch-project/opensearch architecture

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

- Interactive diagram: https://gitdiagram.com/opensearch-project/opensearch
- Repository: https://github.com/opensearch-project/opensearch

## Overview

OpenSearch is a distributed search and observability engine. A typical client submits a request through the high-level REST client and HTTP transport to a cluster, where search services execute queries and optional search pipelines shape processing. Indexing can pass through ingest pipelines before reaching shard engines; streaming ingestion adds poller state management and cluster metadata coordination. The tree and excerpts support these core areas, REST client layers, PPL query service, and cloud repository integrations. Many server links are inferred from component roles; unsampled wiring is not expanded.

Main entry points: [`server/src/main/java/org/opensearch/search/SearchService.java`](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/search/SearchService.java) (Search execution), [`client/rest-high-level/src/main/java/org/opensearch/client/RestHighLevelClient.java`](https://github.com/opensearch-project/opensearch/blob/main/client/rest-high-level/src/main/java/org/opensearch/client/RestHighLevelClient.java) (REST high-level client), [`client/rest-http-client/src/main/java/org/opensearch/internal/httpclient/Request.java`](https://github.com/opensearch-project/opensearch/blob/main/client/rest-http-client/src/main/java/org/opensearch/internal/httpclient/Request.java) (HTTP transport), [`server/src/main/java/org/opensearch/ingest/IngestService.java`](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/ingest/IngestService.java) (Ingest pipelines)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["REST clients"]
  node_hlclient["REST high-level client"]
  node_converters["Request converters"]
  node_httpclient["HTTP transport<br/>[Request.java]"]
end

subgraph group_search["Search and query"]
  node_search["Search execution<br/>[SearchService.java]"]
  node_searchpipeline["Search pipelines"]
  node_ppl["PPL query service"]
  node_metrics["Tiered query metrics"]
end

subgraph group_indexing["Indexing and ingestion"]
  node_ingest["Ingest pipelines<br/>[IngestService.java]"]
  node_engine["Ingestion engine"]
  node_ingeststate["Ingestion state"]
  node_clustermgr["Cluster state manager"]
end

subgraph group_storage["Repository storage"]
  node_azure["Azure repository service"]
  node_gcs["GCS repository service"]
end

node_user(("Client application"))
node_cluster{{"OpenSearch cluster"}}
node_cloud[("Cloud storage")]

node_user -->|"submits requests"| node_hlclient
node_hlclient -->|"converts operations"| node_converters
node_hlclient -->|"sends HTTP"| node_httpclient
node_httpclient -->|"transports requests"| node_cluster
node_cluster -->|"dispatches searches"| node_search
node_search -->|"applies pipelines"| node_searchpipeline
node_ppl -.->|"executes plans"| node_search
node_cluster -->|"dispatches indexing"| node_ingest
node_ingest -->|"processes documents"| node_engine
node_engine -->|"updates poller state"| node_ingeststate
node_ingeststate -->|"updates cluster metadata"| node_clustermgr
node_search -.->|"records query metrics"| node_metrics
node_azure -.->|"accesses blobs"| node_cloud
node_gcs -.->|"accesses objects"| node_cloud

click node_hlclient "https://github.com/opensearch-project/opensearch/blob/main/client/rest-high-level/src/main/java/org/opensearch/client/RestHighLevelClient.java"
click node_converters "https://github.com/opensearch-project/opensearch/blob/main/client/rest-high-level/src/main/java/org/opensearch/client/RequestConverters.java"
click node_httpclient "https://github.com/opensearch-project/opensearch/blob/main/client/rest-http-client/src/main/java/org/opensearch/internal/httpclient/Request.java"
click node_search "https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/search/SearchService.java"
click node_searchpipeline "https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/search/pipeline/SearchPipelineService.java"
click node_ppl "https://github.com/opensearch-project/opensearch/blob/main/sandbox/plugins/test-ppl-frontend/src/main/java/org/opensearch/ppl/action/UnifiedQueryService.java"
click node_ingest "https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/ingest/IngestService.java"
click node_engine "https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/index/engine/IngestionEngine.java"
click node_ingeststate "https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/cluster/metadata/MetadataStreamingIngestionStateService.java"
click node_clustermgr "https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/cluster/service/ClusterManagerService.java"
click node_metrics "https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/storage/slowlogs/TieredStorageQueryMetricService.java"
click node_azure "https://github.com/opensearch-project/opensearch/blob/main/plugins/repository-azure/src/main/java/org/opensearch/repositories/azure/AzureStorageService.java"
click node_gcs "https://github.com/opensearch-project/opensearch/blob/main/plugins/repository-gcs/src/main/java/org/opensearch/repositories/gcs/GoogleCloudStorageService.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_hlclient,node_converters,node_httpclient,node_user toneBlue
class node_search,node_searchpipeline,node_ppl,node_metrics,node_cloud toneAmber
class node_ingest,node_engine,node_ingeststate,node_clustermgr toneMint
class node_azure,node_gcs toneRose
class node_cluster toneIndigo
```

## Components

### REST clients

- [REST high-level client](https://github.com/opensearch-project/opensearch/blob/main/client/rest-high-level/src/main/java/org/opensearch/client/RestHighLevelClient.java): `client/rest-high-level/src/main/java/org/opensearch/client/RestHighLevelClient.java`
- [Request converters](https://github.com/opensearch-project/opensearch/blob/main/client/rest-high-level/src/main/java/org/opensearch/client/RequestConverters.java): `client/rest-high-level/src/main/java/org/opensearch/client/RequestConverters.java`
- [HTTP transport](https://github.com/opensearch-project/opensearch/blob/main/client/rest-http-client/src/main/java/org/opensearch/internal/httpclient/Request.java): `client/rest-http-client/src/main/java/org/opensearch/internal/httpclient/Request.java`

### Search and query

- [Search execution](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/search/SearchService.java): `server/src/main/java/org/opensearch/search/SearchService.java`
- [Search pipelines](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/search/pipeline/SearchPipelineService.java): `server/src/main/java/org/opensearch/search/pipeline/SearchPipelineService.java`
- [PPL query service](https://github.com/opensearch-project/opensearch/blob/main/sandbox/plugins/test-ppl-frontend/src/main/java/org/opensearch/ppl/action/UnifiedQueryService.java): `sandbox/plugins/test-ppl-frontend/src/main/java/org/opensearch/ppl/action/UnifiedQueryService.java`
- [Tiered query metrics](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/storage/slowlogs/TieredStorageQueryMetricService.java): `server/src/main/java/org/opensearch/storage/slowlogs/TieredStorageQueryMetricService.java`

### Indexing and ingestion

- [Ingest pipelines](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/ingest/IngestService.java): `server/src/main/java/org/opensearch/ingest/IngestService.java`
- [Ingestion engine](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/index/engine/IngestionEngine.java): `server/src/main/java/org/opensearch/index/engine/IngestionEngine.java`
- [Ingestion state](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/cluster/metadata/MetadataStreamingIngestionStateService.java): `server/src/main/java/org/opensearch/cluster/metadata/MetadataStreamingIngestionStateService.java`
- [Cluster state manager](https://github.com/opensearch-project/opensearch/blob/main/server/src/main/java/org/opensearch/cluster/service/ClusterManagerService.java): `server/src/main/java/org/opensearch/cluster/service/ClusterManagerService.java`

### Repository storage

- [Azure repository service](https://github.com/opensearch-project/opensearch/blob/main/plugins/repository-azure/src/main/java/org/opensearch/repositories/azure/AzureStorageService.java): `plugins/repository-azure/src/main/java/org/opensearch/repositories/azure/AzureStorageService.java`
- [GCS repository service](https://github.com/opensearch-project/opensearch/blob/main/plugins/repository-gcs/src/main/java/org/opensearch/repositories/gcs/GoogleCloudStorageService.java): `plugins/repository-gcs/src/main/java/org/opensearch/repositories/gcs/GoogleCloudStorageService.java`

### Other components

- **Client application**
- **OpenSearch cluster**
- **Cloud storage**

## Connections

- Client application → REST high-level client: submits requests
- REST high-level client → Request converters: converts operations
- REST high-level client → HTTP transport: sends HTTP
- HTTP transport → OpenSearch cluster: transports requests
- OpenSearch cluster → Search execution: dispatches searches
- Search execution → Search pipelines: applies pipelines
- PPL query service → Search execution: executes plans
- OpenSearch cluster → Ingest pipelines: dispatches indexing
- Ingest pipelines → Ingestion engine: processes documents
- Ingestion engine → Ingestion state: updates poller state
- Ingestion state → Cluster state manager: updates cluster metadata
- Search execution → Tiered query metrics: records query metrics
- Azure repository service → Cloud storage: accesses blobs
- GCS repository service → Cloud storage: accesses objects