# rilldata/rill architecture

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

- Interactive diagram: https://gitdiagram.com/rilldata/rill
- Repository: https://github.com/rilldata/rill

## Overview

Rill is an agent-first BI product: users define data models and metrics, explore dashboards or ask questions, and can deploy projects to Rill Cloud. The principal workflow runs from project files through parsing and resource reconciliation, connectors and OLAP execution, then query APIs to dashboards or agents. Separate branches cover the CLI/local developer experience and cloud administration, deployment, billing, alerts, and reports. README statements establish several product capabilities; source excerpts and the SOURCE INDEX support only the implementation links shown, so uncertain internal connections are omitted or marked unverified.

Main entry points: [`runtime/server/server.go`](https://github.com/rilldata/rill/blob/main/runtime/server/server.go) (Runtime API server), [`admin`](https://github.com/rilldata/rill/tree/main/admin) (Admin services), [`runtime/controller.go`](https://github.com/rilldata/rill/blob/main/runtime/controller.go) (Resource controller), [`admin/server/server.go`](https://github.com/rilldata/rill/blob/main/admin/server/server.go) (Cloud admin API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_author["Author and deploy"]
  node_cli["Rill CLI<br/>[root.go]"]
  node_local["Local server<br/>[server.go]"]
end

subgraph group_runtime["Project runtime"]
  node_controller["Resource controller<br/>[controller.go]"]
  node_parser["Project parser"]
  node_reconcile["Project reconciler"]
  node_metrics["Metrics semantics<br/>[query.go]"]
  node_query["Query execution<br/>[query.go]"]
  node_drivers["OLAP and connectors"]
  node_storage["Project storage<br/>[storage.go]"]
end

subgraph group_explore["Explore and query"]
  node_web["Runtime web client<br/>[runtime-client.ts]"]
  node_querygen["Query helpers<br/>[query-service.ts]"]
  node_runtime_api["Runtime API server<br/>[server.go]"]
  node_runtime_controller_api["Runtime resource API<br/>[controller.go]"]
  node_ai["Conversational BI"]
  node_dashboards["Dashboard experience"]
end

subgraph group_cloud["Cloud services"]
  node_admin_api["Cloud admin API<br/>[server.go]"]
  node_admin_service["Admin services"]
  node_admin_db[("Admin database<br/>[database.go]")]
  node_jobs["Background jobs"]
  node_provision["Deployment provisioning"]
  node_billing["Billing integrations"]
end

node_user(("Developer or analyst"))
node_agent(("External AI agent"))
node_olap[("OLAP engine")]
node_cloud_user(("Cloud user"))

node_user -->|"authors and invokes"| node_cli
node_cli -.->|"starts locally"| node_local
node_user -->|"starts project"| node_local
node_local -.->|"serves project runtime"| node_runtime_api
node_web -->|"uses query helpers"| node_querygen
node_querygen -.->|"sends query RPCs"| node_runtime_api
node_runtime_api -->|"uses runtime"| node_controller
node_runtime_controller_api -->|"reads and updates resources"| node_controller
node_controller -->|"waits for initial parse"| node_parser
node_controller -.->|"coordinates reconciliation"| node_reconcile
node_parser -.->|"creates project resources"| node_reconcile
node_runtime_api -.->|"serves metrics capabilities"| node_metrics
node_runtime_api -.->|"hosts AI capabilities"| node_ai
node_metrics -.->|"defines query model"| node_query
node_query -.->|"executes through connectors"| node_drivers
node_drivers -.->|"queries engine"| node_olap
node_controller -.->|"uses project storage"| node_storage
node_user -->|"explores metrics"| node_dashboards
node_dashboards -.->|"requests runtime data"| node_web
node_agent -->|"asks natural-language questions"| node_ai
node_cloud_user -.->|"uses cloud services"| node_admin_api
node_admin_api -->|"routes administration"| node_admin_service
node_admin_service -.->|"persists admin state"| node_admin_db
node_admin_service -.->|"schedules background work"| node_jobs
node_admin_service -.->|"provisions deployments"| node_provision
node_admin_service -.->|"integrates billing"| node_billing
node_admin_api -.->|"supports cloud deployments"| node_runtime_api

click node_cli "https://github.com/rilldata/rill/blob/main/cli/cmd/root.go"
click node_local "https://github.com/rilldata/rill/blob/main/cli/pkg/local/server.go"
click node_web "https://github.com/rilldata/rill/blob/main/web-common/src/runtime-client/v2/runtime-client.ts"
click node_querygen "https://github.com/rilldata/rill/blob/main/web-common/src/runtime-client/v2/gen/query-service.ts"
click node_runtime_api "https://github.com/rilldata/rill/blob/main/runtime/server/server.go"
click node_runtime_controller_api "https://github.com/rilldata/rill/blob/main/runtime/server/controller.go"
click node_controller "https://github.com/rilldata/rill/blob/main/runtime/controller.go"
click node_parser "https://github.com/rilldata/rill/tree/main/runtime/parser"
click node_reconcile "https://github.com/rilldata/rill/tree/main/runtime/reconcilers"
click node_metrics "https://github.com/rilldata/rill/blob/main/runtime/metricsview/query.go"
click node_query "https://github.com/rilldata/rill/blob/main/runtime/query.go"
click node_drivers "https://github.com/rilldata/rill/tree/main/runtime/drivers"
click node_storage "https://github.com/rilldata/rill/blob/main/runtime/storage/storage.go"
click node_ai "https://github.com/rilldata/rill/tree/main/runtime/ai"
click node_admin_api "https://github.com/rilldata/rill/blob/main/admin/server/server.go"
click node_admin_service "https://github.com/rilldata/rill/tree/main/admin"
click node_admin_db "https://github.com/rilldata/rill/blob/main/admin/database/database.go"
click node_jobs "https://github.com/rilldata/rill/tree/main/admin/jobs/river"
click node_provision "https://github.com/rilldata/rill/tree/main/admin/provisioner"
click node_billing "https://github.com/rilldata/rill/tree/main/admin/billing"
click node_dashboards "https://github.com/rilldata/rill/tree/main/web-common/src/features/dashboards"

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_cli,node_local,node_cloud_user toneBlue
class node_controller,node_parser,node_reconcile,node_metrics,node_query,node_drivers,node_storage,node_olap toneAmber
class node_web,node_querygen,node_runtime_api,node_runtime_controller_api,node_ai,node_dashboards toneMint
class node_admin_api,node_admin_service,node_admin_db,node_jobs,node_provision,node_billing toneRose
class node_user,node_agent toneIndigo
```

## Components

### Author and deploy

- [Rill CLI](https://github.com/rilldata/rill/blob/main/cli/cmd/root.go): `cli/cmd/root.go`
- [Local server](https://github.com/rilldata/rill/blob/main/cli/pkg/local/server.go): `cli/pkg/local/server.go`

### Project runtime

- [Resource controller](https://github.com/rilldata/rill/blob/main/runtime/controller.go): `runtime/controller.go`
- [Project parser](https://github.com/rilldata/rill/tree/main/runtime/parser): `runtime/parser`
- [Project reconciler](https://github.com/rilldata/rill/tree/main/runtime/reconcilers): `runtime/reconcilers`
- [Metrics semantics](https://github.com/rilldata/rill/blob/main/runtime/metricsview/query.go): `runtime/metricsview/query.go`
- [Query execution](https://github.com/rilldata/rill/blob/main/runtime/query.go): `runtime/query.go`
- [OLAP and connectors](https://github.com/rilldata/rill/tree/main/runtime/drivers): `runtime/drivers`
- [Project storage](https://github.com/rilldata/rill/blob/main/runtime/storage/storage.go): `runtime/storage/storage.go`

### Explore and query

- [Runtime web client](https://github.com/rilldata/rill/blob/main/web-common/src/runtime-client/v2/runtime-client.ts): `web-common/src/runtime-client/v2/runtime-client.ts`
- [Query helpers](https://github.com/rilldata/rill/blob/main/web-common/src/runtime-client/v2/gen/query-service.ts): `web-common/src/runtime-client/v2/gen/query-service.ts`
- [Runtime API server](https://github.com/rilldata/rill/blob/main/runtime/server/server.go): `runtime/server/server.go`
- [Runtime resource API](https://github.com/rilldata/rill/blob/main/runtime/server/controller.go): `runtime/server/controller.go`
- [Conversational BI](https://github.com/rilldata/rill/tree/main/runtime/ai): `runtime/ai`
- [Dashboard experience](https://github.com/rilldata/rill/tree/main/web-common/src/features/dashboards): `web-common/src/features/dashboards`

### Cloud services

- [Cloud admin API](https://github.com/rilldata/rill/blob/main/admin/server/server.go): `admin/server/server.go`
- [Admin services](https://github.com/rilldata/rill/tree/main/admin): `admin`
- [Admin database](https://github.com/rilldata/rill/blob/main/admin/database/database.go): `admin/database/database.go`
- [Background jobs](https://github.com/rilldata/rill/tree/main/admin/jobs/river): `admin/jobs/river`
- [Deployment provisioning](https://github.com/rilldata/rill/tree/main/admin/provisioner): `admin/provisioner`
- [Billing integrations](https://github.com/rilldata/rill/tree/main/admin/billing): `admin/billing`

### Other components

- **Developer or analyst**
- **External AI agent**
- **OLAP engine**
- **Cloud user**

## Connections

- Developer or analyst → Rill CLI: authors and invokes (evidence: `README.md`)
- Rill CLI → Local server: starts locally
- Developer or analyst → Local server: starts project (evidence: `README.md`)
- Local server → Runtime API server: serves project runtime
- Runtime web client → Query helpers: uses query helpers (evidence: `web-common/src/runtime-client/v2/runtime-client.ts`)
- Query helpers → Runtime API server: sends query RPCs
- Runtime API server → Resource controller: uses runtime (evidence: `runtime/server/server.go`)
- Runtime resource API → Resource controller: reads and updates resources (evidence: `runtime/server/controller.go`)
- Resource controller → Project parser: waits for initial parse (evidence: `runtime/controller.go`)
- Resource controller → Project reconciler: coordinates reconciliation
- Project parser → Project reconciler: creates project resources
- Runtime API server → Metrics semantics: serves metrics capabilities
- Runtime API server → Conversational BI: hosts AI capabilities (evidence: `runtime/server/server.go`)
- Metrics semantics → Query execution: defines query model
- Query execution → OLAP and connectors: executes through connectors
- OLAP and connectors → OLAP engine: queries engine
- Resource controller → Project storage: uses project storage
- Developer or analyst → Dashboard experience: explores metrics (evidence: `README.md`)
- Dashboard experience → Runtime web client: requests runtime data
- External AI agent → Conversational BI: asks natural-language questions (evidence: `README.md`)
- Cloud user → Cloud admin API: uses cloud services
- Cloud admin API → Admin services: routes administration (evidence: `admin/server/server.go`)
- Admin services → Admin database: persists admin state
- Admin services → Background jobs: schedules background work (evidence: `admin/jobs/river/biller_event_handlers.go`)
- Admin services → Deployment provisioning: provisions deployments
- Admin services → Billing integrations: integrates billing (evidence: `admin/jobs/river/biller_event_handlers.go`)
- Cloud admin API → Runtime API server: supports cloud deployments
