G3N Retail Stack Story

Appearance

G3N Retail Stack Story ​

This is the contract-only, non-technical story of the G3N Retail Stack. It is written for business owners, product leaders, and partners who want to understand what the stack does, why the pieces exist, and how they fit together.

This story is intentionally independent and self-contained. It does not assume you will read other docs. It explains the full stack in plain language, including detailed use cases and how each feature behaves in practice. If you need exact request and response fields, use each service's contract pages and the shared conventions in /common/.

Everything here reflects what is verifiable in this repo. If a feature is not implemented, it is marked as business-only with implementation pending.

How to read this story ​

Start with the Service Map to understand the role of each service. Then read the Shared Rules and End-to-End Stories to see how a real organization moves through the stack. Finally, open each service page for exhaustive feature breakdowns, scenarios, constraints, and how the pieces are implemented.

Operational change readiness ​

If you own rollout, change control, or operational readiness, read /common/training-change-management.html. It defines the required training notes, staged rollout guidance, rollback expectations, and support runbooks that must accompany policy or workflow changes.

Service map (plain language) ​

The stack is a set of focused services that work together. Each one owns a specific part of the business story.

  • UAS is identity. It is where a person exists, how their email is verified, and how they prove who they are.
  • USM is trust. It creates the sessions that every other service trusts and issues long-lived API keys for integrations.
  • OFM is the tenant spine. It defines the organization, its members, its facilities, and the sales channels it operates in.
  • MRS is durable content storage. It holds large or flexible payloads that should not live inside transactional records.
  • PVM is product modeling. It manages suppliers, taxonomy, styles, variants, codes, and collaboration artifacts.
  • PMC is publishing. It takes a PVM snapshot and turns it into channel-specific, versioned products that can go live.
  • ICS is inventory control. It owns real-time stock, bin-level operations, and the stock card history.
  • SCM is sales cycle management. It owns sales orders, fulfillment, and returns that reference sales-channel carts.
  • PCM is procurement cycle management. It owns purchase workflows and creates new item data in PVM during onboarding.
  • PPM is pricing and promotions. It owns temporal pricing, promotions, and discount governance.
  • CRM & Loyalty owns customer accounts, loyalty ledgers, gift cards, and store credits.
  • Influencer/Affiliate owns attribution, earnings, and payout readiness.
  • Accounting/ERP Readiness owns exportable event views and traceability for finance systems.
  • IPM is the integration plane. It exposes event catalog, webhooks, CDC feeds, and bulk import/export for downstream systems.
  • RBS is the retail bus. It delivers owner-scoped event subscriptions to customer-managed SQS queues.
  • UTL is the utility service. It handles tenant offboarding (request, export window freeze, export, purge, archive).
  • UCP is the external commerce adapter. It implements the Universal Commerce Protocol standard so that external platforms (AI agents, apps, search engines) can transact with merchants through a single standardized API. It supports checkout, signed order webhooks, and OAuth 2.0 identity linking.
  • SLC is the Shopify legacy connector. It pushes product and stock data outbound to Shopify stores and receives order events inbound for inventory impact. It supports standard channels (full product lifecycle) and custom channels (variant-level updates only), with config-driven behavioral flags per channel.

System-of-record and data flow (plain language) ​

These boundaries keep the stack coherent and prevent “two systems trying to own the same truth.”

  • Sales channels own carts and checkout context; SCM owns the sales order, fulfillment, and return record. SCM references a cart or checkout context but is the system of record for the transaction.
  • Procurement channels own worksheets and sourcing inputs; PCM owns the purchase order, receipt, and invoice record. PCM references a worksheet but is the system of record for procurement.
  • PVM owns product truth; PMC owns channel sellability; PPM owns temporal price truth; ICS owns inventory positions and stock‑card history.
  • CRM & Loyalty owns customer identity and reward balances; Influencer owns attribution and earnings; Accounting owns export‑ready financial event views (derived from source records).

Sales flow (high level): channel cart → SCM order → PPM price resolution + PMC sellability → ICS reserve/allocate/commit → CRM loyalty impact → Accounting events.
Procurement flow (high level): channel worksheet → PCM PO → PVM NPI (when needed) → receipt/exception → ICS stock changes → Accounting events.

Every transaction preserves an as‑of snapshot of price, sellability, and inventory context to protect auditability and dispute resolution.

Shared rules and constraints ​

