Migration Guide: V1 → V2

This guide helps you migrate from V1 to V2.

Overview

V2 introduces significant changes:

Monorepo-only: No single-app projects
V2Genome format: New genome structure
Marketplace transformation: Marketplaces transform genomes
Framework bootstrap: Frameworks initialize first

Migration Checklist

Convert genome to V2Genome format
Restructure project to monorepo
Update marketplace adapters (if custom)
Test framework bootstrap
Verify module execution

Step 1: Convert Genome

V1 Genome

// V1 format
export default {
  project: {
    name: 'my-app',
    structure: 'single-app'
  },
  modules: [
    { id: 'capabilities/nextjs' },
    { id: 'capabilities/auth' }
  ]
};

V2Genome

// V2 format
import { defineV2Genome } from '@thearchitech.xyz/types';
 
export default defineV2Genome({
  workspace: {
    name: 'my-app'
  },
  marketplaces: {
    saas: {
      type: 'npm',
      version: 'latest'
    }
  },
  packages: {
    auth: {}
  },
  apps: {
    web: {
      type: 'web',
      framework: 'nextjs',
      packages: ['auth']
    }
  }
});

Key Changes:

project → workspace
modules → packages + apps
Business-level packages instead of technical modules

Step 2: Restructure to Monorepo

Before (V1 Single-App)

my-app/
├── src/
├── package.json
└── ...

After (V2 Monorepo)

my-app/
├── apps/
│   └── web/          # Your app
│       ├── src/
│       └── package.json
├── packages/         # Empty (no packages)
└── package.json      # Root with workspaces

Migration Steps

Create monorepo structure:
```
mkdir -p apps/web packages
```

Move app to apps/web:

mv src apps/web/
mv package.json apps/web/

Create root package.json:

{
  "name": "my-app",
  "private": true,
  "workspaces": [
    "apps/*",
    "packages/*"
  ]
}

Update V2Genome:

apps: {
  web: {
    type: 'web',
    framework: 'nextjs',
    packages: []
  }
}

Step 3: Update Marketplace Adapters

If you have custom marketplace adapters, update them:

V1 Adapter

async transformGenome(genome: Genome) {
  // V1 transformation
  return standardizedGenome;
}

V2 Adapter

async transformGenome(genome: V2Genome, options, context) {
  // Use V2GenomeHandler
  const handler = new context.V2GenomeHandler(
    context.marketplaceAdapters,
    context.logger,
    context.projectRoot
  );
  
  const lockFile = await handler.resolveGenome(genome, context.projectRoot);
  return handler.convertLockFileToResolvedGenome(lockFile, genome);
}

Required Changes:

Support V2Genome format
Use V2GenomeHandler from context
Use CompositionEngine for resolution

Step 4: Test Framework Bootstrap

Verify frameworks bootstrap correctly:

architech new genome.ts

Check:

Framework CLI runs (create-next-app, create-expo-app)
App directory created correctly
No nested directories (apps/web/apps/web/)

Step 5: Verify Module Execution

Verify modules execute correctly:

Check:

Modules execute in correct order
Paths resolve correctly
Files created in right locations

Common Issues

Issue: Nested Directories

Symptom: apps/web/apps/web/ created

Solution: Ensure path resolution uses ./ during bootstrap:

// During bootstrap
if (vfsRoot === appDirectory) {
  paths['apps.web.root'] = './';
}

Issue: Framework Modules Execute Twice

Symptom: Framework setup runs during bootstrap AND regular execution

Solution: Filter framework modules from execution plan:

const regularModules = modules.filter(
  mod => !isFrameworkModule(mod, genome)
);

Issue: Path Resolution Errors

Symptom: Path key 'apps.web.root' not found

Solution: Generate paths before framework bootstrap:

// Generate paths first
const paths = await PathMappingGenerator.generateMappings(...);
 
// Then bootstrap
await projectBootstrapService.bootstrap(...);

Benefits of V2

Workspace Dependencies: Use workspace:* protocol
Shared Code: Packages shared across apps
Better Structure: Consistent monorepo structure
Marketplace Flexibility: Different marketplaces can have different structures

Need Help?

Troubleshooting Guide
V2 Concepts - Understand V2 architecture
Getting Started - Create new V2 project

Ready to migrate? Start with Step 1: Convert Genome.

Manifest