Medusa
What is HardGraph? HardGraph publishes curated, provenance-backed agent skills grounded in reproducible vendor documentation.
Medusa is a commerce framework, not a hosted platform configured through a dashboard. Installing it gives you a Node.js application with commerce logic already implemented, and the expectation that non-trivial requirements get met by writing code against that application rather than working around a fixed feature set.
Modules are the unit of business logic
Cart totals, inventory, fulfillment, payments, and pricing each live in their own commerce module — a self-contained package with its own data models and service, isolated from the others by design. A module cannot reach into another module's tables directly; cross-module reads go through links, an explicit relationship declared between two modules' data models.
This isolation is why "just add a column to the order table" is the wrong instinct in Medusa. New business data usually belongs in a new or existing module, connected to core models via a link, not injected into a core table.
Workflows carry the durability guarantee
A workflow is a sequence of steps, each with its own compensation (rollback) function. The engine tracks progress per execution and resumes from the failed step rather than restarting — this is what makes "place an order that touches four modules" safe to write as one function instead of hand-rolled saga logic. Logic that spans more than one module, or must not leave the system half-updated on failure, belongs in a workflow, not a plain async function.
Where custom logic actually goes
Picking the wrong extension point is the most common source of wasted rework: a custom module when the business needs new data models with their own lifecycle (a loyalty-points ledger, a custom subscription model); a workflow when existing modules already model the data but the process touching them is new or must be resumable; a plugin when the goal is packaging integrations or modules for reuse across projects, not modeling this project's own domain.
Admin API vs Store API
The Admin API is for authenticated back-office operations — merchants and internal tooling managing orders, products, and configuration. The Store API is the public-facing surface a storefront calls on behalf of a customer, scoped to publishable API keys and sales channels. Calling the Admin API from storefront code is the usual sign a project reached for the wrong one.
Self-hosting vs Medusa Cloud
Self-hosting is the default throughout the docs and requires running the application, Postgres, and Redis yourself. Medusa Cloud removes that operational surface but is a separate product decision, not a deployment flag — weigh it against your own infra requirements rather than treating it as "production mode" for self-hosting.
What to verify rather than recall
Module and workflow API names, the v1-to-v2 migration surface, exact Admin
and Store API endpoint paths, and CLI flags move quickly between releases.
Confirm these against the mirrored corpus under references/vendor/ rather
than asserting a remembered signature.