Architecture
System overview
The services that make up a Golden Reports deployment - what each one does, how they fit together, and what state lives where.
Golden Reports is a small set of cooperating services, not a single application. You only need this page if you're self-hosting or integrating against the platform's API. Report authors can skip it.
The goal here is to give you enough of a runtime picture to deploy, operate, and reason about scale - without dragging through implementation detail you can't influence.
The runtime in one diagram
The arrows in the request path are synchronous. The operational stores sit beside the API; the engine and data provider hold no persistent state.
The services
Manager
The web UI. It's where you administer workspaces, members, data sources, data contexts, themes, forms, assets, and reports - and where you author reports in the embedded editor.
Platform API
The control plane. Every administrative action (creating a workspace, registering a data source, publishing a data context) and every read of authoritative data goes through here. Authentication, authorization, billing, and audit live here.
Query Engine
The execution plane for data. When a report runs, the API hands the engine a query plan (what data context, what data source, what fields, what filters, what limits). The engine executes the plan and streams results back. The engine never touches your databases directly - it dispatches to the data provider.
Data Provider
The connector host. It loads and runs the connectors that talk to actual data sources - your PostgreSQL, your REST endpoints, your CSV files. Connectors are isolated from the host and from each other.
Operational stores
- PostgreSQL holds the platform's own data: users, organizations, workspaces, data sources, data contexts, themes, reports, assets metadata, billing, audit log.
- Redis is used for caching and distributed coordination across replicas.
Neither store ever holds your report data - that lives in your own data sources and is fetched on demand.
Boundaries that matter for operators
A few invariants worth knowing:
The API never talks to your data sources directly
Only the query engine and data provider do. This keeps credentials, query plans, and result streams off the control plane and lets the engine and provider be scaled independently of the API.
Tenants are isolated in the execution path
Every plan carries a tenant identifier. The engine enforces it on every execution; two reports for two different organizations resolve to two independent executions with two independent credential sets.
The data provider is stateless
Connectors run, return rows, get unloaded. Connection pools live in the connectors themselves, keyed by data source. Nothing persists on disk in the data provider. This is what makes horizontal scaling clean - add more replicas, they pick up traffic immediately.
The engine is stateless
Same shape. Plans come in, result streams go out. No queue, no in-memory cache, no plan registry. Scale it like any other stateless service.
Identity and the request path
Where:
- Browser is the user's browser running the Manager.
- IdP is the identity provider (email / OAuth).
- API is the platform API (control plane).
- Engine is the query engine.
- Provider is the data provider (host for connector plugins).
- Connector is the plugin that talks to the actual data source.
Every step is observable. A single execution carries a correlation ID from step 5 onwards so you can trace it across services in your logging or tracing tool.
Where data physically lives
| Store | What it holds | Lifetime |
|---|---|---|
| Platform PostgreSQL | Users, organizations, workspaces, data sources, contexts, reports, themes, assets metadata, billing, audit. | Persistent. Backed up. |
| Object storage | Asset binaries (logos, fonts, etc.). | Persistent. |
| Redis | Cache, rate-limit counters, distributed locks. | Ephemeral. |
| Query Engine | None. Stateless. | - |
| Data Provider | None (connectors may hold in-memory connection pools). | - |
| Your data sources | The data reports read. | Owned by you. |
The platform never persistently stores customer data row contents - only references to it.
Deployment topology
The standard Kubernetes deployment runs each service as its own workload:
- Platform API (typically 2-10 replicas behind an autoscaler).
- Query Engine (2-10 replicas).
- Data Provider (2-10 replicas).
- Manager (2 replicas; it's a static asset workload).
- Plus the operational PostgreSQL and Redis.
Routing in front of the cluster is via Ingress or Gateway API - pick one. See Deployment overview and Helm chart reference for the full picture.
Concurrency and consistency
Two operator-relevant invariants:
- Concurrent writes don't silently overwrite each other. If two users edit the same record at the same time, the platform surfaces a conflict so the second writer can refresh and retry.
- Background work is coordinated across replicas so scaling out the API doesn't multiply periodic jobs.
Next
- Drill into the data execution plane: The query engine.
- Understand the extension model: Extensibility model.
- Deploy the whole stack: Deployment overview.