> ## Documentation Index
> Fetch the complete documentation index at: https://playbook.smedleygroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hub Regions and Configuration

> How the platform is multi-tenanted by hub region, where business configuration lives and why, and what adding a region involves.

GKL Platform runs one deployment serving many hub regions. This page describes how that works and where the settings that drive it are held.

## The Hub Region

Every request resolves a hub region, from a `hubRegion` query parameter or a `Hub-Region` header, **defaulting to `UK`** when neither is present. Every document carries the region it belongs to, and every configuration lookup is scoped by it.

That one value determines which Vivenu account is called, which classes and power levels apply, which shop URL is used and which currency is shown.

> [!WARNING]
>
> Because the default is `UK` rather than an error, a caller that forgets to send a region does not fail. It silently operates on UK data. This is worth knowing when debugging something that appears in the wrong region.

## Configuration Lives In The Database

Business configuration is not in infrastructure code. It is held as documents in the `Configurations` collection, under well known IDs, some global and some per region. They cover the regions themselves and their Vivenu credentials, the class codes and power level tiers, the booking site settings, and the championship definitions.

### Why It Is Built This Way

Championships are defined per year, marketing redirects move, and new regions launch. If those lived in CDK, every change would need an engineer and a deployment. Holding them as documents means operators change them through the dashboard and the change takes effect immediately.

### The Exception

Race level eligibility, which restricts power levels by race type, is **hardcoded in the application** rather than stored as a document, and has separate tables for the checkout path and the admin path. See [Ticket Eligibility](/software/developer/estate/systems/gkl/ticket-eligibility#race-level-eligibility).

## What Reads The Region

| Consumer | Uses it for |
| - | - |
| GKL API | Selecting Vivenu credentials, class and championship configuration |
| Booking website | Region selection, currency, shop URL, redirects |
| Operator Dashboard | The region selector, and scoping what an operator sees |
| Vivenu webhooks | Passed as a query parameter, and used to select the HMAC secret for verification |
| Telemetry | Passed to GKL when asking whether a run was on a race day |

## Adding A Region

Adding a region is not a deployment. It is a MongoDB migration written by hand, plus configuration in Vivenu.

The full procedure, including the Vivenu seller, domains, API key, webhooks and the migration itself, is documented under [Setting Up a New Hub](/software/third-party/vivenu/hub-deployment/vivenu-setting-up-a-new-hub).

> [!NOTE]
>
> The new region's HMAC secret has to match on both sides: generated for the region configuration, then base64 encoded into each of the four Vivenu webhooks. A mismatch produces webhooks that return 401 and sales data that never arrives.

## Related Documentation

| Page | Relevance |
| - | - |
| [The Domain Model](/software/developer/estate/systems/gkl/domain-model) | The entities the configuration applies to |
| [Ticket Eligibility](/software/developer/estate/systems/gkl/ticket-eligibility) | How class and power level configuration is used |
| [Configuring a New Hub Region](/software/third-party/vivenu/hub-deployment/development/configure-new-hub-region) | The migration procedure |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.