# The Platform Algebra

URL: https://docs.hanzo.ai/docs/architecture/algebra

> The whole cloud is a small set of primitives — Principal, Tenant, Resource, Policy, Ledger, Meter, Schedule, Bus, Gateway, Store, Money — and every product is a composition of them. Declare a schema, attach a policy, and persistence, tenancy, audit, and metering come free.

The platform is an algebra. The [nine domains](https://docs.hanzo.ai/docs/openapi) list every capability, but they are not that many unrelated services stacked side by side. They are **compositions of a small set of primitives** — a fixed vocabulary of generators — and almost everything a product does is one of those primitives applied to its own data.

This is the structural companion to the [Engineering Philosophy](https://docs.hanzo.ai/docs/architecture/philosophy). Philosophy is the _why_ — one contract, decomplect, the wire not FFI. This page is the _what_: the primitives everything decomposes into, and the way a product is assembled from them.

> A product is a \*_composition of primitives, not a new stack._\* It declares its own resources and rules; persistence, tenancy, audit, and metering are inherited from the platform, not rewritten each time.

## The primitives

Eleven primitives generate the platform. Each is one idea, named for what it is. Each is composed by many products; no product owns one outright.

| Primitive     | What it is                                                                                            | Composed by                                                                                                                                                                                                        |
| ------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Principal** | An authenticated identity — a person, an org member, a service, or an agent.                          | [IAM](https://docs.hanzo.ai/docs/openapi/iam), [Identity](https://docs.hanzo.ai/docs/openapi), [API Keys](https://docs.hanzo.ai/docs/api-keys)                                                                     |
| **Tenant**    | The organization boundary every record is scoped to.                                                  | [Organizations](https://docs.hanzo.ai/docs/openapi/iam) — and every capability, "tenant-scoped by org"                                                                                                             |
| **Resource**  | A typed record with a declared **schema**; CRUD, validation, and serialization fall out of the shape. | [ORM](https://docs.hanzo.ai/docs/openapi) (`Model[T]`), [Base](https://docs.hanzo.ai/docs/openapi/base), [SQL](https://docs.hanzo.ai/docs/openapi), [DocDB](https://docs.hanzo.ai/docs/openapi)                    |
| **Policy**    | A rule deciding who may do what to which resource.                                                    | [Authz](https://docs.hanzo.ai/docs/openapi/authz), [Guard](https://docs.hanzo.ai/docs/openapi), [Zero-Trust](https://docs.hanzo.ai/docs/openapi/network)                                                           |
| **Ledger**    | An append-only record of facts — what happened, immutable.                                            | [Traces](https://docs.hanzo.ai/docs/openapi/o11y), [Logs](https://docs.hanzo.ai/docs/openapi/o11y), [O11y](https://docs.hanzo.ai/docs/openapi/o11y)                                                                |
| **Meter**     | A count of usage, for limits and billing.                                                             | [Usage](https://docs.hanzo.ai/docs/usage), [Analytics](https://docs.hanzo.ai/docs/openapi/event), [Billing](https://docs.hanzo.ai/docs/openapi/billing)                                                            |
| **Schedule**  | Deferred and recurring execution — run this later, or on a cadence.                                   | [Workflows](https://docs.hanzo.ai/docs/openapi/workflow), [Pipelines](https://docs.hanzo.ai/docs/openapi/auto)                                                                                                     |
| **Bus**       | Asynchronous delivery between components.                                                             | [PubSub](https://docs.hanzo.ai/docs/openapi/pubsub), [Stream](https://docs.hanzo.ai/docs/openapi), [MQ](https://docs.hanzo.ai/docs/openapi/mq)                                                                     |
| **Gateway**   | The one entry point; every capability is reached at `/v1/<name>`.                                     | [Gateway](https://docs.hanzo.ai/docs/openapi/gateway), [Ingress](https://docs.hanzo.ai/docs/openapi/ingress)                                                                                                       |
| **Store**     | Durable bytes and blobs.                                                                              | [Storage](https://docs.hanzo.ai/docs/openapi/s3), [KV](https://docs.hanzo.ai/docs/openapi), [Vector](https://docs.hanzo.ai/docs/openapi), [Datastore](https://docs.hanzo.ai/docs/openapi)                          |
| **Money**     | Value movement — charges, payouts, balances, rewards.                                                 | [Commerce](https://docs.hanzo.ai/docs/openapi/commerce), [Billing](https://docs.hanzo.ai/docs/openapi/billing), [Referrals](https://docs.hanzo.ai/docs/openapi), [Marketplace](https://docs.hanzo.ai/docs/openapi) |

## How a product is assembled

A product is not a fresh vertical slice of infrastructure. It makes four moves against the primitives, and inherits the rest.

| The move                     | You write                    | You inherit                                                                                                       |
| ---------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Declare a Resource**       | the schema — your `Model[T]` | persistence + validation ([ORM](https://docs.hanzo.ai/docs/openapi)), and tenancy: every row scoped to its Tenant |
| **Attach a Policy**          | who may touch it             | authorization at the boundary ([Authz](https://docs.hanzo.ai/docs/openapi/authz))                                 |
| **Write Ledger facts**       | what happened                | audit + observability ([O11y](https://docs.hanzo.ai/docs/openapi/o11y))                                           |
| **Count with a Meter**       | the unit that matters        | metering + billing ([Billing](https://docs.hanzo.ai/docs/openapi/billing))                                        |
| **Expose a Gateway surface** | the handler                  | routing, auth, and generated SDKs at `/v1/<name>`                                                                 |

Persistence, tenancy, audit, and metering are therefore **not per-product code** — they are what you get for standing on the primitives. And the primitives themselves stand on exactly two things: **one ORM** and **one wire** — every product is a set of `Model[T]` resources served over [ZAP](https://docs.hanzo.ai/docs/zap). One ORM, one wire, one contract: the [philosophy's](https://docs.hanzo.ai/docs/architecture/philosophy) "one and one way" expressed as structure.

> **The proof: a Principal on ORM + ZAP.** Hanzo IAM is being rebuilt exactly this way — a clean-room identity service where a Principal is a `Model[T]` on the shared [ORM](https://docs.hanzo.ai/docs/openapi), served over [ZAP](https://docs.hanzo.ai/docs/zap), with no bespoke persistence, tenancy, or audit layer of its own. It is the first product to drop an inherited third-party stack and stand entirely on the primitives — the demonstration that the algebra composes a real service, not just a diagram.

## Two things named "agent"

The naming law behind the algebra: \*_say what it is._\* No compound words; an academic noun for a primitive, a concrete noun for a product. Because the vocabulary is small, the names have to be exact — and the clearest test is the pair that is deliberately _not_ merged:

- [Engine — the agent runtime](https://docs.hanzo.ai/docs/openapi/engine): The singular. One engine executes one agent's turn — inference, tools, quantization. It runs agents; it is not the set of them.
- [Agents — the open-source set](https://docs.hanzo.ai/docs/openapi/agent): The plural. The library of specialist agents and orchestrators you compose. A collection, not a runtime.

Same word, two referents, kept apart: the [Engine](https://docs.hanzo.ai/docs/openapi/engine) is the runtime that _runs_ an agent; [Agents](https://docs.hanzo.ai/docs/openapi/agent) is the open-source _set_ you compose. Collapsing them would fuse a place (the runtime) with a value (the set) — the exact braid the platform decomplects.

## Read on

- [Engineering Philosophy](https://docs.hanzo.ai/docs/architecture/philosophy): The principles behind the algebra: one and one way, decomplect, the language seam is the wire not FFI.
- [Architecture](https://docs.hanzo.ai/docs/architecture): How the one binary is built today, and the direction it is converging on.
- [Consensus-Backed Plugin Platform](https://docs.hanzo.ai/docs/architecture/plugin-platform): The runtime direction — how compositions of primitives get placed and scaled.
- [Platform & Services](https://docs.hanzo.ai/docs/openapi): The capabilities the primitives compose into, behind one api.hanzo.ai.