CLI Architecture

The Seven-Layer Execution System

The Architech CLI implements a sophisticated seven-layer architecture that transforms TypeScript genomes into generated projects through a series of well-defined, isolated stages.

The Complete Flow

Layer Descriptions

Layer 1: CLI Command Layer →

Entry point for user commands. Loads and validates TypeScript genomes using tsx.

Layer 2: Orchestrator Layer →

Coordinates the entire execution. Handles dependency resolution, blueprint loading, and VFS lifecycle management.

Layer 3: Blueprint Preprocessor →

Converts dynamic blueprint functions into static action arrays for execution.

Layer 4: Blueprint Executor →

Analyzes blueprints, pre-populates VFS, expands forEach actions, and delegates to action handlers.

Layer 5: Action Handler Layer →

Routes semantic actions to appropriate handlers for execution.

Layer 6: Modifier Layer →

Performs complex file modifications using AST manipulation via ts-morph.

Layer 7: Virtual File System →

Provides safe, atomic file operations with in-memory processing.

Core Subsystems

Beyond the 7 layers, several critical subsystems enable the CLI's functionality:

Type System →

How the types package provides shared contracts between CLI and Marketplace.

Dependency Resolution →

Topological sorting, capability registry, and prerequisite validation.

Caching System →

How the CacheManagerService optimizes blueprint loading and execution.

Key Architectural Decisions

The CLI's architecture embodies specific design choices:

1. Per-Blueprint VFS Isolation - Each blueprint runs in its own sandbox
2. AST Not Regex - Reliable code modification via ts-morph
3. Dynamic Blueprints - Functions that generate actions based on config
4. Semantic Actions - High-level operations, not primitives
5. Fail-Fast Philosophy - Any error stops execution immediately

Each decision has deep rationale. See Design Decisions → for complete analysis.

Reading Guide

For Understanding:

1. Start with Execution Flow
2. Read each layer's page sequentially
3. Study Type System
4. Review Dependency Resolution

For Contributing:

1. Understand Blueprint System
2. Learn Blueprint Actions
3. Study Modifiers
4. Review Design Decisions

For Evaluating:

1. Review Architecture Overview
2. Check Limitations
3. See Design Decisions for rationale

Next Steps

Begin with the Execution Flow →

Or jump to a specific topic:

• Type System →
• Virtual File System →
• Dependency Resolution →