# theognis1002/lightfold-cli architecture

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

- Interactive diagram: https://gitdiagram.com/theognis1002/lightfold-cli
- Repository: https://github.com/theognis1002/lightfold-cli

## Overview

##### Project Type and Purpose
- This is a command-line tool (written in Go) for zero-config web app deployment (“lightfold-cli”).
- It auto-detects your framework, builds your artifacts, provisions or configures a server on a cloud provider (DigitalOcean, Vultr, Hetzner, or BYOS), pushes code, configures proxy/SSL, and tracks state.

##### High-Level Architecture Components
a. CLI Frontend (cmd/)
- Entry point: `root.go` and subcommands (`deploy`, `create`, `configure`, `push`, `destroy`, `status`, `logs`, `rollback`, `sync`, `ssh`).
- UI layer: interactive/sequential flows, spinners, animations.
b. Configuration & State
- `pkg/config`: loads user config (`~/.lightfold/config.json`).
- `pkg/state`: persists per-target state (`~/.lightfold/state/<target>.json`).
c. Detection Engine (`pkg/detector`)
- Scans project directory, selects framework, build plan, package manager.
d. Build System (`pkg/builders`)
- Registry of builders: Dockerfile, native Go, Nixpacks, etc.
- Produces build artifacts (container image, static files, binaries).
e. Deployment Orchestrator (`pkg/deploy`)
- Orchestrates provisioning + configuration + launch.
- Uses Executor abstraction to run commands locally or via SSH.
f. Cloud Provider Clients (`pkg/providers`)
- Implements provider API for DigitalOcean, Hetzner, Vultr, plus BYOS (cloudinit).
- Provision droplet/VM, retrieve IP, attach firewall, etc.
g. SSH & Remote Execution (`pkg/ssh`)
- Establishes SSH connections, runs commands, copies files.
- Platform-specific hacks (`ssh_unix.go`, `ssh_windows.go`).
h. Proxy & SSL Layer
- `pkg/proxy/nginx`: generates and applies Nginx configs.
- `pkg/ssl/certbot`: manages TLS certificates via Certbot.
i. Utility Modules (`pkg/util`)
- Git helpers, environment variables, project paths, logging, templating.

##### Component Interactions and Data Flows
- User runs: `lightfold deploy` → CLI Frontend parses flags → loads Configuration → invokes Detection Engine → selects Builder → Build System outputs artifacts.
- Orchestrator → calls Provider Client to create or ensure server → Provider returns server IP/metadata → SSH Executor connects → runs provisioning steps (install runtime, upload artifacts, set up systemd, Nginx, Certbot).
- Proxy Manager writes Nginx templates → Reload Nginx.
- SSL Manager obtains certificates → stores them.
- Orchestrator updates State module.
- CLI Frontend shows progress, logs, and exits.

##### Architectural Patterns and Principles
- Plugin/Registry Pattern: Builders, Detectors, Providers are dynamically registered by name.
- Layered Architecture: clear separation between CLI, core modules, provider/SSH abstractions, templating, and state.
- Single Responsibility: each package handles one concern (detection vs building vs deploying vs state vs util).
- Declarative State: state persisted locally mirrors cloud resource status.

##### Key Details to Capture
- The plugin registries (detection, builders, providers) for extensibility.
- The sequential steps of the deploy command.
- Two external interaction modes: provider API calls + SSH sessions.
- The templating engine usage for workflows, Nginx, systemd, cloudinit.
- Local persistent storage of config and state.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Frontend"]:::cli
    end

    %% Persistence Layer
    subgraph "Persistence"
        Config["Configuration Store"]:::storage
        State["State Store"]:::storage
    end

    %% Core Engine
    subgraph "Core Engine"
        Detector["Detection Engine"]:::core
        Build["Build System"]:::core
        Orchestrator["Deployment Orchestrator"]:::core
        Util["Utility Modules"]:::core
    end

    %% External Integrations (Cloud & Remote)
    subgraph "External Integrations"
        Providers["Cloud Provider Clients"]:::ext
        SSH["SSH Executor"]:::ext
        Proxy["Proxy Manager (Nginx)"]:::ext
        SSL["SSL Manager (Certbot)"]:::ext
    end

    %% Flow of Operations
    CLI -->|"load config"| Config
    CLI -->|"parse command"| Detector
    Detector -->|"framework info"| Build
    CLI -->|"invoke deploy"| Orchestrator
    Build -->|"build artifact"| Orchestrator
    Orchestrator -->|"Provision VM"| Providers
    Providers -->|"return IP/metadata"| Orchestrator
    Orchestrator -->|"connect"| SSH
    SSH -->|"upload & run templates"| Proxy
    SSH -->|"request certificates"| SSL
    Orchestrator -->|"Persist state"| State
    CLI -->|"util calls"| Util

    %% Click Events
    click CLI "https://github.com/theognis1002/lightfold-cli/tree/main/cmd/"
    click Config "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/config/"
    click State "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/state/"
    click Detector "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/detector/"
    click Build "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/builders/"
    click Orchestrator "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/deploy/"
    click Providers "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/providers/"
    click SSH "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/ssh/"
    click Proxy "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/proxy/nginx/"
    click SSL "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/ssl/"
    click Util "https://github.com/theognis1002/lightfold-cli/tree/main/pkg/util/"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0077CC,stroke-width:2px;
    classDef core fill:#E8F8D0,stroke:#33AA00,stroke-width:2px;
    classDef ext fill:#FFE8D0,stroke:#CC7700,stroke-width:2px;
    classDef storage fill:#F0F0F0,stroke:#888888,stroke-width:2px;
```
