V2Genome Structure

The V2Genome is the new genome format that defines your project using business-level concepts (packages and apps) rather than technical modules.

Overview

V2Genome has four main sections:

interface V2Genome {
  workspace: {
    name: string;
    description?: string;
  };
  
  marketplaces: Record<string, MarketplaceConfig>;
  
  packages: Record<string, PackageConfig>;
  
  apps: Record<string, AppConfig>;
}

Workspace

The workspace defines your project metadata:

workspace: {
  name: 'my-saas-app',        // Required: Project name
  description: 'My SaaS app'  // Optional: Project description
}

Purpose: Project-level metadata used throughout generation.

Marketplaces

marketplaces define which marketplaces to use and how to load them:

marketplaces: {
  saas: {
    type: 'npm',              // 'npm', 'git', or 'local'
    version: 'latest'         // Version, tag, or path
  }
}

Types:

• npm: Load from npm package (e.g., @thearchitech/marketplace-saas)
• git: Load from Git repository
• local: Load from local path

Purpose: Marketplaces provide recipe books that map packages to modules.

Packages

packages define business-level capabilities, not technical modules:

packages: {
  database: {
    // Optional: Package-specific config
  },
  auth: {},
  ui: {},
  payments: {
    // Package can have parameters
    parameters: {
      provider: 'stripe'
    }
  }
}

Key Points:

• Packages are business concepts (e.g., "auth", "payments")
• Marketplace recipe books map packages → technical modules
• Packages can have parameters (merged with module defaults)

Example: The payments package might map to capabilities/payments module, which uses Stripe or RevenueCat based on parameters.

Apps

apps define your applications:

apps: {
  web: {
    type: 'web',              // 'web', 'mobile', or 'api'
    framework: 'nextjs',      // Framework (nextjs, expo, hono)
    packages: ['ui', 'auth']  // Packages this app uses
  },
  mobile: {
    type: 'mobile',
    framework: 'expo',
    packages: ['ui', 'auth']
  },
  api: {
    type: 'api',
    framework: 'hono',
    packages: ['database', 'auth']
  }
}

App Types:

• web: Web applications (Next.js, Remix, etc.)
• mobile: Mobile applications (Expo, React Native)
• api: API servers (Hono, Express, etc.)

Frameworks:

• nextjs: Next.js for web
• expo: Expo for mobile
• hono: Hono for API

Packages: Apps declare which packages they use. The marketplace resolves these to modules.

How It Works

1. Package → Module Resolution

When you define:

packages: {
  auth: {}
}

The marketplace's recipe book maps it:

{
  "packages": {
    "auth": {
      "providers": {
        "default": {
          "modules": [
            { "id": "capabilities/auth", "targetPackage": "auth" }
          ]
        }
      }
    }
  }
}

Result: auth package → capabilities/auth module → packages/auth/ directory

2. App → Framework Resolution

When you define:

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

The marketplace resolves:

• nextjs framework → capabilities/nextjs module → apps/web/ directory
• ui package → capabilities/ui module → packages/ui/ directory

3. Dependency Resolution

The composition engine:

1. Expands packages into modules
2. Resolves module prerequisites
3. Builds dependency graph
4. Generates execution plan
5. Creates lock file

Example V2Genome

import { defineV2Genome } from '@thearchitech.xyz/types';
 
export default defineV2Genome({
  workspace: {
    name: 'ecommerce-saas',
    description: 'E-commerce SaaS platform'
  },
  
  marketplaces: {
    saas: {
      type: 'npm',
      version: 'latest'
    }
  },
  
  packages: {
    database: {},
    auth: {},
    ui: {},
    payments: {
      parameters: {
        provider: 'stripe'
      }
    },
    email: {}
  },
  
  apps: {
    web: {
      type: 'web',
      framework: 'nextjs',
      packages: ['ui', 'auth', 'payments']
    },
    api: {
      type: 'api',
      framework: 'hono',
      packages: ['database', 'auth', 'payments', 'email']
    }
  }
});

This creates:

• apps/web/ - Next.js app with UI, auth, payments
• apps/api/ - Hono API with database, auth, payments, email
• packages/database/ - Database package
• packages/auth/ - Auth package
• packages/ui/ - UI package
• packages/payments/ - Payments package (Stripe)
• packages/email/ - Email package

Benefits

1. Business-Level Thinking: Define capabilities, not technical modules
2. Marketplace Flexibility: Different marketplaces can map packages differently
3. Reusability: Packages can be shared across apps
4. Type Safety: defineV2Genome() provides TypeScript types

Related

• Monorepo-Only Architecture - Why V2 is monorepo-only
• Marketplace-CLI Relationship - How marketplaces transform genomes
• Execution Flow - How V2Genome is executed