Celiq
v0.12Open app ↗
Docs/Developer/Platform Architecture

Platform Architecture

A technical overview of how Celiq's layers — Physical, Semantic, and Runtime — work together to serve analytics queries.

LuminaryWeaverUpdated June 2026 · 8 min read
✦
In this section
Part of Celiq's semantic layer platform. Connect your warehouse, model your data once, query it everywhere.
📝
Note

This page is for platform builders and administrators who need to understand Celiq's internals. End users building analytics should start with Quick Start instead.

Celiq is a self-hosted semantic analytics platform. It has three layers: the Physical Layer connects to your warehouse, the Semantic Layer defines what data means, and the Runtime Layer executes queries. This page describes each layer and how they interact.

Three-layer architecture

┌─────────────────────────────────────────────────────┐
│                   RUNTIME LAYER                       │
│  Discover  ·  Orion AI  ·  Mosaics  ·  Scheduling    │
└──────────────────────┬──────────────────────────────┘
                       │ resolves
┌──────────────────────▼──────────────────────────────┐
│                  SEMANTIC LAYER                       │
│  Nodes  ·  Domains  ·  Reveals  ·  Metrics  ·  CML   │
└──────────────────────┬──────────────────────────────┘
                       │ maps to
┌──────────────────────▼──────────────────────────────┐
│                  PHYSICAL LAYER                       │
│  Datasets  ·  Deployments  ·  Mappings               │
└──────────────────────┬──────────────────────────────┘
                       │ queries
┌──────────────────────▼──────────────────────────────┐
│                     WAREHOUSE                         │
│  Snowflake  ·  BigQuery  ·  Postgres  ·  Redshift     │
│  DuckDB  ·  MySQL  ·  SQL Server  ·  Databricks       │
└─────────────────────────────────────────────────────┘

Physical Layer

The Physical Layer resolves abstract dataset names to physical tables at query time. It has three concepts:

Datasets — Logical table definitions. A dataset is a schema: a name plus a list of column definitions (name, type, nullable). It doesn't live in any one warehouse. Deployments — Target environments (Production, Development, Staging). Each workspace has one default deployment; all end-user queries run through it. Dataset Mappings — Bindings that say "in deployment X, dataset Y maps to connection Z, table W." Celiq validates mappings by comparing dataset column definitions against the physical table schema and computes a compatibility score. What it resolves: dataset name + active deployment → (connection, physical table) Storage: PostgreSQL tables datasets, dataset_columns, deployments, dataset_mappings

Semantic Layer

The Semantic Layer defines what data means: metric calculations, dimension taxonomies, join logic, and security rules. It is authored in CML files inside Forge.

Nodes — Map to datasets. Each node defines dimensions (group-by columns) and measures (aggregations). Written in CML. Domains — Join multiple nodes together. A domain defines which nodes can be combined in a query, and with what join logic. Reveals — Named, certified query configurations exposed to end users. A Reveal defines which node/domain to start from, which metrics and dimensions are surfaced, and AI context for Orion. Metrics — Named measures promoted to first-class status. A metric has a canonical definition, a business owner, and usage tracking. Storage: PostgreSQL; CML source files in Forge (Git-backed). A compiled model cache is maintained per workspace. Compile/validate flow: Forge runs a validation pass (Check & Save) before any semantic change goes live. Validation checks SQL parse, fanout risk, join integrity, and field reference correctness.

Runtime Layer

The Runtime Layer is everything that actually runs queries and serves results.

Query execution

  1. Field resolution — Discover sends a query spec (dimensions, measures, filters, grain). The backend resolves field names against the compiled semantic model.
  2. SQL generation — buildSQL() generates warehouse-specific SQL via applyDialect(). It handles type casting, date truncation, CASE expressions, and window functions per warehouse dialect.
  3. Deployment resolution — The active deployment is determined (workspace default, or Mosaic-pinned deployment). The dataset → (connection, physical_table) mapping is looked up.
  4. Execution — SQL is sent to the warehouse via the appropriate driver (pg, @google-cloud/bigquery, snowflake-sdk, duckdb).
  5. Post-processing — Table calculations (window functions, running totals, rank) that can't be expressed as SQL are applied client-side after results arrive.

Security enforcement

Every query passes through two security guards before results are returned:

  • dataSecurityEnforce — Applies row-level security (Data Keys) and column-level security (Data Gates) based on the requesting user's role and attributes. This guard is fail-closed: any error blocks the query rather than returning unredacted data.
  • Tenant isolation — All database queries include workspace_id in WHERE clauses, enforced by tenantRls.js. A user in workspace A cannot access workspace B's data regardless of the query.

Orion AI

Orion is the AI layer that translates natural language into Reveal configurations. It uses Claude (Anthropic) via the workspace's configured API key. The key is stored encrypted per workspace in the database — never as environment variables.

Orion resolves node/domain/metric references using the semantic model via resolveReveal (DISTINCT ON with domain priority — the node that most closely matches the intent is selected, preferring nodes within the active domain).

Scheduling and delivery

Scheduled reports and Mosaic snapshots run via a background job queue. Each scheduled item runs a query through the normal runtime path and delivers results via configured channels (email, Slack).

Stack

ComponentTechnology
BackendNode.js / Express
DatabasePostgreSQL (Railway managed)
FrontendReact 18 + Vite (dist committed to git)
AIAnthropic Claude — model configurable per workspace
Warehouse driverspg (Postgres/Redshift), @google-cloud/bigquery, snowflake-sdk, better-sqlite3 (DuckDB)
DeploymentRailway (auto-deploy on push to main)

Authentication

  • Session tokens — JWT-based, issued on login. No session storage in the database.
  • API keys — Workspace-scoped keys for programmatic access to /api/* endpoints.
  • Workspace AI key — Anthropic API key stored encrypted per workspace, accessed via getWorkspaceApiKey(workspaceId). Never queried from workspace_ai_config directly.

Multi-tenancy

Celiq is a single-instance, multi-tenant deployment. Tenant isolation is enforced at:

  1. Auth middleware — req.workspaceId is set from the authenticated session. All route handlers use req.workspaceId, never req.user.workspace_id.
  2. Database queries — All queries include workspace_id = $1 filters. The tenantRls.js module enforces this pattern.
  3. Credential encryption — Warehouse credentials are encrypted with AES-256-GCM using a per-deployment encryption key (ENCRYPTION_KEY env var). Decryption happens in backend/lib/crypto.js.
Was this page helpful?
✎ Edit this page on GitHub