# User Flows -- LLMHosts.com

## META
- created: 2026-02-14
- references: prd.md, ui-ux-spec, wireframes/
- format: Mermaid diagrams (machine-readable, version-controllable)

---

## 1. FIRST-TIME SETUP FLOW (Persona: Alex)

The most critical flow. Time target: <5 minutes from `pip install` to first value.

```mermaid
flowchart TD
    A[pip install llmhosts] --> B{Ollama installed?}
    B -->|Yes| C[llmhosts serve]
    B -->|No| D[Print: Install Ollama first<br/>ollama.com/download]
    D --> E[User installs Ollama + pulls model]
    E --> C
    C --> F[Auto-discover Ollama models]
    F --> G[Print API endpoints:<br/>localhost:4000/v1/chat/completions<br/>localhost:4000/v1/messages]
    G --> H[Print: Set OPENAI_API_BASE=http://localhost:4000/v1]
    H --> I{User has BYOK keys?}
    I -->|Yes| J[llmhosts keys add openai sk-xxx]
    I -->|No| K[Skip - local only mode]
    J --> L[First request through proxy]
    K --> L
    L --> M[TUI shows: request routed, cost $0.00]
    M --> N[Dashboard: localhost:4000/dashboard]
    N --> O[Baseline capture: How much do you spend on AI monthly?]
    O --> P[✅ ACTIVATED: User sees savings ticker moving]
```

## 2. DAILY USE FLOW (Core Value Loop)

The action the user repeats every day. Must be invisible.

```mermaid
flowchart TD
    A[Developer opens Cursor/Claude Code/Aider] --> B[Tool sends request to localhost:4000]
    B --> C{Cache check}
    C -->|Exact hit| D[Return cached response<br/>Cost: $0, Latency: <5ms]
    C -->|Namespace hit| E[Return cached response<br/>Cost: $0, Latency: <10ms]
    C -->|Semantic hit| F[Return cached response<br/>Cost: $0, Latency: <30ms]
    C -->|Miss| G{Router decision}
    G -->|Tier 0: Rule| H[Route to matching backend]
    G -->|Tier 1: kNN| I[Embed → FAISS lookup → select]
    G -->|Tier 2: ModernBERT| J[6-signal classify → select]
    G -->|Tier 3: Qwen| K[LLM reason → select]
    H --> L{Backend}
    I --> L
    J --> L
    K --> L
    L -->|Local Ollama| M[Inference on GPU<br/>Cost: $0]
    L -->|Cloud API| N[Forward to provider<br/>Cost: token pricing]
    L -->|vLLM| O[Inference via vLLM<br/>Cost: $0]
    M --> P[Response + llmhosts metadata]
    N --> P
    O --> P
    P --> Q[Cache store for future hits]
    Q --> R[Metrics logged: cost, latency, routing tier]
    R --> S[Dashboard updates in real-time]
    D --> S
    E --> S
    F --> S
```

## 3. TUNNEL SETUP FLOW (Persona: Alex -- The Conversion Moment)

This is the free → paid conversion trigger. The "holy shit" moment.

```mermaid
flowchart TD
    A[User at coffee shop, wants to use home GPU] --> B[llmhosts tunnel]
    B --> C{Detect tunnel tools}
    C -->|Tailscale found| D[Configure Tailscale Funnel]
    C -->|Cloudflare found| E[Configure Cloudflare Tunnel]
    C -->|Neither found| F[Print: Install Tailscale or Cloudflare Tunnel<br/>tailscale.com or cloudflare.com/tunnel]
    F --> G[User installs tunnel tool]
    G --> C
    D --> H[Generate HTTPS URL<br/>e.g., mybox.ts.net:4000]
    E --> H
    H --> I[Print: Your GPU is now accessible at<br/>https://xxx.ts.net/v1]
    I --> J[Print: On your laptop, set<br/>OPENAI_API_BASE=https://xxx.ts.net/v1]
    J --> K[User configures Cursor on laptop]
    K --> L[First remote request]
    L --> M[Request → tunnel → home GPU → response]
    M --> N[Dashboard shows: Remote request served<br/>Model: llama3.2:8b, Cost: $0.00]
    N --> O[🎉 Holy shit moment:<br/>My 4090 at home is serving my laptop right now]
    O --> P{Free tier limit reached?}
    P -->|Multi-device needed| Q[Upgrade prompt: Pro $19/mo<br/>for 5 devices + cloud intelligence]
    P -->|Single device OK| R[Continue free]
```

