Magento Project Kickoff Playbook
The architecture document comes later. The irreversible decisions happen now.
The first week of a Magento implementation contains more irreversible decisions than the next six months combined. The choice of data model for a custom entity, whether to use EAV attributes or custom tables, how to approach the integration layer, which third-party modules to adopt — these decisions crystallize quickly and become expensive to undo.
Most teams treat week 1 as setup: installing Magento, creating the repo, adding developers to the project. That's the wrong frame. Week 1 is architecture week. The code that follows week 1 is shaped by the decisions made in it.
The patterns in this guide come from observing what goes right and wrong in the first weeks of dozens of Magento implementations — from small B2C builds to enterprise multi-country rollouts.
Some decisions should be made before the first line of code is written, because they determine what kind of project you're building. A Magento project without answers to these questions will answer them implicitly — through the first decisions developers make, which become de facto architecture.
Where does integration logic live? This is the most consequential week-1 decision. Integrations built inside Magento — as observers, cron jobs, or custom modules that hit external APIs directly — are faster to build in week 1 and more expensive to operate from year 2 onward. The correct pattern: Magento publishes events or exposes APIs; external services consume those events or call those APIs; integration logic lives in a dedicated service layer, not in Magento itself.
Event-driven or synchronous? Order-related integrations (ERP sync, OMS handoff) should be asynchronous with retry logic. Checkout-path integrations (shipping rates, tax calculation) are unavoidably synchronous, which means they need circuit breakers and timeouts. Decide before building.
Caching strategy. Define which data is cached at which layer before the first custom block is built. Magento's block cache, FPC, Varnish, Redis — these work correctly only when the team understands the invalidation model. A block that doesn't declare its cache depends correctly will cause FPC misses in production that are invisible in development.
Module architecture. Decide on naming conventions, module structure, and the rule for when to create a new module vs extend an existing one. Inconsistency here is cumulative — it's invisible in week 1 and painful in year 2.
Magento's EAV model is one of the most misunderstood aspects of the platform. EAV is appropriate for attributes that need to be configurable by merchants without developer involvement — color, size, custom product specifications. It is not appropriate for structured data with complex relationships, high query frequency, or bulk operations.
The week-1 data model decision: for each custom entity, decide explicitly whether it lives in EAV or in a flat custom table. The default answer is not EAV. Custom tables are faster, more maintainable, and easier to query. EAV is for attribute flexibility.
Common week-1 data model mistakes:
Process decisions made in week 1 are the ones that stick. The ones made in month 3 are the ones the team ignores.
Code review before any PR merges. Establish this in week 1, even when the team is small. The habit of having code reviewed before it reaches main is easy to build at the start and very hard to introduce after a team has been working without it.
Staging environment parity. Define from day 1 that staging must mirror production as closely as possible. Configuration differences between staging and production are the most common cause of "it worked in staging" bugs in production.
The definition of done. A feature is not done when the developer marks it done. Define explicitly: code review passed, deployed to staging, QA tested, performance impact assessed. Whatever your team's standard is, make it explicit in week 1.
Documentation standard. At minimum: every custom module has a README with its purpose, dependencies, and configuration. Every integration has a documented data flow. This costs one hour per module in week 1 and saves days per year afterward.
Not everything should be locked down in week 1. Some decisions require more information than you have at the start, and making them prematurely adds rigidity without adding value.
Don't finalize the full module list. You don't know enough about the business requirements yet. Start with the core data model and integration architecture; let the module list evolve.
Don't over-engineer the CI/CD pipeline. Start with a pipeline that ensures tests pass and deploys reliably. Add complexity — multi-environment gates, performance testing, automated security scanning — as the project's needs become clear.
Don't commit to a specific third-party module before evaluating alternatives. Third-party modules differ dramatically in code quality, upgrade compatibility, and maintenance activity. Evaluate two or three options for any significant module before committing.
These guides come from 22+ years and 50+ Magento projects. If your team is facing one of these challenges, I can help — through a focused platform audit, technical leadership engagement, or hands-on development.
Start a Conversation All Guides