Box by Potter: platform documentation
A Box is a self-hostable instance of the Potter commerce platform that a
vendor (typically a bank) runs for its own merchants. Each box bundles an
engine (the backend API) and a console (the admin dashboard), entitled
and composed from @withpotter/* packages according to the box’s license tier.
A central control plane issues licenses, serves the package registry, and owns host → backend routing so a single shared storefront render can serve every bank’s merchant storefronts.
New here? Read the Architecture overview for how the control plane, gated registry, engine, console, and storefront render fit together, then dive into any area below.
Start here
Architecture overviewControl-plane API referenceEngine & OpenAPIPackage catalogPlans & tiersStorefront renderMerchant dashboardBox Retail RailsBox CLIQuickstart: create & run a box
How the pieces fit together
- The CLI authenticates a box’s license against the control plane, installs the entitled engine packages, runs the stack locally, and registers the box’s public domains with the control plane’s storefront resolver.
- The control plane is the planned source of host → backend routing
(
GET /boxes/resolve?host=…) so the shared render knows which bank backend owns a given storefront host. - The storefront render serves every bank’s merchant storefronts and is embedded as a Live Preview inside each bank’s console.
Glossary
| Term | Meaning |
|---|---|
| Box | A vendor’s self-hosted instance: engine + console. |
| Engine | The backend API, composed from entitled @withpotter/* packages. |
| Console | The admin dashboard the vendor’s staff and merchants use. |
| Control plane | Central API that issues licenses, serves the registry, and owns host routing. |
| Storefront render | Shared Next.js app that serves all banks’ public storefronts. |
| Merchant dashboard | Intent-driven Next.js admin app each merchant uses to run their box. |
| Box Retail Rails | In-person selling rails: device-linked client SDKs (Android box-arr) + the box’s RR engine for face-to-face sales. |
| ARR (Android Retail Rails) | The Android implementation of the Box Retail Rails: the box-arr SDK (modules arr-core, arr-session, arr-catalog, arr-order, arr-payment, arr-crypto) that embeds in a host’s own Android app. |
| Tenant | A merchant within a box (resolved by slug subdomain or custom domain). |
| Entitlement | A package/capability a license tier grants to a box. |