V2 Execution Flow

Understanding how V2 executes projects from V2Genome to generated code.

Overview

V2 execution follows a strict order:

V2Genome
  ↓
Marketplace Transformation (transformGenome)
  ↓
StandardizedGenome
  ↓
Path Mapping Generation
  ↓
Framework Bootstrap
  ↓
Module Execution
  ↓
Generated Project

Phase 1: Marketplace Transformation

What Happens:

1. CLI loads marketplaces from V2Genome
2. CLI calls marketplaceAdapter.transformGenome()
3. Marketplace expands packages → modules using recipe book
4. Marketplace resolves dependencies
5. Marketplace generates lock file
6. Marketplace returns StandardizedGenome

Key Components:

• CompositionEngine: Expands packages, resolves dependencies
• RecipeExpander: Maps packages to modules
• DependencyResolver: Resolves module prerequisites
• LockFileService: Generates lock file

Output: StandardizedGenome with:

• modules: Array of modules to execute
• metadata.executionPlan: Execution order
• metadata.moduleIndex: Module metadata

Phase 2: Path Mapping Generation

What Happens:

1. Load path keys from marketplaces
2. Generate path mappings for all path keys
3. Compute paths for apps/packages (even if not created yet)
4. Store paths in PathService

Key Components:

• PathMappingGenerator: Generates all path mappings
• PathService: Stores and resolves paths

Why First?

• Frameworks need paths during bootstrap
• Paths must be available before any file creation
• Prevents path resolution errors

Example:

// Path keys defined in path-keys.json
'apps.web.root' → 'apps/web/'
'apps.web.src' → 'apps/web/src/'
'packages.auth.root' → 'packages/auth/'
 
// Generated before framework bootstrap
paths['apps.web.root'] = 'apps/web/'
paths['apps.web.src'] = 'apps/web/src/'

Phase 3: Framework Bootstrap

What Happens:

1. Identify framework modules (via metadata)
2. For each app with a framework:
   • Create VFS with app directory as root
   • Execute framework blueprint
   • Run framework CLI (create-next-app, create-expo-app, etc.)
3. Framework modules execute only during bootstrap

Key Components:

• ProjectBootstrapService: Orchestrates framework bootstrap
• VirtualFileSystem: Manages file operations
• BlueprintExecutor: Executes framework blueprints

Path Resolution:

• VFS root = app directory (e.g., apps/web)
• Paths resolve relative to VFS root (./ not apps/web/)
• Prevents nested directories

Example:

// Framework: nextjs for web app
// VFS root: /project/apps/web
// Path resolution: paths.apps.web.root → './'
// Command: npx create-next-app@latest . (runs in apps/web)

Phase 4: Module Execution

What Happens:

1. Filter out framework modules (already executed)
2. Execute regular modules in dependency order
3. Each module:
   • Loads blueprint
   • Creates VFS (if needed)
   • Executes blueprint actions
   • Flushes VFS to disk

Key Components:

• OrchestratorAgent: Coordinates execution
• ModuleService: Loads modules and adapters
• BlueprintExecutor: Executes blueprints
• VirtualFileSystem: Manages file operations

Execution Order:

• Based on metadata.executionPlan
• Respects module prerequisites
• Framework modules filtered out

Detailed Flow

Step 1: Load V2Genome

const genome = await loadGenome('genome.ts');
// genome is V2Genome format

Step 2: Transform to StandardizedGenome

const standardizedGenome = await marketplaceAdapter.transformGenome(
  genome,
  options,
  context
);
// standardizedGenome is StandardizedGenome format

Step 3: Generate Path Mappings

const pathMappings = await PathMappingGenerator.generateMappings(
  standardizedGenome,
  marketplaceAdapters,
  recipeBooks
);
// All path keys now available

Step 4: Bootstrap Frameworks

const frameworkConfig = await projectBootstrapService.bootstrap(
  standardizedGenome,
  structureResult,
  marketplaceAdapters,
  recipeBooks
);
// Frameworks initialized (Next.js, Expo, Hono)

Step 5: Execute Modules

const regularModules = standardizedGenome.modules.filter(
  mod => !isFrameworkModule(mod, standardizedGenome)
);
 
for (const module of regularModules) {
  await orchestrator.executeModule(module, standardizedGenome);
}
// All modules executed

Execution Context

Framework Bootstrap Context

{
  projectRoot: '/project/apps/web',  // VFS root = app directory
  paths: {
    'apps.web.root': './',           // Relative to VFS root
    'apps.web.src': './src/'
  },
  targetApp: 'web'
}

Module Execution Context

{
  projectRoot: '/project',            // VFS root = project root
  paths: {
    'apps.web.root': 'apps/web/',     // Absolute from project root
    'packages.auth.root': 'packages/auth/'
  },
  targetPackage: 'auth'               // For package modules
}

Key Differences from V1

Troubleshooting

Framework not bootstrapping

Check:

• Framework module detected? (metadata.type === 'framework')
• VFS root correct? (should be app directory)
• Paths available? (generated before bootstrap)

Modules executing in wrong order

Check:

• Execution plan correct? (from lock file)
• Prerequisites resolved? (dependency graph)
• Framework modules filtered? (should not execute twice)

Path resolution errors

Check:

• Path keys loaded? (from marketplace)
• Paths generated? (before bootstrap)
• Path resolution correct? (relative vs absolute)

Related

• Framework Bootstrap - Detailed bootstrap process
• V2Genome Structure - V2Genome format
• Marketplace-CLI Relationship - How transformation works