# 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