# koki-develop/clive architecture

> Architecture diagram of the GitHub repository koki-develop/clive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/koki-develop/clive
- Repository: https://github.com/koki-develop/clive

## Overview

#### Purpose and Entrypoints
cLive is a Go CLI that automates terminal demonstrations: it launches a terminal through `ttyd`, opens it in a browser, and replays configured typing, key, pause, delay, and screenshot actions. Process entry is `main.go`; command wiring and user-facing commands are in `cmd/root.go`, `cmd/start.go`, `cmd/init.go`, `cmd/validate.go`, and `cmd/notify.go`.

#### CLI Command Boundary
The CLI separates configuration lifecycle from execution:
- `init` creates a starter `clive.yml`.
- `validate` parses and checks a configuration without running it.
- `start` drives the terminal/browser automation workflow.
- Shell completion is exposed from the root command.
Command implementation is concentrated in `cmd/`, while reusable CLI initialization and embedded starter assets live in `internal/cli/cli.go`, `internal/cli/init.go`, and `internal/cli/static/clive.yml`.

#### Configuration Model and Validation
YAML configuration is the primary input boundary. It contains global settings (login command, visual/browser dimensions, headless mode, screenshot directory, default speed) and an ordered action list. The domain model and validation rules are in `internal/config/config.go`, `internal/config/settings.go`, `internal/config/action.go`, `internal/config/key.go`, and `internal/config/error.go`. This layer normalizes action forms such as type/key/ctrl/sleep/pause/screenshot and rejects invalid action or key definitions before runtime automation begins. `schema.json` is the machine-readable contract for the config format.

#### Execution Pipeline
`start` likely follows this control flow: load and validate config → allocate a local endpoint → launch `ttyd` with the configured login shell → open a configured browser session against the terminal URL → execute actions in declaration order → optionally pause before exit. Terminal-server integration is isolated in `internal/ttyd/ttyd.go`; local listener allocation is in `internal/net/listener.go`. This is a local-process orchestration tool rather than a hosted service.

#### Browser and Terminal Automation
The browser boundary is encapsulated by `internal/browser/browser.go`. It applies settings including browser binary, viewport dimensions, font presentation, and headless mode, then sends keyboard-oriented actions to the ttyd-rendered terminal and captures screenshots. `ttyd` is an external runtime prerequisite (v1.7.4+); a compatible installed browser is also required, with an optional explicit binary path. The terminal command itself is user-controlled through `settings.loginCommand`.

#### UI, Pause, and Action Progression
Interactive pause behavior and action progression are represented as a UI model/update/view split in `internal/ui/model.go`, `internal/ui/update.go`, `internal/ui/view.go`, and `internal/ui/init.go`. This forms the human-interaction boundary: automated actions can stop for Enter before continuing, while `skipPauseBeforeQuit` controls the final pause. Styling is centralized in `internal/styles/styles.go`.

#### State, Files, and Delivery
Runtime artifacts include generated config files and screenshots; filesystem handling is centralized in `internal/util/files.go`. `internal/cache/cache.go` and `internal/cache/store.go` provide a persistence/cache boundary for execution-related state. The project is built and released as a Go binary, with release packaging defined in `.goreleaser.yaml`; CI and release automation run through `.github/workflows/ci.yml` and `.github/workflows/release-please.yml`.

