---
name: ecommerce-store-evolution
description: 'Extend or refactor an existing ecommerce project with FastAPI, React, Next.js, admin panel, catalog changes, AGENTS.md updates, and safer rollout planning.'
argument-hint: 'Describe the current project and the features or refactor you need'
---
# Ecommerce Store Evolution

## When to use
- Extending an existing online store.
- Adding a new admin module, catalog flow, account area, or backend capability.
- Refactoring a commerce codebase without losing its current conventions.

## Procedure
1. Audit the existing repo and compare it with [extension checklist](./assets/extension-checklist.md).
2. Create or update AGENTS.md if the repo lacks clear delivery rules.
3. Before serious backend or frontend edits, create a timestamped snapshot under .backup/ and never modify or delete older backup entries.
4. Preserve stable patterns and change only what is necessary.
5. Write a small implementation plan using [rollout plan template](./assets/rollout-plan-template.md).
6. Implement backend and frontend changes with regression awareness.

## Architecture rule
- New backend code should go into the proper layers such as routers, models, schemas, services, repositories, config, and tests.
- New frontend code should go into the proper layers such as app or routes, pages, features, entities, shared components, api or services, hooks, config, styles, and tests.
- If the current project is too flat or mixed, improve the structure incrementally instead of adding more chaos.

## References
- [extension checklist](./assets/extension-checklist.md)
- [rollout plan template](./assets/rollout-plan-template.md)