Skip to content
Xtarterize

Architecture Overview

Architecture Overview

Section titled “Architecture Overview”

Xtarterize is organized as a monorepo using Turborepo for task orchestration and pnpm for package management.

Package Structure

Section titled “Package Structure”
  • Directorypackages/
    • Directorycore/ — @xtarterize/core — Detection, task interface, utils, backup
      • …
    • Directorypatchers/ — @xtarterize/patchers — JSON/YAML merge, AST patching
      • …
    • Directorytasks/ — @xtarterize/tasks — All conformance task implementations
      • …
  • Directoryapps/
    • Directorycli/ — xtarterize — CLI binary (citty + @clack/prompts)
      • …
    • Directorydocs/ — @xtarterize/docs — This documentation site (Astro/Starlight)
      • …
  • Directorytest/
    • Directoryfixtures/ — Test fixtures for various project types
      • …

Package Dependencies

Section titled “Package Dependencies”
flowchart TD
    CLI[xtarterize<br/>apps/cli] --> Core[@xtarterize/core]
    CLI --> Tasks[@xtarterize/tasks]
    Tasks --> Core
    Tasks --> Patchers[@xtarterize/patchers]
    
    style CLI fill:#6366f1,color:#fff
    style Core fill:#22c55e,color:#fff
    style Tasks fill:#f59e0b,color:#fff
    style Patchers fill:#a855f7,color:#fff

How It Works

Section titled “How It Works”
sequenceDiagram
    participant User
    participant CLI as CLI (citty)
    participant Core as @xtarterize/core
    participant Tasks as @xtarterize/tasks
    participant Patchers as @xtarterize/patchers
    
    User->>CLI: xtarterize init
    CLI->>Core: runPreflight(cwd)
    Core-->>CLI: PreflightResult
    CLI->>Core: detectProject(cwd)
    Core-->>CLI: ProjectProfile
    CLI->>Tasks: getAllTasks()
    Tasks-->>CLI: Task[]
    CLI->>Core: resolveTasks(profile, tasks)
    Core-->>CLI: ApplicableTask[]
    CLI->>Core: resolveTaskStatuses(tasks, cwd, profile)
    Core-->>CLI: Map<taskId, TaskStatus>
    CLI->>User: Display plan
    User->>CLI: Confirm
    CLI->>Core: applyTasks(tasks, cwd, profile)
    Core->>Core: backupFile(cwd, filepath)
    Core->>Tasks: task.apply(cwd, profile)
    Tasks->>Patchers: mergeJson / mergeYaml / injectVitePlugin
    Patchers-->>Tasks: Modified content
    Tasks-->>Core: Applied
    Core-->>CLI: { applied, skipped, errors }
    CLI->>User: Summary

Key Design Decisions

Section titled “Key Design Decisions”
  • Detection lives in core — No CLI dependency, reusable by other consumers
  • Tasks are independent — Each task can run standalone via add <task-id>
  • Dry-run is exact — dryRun() output is bit-for-bit identical to what apply() writes
  • Idempotency is non-negotiable — Running twice produces no changes on second run
  • Templates are parameterized — All templates receive ProjectProfile and adapt accordingly

Core Modules

Section titled “Core Modules”
flowchart TD
    Core[@xtarterize/core] --> Detect[detect.ts<br/>Project detection]
    Core --> Resolve[resolve.ts<br/>Task resolution]
    Core --> Apply[apply.ts<br/>Task application]
    Core --> Backup[backup.ts<br/>File backup/restore]
    Core --> Preflight[preflight.ts<br/>Pre-flight checks]
    Core --> Diagnostics[diagnostics.ts<br/>Conflict detection]
    Core --> Utils[utils/<br/>fs, diff, logger, pkg]
    
    style Core fill:#6366f1,color:#fff

Task Categories

Section titled “Task Categories”
flowchart LR
    Tasks[@xtarterize/tasks] --> Lint[lint/<br/>biome, ultracite]
    Tasks --> TS[ts/<br/>incremental]
    Tasks --> Vite[vite/<br/>checker, visualizer]
    Tasks --> CI[ci/<br/>release, auto-update, ci]
    Tasks --> Deps[deps/<br/>renovate]
    Tasks --> Release[release/<br/>commitlint, czg, cat-version]
    Tasks --> Quality[quality/<br/>knip]
    Tasks --> Codegen[codegen/<br/>plop]
    Tasks --> Monorepo[monorepo/<br/>turbo]
    Tasks --> Editor[editor/<br/>vscode, vscode-extensions]
    Tasks --> Agent[agent/<br/>agents-md, skills]
    Tasks --> Scripts[scripts/<br/>package-scripts]
    
    style Tasks fill:#6366f1,color:#fff

Development Workflow

Section titled “Development Workflow”
Terminal window
# Install dependencies
pnpm install
 Explore project detection →