# Catalox — product overview

**Audience:** Product owners, architects, and engineering leads deciding whether to build on Catalox  
**Companion:** [Building apps on Catalox as the content backend](./app-content-backend.md) — the recommended integration pattern

---

## The problem Catalox exists to solve

Every x12i product eventually needs the same thing:

- A **catalog of things** users can browse, pick, configure, or reference — plans, skills, templates, policies, vocabulary, feature matrices, routing rules, prompt libraries, and so on.
- A way for **multiple apps and agents** to discover those catalogs without hardcoding catalog ids, field lists, or CRUD endpoints in each codebase.
- **Governance** — who can see which catalog, which items apply to which account/domain/agent, and what happens when access or configuration is wrong (empty vs denied vs misconfigured).

Without a shared layer, each team rebuilds:

| Repeated work | Typical cost |
|---------------|--------------|
| Firestore/Mongo schema per “settings table” | Weeks per product |
| List/get/filter APIs per entity | Ongoing maintenance |
| Admin UI field metadata | Duplicated in frontend |
| App↔data access rules | Inconsistent security |
| Seed/migration/backup tooling | One-off scripts |
| Agent-readable metadata endpoints | Ad hoc JSON blobs |

Catalox exists so that work is done **once**, with a stable contract, and every app spends its backend budget on **product logic** — checkout, workflows, execution, billing — not catalog plumbing.

---

## What Catalox is (one sentence)

**Catalox is the metadata and content backend for governed catalogs** — the layer where you store *what can be selected or configured*, expose it consistently to web apps and agent runtimes, and keep operational transactions in your own services.

It is **not**:

- A CMS replacement for marketing pages
- An OLTP database for orders, runs, or events
- A UI framework (it returns descriptors and render hints; you render)
- A login system (SSO stays in your SaaS; Authix gates the HTTP API in production)

---

## Why it exists — the “why why”

### 1. Catalogs are a distinct product shape

Most “business data” falls into two buckets:

```text
DEFINITIONS (catalogs)          TRANSACTIONS (your domain)
────────────────────────        ────────────────────────────
Relatively stable               High churn
Read-heavy, curated             Write-heavy, operational
Shared across apps/agents       Owned by one workflow
Needs discovery + descriptors   Needs state machines + events
```

Mixing both in the same custom tables and APIs leads to either under-powered catalogs (no discovery, no generic UI) or over-loaded catalogs (orders and runs stuffed into “items”). Catalox draws the line clearly: **definitions here, transactions in your host**.

### 2. Generic clients need descriptors, not hardcoded screens

A dashboard or agent should not ship with `if (catalogId === 'skills')` column definitions. It should call **bootstrap**, read **queryable fields** and **capabilities**, and render any bound catalog the same way.

That only works if descriptors, bindings, and outcomes are **first-class persisted contracts** — not comments in someone’s BFF. Catalox makes that contract the center of the system.

### 3. Agents need the same metadata humans use

Agent runtimes do not want a separate “agent config service” that drifts from what the admin UI shows. They need **scoped read access to the same catalog rows**, filtered by `domainId`, `agentId`, and account scope. Catalox’s item scope model and Authix token mapping exist so **one source of truth** feeds UI, BFF, and agents.

### 4. Platform economics

x12i ships many apps (Pagenti, agent platforms, partner integrations). Each hour spent reimplementing list/filter/seed/backup is an hour not spent on differentiation. A shared catalog layer amortizes operator tooling, documentation, and security review across the whole platform.

### 5. Interoperability without shared databases

Partners and internal teams should integrate via **HTTPS + OpenAPI + SDK**, not Firestore credentials. The 6.0.0 API line (Authix-gated) exists so **catalogs-as-a-service** is a real product surface, not only an embeddable library.

---

## The recommended main use case

**Build web apps (and agent backends) that treat Catalox as their content and metadata API** — catalogs designed for that app, bound to its `appId`, edited through standard list/get/write flows, consumed by your UI and agents without custom CRUD per entity.

```text
┌─────────────────────────────────────────────────────────────┐
│  Your product (web app, dashboard, agent control plane)     │
│  • SSO / accounts / billing / workflows  ← YOUR backend     │
│  • Thin BFF: auth → CataloxContext or Authix token          │
└───────────────────────────┬─────────────────────────────────┘
                            │ discovery · bootstrap · items
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  Catalox (content + metadata backend)                       │
│  • Descriptors (fields, identity, capabilities)             │
│  • Bindings (which app sees which catalog)                  │
│  • Items (native or mapped) + scope + references            │
└───────────────────────────┬─────────────────────────────────┘
                            │
                            ▼
                     Firestore / Mongo / GCS
```

**What you stop building:**

- Per-entity REST routes for every catalog table
- Admin CRUD handlers duplicated across services
- Frontend column/filter definitions hardcoded per screen
- Separate “agent metadata” stores that diverge from admin data
- One-off seed scripts without validation or idempotency

**What you keep building:**

