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

# Architecture

> The Tenant → Project → Service hierarchy and how everything fits together.

## Hierarchy

```
Tenant
└── Project  (tier: free / xs / s / m / l / xl)
    ├── Service  (kind: backend)   → secret key
    ├── Service  (kind: frontend)  → public key
    └── Umbrella Service           → no API key (shared config parent)
```

Every resource - secrets, configs, feature flags - is scoped to a **service**.

## Tenant

A tenant is your top-level organisation. It is the billing boundary: invoices are issued per tenant, and your tier quota applies per project within that tenant.

* One tenant per company, agency, or individual account
* Tenant roles: `owner` and `member`
* `owner` is automatically an owner of every project in the tenant
* **Tenant capabilities** granted to members by owners: `billing_access` (dashboard + billing/invoices), `all_projects_viewer` (read-only access to every project without explicit membership), `audit_log_viewer` (tenant-level audit log)

## Project

A project represents one product or application. It has:

* A **tier** (`free` / `xs` / `s` / `m` / `l` / `xl`) that controls environments, secrets cap, retention window, and add-on availability
* Its own **member list** with project-level roles
* One or more **services** and a set of allowed **environments**

### Environments

The environments available to a project depend on its tier:

| Tier             | Environments                       |
| ---------------- | ---------------------------------- |
| `free`           | `develop`                          |
| `xs`             | `develop`, `production`            |
| `s`              | `develop`, `staging`, `production` |
| `m` / `l` / `xl` | All environments                   |

### Project roles

| Role             | Description                                                                              |
| ---------------- | ---------------------------------------------------------------------------------------- |
| `owner`          | Full control - all environments, manage members, settings, and all resources             |
| `manager`        | All environments plus member management; manage services, secrets, configs, and flags    |
| `devops`         | All environments, infrastructure management. No destructive content operations           |
| `lead_developer` | Full access to develop, test, and staging; read-only in production. No member management |
| `developer`      | Full access to develop and test; read-only in staging and production                     |
| `tester`         | Read access to develop and test; read-only in staging and production                     |
| `viewer`         | All environments: key names and flag on/off state only, never values                     |

## Service

A service is a single deployable unit - a backend API, a worker, a frontend app. It belongs to one project and one environment.

Every service has an immutable **kind**:

<CardGroup cols={2}>
  <Card title="Backend" icon="server">
    Uses secret keys (`wxs_`). Has access to secrets, configs, and flags. Supports Workload Identity Federation (WIF).
  </Card>

  <Card title="Frontend" icon="browser">
    Uses public keys (`wxp_`). Configs and flags only - secrets are never sent to frontend services. Cannot use WIF.
  </Card>
</CardGroup>

### Umbrella services

An umbrella service acts as a shared config parent. Child services inherit its configs and flags automatically - useful for configs shared across multiple services in the same environment.

* Umbrella services have no API keys of their own
* Child services must have the same `kind` as their umbrella
* The inheritance is flat (no nested umbrellas)

## Auth paths

### API key (classic)

```
X-Nexus-API-Key: wxs_<64-hex>   // backend services
X-Nexus-API-Key: wxp_<64-hex>   // frontend services
```

### Workload Identity Federation (WIF)

Backend services in Kubernetes, AWS, GCP, or Azure environments can authenticate without static API keys. The SDK fetches an OIDC token from the environment, exchanges it at `/api/v1/auth/token-exchange` for a short-lived session JWT, and auto-refreshes before expiry.

See the [SDK reference](/sdks/go#workload-identity-federation) for setup instructions.

## Audit log

Every mutating action - and selected read events (secret reveal, list) - is recorded in the audit log with actor, IP, user agent, and timestamp. The retention window depends on the project tier.