# vtempest/git0 architecture

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

- Interactive diagram: https://gitdiagram.com/vtempest/git0
- Repository: https://github.com/vtempest/git0

## Overview

##### Project Type & Purpose
- This is an **open-source CLI tool** (“git0”) written in JavaScript/TypeScript (Node.js via Bun).
- Primary purpose: search GitHub repos, download source or releases, auto-install dependencies, and launch the user’s IDE/development server.

##### File Structure Highlights
- **src/**: Core modules
- `git0.js` – CLI entrypoint + command dispatcher
- `github-api.js` – GitHub REST API client
- `fm.js` – filesystem utilities & download/decompression logic
- **docs-config/** + **docs/**: Docusaurus static site generator config & generated docs
- **package.json**, **bun.lock**, **tsconfig.json**: language/runtime config

##### Main Components
a. **CLI Frontend** (git0 binary)
b. **Command Parser / Dispatcher**
c. **GitHub API Client**
d. **Download Manager** (HTTP fetch → decompression → filesystem)
e. **Project Type Detector** (checks for `package.json`, `Dockerfile`, `go.mod`, etc.)
f. **Installer** (bun/npm, cargo, pip, docker, go commands)
g. **IDE Launcher** (shell commands to open VS Code, Neovim, WebStorm, etc.)
h. **Dev Server Starter** (for Node.js projects)
i. **Logging & Error Handler**
j. **Config Layer** (env vars like `GITHUB_TOKEN`)
k. **External Services**
- GitHub REST API
- Package registries (npm, crates.io, PyPI…)
- IDE executables
l. **Documentation Pipeline** (Docusaurus build → static site)

##### Relationships & Data Flow
1) **User invokes** `git0 <repo-spec>`
2) CLI -> **Command Parser** calls → **GitHub API Client** (GET search/repo endpoints)
3) API Client returns metadata -> **Download Manager** fetches archive → writes to disk via **fm.js**
4) After unpacking, **Project Type Detector** runs, picks correct **Installer**
5) Installer executes external commands (bun, npm, pip, cargo, docker)
6) On success, **IDE Launcher** spawns user’s preferred editor
7) If Node.js, optionally kick off **Dev Server**
8) All steps emit events to **Logging & Error Handler**
9) Separately, developer runs `npm run build` on **docs-config/** to generate docs in **docs/**

##### Architectural Patterns & Principles
- **Modular SRP**: Each `src/*.js` file does one job.
- **Plugin-style Detection**: Mapping file globs → installer functions.
- **Pipeline Flow**: Sequential stages (API → download → detect → install → launch).
- **External-integration Adapters**: Wrap shell commands and HTTP calls.
- **Config-driven**: Behavior changes via environment vars (`GITHUB_TOKEN`, editor prefs).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Pipeline Flow
    subgraph "Core Pipeline"
        direction TB
        CLI["CLI Frontend\n(git0 binary)"]:::internal
        Parser["Command Parser / Dispatcher"]:::internal
        API["GitHub API Client"]:::internal
        Downloader["Download Manager"]:::internal
        Detector["Project Type Detector\n(plugin slot)"]:::internal
        Installer["Installer"]:::internal
        IDE["IDE Launcher"]:::os
        DevServer["Dev Server Starter"]:::os
        Config["Project & Runtime Config Layer"]:::config
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GHAPI["GitHub REST API"]:::external
        Registries["Package Registries\n(npm, PyPI, crates.io)"]:::external
        IDEExec["IDE Executables\n(VSCode, Neovim, WebStorm)"]:::external
    end

    %% Documentation Pipeline
    subgraph "Documentation Pipeline"
        direction TB
        DocsConfig["Docusaurus Config"]:::internal
        DocsBuild["Generated Documentation"]:::internal
    end

    %% Logging & Error Handling
    Log["Logging & Error Handler"]:::internal

    %% Flow Connections
    CLI -->|1. parse command| Parser
    Parser -->|2. search/repos| API
    API -->|3. metadata| Downloader
    Downloader -->|writes/unpacks| Detector
    Detector -->|selects installer| Installer
    Installer -->|runs install cmds| IDE
    IDE -->|spawns editor| IDEExec
    Installer -->|optional| DevServer
    CLI -->|uses| Config
    CLI -->|logs events| Log
    Parser -->|logs events| Log
    API -->|logs events| Log
    Downloader -->|logs events| Log
    Detector -->|logs events| Log
    Installer -->|logs events| Log
    IDE -->|logs events| Log
    DevServer -->|logs events| Log

    %% External Integrations
    API -->|HTTP calls| GHAPI
    Installer -->|registry fetch| Registries

    %% Docs Flow
    DocsConfig -->|npm run build| DocsBuild

    %% Click Events
    click CLI "https://github.com/vtempest/git0/blob/main/src/git0.js"
    click Parser "https://github.com/vtempest/git0/blob/main/src/git0.js"
    click API "https://github.com/vtempest/git0/blob/main/src/github-api.js"
    click Downloader "https://github.com/vtempest/git0/blob/main/src/fm.js"
    click DocsConfig "https://github.com/vtempest/git0/tree/main/docs-config/"
    click DocsBuild "https://github.com/vtempest/git0/tree/main/docs/"
    click Config "https://github.com/vtempest/git0/blob/main/package.json"

    %% Styles
    classDef internal fill:#9f6,stroke:#070,stroke-width:1px
    classDef external fill:#6cf,stroke:#036,stroke-width:1px
    classDef os fill:#fa3,stroke:#c60,stroke-width:1px
    classDef config fill:#fc9,stroke:#c70,stroke-width:1px
```
