# Architecture Overview

xtarterize is organized as a monorepo using [Turborepo](https://turbo.build/repo) for task orchestration, [pnpm](https://pnpm.io/) for package management, and [Vite Plus](https://viteplus.dev) for build, test, and development workflows.

## Package Structure

- packages/
  - core/ — [`@xtarterize/core`](https://github.com/agustinusnathaniel/xtarterize/tree/main/packages/core) — [`detect.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/core/src/detect.ts) + [`detect/`](https://github.com/agustinusnathaniel/xtarterize/tree/main/packages/core/src/detect), [`resolve.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/core/src/resolve.ts), [`apply.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/core/src/apply.ts), [`backup.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/core/src/backup.ts), [`preflight.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/core/src/preflight.ts)
  - patchers/ — [`@xtarterize/patchers`](https://github.com/agustinusnathaniel/xtarterize/tree/main/packages/patchers) — [`json-merge.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/patchers/src/json-merge.ts), [`ast-patch.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/patchers/src/ast-patch.ts)
  - tasks/ — [`@xtarterize/tasks`](https://github.com/agustinusnathaniel/xtarterize/tree/main/packages/tasks) — [`factory.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/tasks/src/factory.ts), [`factory-config.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/tasks/src/factory-config.ts), [`factory-ops.ts`](https://github.com/agustinusnathaniel/xtarterize/blob/main/packages/tasks/src/factory-ops.ts), all task implementations
- apps/
  - xtarterize/ — **xtarterize** — CLI binary ([citty](https://github.com/unjs/citty) + [@clack/prompts](https://github.com/natemoo-re/clack))
  - docs/ — @xtarterize/docs — This documentation site ([Astro](https://astro.build/)/[Starlight](https://starlight.astro.build/))
- test/
  - fixtures/ — Test fixtures for various project types
## Package Dependencies

```mermaid
flowchart TD
    CLI["xtarterize<br/>apps/xtarterize"] --> 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
```
**Note:** `@xtarterize/patchers` and `@xtarterize/core` have no internal workspace dependencies — they are leaf packages that can be used independently.

## How It Works

```mermaid
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

- **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
- **Factory-based task creation** — Most tasks use `createFileTask`, `createJsonMergeTask`, or `createMultiFileTask` to eliminate boilerplate, with shared seams in `json-config.ts` and `ops.ts`
- **Shared command orchestration** — `init` and `sync` share a `runCommand()` helper in the CLI layer

## Core Modules

```mermaid
flowchart TD
    Core["@xtarterize/core"] --> Detect["detect.ts + detect/*<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 ([picocolors](https://github.com/alexeyraspopov/picocolors)), pkg ([pkg-types](https://github.com/unjs/pkg-types))"]
    
    style Core fill:#6366f1,color:#fff
```

## Task Categories

```mermaid
flowchart LR
    Tasks["@xtarterize/tasks"] --> Lint["lint/<br/>biome, oxlint, oxfmt"]
    Tasks --> TS["ts/<br/>incremental"]
    Tasks --> Gitignore["gitignore/<br/>tsbuildinfo"]
    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, git-hooks"]
    Tasks --> Quality["quality/<br/>knip, lint-staged"]
    Tasks --> Codegen["codegen/<br/>plop"]
    Tasks --> Monorepo["monorepo/<br/>turbo"]
    Tasks --> Editor["editor/<br/>vscode (settings + extensions)"]
    Tasks --> Agent["agent/<br/>agents-md, skills-install"]
    Tasks --> Scripts["scripts/<br/>package-scripts, npmrc"]
    Tasks --> Factory["factory.ts + factory-*<br/>task creation helpers"]
    
    style Tasks fill:#6366f1,color:#fff
```

## Development Workflow

```bash
    # Install dependencies
    vp install
    ```
  ```bash
    # Build all packages
    pnpm build
    ```
  ```bash
    # Run tests
    vp test
    ```
  ```bash
    # Format and lint with Biome
    pnpm check

    # Type check separately (Turborepo)
    pnpm typecheck
    ```
  ```bash
    # Start development (watch mode)
    pnpm dev
    ```
  ## Toolchain

| Tool | Purpose | Command |
|------|---------|---------|
| [Vite Plus](https://viteplus.dev) | Build, test, pack, dev server | `vp build`, `vp test`, `vp pack`, `vp dev` |
| [Turborepo](https://turbo.build/repo) | Monorepo task orchestration | `turbo run build`, `turbo run typecheck` |
| [Biome](https://biomejs.dev/) | Linting and formatting | `biome lint .`, `biome check --write .` |
| [pnpm](https://pnpm.io/) | Package management, workspaces | `pnpm install`, `catalog:` for shared deps |
| [Changesets](https://github.com/changesets/changesets) | Version management and publishing | `changeset`, `changeset version` |

## References

- [Vite Plus Documentation](https://viteplus.dev/guide/) — Unified toolchain for the web
- [Turborepo Documentation](https://turbo.build/repo/docs) — Monorepo task orchestration
- [pnpm Workspaces](https://pnpm.io/workspaces) — Workspace and monorepo management
- [citty](https://github.com/unjs/citty) — Elegant CLI framework for Node.js
- [@clack/prompts](https://github.com/natemoo-re/clack) — Interactive command-line prompts
- [Astro](https://astro.build/) — Content-focused web framework
- [Starlight](https://starlight.astro.build/) — Documentation framework for Astro
- [defu](https://github.com/unjs/defu) — Deep merge utility
- [magicast](https://github.com/unjs/magicast) — AST manipulation for JavaScript/TypeScript
- [picocolors](https://github.com/alexeyraspopov/picocolors) — Tiny terminal colors library
- [pkg-types](https://github.com/unjs/pkg-types) — Package.json type definitions and utilities

[Explore project detection →](/xtarterize/contributing/core/detect/)