── CORE CONCEPTS ──
Architecture
How Exo is built internally — from CLI entry-point to rendered template output.
## System Overview
┌─────────────────────────────────────────────────────────────┐ │ CLI Layer │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────────────┐ │ │ │ init │ │ gen │ │ status │ │ scan / lint / │ │ │ │ (cobra) │ │ (cobra) │ │ (cobra) │ │ validate / ... │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────────┬────────┘ │ │ │ │ │ │ │ ├────────┼───────────┼───────────┼────────────────┼───────────┤ │ ▼ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Internal Packages │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ │ detector │ │ prompt │ │ renderer │ │ │ │ │ │ (stack) │ │ (wizard) │ │ (output) │ │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ │ │ │ ┌──────────┐ │ │ │ │ │ config │ │ │ │ │ │ (.exo) │ │ │ │ │ └──────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ├────────────────────────────┼────────────────────────────────┤ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Template Engine │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │ │ │ │ │ Embedded │ │ Local │ │ Remote (GitHub) │ │ │ │ │ │ (embed) │ │ (~/.exo) │ │ Harsh-BH/exo-tmpl │ │ │ │ │ └──────────┘ └──────────┘ └──────────────────────┘ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ Generated Output │ │ │ │ Docker Terraform K8s CI/CD Helm Monitoring DB │ │ │ └──────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘
## Package Breakdown
main.go
Entry point. Calls cmd/exo.Execute() which boots the Cobra command tree.
package mainimport "github.com/Harsh-BH/Exo/cmd/exo"func main() { exo.Execute()}cmd/exo/
All CLI commands are registered here via Cobra. Each file adds one command to the root.
| File | Command | Description |
|---|---|---|
| root.go | exo | Root command, sets up Cobra with help template |
| init.go | exo init | Interactive wizard → detect + prompt + render |
| gen.go | exo gen <type> | Generate individual templates (12 subcommands) |
| add.go | exo add <type> | Add components to existing config |
| status.go | exo status | Show generated file overview |
| validate.go | exo validate | Validate .exo.yaml against schema |
| scan.go | exo scan | Detect project stack (language, framework) |
| lint.go | exo lint | Lint generated files for best practices |
| plugin.go | exo plugin | Plugin management (install, list, remove) |
| history.go | exo history | Show generation history log |
| update.go | exo update | Refresh remote templates |
| upgrade.go | exo upgrade | Self-upgrade the CLI binary |
| completion.go | exo completion | Shell completion scripts |
| docs.go | exo docs | Open docs in browser |
| version.go | exo version | Print version + build info |
internal/detector/
Scans the current directory for marker files and determines the project's language and framework.
type StackInfo struct { Language string // "go", "node", "python", "unknown" Framework string // "gin", "express", "flask", etc. Files []string // Marker files found}// Detection logic:// go.mod → Go// package.json → Node.js (checks for express/react/next)// requirements.txt, Pipfile, setup.py → Python (checks for flask/django/fastapi)// Otherwise → "unknown"internal/prompt/
Implements the 7-step interactive wizard using Bubble Tea and Lipgloss for a rich TUI experience.
type WizardModel struct { step int // 0-6 (name, lang, provider, ci, monitoring, db, confirm) cursor int // Current selection cursor config ExoConfig // Accumulated answers quitting bool // User cancelled confirmed bool // User confirmed}// Uses Bubble Tea's Model interface:// Init() → start blinking cursor// Update() → handle key events (up/down/enter/q)// View() → render styled TUI with Lipglossinternal/renderer/
Three-tier template resolution engine. Checks for local overrides before falling back to embedded templates, with optional remote fetch from GitHub.
// Resolution order:// 1. Local override: ~/.exo/templates/<path>// 2. Embedded: templates/<path> (via embed.FS)// 3. Remote fetch: github.com/Harsh-BH/exo-templates/<path>func resolveTemplate(name string) ([]byte, error) { // Check local disk first localPath := filepath.Join(home, ".exo", "templates", name) if data, err := os.ReadFile(localPath); err == nil { return data, nil } // Fall back to embedded if data, err := templates.FS.ReadFile(name); err == nil { return data, nil } // Try remote return fetchRemoteTemplate(name)}internal/config/
Reads and writes .exo.yaml configuration. Provides Load/Save helpers and the ExoConfig struct.
type ExoConfig struct { Name string `yaml:"name"` Language string `yaml:"language"` Provider string `yaml:"provider"` CI string `yaml:"ci"` Monitoring string `yaml:"monitoring"` Database string `yaml:"database"`}func LoadConfig() (*ExoConfig, error) { ... }func SaveConfig(cfg *ExoConfig) error { ... }## Design Principles
Single Binary
No runtime dependencies. Compiled Go binary includes all templates via embed.FS.
Opinionated Defaults
Templates encode production best practices — multi-stage Docker builds, proper K8s resource limits, Terraform state locking.
Zero Lock-in
Generated output is plain files. Delete Exo and keep your infrastructure — no proprietary formats.
Template Override
Local ~/.exo/templates/ overrides let teams enforce their own standards without forking.
Idempotent Generation
Re-running exo gen updates files safely. Existing customizations are preserved where possible.
## Dependencies
| Package | Purpose |
|---|---|
cobra | CLI framework — commands, flags, help |
bubbletea | Terminal UI framework for the interactive wizard |
lipgloss | TUI styling — colors, borders, layout |
yaml.v3 | YAML parsing for .exo.yaml config |
embed | Go standard library — embedded template filesystem |
text/template | Go standard library — template rendering |