1
Hexagonal Clean Architecture (Ports & Adapters)
LocalPilot is engineered using strict domain-driven hexagonal boundaries. The core business rules and verification logic have zero dependencies on CLI frameworks, TUI libraries, or specific runtime binaries.
┌────────────────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ Typer CLI (localpilot) │ Textual TUI (Visual Hub) │
└─────────────────────────────────┬──────────────────────────────────────┘
▼
┌────────────────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER │
│ SetupWorkflow │ UpdateWorkflow │ JobManager │ ActivityService │
└─────────────────────────────────┬──────────────────────────────────────┘
▼
┌────────────────────────────────────────────────────────────────────────┐
│ DOMAIN LAYER │
│ CompatibilityPolicy │ ScoringPolicy │ ExecutionPlan │ VerifiedState │
└──────────────┬──────────────────┬──────────────────────┬───────────────┘
▼ ▼ ▼
┌──────────────────────┐ ┌──────────────────┐ ┌─────────────────────────┐
│ PLATFORM ADAPTERS │ │ SOURCE ADAPTERS │ │ RUNTIME ADAPTERS │
│ Linux / Darwin │ │ Ollama Registry │ │ llama.cpp runner │
│ Hardware Inspector │ │ HuggingFace Hub │ │ Ollama API Client │
│ Metal / CUDA check │ │ Local Seed DB │ │ LM Studio Client │
└──────────────────────┘ └──────────────────┘ └─────────────────────────┘
localpilot.domain
Pure Python entities: HardwareSnapshot, ExecutionPlan, CompatibilityCheckResult, scoring heuristics, and evidence-based state transitions.
localpilot.application
Transactional use cases: multi-step model staging, atomic download rollback, non-destructive inventory reconciliation, and background job state.
localpilot.runtimes
Isolated infrastructure adapters: socket probes, subprocess launchers, PID isolation, and HTTP API clients with strict timeouts.