## 4. UPGRADE FLOW (Free → Pro)

```mermaid
flowchart TD
    A[User hits upgrade trigger] --> B{Which trigger?}
    B -->|Multi-device limit| C[Dashboard: You have 2+ devices.<br/>Pro supports 5 for $19/mo]
    B -->|Cloud dashboard interest| D[Dashboard: See your AI spending<br/>across all providers for $19/mo]
    B -->|Tunnel coordination| E[Dashboard: Pro includes managed<br/>tunnel coordination]
    C --> F[Click: Upgrade to Pro]
    D --> F
    E --> F
    F --> G[Redirect to LLMHosts.com/pricing]
    G --> H[Stripe Checkout: $19/mo or $190/yr]
    H --> I{Payment success?}
    I -->|Yes| J[API key issued]
    I -->|No| K[Show error, retry option]
    K --> H
    J --> L[llmhosts config set api_key xxx]
    L --> M[Pro features activated:<br/>multi-device, cloud dashboard, tunnel coord]
    M --> N[Dashboard shows Pro badge]
```

## 5. ERROR RECOVERY FLOW

```mermaid
flowchart TD
    A[Request arrives at proxy] --> B{Proxy healthy?}
    B -->|No| C[Return 503 with helpful error:<br/>llmhosts serve not running]
    B -->|Yes| D{Cache check}
    D --> E{Router decision}
    E --> F{Backend call}
    F -->|Ollama timeout| G[Retry once with 2x timeout]
    G -->|Still fails| H{Cloud keys available?}
    H -->|Yes| I[Fallback to cloud API]
    H -->|No| J[Return 503: Local model unavailable,<br/>no cloud keys configured.<br/>Add with: llmhosts keys add openai sk-xxx]
    I -->|Cloud fails| K[Return 502: All backends unavailable]
    I -->|Cloud succeeds| L[Response + metadata:<br/>backend: openai (fallback from ollama)]
    F -->|Cloud rate limit| M[Return 429 with Retry-After header]
    F -->|Cloud auth error| N[Return 401: API key invalid.<br/>Update with: llmhosts keys add openai sk-xxx]
    F -->|Success| O[Normal response flow]
```

## 6. HIVE MODE JOIN FLOW (Phase 3 -- Persona: Alex + friends)

```mermaid
flowchart TD
    A[Friend shares Hive invite code] --> B[llmhosts hive join ABC123]
    B --> C{Pro subscription active?}
    C -->|No| D[Print: Hive Mode requires Team plan<br/>$49/seat/mo. Upgrade at llmhosts.com/pricing]
    C -->|Yes| E[Connect to Headscale coordination server]
    E --> F[WireGuard mesh established with Hive members]
    F --> G[Discover peer GPU capabilities]
    G --> H[Router now includes Hive peers as backends]
    H --> I[Dashboard shows: Hive ABC123<br/>3 members, 2x 4090 + 1x 3080]
    I --> J{Request arrives}
    J --> K{Contains PII?}
    K -->|Yes| L[Route LOCAL ONLY<br/>Never send to Hive peer]
    K -->|No| M{Best backend?}
    M -->|Local GPU| N[Process locally]
    M -->|Peer GPU has better model| O[Route to peer via WireGuard]
    M -->|Cloud| P[Route to cloud]
    N --> Q[Karma: +1 contributed if peer request served]
    O --> Q
```

---

## 7. STATE MACHINES

### 7.1 Tunnel Connection States