These rules show up in multiple services and explain why the stack behaves the way it does.

  • Closed onboarding: The stack does not support public sign-up. Accounts are created through internal onboarding and controlled workflows.
  • Strong trust boundary: All API calls require credentialed auth (session, API key, or email+passcode where applicable). Sessions and API keys are treated as secrets.
  • Org status gating: When an organization is not verified, tenant writes are blocked across services. Doomed is terminal.
  • Revisioned updates: Many records are revisioned and require explicit concurrency control. Updates provide the last known revision to prevent overwrites.
  • Immutable history in publishing: Publishing creates immutable revisions; history is preserved for audit and rollback.
  • Separation of concerns: Large payloads live in MRS; transactional records remain lean and auditable.
  • Predictable pagination: List endpoints return a default-sized page (default limit 8, clamped 1-256) and use a next_token cursor for pagination.
  • Consistent response envelope: Responses use a consistent envelope that includes success, data, error, and build metadata so clients can reason about outcomes and versions.
  • Training and change management: Policy and workflow changes require training notes, staged rollout, rollback guidance, and support runbooks. See /common/training-change-management.html.

End-to-end stories (in everyday terms) ​

Account onboarding and login. A person is created in UAS, their email is verified, and their passcode is set. When they sign in, USM creates a session. That session becomes the trust token used in every other service call.

Organization setup. OFM creates the organization, establishes owners and members, and builds the facility spine (physical, legal, logical). OFM also records the sales channels that the organization sells through and enforces rules about who can do what.

Product modeling. PVM captures the supplier landscape, the product taxonomy, and the detailed structure of styles and variants. It stores identifiers and barcodes for reliable lookup and supports comments and attachments for collaboration.

Publishing. PMC creates immutable product revisions for each sales channel. A publish action generates a new revision and marks it online. If upstream product data becomes ineligible, PMC takes it offline to keep what is live aligned with the source of truth.

Content storage. MRS stores larger files and flexible payloads that should not live inside transactional records, while still keeping the metadata searchable and auditable.

Cross-service narratives (detailed) ​

New merchant to first publish. A merchant is onboarded in UAS, signs in through USM, and their organization is created in OFM. Facilities are set up, roles are assigned, and a sales channel is declared. Product teams model styles and variants in PVM, then PMC publishes the eligible products to the new channel with a clear audit trail of what went live and why.

Security incident and recovery. A compromised account triggers a passcode reset in UAS, which revokes sessions in USM. The user signs in again with a new passcode. If needed, the org can be parked or suspended in OFM, which blocks tenant writes in PVM and PMC until governance is restored.

Seasonal refresh with large artifacts. A new season is modeled in PVM, including updated taxonomy and variant data. Large publish artifacts or manifests are stored in MRS and referenced by PMC. PMC publishes a new revision set for the season, keeping the prior season's revisions available for audit.

Integration onboarding. A partner system is granted a service-account API key from USM with a limited role set. That key can read or write to OFM or PVM only within the organization that issued it. If the integration is compromised, the key is revoked without impacting human users.

Compliance pause and resume. A regulator inquiry forces a temporary halt. OFM moves the org into a suspended or parked state, blocking tenant writes across services. The team reviews data in read-only mode, then restores verified status to resume normal operations.

Platform commerce via UCP. An external platform (AI shopping agent, marketplace app) registers with the merchant via UCP. The platform creates checkout sessions, adds line items, and completes orders — all through the standardized UCP protocol. The merchant receives signed webhooks for every order lifecycle event. If the merchant enables identity linking, the platform can associate its users with merchant customer records through an OAuth 2.0 flow, enabling personalized experiences.

Implemented vs planned (summary) ​

All modules listed in this story are implemented at a core level and are documented. Remaining work is incremental expansion within each module and the explicitly deferred items below which are out of scope until reactivated.

Planned: MCP operations servers — per-service MCP servers that execute data-plane API operations (create, read, update, status) in addition to the current documentation-discovery MCP server at mcp.g3nretailstack.com. The doc-only server exposes protocol docs, OpenAPI contracts, and doc pages; operations servers would allow AI agents to call service endpoints directly via MCP tools. Deferred until the documentation-discovery server is fully verified and the operational auth model is defined.

Go deeper by service ​

If you need exact API shapes, the service pages include links to their contract surfaces and examples. The shared envelope, pagination, and error conventions are documented in /common/.