/migrate-architecture - Architecture Pattern Migration

Migrate a project's architecture from one pattern to another while preserving all functionality.

Arguments: $ARGUMENTS (e.g., "flat to modular full project", "mvc to clean lite src/modules/auth")

Supported Architecture Patterns

Frontend

Backend / Fullstack

Variants

Workflow

Phase 1: Assessment

1. Read docs/ARCHITECTURE.md if it exists
2. Scan the project structure:
   • List all directories under src/ (or root if no src/)
   • Identify current architecture pattern by matching directory names
   • Count modules/features/components
   • Check for barrel exports (index.ts)
   • Check import patterns between directories
3. Identify the current architecture pattern and confidence level
4. Report findings:

── Architecture Assessment ──
Current: [detected pattern] (confidence: high/medium/low)
Target: [requested pattern] ([variant])
Scope: [project | specific module/path]
Estimated files to move: X
Estimated files to create: X
Risk: low/medium/high

5. Ask for confirmation before proceeding

Phase 2: Planning

1. Generate the target directory structure based on:
   • Target architecture pattern
   • Detected framework (React, Vue, Next.js, etc.)
   • Chosen variant (Full or Lite)
2. Map existing files to their new locations:
   • Components → appropriate layer/module
   • Services → service layer or domain layer
   • Types → types layer
   • Tests → co-located tests/
   • Utils/Helpers → shared/
3. Identify new files to create:
   • Barrel exports (index.ts) per module
   • Adapter layer (if Full variant)
   • Type separation (.types.ts + .contracts.ts for Full)
4. Create migration plan with ordered steps:
   • Phase 2a: Create target directory structure
   • Phase 2b: Move files (least coupled first)
   • Phase 2c: Create new files (barrel exports, adapters)
   • Phase 2d: Update imports
   • Phase 2e: Validate

Phase 3: Execution

Execute the migration plan step by step:

1. Create target directory structure (mkdir -p)
2. Move files one module at a time:
   • Start with the LEAST coupled module
   • Move component files
   • Move service files
   • Move type files
   • Move test files
3. Create new architectural files:
   • Barrel exports (index.ts) for each module
   • Adapter files (if migrating to Modular Full, Clean, or Hexagonal)
   • Type separation files (.types.ts + .contracts.ts)
4. Update all import paths:
   • Use Grep to find all imports referencing moved files
   • Update each import to the new path
   • Use barrel exports where possible
5. Generate or update docs/ARCHITECTURE.md for the target pattern

Phase 4: Validation

1. Check directory structure matches target pattern
2. Verify no broken imports:

   npx tsc --noEmit 2>&1 | head -50

3. Validate import rules:
   • Modules don't import from each other (Modular)
   • Dependencies point inward (Clean/Hexagonal)
   • FSD layers import top-down only
4. Run tests if they exist:

   npm test 2>&1 | tail -20

5. Report results:

── Architecture Migration Complete ──
From: [source pattern]
To: [target pattern] ([variant])

Files moved: X
Files created: X
Imports updated: X
Barrel exports created: X

Validation:
  TypeScript: ✓ compiles
  Import rules: ✓ no violations
  Tests: ✓ passing (or N/A)

docs/ARCHITECTURE.md: ✓ generated

Migration Strategies by Pattern

Flat → Modular

1. Group components by domain/feature
2. Create modules/[feature]/components/ for each group
3. Move related services, types into module
4. Create index.ts for each module
5. Move shared components to shared/components/

MVC → Modular

1. For each controller+service pair, create a module
2. Move controller logic to module's hooks/composables
3. Move models to module's types/
4. Create service layer in each module
5. Move shared middleware to shared/

MVC → Clean Architecture

1. Extract domain entities (pure business objects, no framework deps)
2. Create use-case classes for each business operation
3. Define port interfaces for external dependencies
4. Move database/HTTP code to infrastructure/ as adapter implementations
5. Wire use cases to ports in the composition root

Modular → Clean Architecture

1. For each module, add domain/ and application/ sub-layers
2. Extract entities from services into domain/entities/
3. Create use-cases from service methods
4. Define port interfaces for external deps
5. Move HTTP/DB code to infrastructure/

Modular → Hexagonal

1. Create core/ with domain/ and ports/
2. Extract entities to core/domain/
3. Define driving ports (use case interfaces) in core/ports/in/
4. Define driven ports (repository interfaces) in core/ports/out/
5. Move components to adapters/in/web/
6. Move HTTP/DB to adapters/out/

Modular → Feature-Sliced Design

1. Map modules to FSD layers:
   • Shared components → shared/ui/
   • Feature-specific → features/[feature]/
   • Business entities → entities/[entity]/
   • Page compositions → pages/
2. Enforce top-down import rules
3. Split cross-cutting features into widgets/

Modular → DDD

1. Identify bounded contexts from modules
2. Add aggregates/ with aggregate roots
3. Extract value objects from entity properties
4. Create domain events for state changes
5. Add command/query handlers in application layer

Any → Modular Monolith

1. Start with Modular structure
2. Add domain/application/infrastructure layers per module
3. Enforce module boundaries with barrel exports
4. Validate no cross-module internal imports
5. Each module = potential future microservice

Anti-Patterns to Avoid

Rules

1. ALWAYS assess before migrating - understand current state first
2. NEVER migrate without user confirmation
3. ONE module at a time - never parallel moves
4. VALIDATE after each module migration (TypeScript + imports)
5. PRESERVE all existing tests (move them, don't delete)
6. CREATE docs/ARCHITECTURE.md for the target pattern
7. USE the appropriate variant (Full for established teams, Lite for small teams)
8. If TypeScript errors appear, FIX them before continuing