# Architecture Decisions Summary -- LLMHosts.com

## ALWAYS APPLY
Reference these decisions when making implementation choices. Full ADRs in docs/architecture/.

## ADR-001: Intelligent Router → Three-tier hybrid router (kNN + ModernBERT + Qwen-0.5B). REVISED.
- **Architecture**: <1GB VRAM. Rule-based Tier 0, kNN Tier 1 (75%, <15ms), ModernBERT Tier 2 (20%, <50ms), Qwen-0.5B Tier 3 (5%, <500ms).
- **Why**: Graduated complexity -- most requests handled by fast kNN, only edge cases hit the LLM tier. No 8B model needed for routing.
- **Full ADR**: docs/architecture/adr-001-orchestrator-model.md

## ADR-002: Inference Engines → Ollama-primary, vLLM upgrade path, exo LAN-only. SUPERSEDED.
- **Ollama**: Primary engine ("Ollama Inside"). Discovers existing installations, wraps them. 90% of users.
- **vLLM**: Opt-in for power users with dedicated NVIDIA GPUs. Real upgrade path, not afterthought.
- **exo**: LAN-only clusters (same subnet, <1ms latency). NOT used for WAN/Hive Mode.
- **Cloud API**: BYOK fallback for frontier models and cold start.
- **Full ADR**: docs/architecture/adr-002-inference-engine.md

## ADR-003: API Proxy → LiteLLM + Custom Conductor Strategy
- LiteLLM proxy handles: routing, fallback, rate limiting, cost tracking, 100+ providers
- Custom ConductorRoutingStrategy extends CustomRoutingStrategyBase
- Conductor decides routing, LiteLLM executes with fallback/retry
- BYOK support: users add their own external API keys
- **Full ADR**: docs/architecture/adr-003-api-proxy.md

## ADR-004: Networking → Phased approach + IslandRun Privacy Routing. REVISED.
- **Phase 1**: Localhost only. No networking complexity.
- **Phase 2**: Tailscale/Cloudflare auto-detect (`llmhost tunnel`). Personal remote access.
- **Phase 3**: Headscale for Hive Mode coordination only.
- **OpenZiti**: Deferred to Phase 4+ enterprise.
- IslandRun pattern: tiered trust (personal=1.0, private=0.7, external=0.4)
- PII detection before external API routing
- **Full ADR**: docs/architecture/adr-004-security-overlay.md

## ADR-005: Frontend → Next.js + TailwindCSS + shadcn/ui
- React ecosystem for complex dashboard UI
- shadcn/ui for production-ready accessible components
- WebSocket for real-time compute metrics
- **Full ADR**: docs/architecture/adr-005-frontend-framework.md

## ADR-006: Tool Protocol → Model Context Protocol (MCP)
- Each compute node runs MCP server exposing capabilities
- Conductor acts as MCP Host connecting to all nodes
- Dynamic tool discovery + real-time notifications
- Growing ecosystem adds integrations automatically
- **Full ADR**: docs/architecture/adr-006-tool-protocol.md

## ADR-007: Containers → Docker Compose + K3s
- Docker Compose for dev and small deployments (1-5 users)
- K3s for production scaling (50+ users)
- All services have Dockerfiles, health checks
- **Full ADR**: docs/architecture/adr-007-container-strategy.md

## ADR-008: Distribution → CLI-first, tiered pip install, Anthropic dialect. REVISED.
- **Install tiers**: `pip install llmhost` (core ~50MB), `llmhost[smart]` (~150MB, +ModernBERT), `llmhost[full]` (~2GB, +Qwen-0.5B)
- **CLI-first**: `llmhost serve`, `llmhost tunnel`, `llmhost keys`, `llmhost doctor`
- **API compatibility**: OpenAI + Anthropic API dialect support via LiteLLM + custom adapter
- **Full ADR**: docs/architecture/adr-008-distribution.md

## HIVE.CEO ARCHITECTURE DECISIONS (ADR-H series)
The Hive.CEO embedded agent system has 10 ADRs. Full details in: `/home/dev/projects/admin/aut-o.com/prompts/Hive/knowledge-base/design-decisions.md`
- **ADR-H01**: Embedded vs External → Embedded (agents live inside the app, not external)
- **ADR-H02**: Communication → Hub-and-spoke through CEO (exception: Watcher→Builder fast path)
- **ADR-H03**: Autonomy → Human-in-the-loop by default (configurable auto-approve for low-risk)
- **ADR-H04**: Code Changes → GitHub PRs exclusively (never direct modification)
- **ADR-H05**: Organization → Adaptive (5 agents default, can split/merge/add/rename as app evolves)
- **ADR-H06**: Memory → Institutional (.hive/memory/ persists across sessions, not context-dependent)
- **ADR-H07**: Design Philosophy → Evolution-first (assumes app WILL pivot; detects and adapts)
- **ADR-H08**: Self-Healing → 4-tier escalation (Restart→Known Fix→Diagnose→Escalate)
- **ADR-H09**: Integration → Progressive enhancement (app works without Hive)
- **ADR-H10**: Skill Automation → 5+ successful applications with 70%+ success rate → crystallize to skill

**NOTE**: Hive.CEO (embedded agent system managing the app) is DIFFERENT from Hive Mode (Phase 3 user-facing GPU pooling feature).
