---
$id: https://apps.ax/docs/concepts
$type: TechArticle
$context: https://schema.org
title: "Concepts"
publishedWith: https://apps.ax
---


# Concepts

Three ideas explain how apps.ax behaves: the **Projection Law**, the
`{Definition, seed, theme}` model, and **instances as data**.

## The Projection Law

An App deserves to be data, not hand-authored code, whenever it can be: every
face — the JSON API, the faceted HTML directory, the markdown-of-live-state
twin, the admin — is a **projection of the same read model**, folded once per
request from a Definition and its live state (`src/generate.ts`'s
`buildReadModel`). No face is authored twice. Add a field to the Definition
and it appears in the API response, the directory's cards, the detail page,
and the markdown twin — simultaneously, because they all iterate the same
parsed fields rather than naming `category`/`provider`/`url` literally.

This is what makes facets **derived**, not configured: an enum field becomes a
facet group whose options are the type's declared values; a relation field
becomes a facet group whose options are the distinct values actually present
in the live collection. Both are counted over the SAME collection every other
face reads (`src/facets.ts`). Nothing about a browse dimension is
hand-authored — it falls out of the type.

## The `{Definition, seed, theme}` model

Presentation is data. Every mounted App is exactly three things:

- **Definition** — the typed noun(s) and verb(s) (`src/definition.ts`'s
  `AppDefinition`): what fields a Listing carries, and what create verbs exist.
- **seed** — the live state: either a KV-persisted, submit-able collection, or
  a fixed, read-only in-memory collection.
- **theme** — the one brand token set (an accent color + a label) that makes
  one instance look distinct from another WITHOUT a code fork. The render
  functions are shared; only the theme varies per instance.

Swapping a theme rebrands an App. Swapping a seed changes its live state.
Neither requires touching the render pipeline.

## Instances as data, not Workers

apps.ax is **one Worker**, not a Worker-per-tenant. At request time it resolves
an **instance** — a `{Definition, seed, theme}` row — by request hostname
(`src/registry.ts`'s `resolveInstance`) and renders that instance through the
same generator every other instance uses. Four instances are mounted today,
over the one interpreter (mounted as data in the registry — a hostname's public
DNS routing is a separate concern from whether the interpreter resolves it):

- `apis.directory` (the default) — the submit-able API marketplace, KV-backed.
- `apis.ax` — the curated agent-first API marketplace (~40 listings), a
  read-only seed with its own theme.
- `api.lawyer` — the legal possibility surface, a read-only seed.
- `api.insure` — the insurance possibility surface, a read-only seed.

Adding a fifth tenant is adding a row to the hostname → instance map, never
shipping a new Worker. An unknown hostname falls back to the default instance
— a sensible default, never a crash.

## The screen law: one URL, two registers

Every face that renders content (the directory, a listing's detail, a docs
page — this one included) serves **two byte-consistent projections of the
same state** at one URL: a designed HTML page for humans, and a clean markdown
twin for agents (`?format=md` — or, for the directory and docs, the default
whenever the request does not affirmatively prefer `text/html`). Both come
from the same fold, so the two faces can never drift, and there is no `/raw`
fork to discover separately.

## Two tiers: data now, code first-class

The default projection above is the **data tier**: a Definition renders every
face with zero per-face authoring and zero marginal cost. A second,
first-class **code tier** — custom verbs, custom logic, or custom components
running securely in their own isolated Worker — is in progress, so an App
never has to choose between "fits the data model" and "needs real logic." Data
is the free optimization, not the ceiling.

---

Previous: [Quickstart](https://apps.ax/docs/quickstart)

Next: [Reference](https://apps.ax/docs/reference)

Docs index: https://apps.ax/docs · all pages: https://apps.ax/docs/llms.txt

This page is also served as designed HTML at the same URL (add `?format=html`).
