# Under the hood

How GOAT works on Google Cloud, for readers who want the detail.

This section explains how GOAT works on Google Cloud: what runs where, how a chart becomes a query, and how each customer is kept to their own rows. It is for readers who review security, tune performance and cost, or want to know what runs in their project.

On these pages, *operators* are the people who sign in to the GOAT app to build dashboards, as Admins or Authors. *Viewers* are the people using embedded dashboards in your product. A *tenant* is one of your customers, and a dataset's *tenant key* is the column that says which tenant each row belongs to.

## What runs in your project

Everything GOAT needs runs in the Google Cloud project it is installed in. There is no GOAT-hosted service in between.

```mermaid
flowchart LR
  ops[Operators' browsers]
  subgraph app[Your application]
    page[Your web page]
    backend[Your backend]
  end
  subgraph project[Your Google Cloud project]
    run[GOAT service on Cloud Run]
    fs[(Firestore: dashboards, charts, settings)]
    bq[(BigQuery: your data and GOAT's copies)]
    gcs[(Cloud Storage: uploaded files)]
    idp[Identity Platform: operator sign-in]
    sm[Secret Manager: token signing keys]
    log[(Cloud Logging: a record of each query)]
  end
  ops -- sign in --> idp
  ops -- build and publish --> run
  page -- dashboard requests --> run
  backend -- API key: ask for a viewer token --> run
  run --> fs
  run --> bq
  run --> gcs
  run --> sm
  run --> idp
  run --> log
```

| Part | What it does |
|---|---|
| Cloud Run | Runs the GOAT service: the app that operators sign in to, the API, and the embed script. |
| Firestore | Holds what operators build: datasets' settings, collections, charts, dashboards, tenants, and access. |
| BigQuery | Holds your data, and GOAT's managed copies of it in the install's own `goat` dataset. Runs every chart's query. |
| Cloud Storage | Holds the files operators upload. An uploaded file is kept there for as long as its dataset uses it. |
| Identity Platform | Signs in operators, by email and password with an optional second factor, or with Google single sign-on. |
| Secret Manager | Holds the keys that sign viewer tokens. |
| Cloud Logging | Records each query GOAT serves. Those records feed GOAT's usage and cost figures. |

## How a chart reaches a viewer

```mermaid
sequenceDiagram
  participant V as Viewer's browser
  participant B as Your backend
  participant G as GOAT
  participant Q as BigQuery
  V->>B: Ask for a viewer token
  B->>G: Request a token for tenant "acme" (API key)
  G-->>B: Token naming "acme", valid for an hour
  B-->>V: Token
  V->>G: Show chart X (token)
  G->>G: Check the dashboard is published and acme has access
  G->>Q: Run chart X's saved query, filtered to acme's rows
  Q-->>G: Results
  G-->>V: Chart data
```

A viewer's browser never sends a query. It names a saved chart, and GOAT runs that chart's saved query, so a viewer can see only the charts on dashboards you published.

The tenant comes from the token. Your backend chose it when it asked for the token, and GOAT signed it into the token. GOAT adds the tenant filter on the server for every query on a dataset with a tenant key. A dataset with no tenant key has no tenant filter; see [Security model](security-model.md#datasets-with-no-tenant-key).

On every request, GOAT checks that the dashboard is published and that the tenant has access. The check reads records at most a minute old, so unpublishing or removing access takes effect within a minute.

## In this section

- [Architecture on Google Cloud](architecture.md): each service and what it is allowed to do.
- [How queries run and what they cost](how-queries-run.md): from a chart to a BigQuery job and its bill.
- [How data loads](data-loading.md): Live connect and Managed copy datasets, and how each one loads.
- [Performance](performance.md): caching and keeping dashboards fast.
- [Security model](security-model.md): how customers are kept apart.
