Platform Overview

Rokks is a self-hosted analytical intelligence platform built for teams that need full control over their data pipeline, storage, and visualization — without vendor lock-in.

Core concepts

Environments

An environment is an isolated data namespace. Each environment has its own Firestore namespace, TimescaleDB schema, and service credentials. You can run PROD, STAGING, and DEV on the same installation with zero data overlap.

Switch environments at any time via the environment switcher in the top-left of the app header.

Data Fabric

The Data Fabric is where external data enters Rokks. Three source types are supported:

File Areas — Upload CSV, JSON, Parquet, or Excel files. Rokks’s ETL pipeline parses, transforms, and loads them into physical tables.
Web API Streams — Connect to any REST or WebSocket endpoint. The Dispatcher schedules recurring syncs; incremental-cursor mode only fetches new records.
App Connect — Native integrations with Airtable, with a constellation graph that mirrors relational structures into normalized tables.

Dashboards

Dashboards group widgets into pages. Each widget queries a physical table through the SQL Gateway using a compiled query — built either through the drag-and-drop Query Builder or by writing raw SQL.

Widgets support: line/bar/area/scatter/pie charts, tables, maps, network graphs, IBCS scorecards, and more.

Sidekick Agent

Sidekick is an AI agent scoped to the current dashboard. It can:

Add, modify, and delete widgets
Write and explain SQL queries
Suggest and apply indexes for slow queries
Materialize derived tables in the Analytic Warehouse

Every action Sidekick takes is immediately undoable. Conversations are persisted per dashboard context.

Service architecture

Rokks runs as a Docker Compose stack. The browser communicates exclusively with the Edge service (an nginx reverse proxy), which routes requests to the appropriate backend microservice.

Browser → Edge (nginx, port 3000/3443)
              ├── /auth/*       → Auth service
              ├── /api/*        → Edge proxy → Worker / Gateways
              └── /             → Frontend SPA

Key services:

Service	Role
`registry`	Bootstrap anchor — secrets, service discovery, global config
`doc-gateway`	Firestore + GCS proxy
`sql-gateway`	TimescaleDB / PostgreSQL proxy
`worker`	Job engine — ETL, sync, index, alert jobs
`dispatcher`	Cron scheduler — triggers sync jobs
`sentinel`	Alert evaluator — triggers notification jobs
`ai`	AI Gateway — proxies LLM calls (Gemini or local LM Studio)

See the Architecture Reference for the full service map and communication topology.