Potter Box 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.
This site is being built out area by area. The Box CLI reference below is complete; control-plane API, storefront render, package API references, and the CI/plan gating model are coming next.
Start here
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 answers
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. |
| Tenant | A merchant within a box (resolved by slug subdomain or custom domain). |
| Entitlement | A package/capability a license tier grants to a box. |