# create-go-app/cli architecture

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

- Interactive diagram: https://gitdiagram.com/create-go-app/cli
- Repository: https://github.com/create-go-app/cli

## Overview

##### Main components
- CLI Binary (cgapp)
- Command Parser & Root (cmd/root.go)
- “create” command (cmd/create.go)
- “deploy” command (cmd/deploy.go)
- Business-logic packages (pkg/cgapp)
- File generators (files.go)
- Git helper (git.go)
- Shell executor (exec.go)
- Utility functions (utils.go)
- Template Registry (pkg/registry)
- Defaults & configuration (defaults.go, templates)
- Ansible playbook template
- Ansible roles (nginx, traefik, postgres, redis, etc.) with tasks and Jinja2 templates
- External tools
- Git (for repo init)
- npm/vite (for frontend scaffolding)
- Docker (for container images)
- Ansible (for remote deployment)
- Generated project
- Frontend code (React, Vue, etc.)
- Backend code (Go REST API template)
- Ansible inventory & playbook file
- Runtime environment
- Developer’s machine (CLI host)
- Remote server(s) (where Ansible deploys containers)

##### Relationships and data flow
a. User invokes `cgapp create` (CLI Binary → Command Parser → Create Command)
b. Create Command calls pkg/cgapp to:
- Initialize Git repo
- Copy/write scaffold files from pkg/registry/templates
- Invoke `npm`/`yarn` via exec for frontend
- Write Ansible inventory and playbook files
c. User edits hosts.ini
d. User invokes `cgapp deploy` (CLI Binary → Deploy Command)
e. Deploy Command triggers pkg/cgapp to:
- Invoke `ansible-playbook` with generated playbook
- Leverage roles in pkg/registry/roles to launch Docker containers on remote
f. External tools (Docker, Traefik, Nginx, PostgreSQL, Redis) spin up

##### Architectural patterns & principles
- Modular CLI: commands wired via Cobra-like structure (root + subcommands)
- Separation of concerns:
- cmd/* = interface layer
- pkg/cgapp = orchestration & helpers
- pkg/registry = templates & defaults
- Template-driven codegen: Jinja2/Go templates for config files and playbooks
- External process calls: Git, npm, Ansible, Docker invoked via exec

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User interaction
    User["User"]:::external
    User -->|"cgapp create"| CLI
    User -->|"cgapp deploy"| CLI

    %% CLI Binary and subcomponents
    subgraph "CLI Binary"
        CLI["cgapp CLI Binary"]:::cli
        Parser["Command Parser & Root"]:::cli
        Create["Create Command"]:::cli
        Deploy["Deploy Command"]:::cli
    end
    CLI --> Parser
    Parser -->|"on create"| Create
    Parser -->|"on deploy"| Deploy

    %% pkg/cgapp modules
    subgraph "Business Logic (pkg/cgapp)"
        Files["File Generators"]:::pkg
        GitHelper["Git Helper"]:::pkg
        Exec["Shell Executor"]:::pkg
        Utils["Utility Functions"]:::pkg
    end
    Create -->|"init, scaffold"| Files
    Create -->|"git init"| GitHelper
    Create -->|"run npm/vite"| Exec
    Create -->|"util operations"| Utils

    Deploy -->|"use exec"| Exec

    %% Template Registry
    subgraph "Template Registry (pkg/registry)"
        Defaults["Defaults & Config"]:::registry
        InventoryTmpl["Inventory Template"]:::registry
        PlaybookTmpl["Ansible Playbook Template"]:::registry
        subgraph "Ansible Roles"
            BackendRole["Backend Role"]:::registry
            DockerRole["Docker Role"]:::registry
            NginxRole["Nginx Role"]:::registry
            PostgresRole["Postgres Role"]:::registry
            RedisRole["Redis Role"]:::registry
            TraefikRole["Traefik Role"]:::registry
        end
    end
    Files -->|"copy templates"| Defaults
    Files --> InventoryTmpl
    Files --> PlaybookTmpl
    PlaybookTmpl --> BackendRole
    PlaybookTmpl --> DockerRole
    PlaybookTmpl --> NginxRole
    PlaybookTmpl --> PostgresRole
    PlaybookTtmpl -.-> RedisRole
    PlaybookTmpl --> TraefikRole

    %% External tools
    subgraph "External Tools"
        GitExt["Git"]:::external
        NpmExt["npm/vite"]:::external
        AnsibleExt["Ansible"]:::external
        DockerExt["Docker"]:::external
    end
    GitHelper -->|"exec git"| GitExt
    Exec -->|"exec npm"| NpmExt
    Deploy -->|"ansible-playbook"| AnsibleExt
    AnsibleExt --> DockerExt

    %% Generated project
    Generated["Generated Project Files"]:::gen
    Create -->|"generates"| Generated

    %% Remote environment
    subgraph "Remote Servers" 
        Remote["Remote Server(s)"]:::remote
        TraefikRole --> Remote
        NginxRole --> Remote
        PostgresRole --> Remote
        RedisRole --> Remote
    end
    DockerExt --> Remote

    %% Connections for deploy flow
    Deploy --> Exec
    Exec --> PlaybookTmpl
    PlaybookTmpl --> AnsibleExt
    AnsibleExt --> Remote

    %% Click events
    click CLI "https://github.com/create-go-app/cli/blob/main/cmd/cgapp/main.go"
    click Parser "https://github.com/create-go-app/cli/blob/main/cmd/root.go"
    click Create "https://github.com/create-go-app/cli/blob/main/cmd/create.go"
    click Deploy "https://github.com/create-go-app/cli/blob/main/cmd/deploy.go"
    click Files "https://github.com/create-go-app/cli/blob/main/pkg/cgapp/files.go"
    click GitHelper "https://github.com/create-go-app/cli/blob/main/pkg/cgapp/git.go"
    click Exec "https://github.com/create-go-app/cli/blob/main/pkg/cgapp/exec.go"
    click Utils "https://github.com/create-go-app/cli/blob/main/pkg/cgapp/utils.go"
    click Defaults "https://github.com/create-go-app/cli/blob/main/pkg/registry/defaults.go"
    click InventoryTmpl "https://github.com/create-go-app/cli/blob/main/pkg/registry/templates/hosts.ini.tmpl"
    click PlaybookTmpl "https://github.com/create-go-app/cli/blob/main/pkg/registry/templates/playbook.yml.tmpl"
    click BackendRole "https://github.com/create-go-app/cli/tree/main/pkg/registry/roles/backend"
    click DockerRole "https://github.com/create-go-app/cli/tree/main/pkg/registry/roles/docker"
    click NginxRole "https://github.com/create-go-app/cli/tree/main/pkg/registry/roles/nginx"
    click PostgresRole "https://github.com/create-go-app/cli/tree/main/pkg/registry/roles/postgres"
    click RedisRole "https://github.com/create-go-app/cli/tree/main/pkg/registry/roles/redis"
    click TraefikRole "https://github.com/create-go-app/cli/tree/main/pkg/registry/roles/traefik"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef pkg fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32;
    classDef registry fill:#FFF3E0,stroke:#EF6C00,color:#E65100;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef gen fill:#FFF9C4,stroke:#F9A825,color:#F9A825;
    classDef remote fill:#EDE7F6,stroke:#5E35B1,color:#5E35B1;
```
