# Data Model Reference This document summarizes the durable and in-memory data shapes that define Frosty Deno's configuration, governance, caching, logging, and operator surfaces. ## Durable storage model ### PostgreSQL state store `packages/config/src/store_postgres.ts` defines two generic durable tables: | Object | Shape | Purpose | | ----------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `frosty.state` | `key_text text primary key`, `key_path text[]`, `value jsonb`, `updated_at timestamptz` | Durable JSON document store for config, hierarchy, settings, logs, and related state | | `frosty.counters` | `key_text text primary key`, `key_path text[]`, `value bigint`, `updated_at timestamptz` | Durable atomic counters for usage, cost, budgets, and shared rate-limit windows | State and counter namespaces are intentionally separate so additive counters never masquerade as ordinary JSON documents. ### Cache and vector tables | Object | Purpose | Source | | ------------------------------------------------ | --------------------------------------------- | ----------------------------------------------------------- | | `frosty.response_cache` | Cached response payloads with TTL support | `packages/cache/src/pg_cache.ts` | | `FROSTY_PG_TABLE` defaulting to `frosty_vectors` | pgvector embeddings for semantic cache lookup | `apps/gateway/context.ts`, `packages/cache/src/pgvector.ts` | ## Key-path conventions in `frosty.state` The durable store is key-path driven. Important observed prefixes include: | Prefix | Stored object family | | ------------------------------- | ------------------------------------------------------------- | | `['config', 'providers', ]` | Provider account configuration | | `['config', 'settings']` | Gateway config-level settings data | | `['virtual_keys', ...]` | Virtual-key state | | `['teams', ...]` | Team hierarchy data | | `['customers', ...]` | Customer hierarchy data | | `['settings', ]` | Per-group operator override fragments | | `['logs', ...]` | Durable log entries when log storage is enabled | | `['config', 'crypto', 'dek']` | Wrapped data-encryption key record for encrypted config state | ## Configuration entities ### `ProviderAccountConfig` Defined in `packages/contracts/src/config.ts`. Major fields: | Field | Type | Purpose | | --------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Stable provider account id | | `type` | enum | Provider family such as `openai`, `anthropic`, `azure`, `bedrock`, `vertex`, `openai-compatible`, or `lmstudio` | | `apiKey` | `string?` | Provider API key when that provider uses one | | `baseUrl` | `string?` | Upstream base URL | | `endpoint`, `apiVersion` | `string?` | Azure-specific routing values | | `enabled` | `boolean` | Provider account enablement | | `models` | `string[]` | Advertised model catalog | | `priority`, `weight` | `number` | Fallback and weighted balancing hints | | `retry` | object | Provider retry policy | | `aws*` | strings | Bedrock and S3 integration fields | | `projectId`, `location`, `serviceAccountJson` | strings | Vertex AI configuration | | `proxyUrl` | `string?` | Per-provider proxy endpoint | | `network`, `proxy`, `performance`, `governance`, `betaHeaders`, `debugging` | objects | Six grouped provider-control panels | Redacted browser-safe view: - `ProviderAccountPublic` replaces secrets with presence markers such as `hasApiKey`, `hasCloudCredentials`, `hasProxy`, `hasProxyPassword`, and `hasCaCert`. - Header values, proxy passwords, bypass rules, certificate PEM data, raw provider secrets, and stored cloud credentials do not reach the browser. ### `GatewayConfig` and `ConfigExport` | Type | Purpose | | --------------- | ------------------------------------------------------------------------- | | `GatewayConfig` | Strict object with `defaultProvider` and `providers[]` | | `ConfigExport` | Versioned export payload containing `version`, `exportedAt`, and `config` | ## Governance entities ### `Budget` Defined in `packages/governance/src/virtual_keys.ts`. | Field | Purpose | | ----------------- | ------------------------------------------ | | `maxRequests` | Request-count budget ceiling | | `maxCostUsd` | Dollar-cost budget ceiling | | `resetIntervalMs` | Optional server-timed fixed reset interval | ### `VirtualKey` Defined in `packages/governance/src/virtual_keys.ts`. | Field | Purpose | | ----------------------------------- | --------------------------------------------------------------------- | | `id`, `name`, `description` | Stable identifier and operator label | | `token` | Raw bearer token accepted transiently on creation or legacy migration | | `tokenHash` | Persisted SHA-256 hex token hash | | `tokenHint` | Non-secret last-four-character hint for UI display | | `enabled` | Key enablement | | `rateLimit` | Request-based fixed window | | `tokenLimit` | Token-metered fixed window | | `budget` | Request and/or cost budget | | `allowedProviders`, `allowedModels` | Admission scope restrictions | | `usedRequests`, `usedCostMicroUsd` | Accrued metering data | | `teamId` | Optional team membership | Public browser-safe projections drop the raw token and its hash and add a derived `usedCostUsd` field. ### `Team` and `Customer` Defined in `packages/governance/src/hierarchy.ts`. | Type | Key fields | Purpose | | ---------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------- | | `Team` | `id`, `name`, `enabled`, `customerId`, `budget`, `usedRequests`, `usedCostMicroUsd` | Mid-level hierarchy node collecting usage from virtual keys | | `Customer` | `id`, `name`, `enabled`, `budget`, `usedRequests`, `usedCostMicroUsd` | Top-level hierarchy node collecting usage from teams | Unknown references fail closed during chain validation. ## Settings model Defined in `packages/contracts/src/settings.ts` and `apps/gateway/routes/settings.ts`. Settings groups: | Group | Purpose | | --------------- | ------------------------------------------------------ | | `security` | Auth and route-protection-related operator settings | | `compatibility` | Request translation and unsupported-parameter handling | | `performance` | Request-body and pool-size tuning | | `caching` | Cache enablement and tuning | | `mcp` | MCP tool and external-client settings | Important settings response characteristics: - `GET /api/settings` returns effective values plus per-field provenance in `sources`. - Provenance values are `default`, `env`, or `override`. - Persisted overrides are stored by group under `['settings', ]`. - `security.hasPassword` is derived metadata; the password itself is not returned. - Runtime enforcement is exposed separately through an `enforcement` map because not every persisted setting is wired live. ## MCP data shapes Observed browser-facing MCP view types in `apps/control-ui/src/api.ts`: | Type | Purpose | | ---------------- | ----------------------------------------------------------------------------------------------------- | | `MCPClientView` | Browser-safe MCP client record with `headerNames`, `hasCommand`, `hasUrlCredentials`, and `toolCount` | | `MCPClientInput` | UI write shape for MCP client creation and updates | | `MCPToolView` | Aggregated tool metadata including `clientId` and optional annotations | | `MCPHealthView` | Per-client health summary | ## Telemetry and log model ### `LogEntry` Defined in `packages/telemetry/src/logbus.ts`. | Field family | Purpose | | ----------------------------------------------------- | ----------------------------------------------------- | | `ts`, `level`, `message` | Base log metadata | | `requestId`, `method`, `path`, `status`, `durationMs` | HTTP request identification and timing | | `provider`, `model` | Resolved inference target | | `promptTokens`, `completionTokens`, `totalTokens` | Usage accounting | | `costMicroUsd` | Cost in the repo-wide integer micro-USD unit | | `content` | Opt-in captured request/response content when enabled | Request and response content capture is disabled by default and redacts secret-looking keys before persistence. ## UI-facing transport shapes The control UI imports shared contracts directly and adds view-specific wrapper shapes in `apps/control-ui/src/api.ts`, including: - `GatewayConfigView` - `VersionInfo` - `AnalyticsRollup`, `AnalyticsTotals`, `AnalyticsBucket`, `AnalyticsModelRow`, `AnalyticsProviderRow` - `StoredLogsResult` Those client-side view types are projections over gateway responses, not independent persistence models.