Core concepts

Golden Reports has a small, opinionated vocabulary. The same terms appear in the Manager, in the report editor, in the GraphQL API, and across these docs - so it's worth learning them once.

Containers: organizations, workspaces, and projects

Multi-tenancy in Golden Reports is structural - every record below the org level carries a tenant id, every query is scoped automatically, and no two organizations can ever see each other's data.

• Organization - the top-level tenant. Sign-up creates one. Billing, members, and integrations belong here.
• Workspace - a collaboration unit inside an organization, owning its own data contexts, reports, themes, and assets. Think of it as a project space for a team. Data sources live one level up at the organization, and are shared across workspaces under access policies.
• Project - a folder inside a workspace that groups related reports. Projects exist to keep large workspaces tidy; they do not introduce new permission scopes.

A real layout might look like:

Acme Inc. (organization)
├── Operations (workspace)
│   ├── Shipping (project) - pick slips, packing labels
│   └── Inventory (project) - stock reports
└── Finance (workspace)
    ├── Monthly (project) - P&L, balance sheets
    └── Customer-facing (project) - invoices, credit notes

Members of Operations cannot see Finance content unless they're granted access.

Data plumbing: data sources, contexts, and connectors

These three terms get mixed up constantly. The distinction is load-bearing.

• A connector is code that knows how to talk to one kind of data source - PostgreSQL, a REST API, a CSV file. Connectors are plugins that the platform loads at runtime.
• A data source is a configured instance of a connector - the actual hostname, database, credentials, and any source-specific options. "Our production Postgres on RDS" is a data source; "PostgreSQL" is the connector behind it.
• A data context is a GraphQL schema on top of one or more data sources. Report authors write GraphQL queries against the context; the platform resolves them down to the underlying sources. A data context can pull customer_name from a SQL view and order_total from a REST API, then present them to the author as a single typed schema.

Data contexts have a lifecycle of their own - drafts, locks (so two engineers don't trample each other's edits), and immutable versions that reports pin to. See Data contexts for the full story.

The output: reports, templates, and blocks

• A report is the unit you author, share, embed, and export. It carries metadata (name, project, owner), a template, a GraphQL query, and the data context that query runs against.
• A template is the visual definition of the report. Under the hood it's an HTML + Liquid document - the same languages you'd write for any web page, plus templating placeholders for data. You can write it as pure HTML; the visual editor just provides a friendlier surface over the same template.
• A block is a web component you can drop into a template to handle a specific reporting concern. The built-in blocks cover the things that are genuinely hard in plain HTML - multi-page tables that paginate cleanly, repeating page headers and footers when the report is printed, charts, barcodes, QR codes, gauges. They're optional enrichers, not a wall. Anywhere a block doesn't fit, write plain HTML and Liquid.

A catalog of built-in blocks ships with the platform; custom blocks are plugins. See Blocks reference for the catalog.

The data flow: parameters, queries, and variables

A report has three separate data concepts. Conflating them is the single most common modelling mistake authors make in the editor, so the platform enforces the separation strictly.

• Parameters are the report's external contract - its public API. They are how the outside world feeds values into the report. A user can supply them via a popup before running the report, or a calling system can pass them programmatically. Parameters look like inputs (startDate, customerId, currency).
• Query arguments are the GraphQL operation variables that parameterize the report's query (e.g. query($id: ID!) { customer(id: $id) { ... } }). Each argument is either a literal or a reference to a parameter ($customerId).
• Variables are values available inside the Liquid template. The template - {{ order.total | money }}, {% if customer.is_vip %} - can only reference query results and variables.

See Parameters, variables & queries for the full ruleset and worked examples.

Identity & access

• Authentication. Users sign in with email or a supported OAuth provider (Google, Microsoft, and a handful of others). One sign-in covers the whole platform.
• Authorization is layered. Members belong to an organization; they're granted access to workspaces; within a workspace, data access policies further restrict which data contexts and data sources they can use. Sharing a single report inherits and can narrow these grants.

See Sharing & permissions for the model in detail.

Themes & assets

• Themes are reusable visual specifications (colors, typography, spacing tokens, table styles). A theme can be applied to a report or to a whole workspace.
• Assets are uploaded files - images, fonts, logos - that report templates and themes can reference by stable URL.

Both themes and assets live in the Manager and are scoped to the workspace.

Extensions & the marketplace

The platform is plugin-driven on both sides:

• Block plugins ship new web components usable in any report template. The built-in blocks are themselves built on the same plugin shape; a third-party plugin can add new ones in the same way.
• Connector plugins ship data connectors. The PostgreSQL, REST API, and CSV connectors are bundled; new connectors plug in identically.

The Marketplace in the Manager is where workspace admins install, update, or remove extensions for their organization.

Next

Walk through the Quick start to see all of this in action.