How theognis1002/lightfold-cli works
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.