The 3-in-1 Commerce Package — architecture

Instruction (Young): "Package 3 products into single package as sell services."My lane: design and architecture. Mira: business plan. Min + Tam: package deep dive.

What is being packaged (from the verified studies)

The product claim, kept honest: "e-commerce website + POS + AI staff" — the AI-staff tier is what Medusa Cloud does not bundle. That is the only differentiator, so it is the tier the architecture must protect.

The design principle that carries the package

One backend, three frontdoors. The three products are not three systems to run — they are three surfaces on one Medusa tenant. The storefront, the POS and the agent all address the same Postgres via the same API surfaces. Nothing in the package duplicates state.

Why this matters commercially: support cost is the hidden price of a 3-product bundle. Three sync paths is the failure mode; three frontdoors on one backend is the sellable claim.

Architecture

                    ┌──────────────────────────────┐
   storefront  ───▶ │  Store API  (publishable key, │
   POS (Agilo) ───▶ │  read-scope, tenant-scoped)  │  ◀── EVE tools hit this too
                    └──────────────┬───────────────┘
                                   │
                    ┌──────────────▼───────────────┐
                    │  Medusa server + worker      │
                    │  Postgres · Redis            │
                    └──────────────┬───────────────┘
                                   │
                    ┌──────────────▼───────────────┐
                    │  Admin API (scoped app token)│
                    │  ← only HIL-approved writes  │
                    └──────────────────────────────┘

   EVE agent (per tenant, self-hosted Nitro)
   ├── instructions.md   tenant-tuned persona
   ├── tools/            Store API wrappers (products, carts, checkout, order-status)
   ├── connections/medusa.ts   zod config, secrets from env — never in source
   ├── skills/           refund-playbook · checkout-flow · gift-card (load-on-demand)
   └── workflows         order-status watcher · HIL gates (refund, bulk-pricing)

The trust layer, stated as architecture not as a caution: the publishable key can only read. Every write path in the package terminates at the Admin API, and the Admin API is reachable only through a durable workflow gated by human approval. This is what makes an AI-staff tier sellable at all — a tenant will not adopt it if "AI" and "Admin" sit in the same blast radius.

Package tiers (the sellable shape)

The POS is the keystone: it is why one backend is non-negotiable. A POS writing to a separate stock store needs a sync layer, and a sync layer is the defect class this project exists to remove.

Security layer in the package (Echo, 2026-10-18)

The trust layer above governs what the AI may write. This section adds what governs humans — and it changes one sellable claim.

The package carries three identity layers, all A$0 software:

Full evidence: [2fa-and-account-management](2fa-and-account-management) · [authelia-optimization](authelia-optimization).

🔴 The package cannot promise staff roles

The tiers table above sells "Storefront + POS + AI staff" to a retailer — who will very likely have staff. Role separation (admin / staff / read-only) is a paid Medusa Enterprise feature, not MIT core. Medusa's ENTERPRISE-LICENSE.md is explicit that RBAC and SSO are Enterprise Edition, and that the RBAC module, its admin APIs, and its dashboard routes are proprietary.

So the honest package position:

• Pilot (1–3 people): every admin user is a full admin. Ship it.
• Any tenant with staff who must not see margin or pricing: RBAC becomes a licence line item, not build labour.

This is a pricing fact for Mira, not an engineering gap — the build is unavailable at any effort, because the code is not ours to ship.

The second guard the architecture did not have

The trust layer's claim — "every write terminates at the Admin API behind a human-approval workflow" — gains a real enforcement seam it lacked: Medusa's requireMfa: { maxAgeSeconds: N } requires a recent MFA challenge for elevated actions. A refund or a bulk-pricing change approved hours ago in a stolen session does not satisfy it.

F7 in the feature spec should therefore be strengthened: the HIL gate is proven armed and the elevated-write path requires a fresh MFA challenge. Two independent controls on the same boundary — which is what makes the AI-staff tier defensible to a tenant.

One integration rule

Do not put a tenant's Medusa Admin behind Authelia. Both layers work, but stacking them prompts the tenant admin twice. Authelia protects surfaces with no application login (static KB); Medusa MFA protects Medusa identities. Keep them disjoint — the admin vhost gets Medusa's MFA only.

Tenant isolation

Per-tenant Docker compose: server + worker + Postgres + Redis + storefront + EVE agent, entirely separate per tenant. No shared database, no shared credential. Postgres is the state of record; a tenant's data never crosses a process boundary another tenant can reach.

Sizing (carried from the co-hosting study)

One Oracle ARM node, 2–3 tenants as the pilot. Rough per-tenant footprint: Medusa server + worker (~1 GB), Postgres + Redis (~0.5 GB), storefront (~0.5 GB), EVE agent (~0.5–1 GB co-hosting scale). Per-tenant budget ≈ 3 GB — so a 24 GB ARM node pilots eight tenants, not two. I will confirm the real node spec before that number is quoted anywhere commercial; a budget measured off a study rather than the host is the stale-measurement defect.

Build sequencing (Ace's lane, off this note)

1. Tenant template: Medusa prod compose + shared image pipeline.
2. EVE agent template: eve init, medusa.ts connection, 4 starter tools, 2 skills, HIL workflow skeleton, version-pinned @workflow/*.
3. Demo tenant, gated on both /health and /eve/v1/health — a green storefront with a dead agent reads as healthy, which is the dark-fleet pattern.
4. POS against the same backend.
5. Tenant provisioning script: compose → seed → keys → agent config.

Risk register