The Architech CLI

The Generic Code Generation Engine

The Architech CLI is the core execution engine — a sophisticated, unopinionated platform that transforms TypeScript genome files into fully-functional projects.

What is the CLI?

The CLI is not a React tool, or a Next.js generator, or a database scaffolder. It's a generic code generation engine that can create any type of project based on blueprints provided by a marketplace.

Core Purpose

User writes: TypeScript Genome
     ↓
CLI executes: Blueprint Actions
     ↓
Result: Generated Project

The CLI doesn't care what you're building. It only cares about how to safely execute the instructions from marketplace blueprints.

CLI vs Marketplace: The Critical Separation

The CLI Provides:

• 🔧 Blueprint execution engine
• 🔧 Virtual File System (VFS)
• 🔧 AST-based file manipulation
• 🔧 Dependency resolution
• 🔧 Type-safe genome system
• 🔧 Error handling & rollback

The Marketplace Provides:

• 🎯 Module blueprints (what to generate)
• 🎯 Technology choices (React, Vue, etc.)
• 🎯 Architectural patterns (TanStack Query, etc.)
• 🎯 Templates and code snippets

The separation means: Same CLI can power a React marketplace, Vue marketplace, Angular marketplace, or your company's internal marketplace.

Key Features

1. TypeScript Genome System

Define projects with full IDE support:

import { defineGenome } from '@thearchitech.xyz/types';
 
export default defineGenome({
  project: {
    name: 'my-app',
    framework: 'nextjs',
    path: './my-app'
  },
  modules: [
    {
      id: 'framework/nextjs',
      parameters: {
        typescript: true,  // ← Full autocomplete
        tailwind: true     // ← Type-safe
      }
    }
  ]
});

2. Virtual File System (VFS)

Safe, atomic file operations:

• All changes in memory until commit
• Per-blueprint isolation
• Rollback on errors
• Pre-population for efficiency

3. AST-Based Manipulation

Reliable code modification via ts-morph:

• Add imports without breaking code
• Merge TypeScript files intelligently
• Wrap JSX components
• Handle complex syntax

4. Dynamic Blueprints

Blueprints as functions for conditional generation:

export default function(config: MergedConfiguration): BlueprintAction[] {
  const actions = [...coreActions];
  
  if (config.features.mfa) {
    actions.push(...mfaActions);
  }
  
  return actions;
}

5. Intelligent Dependency Resolution

Automatic module ordering via topological sort:

• Adapters before connectors
• Prerequisites validated
• Conflicts detected

6. Semantic Actions

High-level operations that hide complexity:

• CREATE_FILE - Create files
• ENHANCE_FILE - Modify with AST
• INSTALL_PACKAGES - Manage dependencies
• Not low-level file operations!

Architecture Overview

The 7-Layer Execution Stack

Layer 1: CLI Command Layer
   ↓ (validates & loads genome)
Layer 2: Orchestrator Layer
   ↓ (resolves dependencies, creates VFS)
Layer 3: Blueprint Preprocessor
   ↓ (dynamic → static actions)
Layer 4: Blueprint Executor
   ↓ (analyzes, pre-populates VFS, expands forEach)
Layer 5: Action Handlers
   ↓ (routes actions)
Layer 6: Modifiers (AST)
   ↓ (complex file operations)
Layer 7: Virtual File System
   ↓ (atomic flush to disk)

Each layer has a specific responsibility and interacts cleanly with adjacent layers.

Documentation Sections

Explore the CLI in depth:

Architecture →

Deep dive into the 7-layer system, execution flow, and core components.

Blueprint Actions →

Complete reference for semantic actions and the modifier system.

Design Decisions →

Why we made specific architectural choices and their trade-offs.

Limitations & Future →

Honest assessment of current limitations and proposed upgrades.

Reference →

Complete CLI API reference, commands, and configuration.

Who Should Read This?

If You Want To:

• Understand how The Architech works internally → Start with Architecture
• Create marketplace modules → Read Blueprint Actions
• Contribute to CLI development → Review Design Decisions
• Evaluate The Architech → Check Limitations & Future
• Use CLI commands → See Reference

Core Principles

The CLI is built on three foundational principles:

1. Simplicity for the Creator

Complexity must be in the CLI, never in the blueprint. Blueprint authors use semantic actions, not low-level operations.

2. Security by Default

Never corrupt a user's project. Every operation must be safe, atomic, and reversible.

3. Open Extensibility

Architecture must encourage and facilitate community contribution through clear abstractions.

What Makes This CLI Different

Traditional Code Generators:

• ❌ Template-based (string replacement)
• ❌ Fragile (regex breaks on edge cases)
• ❌ Opinionated (tied to specific tech)
• ❌ Risky (direct file writes)
• ❌ Limited (can't modify existing files)

The Architech CLI:

• ✅ AST-based (reliable modifications)
• ✅ Safe (VFS with atomic operations)
• ✅ Unopinionated (marketplace provides opinions)
• ✅ Powerful (can enhance existing files)
• ✅ Type-safe (TypeScript genomes + validation)

Quick Example: What the CLI Does

User Writes:

// my-app.genome.ts
export default defineGenome({
  modules: [
    { id: 'framework/nextjs' },
    { id: 'database/drizzle' },
    { id: 'connector/drizzle-nextjs' }
  ]
});

CLI Executes:

1. Loads genome via tsx (TypeScript execution)
2. Resolves order via topological sort (nextjs → drizzle → connector)
3. Creates VFS for each blueprint
4. Loads blueprints from marketplace
5. Preprocesses if dynamic (function → actions)
6. Executes actions via handlers
7. Uses modifiers for AST manipulation
8. Flushes to disk atomically

Result:

my-app/
├── src/
│   ├── app/
│   │   └── api/users/route.ts     ← Generated by connector
│   ├── db/
│   │   └── schema.ts              ← Generated by drizzle
│   └── hooks/
│       └── use-users.ts           ← Generated by connector
├── drizzle.config.ts              ← Generated by drizzle
├── next.config.js                 ← Generated by nextjs
└── package.json                   ← Merged by all modules

All safe. All atomic. All type-checked.

Dive deep into the architecture to understand how this magic happens.

→ Start with Architecture