Architecture overview
Box by Potter is a self-hostable commerce platform. A vendor: typically a bank: runs a box for its own merchants. The system has four cooperating parts plus a gated package registry.
The four planes
| Plane | What it is | Who runs it | Public interface |
|---|---|---|---|
| Control plane | Issues licenses, mints activation tokens, registers box domains, serves the package registry’s trust root. | Potter (central) | Control-plane API |
| Gated registry | Tier-aware npm registry that serves only the @withpotter/* packages a license is entitled to. | Potter (central) | registry.withpotter.com |
| Engine | The backend API a box runs, composed from entitled @withpotter/* packages. Serves an OpenAPI document at /docs. | The vendor (self-hosted) | @box/backend |
| Console | The admin dashboard the vendor’s staff and merchants use. | The vendor (self-hosted) | @box/dashboard |
| Storefront render | A single shared Next.js app that serves every bank’s public merchant storefronts. | Potter (central) | Managed service |
A box is one vendor’s deployment: an engine plus a console, wired
to the control plane and the gated registry. The CLI (@withpotter/box)
authenticates, composes, runs, and deploys a box.
How the pieces fit together
Composition vs. runtime
Box separates what gets installed from what runs:
- Composition (install time).
box authexchanges a license key for an activation token and the entitled package set, then writes the entitled@withpotter/*packages into the engine and console.box install/box updatepull them from the gated registry. See Plans & tiers and Packages. - Runtime. The engine (
@box/backend) imports every installed package’s Nest module and boots one API. Cross-package dependencies are resolved through ports (DI tokens), and the box binds adapters to those ports: noop defaults out of the box, real implementations (payment gateways, mailers, settlement banking) when the operator provides them. See Engine → Adapters.
Glossary
| Term | Meaning |
|---|---|
| Box | A vendor’s self-hosted deployment: engine + console. |
| Engine | The backend API (@box/backend), composed from entitled @withpotter/* packages. Serves OpenAPI at /docs. |
| Console | The admin dashboard (@box/dashboard). |
| Control plane | Central API that issues licenses, mints activation tokens, and registers box domains. |
| Gated registry | Tier-aware npm registry that serves only entitled packages. |
| Storefront render | Shared managed app that serves all banks’ public storefronts. |
| ARR (Android Retail Rails) | The Android implementation of the Box Retail Rails: the box-arr SDK that embeds in a host’s own Android app to run in-person sales against the box’s RR engine. |
| Tenant | A merchant within a box, resolved by slug subdomain or custom domain. |
| Tier | A license level (basic / growth / enterprise) that determines the entitled package set. |
| Entitlement | A package a tier grants to a box. |
| Port | A DI token an engine package depends on instead of importing another package directly. |
| Adapter | A concrete implementation bound to a port (e.g. a payment gateway). |
Where to go next
- Request flows: activation, storefront render, and checkout, step by step.
- Control plane: the API the CLI and boxes call.
- Engine: the runnable backend, its OpenAPI, and the adapter model.
- Packages: the
@withpotter/*engine package catalog and contract. - Plans & tiers: how tiers map to entitled packages.
- Storefront render: how one app serves every bank’s storefronts.