── 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.

go
package main
import "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.

FileCommandDescription
root.goexoRoot command, sets up Cobra with help template
init.goexo initInteractive wizard → detect + prompt + render
gen.goexo gen <type>Generate individual templates (12 subcommands)
add.goexo add <type>Add components to existing config
status.goexo statusShow generated file overview
validate.goexo validateValidate .exo.yaml against schema
scan.goexo scanDetect project stack (language, framework)
lint.goexo lintLint generated files for best practices
plugin.goexo pluginPlugin management (install, list, remove)
history.goexo historyShow generation history log
update.goexo updateRefresh remote templates
upgrade.goexo upgradeSelf-upgrade the CLI binary
completion.goexo completionShell completion scripts
docs.goexo docsOpen docs in browser
version.goexo versionPrint version + build info

internal/detector/

Scans the current directory for marker files and determines the project's language and framework.

go
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.

go
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 Lipgloss

internal/renderer/

Three-tier template resolution engine. Checks for local overrides before falling back to embedded templates, with optional remote fetch from GitHub.

go
// 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.

go
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

PackagePurpose
cobraCLI framework — commands, flags, help
bubbleteaTerminal UI framework for the interactive wizard
lipglossTUI styling — colors, borders, layout
yaml.v3YAML parsing for .exo.yaml config
embedGo standard library — embedded template filesystem
text/templateGo standard library — template rendering