Main entry points: [`cmd/start.go`](https://github.com/koki-develop/clive/blob/main/cmd/start.go) (Start orchestration), [`cmd/root.go`](https://github.com/koki-develop/clive/blob/main/cmd/root.go) (Commands), [`internal/browser/browser.go`](https://github.com/koki-develop/clive/blob/main/internal/browser/browser.go) (Browser automation), [`main.go`](https://github.com/koki-develop/clive/blob/main/main.go) (Process entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main(("Process entry<br/>Go entrypoint<br/>[main.go]"))
  node_commands["Commands<br/>[root.go]"]
  node_cli_init["CLI initialization<br/>CLI support<br/>[cli.go]"]
  node_starter_config["Starter config<br/>embedded YAML<br/>[clive.yml]"]
end

subgraph group_core["Automation Core"]
  node_config_input["clive.yml<br/>YAML input"]
  node_schema["Config schema<br/>JSON Schema<br/>[schema.json]"]
  node_config_model["Config validation<br/>domain model<br/>[config.go]"]
  node_execution["Start orchestration<br/>execution pipeline<br/>[start.go]"]
  node_pause_ui["Pause UI<br/>interactive UI<br/>[model.go]"]
  node_cache[("Execution cache<br/>persistence<br/>[cache.go]")]
  node_files["Artifact files<br/>filesystem handling<br/>[files.go]"]
  node_artifacts["Generated artifacts<br/>filesystem output"]
end

subgraph group_runtime["Local Runtime"]
  node_listener["Local endpoint<br/>listener allocator<br/>[listener.go]"]
  node_ttyd_adapter["ttyd integration<br/>terminal server adapter<br/>[ttyd.go]"]
  node_ttyd{{"ttyd process<br/>external runtime"}}
  node_browser_adapter["Browser automation<br/>browser adapter<br/>[browser.go]"]
  node_browser{{"Browser session<br/>external runtime"}}
end

subgraph group_delivery["Delivery"]
  node_release["Build and release<br/>delivery automation<br/>[.goreleaser.yaml]"]
end

node_main -->|"starts"| node_commands
node_commands -->|"initializes"| node_cli_init
node_cli_init -->|"embeds"| node_starter_config
node_commands -->|"init creates / commands read"| node_config_input
node_schema -.->|"defines"| node_config_input
node_config_input -->|"parse and validate"| node_config_model
node_commands -->|"start"| node_execution
node_config_model -->|"validated settings and actions"| node_execution
node_execution -->|"allocates"| node_listener
node_listener -->|"endpoint"| node_ttyd_adapter
node_ttyd_adapter -->|"launches"| node_ttyd
node_execution -->|"drives actions"| node_browser_adapter
node_browser_adapter -->|"controls"| node_browser
node_browser -->|"opens terminal URL"| node_ttyd
node_execution -->|"pause actions"| node_pause_ui
node_execution -->|"persists state"| node_cache
node_browser_adapter -->|"writes screenshots"| node_files
node_files -->|"creates"| node_artifacts
node_release -.->|"packages binary"| node_main

click node_main "https://github.com/koki-develop/clive/blob/main/main.go"
click node_commands "https://github.com/koki-develop/clive/blob/main/cmd/root.go"
click node_cli_init "https://github.com/koki-develop/clive/blob/main/internal/cli/cli.go"
click node_starter_config "https://github.com/koki-develop/clive/blob/main/internal/cli/static/clive.yml"
click node_schema "https://github.com/koki-develop/clive/blob/main/schema.json"
click node_config_model "https://github.com/koki-develop/clive/blob/main/internal/config/config.go"
click node_execution "https://github.com/koki-develop/clive/blob/main/cmd/start.go"
click node_listener "https://github.com/koki-develop/clive/blob/main/internal/net/listener.go"
click node_ttyd_adapter "https://github.com/koki-develop/clive/blob/main/internal/ttyd/ttyd.go"
click node_browser_adapter "https://github.com/koki-develop/clive/blob/main/internal/browser/browser.go"
click node_pause_ui "https://github.com/koki-develop/clive/blob/main/internal/ui/model.go"
click node_cache "https://github.com/koki-develop/clive/blob/main/internal/cache/cache.go"
click node_files "https://github.com/koki-develop/clive/blob/main/internal/util/files.go"
click node_release "https://github.com/koki-develop/clive/blob/main/.goreleaser.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_commands,node_cli_init,node_starter_config toneBlue
class node_config_input,node_schema,node_config_model,node_execution,node_pause_ui,node_cache,node_files,node_artifacts toneAmber
class node_listener,node_ttyd_adapter,node_ttyd,node_browser_adapter,node_browser toneMint
class node_release toneRose
```

## Components

### CLI

- [Process entry](https://github.com/koki-develop/clive/blob/main/main.go): Go entrypoint · `main.go`
- [Commands](https://github.com/koki-develop/clive/blob/main/cmd/root.go): Cobra commands · init, validate, start, notify, and root wiring. · `cmd/root.go`
- [CLI initialization](https://github.com/koki-develop/clive/blob/main/internal/cli/cli.go): CLI support · Reusable setup and embedded starter assets. · `internal/cli/cli.go`
- [Starter config](https://github.com/koki-develop/clive/blob/main/internal/cli/static/clive.yml): embedded YAML · `internal/cli/static/clive.yml`

### Automation Core

- **clive.yml**: YAML input · Global settings and ordered automation actions.
- [Config schema](https://github.com/koki-develop/clive/blob/main/schema.json): JSON Schema · Machine-readable configuration contract. · `schema.json`
- [Config validation](https://github.com/koki-develop/clive/blob/main/internal/config/config.go): domain model · Parses, normalizes, and validates settings, actions, and keys. · `internal/config/config.go`
- [Start orchestration](https://github.com/koki-develop/clive/blob/main/cmd/start.go): execution pipeline · Runs validated actions through terminal and browser boundaries. · `cmd/start.go`
- [Pause UI](https://github.com/koki-develop/clive/blob/main/internal/ui/model.go): interactive UI · Waits for Enter at configured pause points. · `internal/ui/model.go`
- [Execution cache](https://github.com/koki-develop/clive/blob/main/internal/cache/cache.go): persistence · Stores execution-related state. · `internal/cache/cache.go`
- [Artifact files](https://github.com/koki-develop/clive/blob/main/internal/util/files.go): filesystem handling · Creates generated config and screenshot artifacts. · `internal/util/files.go`
- **Generated artifacts**: filesystem output · Configuration files and screenshots.

### Local Runtime

- [Local endpoint](https://github.com/koki-develop/clive/blob/main/internal/net/listener.go): listener allocator · `internal/net/listener.go`
- [ttyd integration](https://github.com/koki-develop/clive/blob/main/internal/ttyd/ttyd.go): terminal server adapter · Launches ttyd with the configured login command. · `internal/ttyd/ttyd.go`
- **ttyd process**: external runtime · Serves the local terminal session.
- [Browser automation](https://github.com/koki-develop/clive/blob/main/internal/browser/browser.go): browser adapter · Applies browser settings, sends actions, and captures screenshots. · `internal/browser/browser.go`
- **Browser session**: external runtime · Renders the ttyd terminal URL.

### Delivery

- [Build and release](https://github.com/koki-develop/clive/blob/main/.goreleaser.yaml): delivery automation · Packages the Go binary and runs CI/release workflows. · `.goreleaser.yaml`

## Connections

- Process entry → Commands: starts
- Commands → CLI initialization: initializes
- CLI initialization → Starter config: embeds
- Commands → clive.yml: init creates / commands read
- Config schema → clive.yml: defines
- clive.yml → Config validation: parse and validate
- Commands → Start orchestration: start
- Config validation → Start orchestration: validated settings and actions
- Start orchestration → Local endpoint: allocates
- Local endpoint → ttyd integration: endpoint
- ttyd integration → ttyd process: launches
- Start orchestration → Browser automation: drives actions
- Browser automation → Browser session: controls
- Browser session → ttyd process: opens terminal URL
- Start orchestration → Pause UI: pause actions
- Start orchestration → Execution cache: persists state
- Browser automation → Artifact files: writes screenshots
- Artifact files → Generated artifacts: creates
- Build and release → Process entry: packages binary