- User sessions, payments, orchestration, execution state
- Product-specific business rules that *use* catalog items
- Custom UI where descriptors allow escape hatches (`customRenderer`, templates)

Full pattern, maturity notes, and step-by-step: **[app-content-backend.md](./app-content-backend.md)**

---

## Product value summary

| Stakeholder | Value |
|-------------|-------|
| **Product** | Faster time-to-market for admin surfaces and configurable products |
| **Frontend** | Generic catalog screens driven by bootstrap/descriptors |
| **Backend** | No N× CRUD APIs; one integration (embed or HTTP client) |
| **Agents** | Scoped reads/writes on the same metadata humans curate |
| **Platform ops** | CLI seed, backup, binding diagnostics, history |
| **Partners** | Public API + SDK (6.0.0) without datastore access |

**Core value statement:** *One governed catalog platform so every app and agent reads the same curated metadata — with less backend code and clearer boundaries.*

---

## What “content designed for the app” means

Each app gets:

1. **`appId`** — tenant in the catalog world  
2. **`catalogBindings`** — which catalogs this app may use (read/write/admin)  
3. **`catalogDescriptors`** — how each catalog behaves (fields, filters, identity, smart properties)  
4. **Items** — rows in native or mapped storage, optionally scoped to account/domain/agent  

The app’s **domain payload** lives in `item.data` (your JSON shape). Catalox handles identity, indexing, listing, validation, references, and access. Your app handles **when** an item is used in a workflow — not **how** it is stored and discovered.

Example: a “Skills” catalog for an agent platform holds skill definitions, tools, and prompts. The execution engine stores **runs**; Catalox stores **which skills exist and what metadata they carry**.

---

## Maturity and expectations

Catalox is **production-grade platform infrastructure**, not a greenfield experiment. Current monorepo version **5.9.8** reflects years of engine evolution (native layout, mapped catalogs, smart properties, record history, GCS backup, structured outcomes, HTTP API packages).

| Area | Maturity | Notes |
|------|----------|-------|
| **Engine / embedder** | **High** | Used as library; broad API surface; live Firestore integration tests |
| **CLI / operator** | **High** | Seed, items, toolbox, backup, history, catalog lifecycle |
| **Descriptors & generic UI** | **High** | Bootstrap, render maps, presentation bindings documented |
| **Private HTTP API (5.9.x)** | **Medium–high** | `catalox-service` + client; internal network only in open mode |
| **Public API + Authix (6.0.0)** | **Planned product line** | Spec and packages in repo; production rollout per [catalox-v6/6.0.0](./catalox-v6/6.0.0/README.md) |
| **Hosted SaaS** | **N/A** | You deploy library or `catalox-service`; not a multi-tenant cloud product by default |
| **Known gaps** | **Documented** | See [Known-Gaps](../Known-Gaps/README.md) for reserved provider types |

**Reasonable expectations:**

- ✅ Adopt today for **native catalogs**, app bindings, bootstrap-driven UIs, agent metadata reads, operator seed/backup  
- ✅ Embed in Node BFFs for lowest latency; use HTTP client when polyglot or strict service boundaries matter  
- ⚠️ Plan Authix and TLS before **public** HTTP exposure  
- ❌ Do not use for high-frequency transactional state or secret storage  

---

## How Catalox relates to other x12i pieces

| Piece | Role relative to Catalox |
|-------|---------------------------|
| **Your app backend** | SSO, billing, workflows; issues Authix tokens; calls Catalox |
| **catalox-ui** | Generic catalog UI consuming BFF + bootstrap ([catalox-ui-contract.md](./catalox-ui-contract.md)) |
| **Authix** | Token issue/verify for public API (6.0.0); not user login |
| **aifunctions-js** | Optional AI create/modify/search on catalog items |
| **Agent runtime** | Reads scoped items from Catalox; stores runs elsewhere |

---

## Decision guide

**Choose Catalox when:**

- You have (or will have) **multiple catalogs** or many items shared across features  
- You want a **generic admin or picker UI** without hardcoding each catalog  
- **Agents and humans** must see the same curated metadata  
- You need **governed access** (bindings, scope, explicit outcomes)  
- You want to **avoid rebuilding** list/filter/seed/backup on every project  

**Choose something else when:**

- You need a single static config file with no discovery  
- Data is purely transactional (orders, events, balances)  
- You need sub-10ms reads at massive QPS with no caching layer (Catalox is a data tier, not a CDN)  

---

## Where to go next

| Goal | Document |
|------|----------|
| **Recommended app architecture** | [app-content-backend.md](./app-content-backend.md) |
| Example flows | [USE-CASES.md](./USE-CASES.md) |
| First-time setup | [onboarding-happy-path.md](./onboarding-happy-path.md) |
| Deploy library or service | [DEPLOYMENT.md](./DEPLOYMENT.md) |
| Common questions | [FAQ.md](./FAQ.md) |
| Technical reference | [README.md](../README.md) |
| Public API product | [catalox-v6/6.0.0/README.md](./catalox-v6/6.0.0/README.md) |