🎉 The Architech v1.0 is now available. Read more →
v2
CLI Documentation
Architecture
V2Genome Handler

V2Genome Handler

The V2Genome Handler converts V2Genome to StandardizedGenome format, preserving V2 structure for blueprint access.

Overview

The V2Genome Handler:

  1. Uses Composition Engine to resolve V2Genome → LockFile
  2. Converts LockFile → StandardizedGenome
  3. Preserves V2 structure (packages, apps, marketplaces) for blueprints

Architecture

V2Genome
  ↓
V2GenomeHandler.resolveGenome()
  ↓
CompositionEngine.resolve()
  ↓
LockFile
  ↓
V2GenomeHandler.convertLockFileToResolvedGenome()
  ↓
StandardizedGenome (with V2 structure preserved)

Key Methods

resolveGenome()

Resolves V2Genome to LockFile:

async resolveGenome(
  genome: V2Genome,
  projectRoot?: string,
  forceRegenerate: boolean = false
): Promise<LockFile>

Process:

  1. Check for existing lock file (if projectRoot provided)
  2. Validate lock file (genome hash, marketplace versions)
  3. If valid and not forced, return existing lock file
  4. Otherwise, use Composition Engine to resolve
  5. Generate new lock file

convertLockFileToResolvedGenome()

Converts LockFile to StandardizedGenome:

async convertLockFileToResolvedGenome(
  lockFile: LockFile,
  originalGenome: V2Genome,
  genomeFilePath?: string
): Promise<StandardizedGenome>

Process:

  1. Extract modules from lock file
  2. Build module index (metadata lookup)
  3. Filter framework modules from execution plan
  4. Create StandardizedGenome with:
    • project: From V2Genome workspace
    • modules: From lock file
    • metadata: Execution plan, module index
    • packages: Preserved from V2Genome (for blueprints)
    • apps: Preserved from V2Genome (for blueprints)
    • marketplaces: Preserved from V2Genome (for blueprints)

Framework Module Filtering

Framework modules are filtered from execution plan:

const filteredExecutionPlan = lockFile.executionPlan.filter(moduleId => {
  const moduleMetadata = moduleIndex[moduleId];
  const isFramework = 
    moduleMetadata?.category === 'framework' ||
    moduleMetadata?.category === 'foundation' ||
    (moduleMetadata?.type && String(moduleMetadata.type).toLowerCase() === 'framework');
  
  return !isFramework;
});

Why?

  • Framework modules execute during bootstrap
  • They should not execute again in regular module execution
  • Execution plan is for regular modules only

StandardizedGenome Structure

interface StandardizedGenome {
  // CLI execution structure
  project: {
    name: string;
    structure: 'monorepo';
    monorepo: MonorepoConfig;
  };
  
  modules: Module[];  // All modules (framework + regular)
  
  metadata: {
    executionPlan: string[];  // Filtered (no framework modules)
    moduleIndex: ModuleIndex;
    // ...
  };
  
  // V2 structure preserved (for blueprints)
  packages?: Record<string, PackageConfig>;
  apps?: Record<string, AppConfig>;
  marketplaces?: Record<string, MarketplaceConfig>;
}

Key Points:

  • modules: All modules (for bootstrap lookup)
  • metadata.executionPlan: Regular modules only (for execution)
  • packages/apps/marketplaces: Preserved for blueprint dependency checks

Example

Input V2Genome

{
  workspace: { name: 'my-app' },
  packages: { auth: {} },
  apps: { web: { framework: 'nextjs' } }
}

Lock File

{
  "executionPlan": ["capabilities/nextjs", "capabilities/auth"],
  "modules": [
    { "id": "capabilities/nextjs", ... },
    { "id": "capabilities/auth", ... }
  ]
}

Output StandardizedGenome

{
  project: { name: 'my-app', structure: 'monorepo', ... },
  modules: [
    { id: 'capabilities/nextjs', ... },
    { id: 'capabilities/auth', ... }
  ],
  metadata: {
    executionPlan: ['capabilities/auth'],  // Framework filtered out
    moduleIndex: { ... }
  },
  packages: { auth: {} },  // Preserved from V2Genome
  apps: { web: { framework: 'nextjs' } },  // Preserved from V2Genome
  marketplaces: { saas: { ... } }  // Preserved from V2Genome
}

Why Preserve V2 Structure?

Blueprints need to check dependencies at package/app level:

// Blueprint can check
if (context.templateContext.genome?.packages?.auth) {
  // Auth package exists
}
 
if (context.templateContext.genome?.apps?.web) {
  // Web app exists
}

Benefits:

  • Blueprints can check business-level dependencies
  • Not just technical module dependencies
  • More intuitive for blueprint authors

Related

Composition EngineRecipe Book Resolver