Getting Started with V2

This guide will help you create your first V2 project using The Architech.

Prerequisites

Node.js 18+ installed
npm, yarn, or pnpm installed
Basic understanding of TypeScript

Installation

npm install -g @thearchitech.xyz/cli

Or use npx:

npx @thearchitech.xyz/cli new genome.ts

Creating a V2Genome

V2 uses a new genome format called V2Genome. Create a genome.ts file:

import { defineV2Genome } from '@thearchitech.xyz/types';
 
export default defineV2Genome({
  workspace: {
    name: 'my-saas-app',
    description: 'My SaaS application'
  },
  
  marketplaces: {
    saas: {
      type: 'npm',
      version: 'latest'
    }
  },
  
  packages: {
    database: {},
    auth: {},
    ui: {},
    payments: {}
  },
  
  apps: {
    web: {
      type: 'web',
      framework: 'nextjs',
      packages: ['ui', 'auth', 'payments']
    },
    api: {
      type: 'api',
      framework: 'hono',
      packages: ['database', 'auth', 'payments']
    }
  }
});

Understanding V2Genome Structure

Workspace

The workspace defines your project:

workspace: {
  name: 'my-saas-app',        // Project name
  description: '...'          // Optional description
}

Marketplaces

marketplaces define which marketplaces to use:

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

Packages

packages define business-level capabilities:

packages: {
  database: {},              // Database package
  auth: {},                  // Authentication package
  ui: {},                    // UI components package
  payments: {}               // Payments package
}

Packages are business-level concepts. The marketplace's recipe book maps them to technical modules.

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
  }
}

Generating Your Project

Run the CLI with your genome:

architech new genome.ts

The CLI will:

Load marketplaces and recipe books
Expand packages into modules
Resolve dependencies
Generate lock file
Bootstrap frameworks (Next.js, Expo, Hono)
Execute modules
Install dependencies

Project Structure

V2 always creates a monorepo structure:

my-saas-app/
├── apps/
│   ├── web/          # Next.js app
│   ├── api/          # Hono API
│   └── mobile/       # Expo app (if mobile app defined)
├── packages/
│   ├── database/     # Database package
│   ├── auth/         # Auth package
│   ├── ui/           # UI package
│   └── payments/     # Payments package
├── package.json      # Root package.json with workspaces
└── genome.lock       # Lock file (generated)

Next Steps

V2Genome Structure - Deep dive into V2Genome
Monorepo-Only Architecture - Why monorepo-only?
Marketplace-CLI Relationship - How marketplaces work
CLI Architecture - How the CLI works

Having issues? Check the Troubleshooting Guide or Migration Guide if upgrading from V1.

V2 Overview Overview