# marcellodesales/cloner architecture

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

- Interactive diagram: https://gitdiagram.com/marcellodesales/cloner
- Repository: https://github.com/marcellodesales/cloner

## Overview

##### Project type and purpose
- **Type**: Standalone CLI application (open-source tool) written in Go.
- **Purpose**: Accepts a git-URL (HTTPS or SSH), reads optional YAML config, and clones into a predictable directory tree (`$CLONE_BASE/host/org/repo`), supporting idempotence and a force-overwrite flag.

##### File structure
- **Top-level packages**
- `cmd/` – Cobra commands (CLI entrypoints: `root`, `local`)
- `api/` – Service layer abstractions (`git_service`, `git_controller`, `git_type`)
- `config/` – Viper-backed YAML configuration loader
- `util/` – Low-level utilities (filesystem, logging, regex, dirs)
- `main.go` – application bootstrap
- **Supporting files**
- Dockerfiles & `docker-compose.yaml` – containerization
- CI workflows (`.github/workflows`) – build, lint, test, release
- `Makefile` – build/test/release commands

##### README for architectural clues
- Provided ASCII overview:

- main +-> CMD +----->+ API +----->+ UTIL |

- ^            |
- v
- > CONFIG
- Key frameworks: Cobra (CLI), Viper (config), Go modules

##### Main components & interactions
a. **Components**
- **User / Shell**
- **main** (bootstrap)
- **CMD** (Cobra commands package)
- **CONFIG** (Viper loader)
- **API** (git service abstractions)
- **UTIL** (filesystem, logging, SSH)
- **External Systems**:
- File System (for directory creation, deletion)
- Git Hosts / Network (SSH/HTTPS)
b. **Data ﬂow**
1. User invokes `cloner local --repo URL [--force] [--privateKey ...]`
2. `main` initializes logger, root command, and loads global flags
3. CMD reads flags, calls CONFIG to load `~/.cloner.yaml`
4. CMD invokes appropriate API service (git clone)
5. API calls UTIL functions to:
- parse URL and derive `host/org/repo`
- create directories
- invoke external `git clone` process (with SSH key or HTTPS)
6. UTIL logs progress, returns status to API → CMD → main → User
c. **Architectural patterns / principles**
- **Separation of concerns**:
- CLI logic (parsing, help) isolated in `cmd/`
- Business logic in `api/`
- Configuration in `config/`
- Side-effecting operations in `util/`
- **Dependency injection** via function parameters rather than global state
- **Idempotency**: clone operation checks for existing paths
d. **Key technologies**
- Go modules, Cobra, Viper, standard library (os/exec, filepath), Docker for packaging, Git CLI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External user
    User["User / Shell"]:::external

    %% Main bootstrap
    main(("main")):::bootstrap

    %% Layers
    cmd["CMD"]:::cmd
    config["CONFIG"]:::config
    api["API"]:::api
    util["UTIL"]:::util

    %% External systems
    fs[(Filesystem)]:::fs
    git(("Git Hosts")):::external

    %% Connections
    User -->|"invoke CLI"| main
    main -->|"Cobra root & subcommands"| cmd
    cmd -->|"Viper Load(~/.cloner.yaml+flags)"| config
    cmd -->|"gitController.Clone(repoURL,force,key)"| api
    api -->|"util.MkdirAll,util.ExecGit()"| util
    util --> fs
    util -->|"SSH/HTTPS network call"| git

    %% Feedback
    fs -->|"status"| util
    util -->|"status"| api
    api -->|"status"| cmd
    cmd -->|"status"| main
    main -->|"output"| User

    %% Click events
    click main "https://github.com/marcellodesales/cloner/blob/master/main.go"
    click cmd "https://github.com/marcellodesales/cloner/blob/master/cmd/root.go"
    click config "https://github.com/marcellodesales/cloner/blob/master/config/config.go"
    click api "https://github.com/marcellodesales/cloner/blob/master/api/git/git_controller.go"
    click util "https://github.com/marcellodesales/cloner/blob/master/util/dirs.go"

    %% Styles
    classDef bootstrap fill:#e6f2ff,stroke:#3399ff,stroke-width:2px
    classDef cmd fill:#b3e6b3,stroke:#339933,stroke-width:1px
    classDef api fill:#b3d1f5,stroke:#336699,stroke-width:1px
    classDef util fill:#d9d9d9,stroke:#666666,stroke-width:1px
    classDef config fill:#fff2b3,stroke:#cccc33,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#999999,stroke-width:1px
    classDef fs fill:#cccccc,stroke:#666666,stroke-width:1px
```
