# Architecture on Google Cloud

The services an install runs and what each one does.

This page lists each Google Cloud service an install runs, the access GOAT's service account holds, and what an install never has. Names below use `goat` for your install's name and `your-project` for the project it is installed in.

## The services

| Service | What the install creates | What it is for |
|---|---|---|
| Cloud Run | The service `goat-platform` | Runs GOAT: the app, the API, and the embed script. One instance stays warm; up to 10 by default. |
| Firestore | A named database `goat-metastore`, protected from deletion | What operators build: datasets' settings, collections, charts, dashboards, tenants, grants, and settings. |
| BigQuery | The dataset `goat` | GOAT's managed copies of your data. |
| BigQuery | The dataset `goat_telemetry`, and a log sink feeding it | A record of each chart query, kept 400 days, for usage and cost figures. |
| Cloud Storage | The bucket `goat-uploads-your-project` | Files operators upload. Public access is prevented, and files are kept for as long as their datasets use them. |
| Identity Platform | Email and password sign-in with an optional authenticator second factor, and Google sign-in if it is chosen at install | Signing in operators. |
| Secret Manager | The secret `goat-embed-keyring` | The keys that sign viewer tokens. |
| Service account | `goat-platform` | The identity GOAT runs as. |

## What GOAT's service account may do

| Access | On | Why |
|---|---|---|
| Run BigQuery jobs (`roles/bigquery.jobUser`) | The project | Every chart query and every load. |
| Read BigQuery metadata (`roles/bigquery.metadataViewer`) | The project | Browsing datasets, tables, and columns. It reads names, columns, view definitions, and who has access to each table, never table data. |
| Read and write data (`roles/bigquery.dataEditor`) | The `goat` dataset only | Managed copies. |
| Read data (`roles/bigquery.dataViewer`) | The `goat_telemetry` dataset only | Usage and cost figures. |
| Read and write documents (`roles/datastore.user`) | The `goat-metastore` database only, by an IAM condition | What operators build. |
| Read and write files (`roles/storage.objectAdmin`) | The uploads bucket only | Uploaded files. |
| Read the secret (`roles/secretmanager.secretAccessor` and `roles/secretmanager.viewer`) | The `goat-embed-keyring` secret only | Signing and checking viewer tokens. |
| Read and update Identity Platform users (a custom role `goat.operatorClaims`) | The project | Setting each operator's role on their account. |
| Read data (`roles/bigquery.dataViewer`), only if a billing export table in the same project is chosen at install | That billing export dataset only | Actual amounts in cost figures. |
| Manage Data Transfer Service configs (a custom role `goat.transferManager`), change the `goat` dataset's settings and access list (a custom role `goat.transferDestination`), and act as itself (`roles/iam.serviceAccountUser` on itself) | The project; the `goat` dataset; the service account itself | Granted ahead of scheduled reloads, which GOAT does not offer yet. |

Two of these reach further than their purpose, and a security review should weigh them:

- The Identity Platform role can update any user in the project: their password, email, and claims. So whoever controls GOAT's service account could take over any account that signs in through that Identity Platform, operators included. It cannot create users, read password hashes, or change the sign-in setup.
- The transfer role reaches every Data Transfer Service config in the project, not only GOAT's.

## Your own data

GOAT's service account gets no access to your own datasets' rows or your buckets' files when GOAT is installed, apart from an optional billing export table. You grant it, one dataset or bucket at a time. See [Give GOAT access to your data](/docs/run-goat/data-access).

## What an install never has

- No public access grant on Cloud Run. The service turns off Cloud Run's own invoker check, so its address is reachable, and GOAT's own sign-in, API keys, and viewer tokens decide every request.
- No automatic updates, and no reporting back to anyone. A new version runs only when whoever runs the install applies it.
- No GOAT-hosted service in between. Your browsers, your backend, and Google Cloud talk to your install directly.

## Encryption with your own key

An install can use a customer-managed key, chosen when it is installed, for the Firestore database, both BigQuery datasets, the uploads bucket, the token signing secret, and Cloud Run's copy of GOAT's image. It cannot be switched on later by a setting; that is a migration.

## Network

By default the service accepts traffic from anywhere, and GOAT's own checks decide each request. An install can instead accept traffic only through your own load balancer. Sign-in requests to Identity Platform leave the service over its default internet connection.
