# Catalox use cases

Who uses Catalox, what problems it solves, and example flows across embedder, CLI, and HTTP API paths.

**Recommended main pattern:** [Building apps on Catalox as the content backend](./app-content-backend.md) — web apps and agents share one metadata layer; your backend skips per-catalog CRUD. Product rationale: [overview.md](./overview.md).

For “when not to use Catalox” see the [root README](../README.md#what-catalox-does). For Authix-gated public API scenarios see [catalox-v6/6.0.0/use-cases-and-values.md](./catalox-v6/6.0.0/use-cases-and-values.md).

---

## Product value

Catalox gives x12i apps and partners a **single catalog layer**:

1. **Define once** — descriptors describe capabilities, fields, and identity; no per-app hardcoding
2. **Bind per app** — `catalogBindings` control which tenants see which catalogs
3. **Consistent outcomes** — empty vs denied vs misconfigured are explicit
4. **Operate safely** — seed manifests, CLI tools, backup/history, binding diagnostics
5. **Expose flexibly** — embed in-process, private HTTP, or public Authix API

**Core statement:** *Catalogs-as-infrastructure — governed, scoped, and reusable — without duplicating catalog logic in every service.*

---

## Fit vs misfit

### Good fits

| Domain | Example catalogs |
|--------|------------------|
| Product & pricing | Plans, SKUs, feature bundles |
| Routing & policy | Rules, feature flags, lookup tables |
| Templates | Graph templates, prompt templates, execution matrices |
| Knowledge & vocabulary | Skills, roles, use cases (smart properties) |
| Configuration-as-data | Mappings, enums, design tokens refs |

### Poor fits

| Domain | Why not Catalox |
|--------|-----------------|
| Orders & payments | OLTP transaction state |
| Live execution runs | High-churn operational state |
| Event/audit streams | Append-heavy mutable logs |
| Secret storage | Use a secrets manager; store refs only |

---

## Consumers

| Consumer | Integration | Typical access |
|----------|-------------|----------------|
| **Product BFF** | Embed `@x12i/catalox-engine` | `createCatalox` + host auth → `CataloxContext` |
| **catalox-ui** | BFF + optional HTTP client | Discovery + item read/write features |
| **Agent runtimes** | HTTP or embedder | Scoped token: `domainIds`, `agentIds` |
| **CI / seed workers** | CLI or embedder | `seed apply`, `items batch-upsert` |
| **Platform ops** | CLI | backup, GCS export, toolbox, history |
| **Partner integrations** | Public HTTP (6.0.0) | Authix token via partner BFF |

---

## Use case 1 — Bootstrap a new app with catalogs

**Goal:** Stand up catalogs, bindings, descriptors, and seed items for a new `appId`.

**Actors:** Platform engineer, CI pipeline.

**Flow:**

1. Set Firebase credentials ([environment.md](./environment.md))
2. `catalox firestore probe`
3. `catalox seed validate --file preset.json`
4. `catalox seed apply --app myApp --file preset.json --god`
5. `catalox toolbox check-access --app myApp --catalog signals`
6. `catalox items list --app myApp --catalog signals`

**Value:** Repeatable, reviewable manifests; idempotent apply; validate before write.

→ [onboarding-happy-path.md](./onboarding-happy-path.md) · [native-map-catalog-preset.md](./native-map-catalog-preset.md)

---

## Use case 2 — Generic catalog UI (no hardcoded catalog ids)

**Goal:** A dashboard lists any catalog bound to the app and renders items from descriptor metadata alone.

**Actors:** Frontend + BFF.

**Flow:**

1. BFF: `listAppCatalogs({ appId })`
2. BFF: `getAppCatalogBootstrap(appId)` → descriptors
3. UI: build columns/filters from `queryableFields`
4. UI: `listCatalogItems(catalogId, { filter, limit })` per selected catalog
5. Optional: `buildCatalogListPresentationSurface(...)` → `{ map, binding }` for custom renderers

**Value:** New catalogs appear in UI when bound + described — no frontend deploy for each catalog.

→ [catalog-format.md](./catalog-format.md) · [catalog-custom-ui.md](./catalog-custom-ui.md) · [catalox-ui-contract.md](./catalox-ui-contract.md)

---

## Use case 3 — Mapped catalog from MongoDB

**Goal:** Expose an existing Mongo collection as a read-only (or synced) catalog without migrating data to Firestore.

**Actors:** Backend engineer.

**Flow:**

1. `createCatalog` with `sourceMode: "mapped"`, Mongo adapter config
2. Define `catalogMappings` field mapping spec
3. `listCatalogItems` returns unified items; mapping validation surfaces as `mapping_blocked`

**Value:** Single discovery/descriptor layer over heterogeneous sources.

→ Engine mapping module · [catalog-format.md](./catalog-format.md)

---

## Use case 4 — Smart properties (vocabulary catalogs)

**Goal:** Article items reference roles and use cases stored as separate catalogs, with auto-create and usage ranking.

**Actors:** Knowledge product (e.g. Pagenti).

**Flow:**

1. Descriptor defines `smartProperties` → target catalogs (`roles`, `use_cases`)
2. Upsert article with `role: ["ciso"]`, `useCase: ["vendorAccessReview"]`
3. Catalox resolves codes, optionally auto-creates target rows, updates `usageCount`

**Value:** Normalized vocabulary; FK validation at write time; searchable indexed fields.

→ [smart-properties.md](./smart-properties.md) · [pagenti-knowledge-usage.md](./pagenti-knowledge-usage.md)

---

## Use case 5 — Agent reads scoped catalog items

**Goal:** An agent sees only skills in its domain, not the full catalog.

**Actors:** Agent runtime, control plane.

**Flow (6.0.0 HTTP):**

1. Control plane issues Authix token with `catalox.item.read`, `scope.domainIds: ["sales"]`
2. Agent: `GET /v1/catalogs/skills/items` with Bearer token
3. API maps token → `CataloxContext.scope`
4. Engine filters items by scope intersection

**Flow (embedder):**

```ts
const context = mapAuthixToCataloxContext(payload);
await catalox.listCatalogItemsWithOutcome(context, "skills", { limit: 50 });
```

**Value:** Least-privilege catalog exposure for autonomous agents.

→ [catalox-v6/6.0.0/README.md](./catalox-v6/6.0.0/README.md) · [authorization.md](./authorization.md)

---

## Use case 6 — Operator backup before migration

**Goal:** Snapshot Firestore catalog data before layout migration or bulk edit.

**Actors:** SRE, platform ops.

**Flow:**

1. `catalox firestore backup --mode gcs --bucket my-backups --app myApp`
2. Run migration or bulk change
3. If needed: `firestore restore-backup-from-gcs` or compare with `firestore compare-gcs`

**Value:** Recoverable operator workflows; NDJSON artifacts in GCS.

→ [backup.md](./backup.md) · [firestore-gcs-export.md](./firestore-gcs-export.md) · [restore-firestore-backup.md](./restore-firestore-backup.md)

---

## Use case 7 — Per-item audit history

**Goal:** Track who changed a native catalog row and restore prior versions (including single-field history).

**Actors:** Compliance, catalog editors.

**Flow:**

1. Enable `recordHistory` on `createCatalox` (GCS bucket + `catalogItemHistory` index)
2. Native writes emit history events automatically
3. `catalox history list --app … --catalog … --item …`
4. `catalox history restore …` or field-level restore

**Value:** Audit trail without building custom versioning in each app.

→ [record-history.md](./record-history.md)

---

## Use case 8 — Internal microservice catalog API (5.9.x)

**Goal:** Other services on a private network call HTTP instead of linking the engine.

**Actors:** Internal service mesh.

**Flow:**

1. Deploy `catalox-service` with `CATALOX_AUTH_MODE=open`, `CATALOX_PRIVATE_MODE=true`
2. Consumers use `@x12i/catalox-client` with `withContext({ appId, superAdmin: … })`
3. Same routes as future 6.0.0 public API

**Value:** Language-agnostic access; thin wrapper over proven engine.

→ [DEPLOYMENT.md](./DEPLOYMENT.md) · [catalox-v6/5.9.5/README.md](./catalox-v6/5.9.5/README.md)

---

## Use case 9 — Public partner API (6.0.0)

**Goal:** External integrators call HTTPS with revocable tokens.

**Flow:**

1. Partner authenticates users in their system
2. Partner BFF issues Authix token with minimal features (`catalog.read`, `item.read`)
3. Client calls `https://catalox-api.example.com/v1/...` with Bearer token
4. Missing feature → 403; invalid binding → 403; success → engine outcomes in JSON

**Value:** Public integrability without open database mode.

→ [catalox-v6/6.0.0/README.md](./catalox-v6/6.0.0/README.md) · [transition-from-5.9.5.md](./catalox-v6/6.0.0/transition-from-5.9.5.md)

---

## Use case 10 — Offline read-only catalog snapshot

**Goal:** Tests, demos, or edge nodes read catalog data without Firebase credentials.

**Flow:**

```ts
import { createCatalox, LocalFileStore } from "@x12i/catalox/embedder";

const catalox = createCatalox({
  store: new LocalFileStore({ root: ".catalox/local", access: "read-only" }),
});
```

**Value:** Deterministic fixtures; no cloud on read path.

→ [local-file-store.md](./local-file-store.md)

---

## Choosing an integration path

| Need | Path |
|------|------|
| Lowest latency, full engine surface | Embed `@x12i/catalox-engine` |
| Shell/CI operations | `catalox` CLI |
| Internal polyglot consumers | `catalox-service` (private) |
| Browser/external HTTPS | `catalox-service` + Authix + `@x12i/catalox-client` |
| Read-only fixtures | `LocalFileStore` |

→ [FAQ.md](./FAQ.md) · [DEPLOYMENT.md](./DEPLOYMENT.md)