```mermaid
stateDiagram-v2
    [*] --> Disconnected
    Disconnected --> Detecting: llmhosts tunnel
    Detecting --> TailscaleFound: Tailscale detected
    Detecting --> CloudflareFound: Cloudflared detected
    Detecting --> NoTool: Neither found
    NoTool --> Disconnected: User installs tool
    TailscaleFound --> Connecting: Configure Funnel
    CloudflareFound --> Connecting: Configure Tunnel
    Connecting --> Connected: URL generated
    Connecting --> Error: Configuration failed
    Error --> Connecting: Retry
    Error --> Disconnected: Give up
    Connected --> Disconnected: llmhosts tunnel stop
    Connected --> Reconnecting: Connection lost
    Reconnecting --> Connected: Restored
    Reconnecting --> Disconnected: Timeout (30s)
```

### 7.2 Request Processing Pipeline

```mermaid
stateDiagram-v2
    [*] --> Received
    Received --> Normalized: Detect dialect (OpenAI/Anthropic)
    Normalized --> CacheCheck: Normalize to CanonicalRequest
    CacheCheck --> CacheHit: Match found
    CacheCheck --> Routing: Cache miss
    CacheHit --> ResponseReady: Return cached
    Routing --> Tier0: Rule match
    Routing --> Tier1: kNN lookup
    Routing --> Tier2: ModernBERT classify
    Routing --> Tier3: Qwen reason
    Tier0 --> BackendCall: Route decided
    Tier1 --> BackendCall: Route decided
    Tier1 --> Tier2: Low confidence
    Tier2 --> BackendCall: Route decided
    Tier2 --> Tier3: Ambiguous
    Tier3 --> BackendCall: Route decided
    BackendCall --> ResponseReady: Success
    BackendCall --> Fallback: Backend error
    Fallback --> BackendCall: Try next backend
    Fallback --> ErrorResponse: All backends failed
    ResponseReady --> CacheStore: Store for future
    CacheStore --> MetricsLog: Log cost + latency
    MetricsLog --> [*]: Return response
    ErrorResponse --> MetricsLog: Log error
```

---

## 8. SEQUENCE DIAGRAMS

### 8.1 Standard Request Flow

```mermaid
sequenceDiagram
    participant User as AI Tool (Cursor/etc)
    participant Proxy as LLMHosts Proxy
    participant Cache as vCache
    participant Router as Three-Tier Router
    participant Ollama as Ollama (local)
    participant Cloud as Cloud API
    participant DB as Metrics DB
    participant WS as WebSocket (Dashboard)

    User->>Proxy: POST /v1/chat/completions
    Proxy->>Proxy: Detect dialect, normalize
    Proxy->>Cache: Check (hash → namespace → semantic)
    alt Cache Hit
        Cache-->>Proxy: Cached response
        Proxy->>DB: Log (cache hit, cost $0)
        Proxy->>WS: Push update
        Proxy-->>User: Response + llmhosts metadata
    else Cache Miss
        Proxy->>Router: Route request
        Router->>Router: Tier 0 rules → Tier 1 kNN → Tier 2/3 if needed
        Router-->>Proxy: RoutingDecision {backend, model, reason}
        alt Local Route
            Proxy->>Ollama: Forward request
            Ollama-->>Proxy: Response (streaming)
        else Cloud Route
            Proxy->>Cloud: Forward request (BYOK key)
            Cloud-->>Proxy: Response (streaming)
        end
        Proxy->>Cache: Store response
        Proxy->>DB: Log (model, cost, latency, routing tier)
        Proxy->>WS: Push update
        Proxy-->>User: Response + llmhosts metadata
    end
```

### 8.2 Tunnel Remote Access Flow

```mermaid
sequenceDiagram
    participant Laptop as Laptop (coffee shop)
    participant Tunnel as Tailscale/Cloudflare
    participant Home as Home Machine (GPU)
    participant Proxy as LLMHosts Proxy
    participant Ollama as Ollama

    Laptop->>Tunnel: POST https://xxx.ts.net/v1/chat/completions
    Tunnel->>Home: Forward (encrypted WireGuard/TLS)
    Home->>Proxy: localhost:4000/v1/chat/completions
    Proxy->>Proxy: Cache check → Router → Backend selection
    Proxy->>Ollama: Forward to local model
    Ollama-->>Proxy: Response stream
    Proxy-->>Home: Response + metadata
    Home-->>Tunnel: Response (encrypted)
    Tunnel-->>Laptop: Response
    Note over Laptop: Total added latency: ~20-50ms<br/>(tunnel overhead)
```
