HostKeeper/docs/ARCHITECTURE.md

Architecture

Overview

Hostkeeper follows a layered architecture:

CLI Layer (cmd/hostkeeper/)
  |
  | calls
  v
Application Layer (pkg/)
  |
  | calls
  v
Storage Layer (pkg/config/, pkg/storage/)
  |
  | reads/writes
  v
File System (~/.config/hostkeeper/)

Directory Structure

cmd/hostkeeper/       — CLI commands (Cobra)
  ├── main.go         — Entry point
  ├── root.go         — Root command setup
  ├── add.go          — Add host command
  ├── list.go         — List hosts command
  ├── connect.go      — Connect command
  ├── edit.go         — Edit host command
  ├── delete.go       — Delete host command
  ├── export.go       — Export command
  ├── import.go       — Import command
  ├── tui.go          — TUI command entry
  ├── version.go      — Version command
  ├── completion.go   — Shell completion
  └── *_test.go       — CLI command tests

pkg/                  — Library code
  ├── config/         — Configuration and data directory
  ├── models/         — Data models (Host, Key, Snippet)
  ├── storage/        — File and export/import operations
  ├── errors/         — Error types
  └── tui/            — TUI implementation (Bubble Tea)

test/                 — Test suites
  ├── integration/    — End-to-end integration tests
  └── storage/        — Storage tests

docs/                 — Documentation
  ├── plans/          — Design and implementation plans
  ├── INSTALLATION.md
  ├── USAGE.md
  └── ARCHITECTURE.md

Key Components

Models (pkg/models/)

The core data structures:

• Host — SSH host with address, credentials, group, tags
• Key — SSH key metadata
• Snippet — Reusable connection snippets

Configuration (pkg/config/)

Manages application configuration, data directory path, and initialization.

Storage (pkg/storage/)

Handles persistent storage:

• File-based JSON storage per data type
• Export/import with replace and merge strategies
• File permission enforcement (0600)

CLI Layer (cmd/hostkeeper/)

Each command follows a consistent pattern:

1. Parse flags
2. Load config and storage
3. Execute business logic
4. Format output

TUI (pkg/tui/)

Bubble Tea model with:

• Screen-based navigation (extensible for future screens)
• Host list view with styled output
• Keyboard-driven interaction

Data Flow

Adding a Host

User → hostkeeper add (flags) → parse args → Host model → storage.SaveHost() → JSON file

Connecting to a Host

User → hostkeeper connect <name> → findHost() by ID → resolve key → exec native SSH or Go SSH

Export/Import

Export: storage → marshal JSON → write file
Import: read file → unmarshal → strategy (merge/replace) → save all

Security

• Credential files stored with 0600 permissions
• SSH key content stored within host credentials
• Direct mode uses Go SSH client (no shell, command execution only)
• Native SSH mode delegates all terminal handling to system SSH

Future Architecture

• SQLite database for improved query capabilities
• Encrypted credential storage (age/gpg)
• Configuration encryption
• Plugin system for custom authentication methods