building-with-medusa

This skill provides a structured guide for building backend systems using Medusa, focusing on enforcing a consistent and scalable architecture across all backend development tasks. It addresses common challenges in Medusa applications such as unclear separation of concerns, improper business logic placement, and unsafe or inconsistent data handling. By standardizing how modules, workflows, and API routes interact, it helps developers avoid architectural drift and ensures maintainable, production-ready systems.

The skill defines a strict layered architecture where modules handle data models and CRUD operations, workflows encapsulate business logic and mutations (including rollback behavior), API routes serve as HTTP interfaces with validation, and frontend applications interact via SDKs. It introduces important constraints such as using only GET, POST, and DELETE HTTP methods, requiring workflows for all mutations, and enforcing module isolation through module links. It also highlights correct data access patterns using query.graph() for cross-module queries and query.index() for filtered queries across linked modules, while emphasizing type safety through schema inference and request typing conventions.

This skill is intended for developers working on Medusa backend systems, including those building custom modules, workflows, API routes, authentication systems, or complex business logic. It is also relevant when integrating backend functionality with admin dashboards or storefront applications. Its primary goal is to ensure backend consistency, reduce architectural mistakes, and guide teams toward best practices in modular, scalable e-commerce backend development.