# olacabs/roadrunner architecture

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

- Interactive diagram: https://gitdiagram.com/olacabs/roadrunner
- Repository: https://github.com/olacabs/roadrunner

## Overview

RoadRunner is an in-memory geospatial record store and query engine. A client supplies records and searches by radial area or partition/ID, applies typed column filters, combines matching record indexes, then streams, groups, sorts, or retrieves records. The store implementation routes data into partition buckets; buckets maintain record versions and indexes, while searchers select buckets and construct filters. The README documents cleanup, checksum intervals, bucket sizing, and cooloff behavior. The graph omits uncertain internal dispatch links where source excerpts do not establish ownership.

Main entry points: [`src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java) (Store engine), [`src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java`](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java) (Search engine), [`src/main/java/com/olacabs/roadrunner/impl/filter`](https://github.com/olacabs/roadrunner/tree/master/src/main/java/com/olacabs/roadrunner/impl/filter) (Filter implementations), [`src/main/java/com/olacabs/roadrunner/impl/PartitionBucket.java`](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/PartitionBucket.java) (Partition buckets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Client API"]
  node_store_api["Store API"]
  node_record["Record model<br/>[Record.java]"]
  node_field["Indexable fields"]
  node_search_api["Searcher API"]
end

subgraph group_store["Store and partitions"]
  node_store_impl["Store engine"]
  node_partition["Partition routing<br/>[Partitioner.java]"]
  node_bucket[("Partition buckets")]
  node_holder["Record versions<br/>[RecordHolder.java]"]
  node_record_version["Version data"]
  node_indexes["Record indexes"]
end

subgraph group_query["Search and filters"]
  node_search_impl["Search engine"]
  node_filter_api["Typed filter API"]
  node_filter_impl["Filter implementations"]
  node_bitset["Bitset operations<br/>[BitSetExposed.java]"]
  node_bitset_cache["Bitset cache<br/>[BitsetCache.java]"]
  node_dictionary["Filter dictionaries"]
  node_s2_query["S2 query parsing<br/>[S2QueryParser.java]"]
end

subgraph group_support["Monitoring and utilities"]
  node_metrics["Metric collection"]
  node_utils["Runtime utilities"]
end

node_client(("Application"))

node_client -->|"configures and writes"| node_store_api
node_client -->|"builds searches"| node_search_api
node_store_api -.->|"implemented by"| node_store_impl
node_store_impl -->|"routes records"| node_bucket
node_store_impl -->|"creates searcher"| node_search_impl
node_store_impl -.->|"uses partitioning"| node_partition
node_bucket -->|"stores records"| node_holder
node_holder -->|"keeps versions"| node_record_version
node_store_impl -->|"accepts records"| node_record
node_store_impl -->|"configures fields"| node_field
node_search_impl -->|"selects buckets"| node_bucket
node_search_impl -->|"constructs filters"| node_filter_impl
node_filter_impl -.->|"implements operations"| node_filter_api
node_filter_impl -->|"leases bitsets"| node_bitset_cache
node_filter_impl -->|"produces matches"| node_indexes
node_indexes -->|"holds match bits"| node_bitset
node_search_impl -->|"uses dictionaries"| node_dictionary
node_search_api -->|"consumes indexes"| node_indexes
node_store_impl -->|"reports metrics"| node_metrics
node_utils -->|"records invalid inputs"| node_metrics
node_client -.->|"parses S2 queries"| node_s2_query

click node_store_api "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/GeoSpatialStore.java"
click node_record "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/Record.java"
click node_field "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/IndexableField.java"
click node_search_api "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/GeoSpatialSearcher.java"
click node_store_impl "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java"
click node_partition "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/Partitioner.java"
click node_bucket "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/PartitionBucket.java"
click node_holder "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/RecordHolder.java"
click node_record_version "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/RecordImplVersion.java"
click node_indexes "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/RecordIndexesImpl.java"
click node_search_impl "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java"
click node_filter_api "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/filter/ColumnFilterString.java"
click node_filter_impl "https://github.com/olacabs/roadrunner/tree/master/src/main/java/com/olacabs/roadrunner/impl/filter"
click node_bitset "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/BitSetExposed.java"
click node_bitset_cache "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/BitsetCache.java"
click node_dictionary "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/DictionaryHolder.java"
click node_s2_query "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/lucene/booleangate/S2QueryParser.java"
click node_metrics "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/monitor/RoadRunnerMetricFactory.java"
click node_utils "https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/utils/RoadRunnerUtils.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_store_api,node_record,node_field,node_search_api toneBlue
class node_store_impl,node_partition,node_bucket,node_holder,node_record_version,node_indexes toneAmber
class node_search_impl,node_filter_api,node_filter_impl,node_bitset,node_bitset_cache,node_dictionary,node_s2_query toneMint
class node_metrics,node_utils toneRose
class node_client toneIndigo
```

## Components

### Client API

- [Store API](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/GeoSpatialStore.java): `src/main/java/com/olacabs/roadrunner/api/GeoSpatialStore.java`
- [Record model](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/Record.java): `src/main/java/com/olacabs/roadrunner/api/Record.java`
- [Indexable fields](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/IndexableField.java): `src/main/java/com/olacabs/roadrunner/api/IndexableField.java`
- [Searcher API](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/GeoSpatialSearcher.java): `src/main/java/com/olacabs/roadrunner/api/GeoSpatialSearcher.java`

### Store and partitions

- [Store engine](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java): `src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`
- [Partition routing](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/Partitioner.java): `src/main/java/com/olacabs/roadrunner/api/Partitioner.java`
- [Partition buckets](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/PartitionBucket.java): `src/main/java/com/olacabs/roadrunner/impl/PartitionBucket.java`
- [Record versions](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/RecordHolder.java): `src/main/java/com/olacabs/roadrunner/impl/RecordHolder.java`
- [Version data](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/RecordImplVersion.java): `src/main/java/com/olacabs/roadrunner/impl/RecordImplVersion.java`
- [Record indexes](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/RecordIndexesImpl.java): `src/main/java/com/olacabs/roadrunner/impl/RecordIndexesImpl.java`

### Search and filters

- [Search engine](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java): `src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java`
- [Typed filter API](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/api/filter/ColumnFilterString.java): `src/main/java/com/olacabs/roadrunner/api/filter/ColumnFilterString.java`
- [Filter implementations](https://github.com/olacabs/roadrunner/tree/master/src/main/java/com/olacabs/roadrunner/impl/filter): `src/main/java/com/olacabs/roadrunner/impl/filter`
- [Bitset operations](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/BitSetExposed.java): `src/main/java/com/olacabs/BitSetExposed.java`
- [Bitset cache](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/BitsetCache.java): `src/main/java/com/olacabs/roadrunner/impl/BitsetCache.java`
- [Filter dictionaries](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/impl/DictionaryHolder.java): `src/main/java/com/olacabs/roadrunner/impl/DictionaryHolder.java`
- [S2 query parsing](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/lucene/booleangate/S2QueryParser.java): `src/main/java/com/olacabs/roadrunner/lucene/booleangate/S2QueryParser.java`

### Monitoring and utilities

- [Metric collection](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/monitor/RoadRunnerMetricFactory.java): `src/main/java/com/olacabs/roadrunner/monitor/RoadRunnerMetricFactory.java`
- [Runtime utilities](https://github.com/olacabs/roadrunner/blob/master/src/main/java/com/olacabs/roadrunner/utils/RoadRunnerUtils.java): `src/main/java/com/olacabs/roadrunner/utils/RoadRunnerUtils.java`

### Other components

- **Application**

## Connections

- Application → Store API: configures and writes
- Application → Searcher API: builds searches (evidence: `src/main/java/com/olacabs/roadrunner/api/GeoSpatialSearcher.java`)
- Store API → Store engine: implemented by (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`)
- Store engine → Partition buckets: routes records (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`)
- Store engine → Search engine: creates searcher (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`)
- Store engine → Partition routing: uses partitioning
- Partition buckets → Record versions: stores records (evidence: `src/main/java/com/olacabs/roadrunner/impl/PartitionBucket.java`)
- Record versions → Version data: keeps versions (evidence: `src/main/java/com/olacabs/roadrunner/impl/RecordHolder.java`)
- Store engine → Record model: accepts records (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`)
- Store engine → Indexable fields: configures fields (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`)
- Search engine → Partition buckets: selects buckets (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java`)
- Search engine → Filter implementations: constructs filters (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java`)
- Filter implementations → Typed filter API: implements operations (evidence: `src/main/java/com/olacabs/roadrunner/impl/filter/ColumnFilterDoubleUniqueImpl.java`)
- Filter implementations → Bitset cache: leases bitsets (evidence: `src/main/java/com/olacabs/roadrunner/impl/filter/ColumnFilterDoubleUniqueImpl.java`)
- Filter implementations → Record indexes: produces matches (evidence: `src/main/java/com/olacabs/roadrunner/impl/filter/ColumnFilterDoubleUniqueImpl.java`)
- Record indexes → Bitset operations: holds match bits (evidence: `src/main/java/com/olacabs/roadrunner/impl/RecordIndexesImpl.java`)
- Search engine → Filter dictionaries: uses dictionaries (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpacialSearcherImpl.java`)
- Searcher API → Record indexes: consumes indexes (evidence: `src/main/java/com/olacabs/roadrunner/api/GeoSpatialSearcher.java`)
- Store engine → Metric collection: reports metrics (evidence: `src/main/java/com/olacabs/roadrunner/impl/GeoSpatialStoreImpl.java`)
- Runtime utilities → Metric collection: records invalid inputs (evidence: `src/main/java/com/olacabs/roadrunner/utils/RoadRunnerUtils.java`)
- Application → S2 query parsing: parses S2 queries
