Skip to content

architecture.md

Latest commit

 

History

History
148 lines (106 loc) · 3.59 KB

architecture.md

File metadata and controls

148 lines (106 loc) · 3.59 KB

Architecture

Goal

KOMU CLI is structured so terminal UX, application workflows, domain models, persistence, providers, and SSH execution remain separable. The current shape is intended to support both continued CLI growth and a future desktop frontend that reuses the same backend services.

Layering

cli/

Terminal-only presentation.

  • Typer entrypoints
  • Rich rendering
  • interactive shell
  • approval prompts
  • history and explain views

services/

Application workflow layer.

  • OperationService coordinates planning, execution, repair, and history
  • PlanningService chooses playbooks first and providers second
  • SecurityService classifies command and plan risk
  • ExecutionService executes reviewed plans over SSH
  • RepairService prepares repair paths after failures
  • ExplainService turns history and plans into operator-facing explanations
  • HistoryService persists task history and reconstructs session summaries
  • ProfileService owns profile validation and active/default behavior
  • ProviderService owns routing, fallback, and provider health
  • ExtensionService discovers custom playbook and policy-pack locations

models/

Shared typed data for:

  • plans and steps
  • rollback guidance
  • inspections and execution results
  • repair attempts
  • playbooks and playbook matches
  • providers and provider selections
  • security reviews and risk signals
  • profiles
  • history and session records
  • explanation records
  • extension manifests

playbooks/

Verified operational flows.

  • JSON catalog metadata
  • natural-language matching
  • renderer methods that build typed plans

security/

Reusable safety policy layer.

  • pattern-based risk rules
  • policy packs
  • command review signals
  • plan review summaries

providers/

Provider abstraction.

  • adapter interface
  • built-in adapters
  • provider registry
  • capability metadata
  • controlled fallback

ssh/

Remote execution boundary.

  • session creation
  • command execution
  • environment inspection
  • connection testing
  • stdout, stderr, exit code, and timeout capture

storage/, config/, logging/

Infrastructure support.

  • local JSON persistence
  • environment loading
  • audit JSONL logs
  • session JSONL logs
  • user-scoped app paths

Desktop-ready boundaries

The CLI does not own planning or execution logic.

A future desktop frontend can reuse:

  • OperationService
  • PlanningService
  • SecurityService
  • ExecutionService
  • RepairService
  • ExplainService
  • ProfileService
  • ProviderService
  • HistoryService
  • playbook and provider registries
  • SSH and storage layers

Only the presentation surface has to change.

Trust path

The review-first flow is:

  1. resolve profile context
  2. inspect the environment when requested
  3. prefer a verified playbook
  4. fall back to provider planning only when necessary
  5. classify every command with the risk engine
  6. build a plan review summary
  7. present exact commands and rollback guidance
  8. request approval
  9. execute
  10. record history, session events, and audit logs

Extension direction

The runtime now creates extension directories for:

  • extensions/playbooks
  • extensions/policies

This lets future custom playbook catalogs and enterprise policy packs plug into the existing service graph without changing the CLI contract.

Multi-server future

KOMU is still single-profile at execution time, but the architecture now avoids dead ends:

  • plans already support target_labels
  • profiles support environments and tags
  • history records preserve profile and target context
  • the orchestration layer is not hard-coded to one forever-targeted terminal flow