# Orbit architecture

> How Orbit turns GitLab data and code into a graph you can query.

![Orbit at a glance](https://gitlab.com/gitlab-org/orbit/knowledge-graph/-/raw/bda74fca6a41817edd0e0d05184e0e0951edb653/docs/assets/architecture/overview.svg)

Orbit turns GitLab data and code into one graph. Agents and people query that
graph to answer questions that would take many GitLab API calls. The
[data model](/engineering/architecture/data-model) page describes what the graph holds.

## How data gets in

Orbit only reads from GitLab. It never connects to the GitLab database. Siphon
copies the GitLab tables we need into a data lake. The SDLC indexer turns
those rows into nodes and edges. The code indexer fetches repositories through
GitLab and adds the code graph. A dispatcher schedules work for both indexers.

[SDLC indexing](/engineering/architecture/indexing/sdlc-indexing) and
[code indexing](/engineering/architecture/indexing/code-indexing) walk through each indexer.
[Schema evolution](/engineering/architecture/indexing/schema-evolution) covers schema changes with no
downtime. [Resiliency](/engineering/architecture/indexing/resiliency) covers how indexing recovers
from failures.

## How a question gets answered

Every request goes through GitLab first. GitLab checks who the caller is and
what they can see. Orbit then runs one bounded query inside that scope. GitLab
checks each result again before it goes back. Results show the graph as of the
last indexing run.

[Querying](/engineering/architecture/querying) follows a request from start to end.
[Security](/engineering/architecture/security) explains each check.

## Why we built it this way

We wanted deploying Orbit to add no operational load to GitLab. Orbit runs
every query on its own store, so the GitLab database never serves graph
queries. We built that store on data infrastructure that GitLab already runs.

[ADR 000](/engineering/adr/000_clickhouse_graph_storage) compares dedicated graph
databases, like Neo4j, with the databases GitLab already runs. Reusing one of
those meant one less database to deploy and maintain.

## Where it runs

Orbit runs on GitLab.com, GitLab Dedicated, and GitLab Self-Managed. It ships
separately from GitLab.
[Orbit on GitLab Self-Managed](https://docs.gitlab.com/orbit/self-managed/)
covers the setup.

## More pages

- [Orbit CLI](/engineering/architecture/orbit-cli) brings Orbit to your terminal and to your AI agents.
- [Monetization](/engineering/architecture/monetization) explains how Orbit reports billable usage and
  checks quota.
- [Testing](/engineering/testing) shows how we prove a change works before it
  ships.
- The [ADRs](/engineering/adr) record our main decisions and why we made them.
