# vapor/toolbox architecture

> Architecture diagram of the GitHub repository vapor/toolbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vapor/toolbox
- Repository: https://github.com/vapor/toolbox

## Overview

##### Project Type and Purpose
- This is a command-line interface (CLI) tool written in Swift, called “Vapor Toolbox.”
- Its sole subcommand is `new`, which scaffolds new Vapor (server-side Swift) projects by fetching or reading a template manifest, rendering files/folders, initializing a Git repository, and printing progress.

##### File Structure Analysis
- Top level:
- Package.swift, Makefile, Dockerfile – build/distribution scripts
- Sources/VaporToolbox – main Swift modules
- Tests/VaporToolboxTests – unit tests for manifest parsing, rendering, utilities
- scripts/build.swift – custom build steps
- Sources/VaporToolbox components:
- New.swift – entry point & command dispatcher
- TemplateManifest.swift – in-memory model of manifest (YAML/JSON)
- TemplateRenderer.swift – takes a manifest + variables → generates files/directories
- Util/ANSIColor.swift, PrintUtilities.swift – console output formatting
- Util/Process+runUntilExit.swift – shell command runner (e.g., `git init`)
- Version.swift, Vapor.swift – metadata, CLI help/version info

##### README Insights
- Core workflow:
a. Parse CLI args (project name, flags, template URL/branch/manifest path)
b. Download or locate template repository (default or custom URL)
c. Load & parse manifest (manifest.yml or manifest.json) into TemplateManifest
d. Ask interactive questions based on manifest variables (unless `-n`)
e. Render files/folders via TemplateRenderer using Mustache templating
f. Initialize Git repo, make initial commit (unless flags disable it)
- Extensibility: support for custom templates, dynamic files/folders, conditional rendering.

##### Main Components
- 1) CLI Layer
- NewCommand (Sources/VaporToolbox/New.swift)
- Argument parsing & help/version display
- 2) Template Loader
- GitFetcher (shell out via Process+runUntilExit) or local folder reader
- TemplateManifest parser (YAML/JSON → Swift model)
- 3) Interaction Layer
- PromptService (PrintUtilities + ANSIColor)
- User input gathering for manifest variables
- 4) Rendering Engine
- TemplateRenderer (processing Mustache templates, dynamic names, conditional inclusion)
- FileSystem writer (creates folders/files)
- 5) Post-processing
- GitInitializer (invokes `git init`, `git commit`)
- 6) Utilities
- ANSIColor, PrintUtilities, Process runner
- 7) External Dependencies
- Remote Git repository (template source)
- Local file system
- Shell (for `git`, `chmod`, etc.)

##### Data Flow & Relationships
- User invokes `vapor new <ProjectName> [--flags]` → CLI Layer
- CLI Layer calls Template Loader to clone or copy template repo → Template directory
- Template Loader hands off manifest file path to TemplateManifest parser → in-memory manifest object
- CLI Layer + PromptService iterate manifest.variables → gather user inputs
- Inputs + manifest feed into TemplateRenderer → generate file/folder tree on Local FS
- Post-processing by GitInitializer → run shell commands via Process runner
- Progress & errors printed via PrintUtilities/ANSIColor to console

##### Architectural Patterns & Design Principles
- Single-responsibility modules: CLI parsing, template parsing, rendering, FS operations, shell commands all in separate types
- Dependency injection is light but utilities are separated for testability
- Manifest supports dynamic, conditional rendering – akin to a simple template engine + rule engine

##### Must-Include
- Clear labels: e.g., “NewCommand (entry point),” “TemplateManifest,” “TemplateRenderer”
- Rectangles = internal modules
- Clouds = external template repo
- Hexagons = utilities

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Modules
    subgraph "CLI Layer"
        direction TB
        NewCommand["NewCommand (entry point)"]:::core
        Vapor["Vapor (help/version)"]:::core
        Version["Version (metadata)"]:::core
    end

    subgraph "Template Loader"
        direction TB
        TemplateLoader["TemplateLoader"]:::core
        ProcessRunner["Process+runUntilExit (shell)"]:::utilities
    end

    subgraph "Manifest Parser"
        direction TB
        TemplateManifest["TemplateManifest"]:::core
    end

    subgraph "Interaction Layer"
        direction TB
        PrintUtilities["PrintUtilities"]:::utilities
        ANSIColor["ANSIColor"]:::utilities
        PromptService["PromptService"]:::core
    end

    subgraph "Rendering Engine"
        direction TB
        TemplateRenderer["TemplateRenderer"]:::core
        FileSystemWriter["FileSystem Writer"]:::core
    end

    subgraph "Post-Processing"
        direction TB
        GitInitializer["GitInitializer"]:::core
    end

    subgraph "External Dependencies"
        direction TB
        RemoteGit["Remote Git Repo"]:::external
        Shell["Shell/OS"]:::external
    end

    subgraph "Storage"
        direction TB
        LocalFS["Local File System"]:::storage
    end

    subgraph "Unit Tests"
        direction TB
        TestManifestYML["manifest.yml"]:::test
        TestManifestJSON["manifest.json"]:::test
        UtilTests["UtilTests.swift"]:::test
        ToolboxTests["VaporToolboxTests.swift"]:::test
    end

    %% Data Flow
    User["User"]:::external -->|"runs vapor new"| NewCommand
    NewCommand -->|"fetch template"| TemplateLoader
    TemplateLoader -->|"clones or copies"| RemoteGit
    TemplateLoader --> ProcessRunner
    TemplateLoader --> TemplateManifest
    TemplateManifest -->|"provides variables"| PromptService
    PromptService --> PrintUtilities
    PromptService --> ANSIColor
    PromptService --> TemplateRenderer
    TemplateRenderer --> FileSystemWriter
    FileSystemWriter --> LocalFS
    LocalFS -->|"init git"| GitInitializer
    GitInitializer --> ProcessRunner
    ProcessRunner --> Shell

    %% Click Events
    click NewCommand "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/New.swift"
    click Vapor "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/Vapor.swift"
    click Version "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/Version.swift"
    click ProcessRunner "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/Util/Process+runUntilExit.swift"
    click TemplateManifest "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/TemplateManifest.swift"
    click PrintUtilities "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/Util/PrintUtilities.swift"
    click ANSIColor "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/Util/ANSIColor.swift"
    click TemplateRenderer "https://github.com/vapor/toolbox/blob/main/Sources/VaporToolbox/TemplateRenderer.swift"
    click TestManifestYML "https://github.com/vapor/toolbox/blob/main/Tests/VaporToolboxTests/Manifests/manifest.yml"
    click TestManifestJSON "https://github.com/vapor/toolbox/blob/main/Tests/VaporToolboxTests/Manifests/manifest.json"
    click UtilTests "https://github.com/vapor/toolbox/blob/main/Tests/VaporToolboxTests/UtilTests.swift"
    click ToolboxTests "https://github.com/vapor/toolbox/blob/main/Tests/VaporToolboxTests/VaporToolboxTests.swift"

    %% Styles
    classDef core fill:#AEDFF7,stroke:#1f77b4,stroke-width:1px
    classDef utilities fill:#FDE9A9,stroke:#FFAE00,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#888,stroke-width:1px,stroke-dasharray: 5 5
    classDef storage fill:#CDEAC0,stroke:#2E8B57,stroke-width:1px
    classDef test fill:#F4C2C2,stroke:#D22B2B,stroke-width:1px,stroke-dasharray: 2 2
```
