feat: Machine-Hosted MeticAI PWA — Implementation Plan

[hessius]

Implementation Plan: Machine-Hosted MeticAI PWA

Branch: feat/machine-hosted-pwa (from main after v2.3.0 merges)
Milestone: 2.4
Related: #305 (Feasibility Study), #253 (Capacitor App)

Overview

Port MeticAI's React frontend to run directly on the Meticulous machine as a static PWA served by Tornado's StaticFileHandler. The frontend communicates with the machine API directly via @meticulous-home/espresso-api and with Google Gemini directly via @google/genai. No Python backend required for the machine-hosted deployment.

Resource impact: ~6.5 MB disk (~3% of free space), zero additional RAM, negligible CPU.

Code sharing with Capacitor app (#253): ~85%. Phases 1–6 are fully reusable by both deployment targets. Only Phase 7 (install scripts) and Phase 9 (service worker) are PWA-specific.

---

Architecture

Current (Docker)

┌────────────┐     ┌─────────────────────────────────┐     ┌──────────────┐
│  Browser   │────▶│ MeticAI Docker Container         │────▶│ Meticulous   │
│            │     │ nginx → FastAPI → pyMeticulous   │     │ Machine      │
│            │◀────│       → MQTT Bridge → Socket.IO  │◀────│ REST + SIO   │
└────────────┘     └─────────────────────────────────┘     │ :8080        │
                   Port 3550                                └──────────────┘

Target (Machine-Hosted PWA)

┌────────────┐     ┌──────────────────┐
│  Browser   │────▶│ Meticulous       │
│            │     │ Machine          │  ← Same origin, no CORS/PNA issues
│  React App │◀────│ Tornado :8080    │
│  + SIO     │     │ /meticai/* (static)│
│  + Gemini  │     │ /api/v1/* (REST)  │
│            │     │ /socket.io (SIO)  │
└────────────┘     └──────────────────┘
       │
       │ HTTPS (cross-origin, allowed)
       ▼
┌──────────────┐
│ Google Gemini│
│ Cloud API    │
└──────────────┘

---

Phase 1: MachineService Abstraction Layer

Create an adapter pattern that both the machine-hosted PWA and future Capacitor app share.

1.1 — MachineService Interface

File: src/services/machine/MachineService.ts

interface MachineService {
  // Connection
  connect(url: string): Promise<void>
  disconnect(): void
  isConnected(): boolean
  onConnectionChange(cb: (connected: boolean) => void): void

  // Profiles
  listProfiles(): Promise<ProfileIdent[]>
  fetchAllProfiles(): Promise<Profile[]>
  getProfile(id: string): Promise<Profile>
  saveProfile(profile: Profile): Promise<void>
  deleteProfile(id: string): Promise<void>
  loadProfileById(id: string): Promise<void>
  loadProfileFromJSON(profile: object): Promise<void>

  // Actions
  executeAction(action: ActionType): Promise<void>

  // Telemetry (real-time)
  onStatus(cb: (data: StatusData) => void): () => void
  onActuators(cb: (data: Actuators) => void): () => void
  onNotification(cb: (data: Notification) => void): () => void

  // History
  getHistoryListing(): Promise<HistoryEntry[]>
  getShotData(date: string, filename: string): Promise<ShotData>
  getLastShot(): Promise<HistoryEntry | null>

  // Settings
  getSettings(): Promise<Settings>
  updateSetting(key: string, value: unknown): Promise<void>
  getDeviceInfo(): Promise<DeviceInfo>
}

1.2 — ProxyAdapter

File: src/services/machine/ProxyAdapter.ts

• Wraps current fetch() calls to MeticAI FastAPI backend
• Used by Docker deployment (existing architecture, zero behavior change)
• Acts as a drop-in replacement for the current scattered fetch calls

1.3 — DirectAdapter

File: src/services/machine/DirectAdapter.ts

• Wraps @meticulous-home/espresso-api (v0.10.11)
• HTTP via axios (profiles, actions, history, settings)
• Socket.IO via socket.io-client (telemetry: status, actuators, notifications)
• Used by machine-hosted PWA and Capacitor app
• Handles .zst decompression via fzstd library for shot data

1.4 — Provider & Selection

File: src/services/machine/MachineServiceProvider.tsx

• React context provider: <MachineServiceProvider>
• Hook: useMachineService(): MachineService
• Selection logic:
  • Build-time: VITE_MACHINE_MODE=direct|proxy
  • Runtime fallback: if window.location.port === '8080' → direct mode

1.5 — Type Definitions

• Import Profile, ProfileIdent, StatusData, Actuators etc. from @meticulous-home/espresso-profile
• Create mapping layer between espresso-api types and our existing MachineProfile, MachineState types

---

Phase 2: AI Service Abstraction

2.1 — AIService Interface

File: src/services/ai/AIService.ts

interface AIService {
  isConfigured(): boolean
  
  // Profile generation
  generateProfile(
    image: Blob | null,
    preferences: ProfilePreferences,
    onProgress?: (event: ProgressEvent) => void
  ): Promise<ProfileResult>
  
  // Shot analysis
  analyzeShot(
    shotData: ShotData,
    profileName: string,
    profileDescription?: string
  ): Promise<string>
  
  // Image generation
  generateImage(
    profileName: string,
    style: string,
    profileData?: object
  ): Promise<Blob>
  
  // Recommendations
  getRecommendations(context: RecommendationContext): Promise<Recommendation[]>
}

2.2 — ProxyAIService

File: src/services/ai/ProxyAIService.ts

• Wraps current backend endpoints (/api/analyze_and_profile, /api/shots/analyze-llm, etc.)
• Used by Docker deployment

2.3 — BrowserAIService

File: src/services/ai/BrowserAIService.ts

• Uses @google/genai JavaScript SDK directly in the browser
• User provides own Gemini API key (stored in localStorage with clear disclosure)
• Streaming support via generateContentStream() for progress events
• Image generation via Imagen model endpoint
• API key security: Gemini API keys can be restricted to specific HTTP referrers via Google Cloud Console, mitigating exposure risk

2.4 — Prompt Builders (TypeScript Port)

Port the Python prompt_builder.py (732 lines) to TypeScript:

Python Module	TypeScript File	Purpose
prompt_builder.py build()	src/services/ai/prompts/ProfilePromptBuilder.ts	Profile generation system prompt
prompt_builder.py CORE_SAFETY_CONSTRAINTS	src/services/ai/prompts/ImagePromptBuilder.ts	Imagen prompt construction
Shot analysis prompt (in routes)	src/services/ai/prompts/AnalysisPromptBuilder.ts	Shot analysis system prompt
Recommendation prompt (in routes)	src/services/ai/prompts/RecommendationPromptBuilder.ts	Profile recommendations

Each prompt builder mirrors the Python version exactly to ensure identical AI output quality.

2.5 — API Key Management

• Settings page: text input for Gemini API key (already exists)
• Storage: localStorage (consistent with current UX where user enters key)
• Warning banner: "Your API key is stored locally in this browser"
• Optional "session-only" toggle: key stored in memory only, cleared on tab close
• Validation: test call to Gemini on save, show error if invalid

---

Phase 3: IndexedDB Persistence Layer

3.1 — Database Schema

File: src/services/storage/AppDatabase.ts
Using idb library (lightweight IndexedDB wrapper, ~1.2 KB gzipped):

interface AppDB extends DBSchema {
  settings: {
    key: string
    value: { key: string; value: unknown; updatedAt: number }
  }
  'shot-annotations': {
    key: string // "{date}/{filename}"
    value: {
      shotKey: string
      rating: number | null
      notes: string
      tags: string[]
      updatedAt: number
    }
    indexes: { 'by-rating': number }
  }
  'ai-cache': {
    key: string // hash of shot data
    value: {
      cacheKey: string
      analysis: string
      createdAt: number
      expiresAt: number
    }
    indexes: { 'by-expiry': number }
  }
  'pour-over-state': {
    key: string // "default"
    value: {
      coffeeWeight: number
      brewRatio: number
      bloomAmount: number
      bloomTime: number
      updatedAt: number
    }
  }
  'dial-in-sessions': {
    key: string // session ID
    value: {
      id: string
      coffee: CoffeeDetails
      steps: DialInStep[]
      createdAt: number
    }
    indexes: { 'by-date': number }
  }
  'profile-images': {
    key: string // profile ID
    value: {
      profileId: string
      imageBlob: Blob
      updatedAt: number
    }
  }
}

3.2 — Cache Management

• AI cache: TTL-based expiry (7 days default), auto-cleanup on app start
• Profile images: LRU eviction when total exceeds 50 MB
• Estimate total IndexedDB usage: 10–100 MB depending on cached images

3.3 — Migration Hook

• useStorageMigration() hook runs on app mount
• Detects first-run (no IndexedDB) → initializes defaults
• Future: version-based schema migrations

---

Phase 4: Direct Socket.IO Telemetry

4.1 — Replace WebSocket Chain

Current: Machine(SIO :8080) → Bridge(MQTT) → Server(WS) → Browser
New: Machine(SIO :8080) → Browser (direct via espresso-api)

4.2 — Hook Adaptation

File: src/hooks/useWebSocket.ts → refactor to src/hooks/useMachineTelemetry.ts

function useMachineTelemetry(): MachineState {
  const machine = useMachineService()
  const [state, setState] = useState<MachineState>(initialState)

  useEffect(() => {
    const unsub1 = machine.onStatus((data) => {
      setState(prev => ({
        ...prev,
        temperature: data.temperature,
        pressure: data.pressure,
        weight: data.weight,
        flow: data.flow_rate,
        // ... field mapping
      }))
    })
    const unsub2 = machine.onActuators((data) => {
      setState(prev => ({ ...prev, power: data.power }))
    })
    return () => { unsub1(); unsub2() }
  }, [machine])

  return state
}

4.3 — Field Mapping

The machine's Socket.IO status event fields may differ slightly from our MachineState type. Create a mapping layer:

Machine (StatusData)	MeticAI (MachineState)
temperature	temperature
pressure	pressure
weight	weight
flow_rate	flow
shot_time	timer
state	machineState

4.4 — Connection Status

• Expose connection state: connected | disconnected | reconnecting
• Auto-reconnect with exponential backoff (built into socket.io-client)
• Visual indicator in header/footer bar

---

Phase 5: Feature Triage

✅ KEEP (works in browser, no server needed)

Feature	How	Notes
Profile CRUD	espresso-api REST	Direct to machine
Start/Stop/Preheat	espresso-api.executeAction()	Direct to machine
Real-time telemetry	espresso-api Socket.IO	Direct to machine
Shot history browsing	espresso-api.getHistoryShortListing()	+ fzstd for .zst
Shot data visualization	Client-side Recharts	Already browser-only
Profile generation (AI)	@google/genai direct	User's own API key
Shot analysis (AI)	@google/genai direct	Cached in IndexedDB
Image generation (AI)	Imagen via @google/genai	User's own API key
Profile recommendations	Token-free engine + Gemini	Local scoring + optional AI
Pour-over mode	Timer + espresso-api commands	State in IndexedDB
Espresso compass	Client-side + Gemini	Direct AI calls
Variable adjustments	espresso-api.loadProfileFromJSON()	Ephemeral loading
Profile validation	@meticulous-home/espresso-profile	Pure TS, zero deps
Shot annotations	IndexedDB	Local storage
Profile image cache	IndexedDB blob store	LRU eviction
i18n (6 languages)	Static JSON bundles	Already client-side
Dark/light theme	CSS/localStorage	Already client-side
PWA install prompt	manifest.json (exists) + service worker	Add SW

❌ REMOVE (requires server infrastructure)

Feature	Reason	Impact
mDNS auto-discovery	Browsers can't do mDNS	Low — user enters IP or uses meticulous.local
Scheduled/recurring shots	No persistent scheduler in browser	Low — manual shot start
Profile cloud sync	No server-side storage	None — machine is source of truth
System restart/update	Requires OS access	None — use machine's own UI
Tailscale configuration	CLI tool	None — not core feature
MCP server	Server-side tool integration	None — not user-facing

🟡 DEGRADE (partial functionality change)

Feature	Change	Solution
.zst shot decompression	Python zstd → JS	fzstd library (2.4 KB gzipped)
Generation progress	SSE from backend → Gemini streaming	generateContentStream() native
AI analysis caching	Server DB → browser	IndexedDB with 7-day TTL
Machine connectivity check	Server-side health check	Browser fetch with timeout

---

Phase 6: Build Configuration

6.1 — package.json Scripts

{
  "scripts": {
    "build": "tsc -b --noCheck && vite build",
    "build:machine": "VITE_MACHINE_MODE=direct tsc -b --noCheck && vite build",
    "build:docker": "VITE_MACHINE_MODE=proxy tsc -b --noCheck && vite build",
    "test:run": "vitest run",
    "test:direct": "VITE_MACHINE_MODE=direct vitest run"
  }
}

6.2 — New Dependencies

Package	Version	Size (gzipped)	Purpose
@meticulous-home/espresso-api	^0.10.11	~15 KB	Machine API client
@meticulous-home/espresso-profile	^0.4.2	~5 KB	Profile types & validation
@google/genai	^1.46.0	~25 KB	Gemini JS SDK
idb	^8.x	~1.2 KB	IndexedDB wrapper
fzstd	^0.1.x	~2.4 KB	Zstandard decompression
vite-plugin-pwa	^0.21.x	dev only	Service worker generation

Build size impact: ~50–80 KB additional gzipped. Total: ~800 KB gzipped, ~6.5 MB on disk.

6.3 — Vite Environment Variables

VITE_MACHINE_MODE=direct|proxy    # Adapter selection
VITE_DEFAULT_MACHINE_URL=http://meticulous.local  # Machine URL default

6.4 — Tree Shaking

• proxy build excludes: espresso-api, espresso-profile, @google/genai, fzstd
• direct build excludes: ProxyAdapter, ProxyAIService
• Conditional imports via dynamic import() keyed on VITE_MACHINE_MODE

6.5 — Service Worker

File: src/sw.ts (generated via vite-plugin-pwa)

Strategies:

• Static assets (JS, CSS, images, locale JSON): CacheFirst with versioned cache names
• Machine API responses (profiles, settings): NetworkFirst with 5s timeout → fall back to cache
• AI responses: NetworkOnly (no caching of Gemini calls in SW)
• Offline mode: Show cached profiles and history, disable machine commands with "offline" badge

---

Phase 7: Machine-Side Installation

7.1 — Install Script (install-meticai.sh)

#!/bin/bash
set -euo pipefail
METICAI_VERSION="${1:-latest}"
INSTALL_DIR="/opt/meticai-web"

echo "=== MeticAI PWA Installer v${METICAI_VERSION} ==="

# Pre-flight resource checks
FREE_DISK_MB=$(df -m / | awk 'NR==2{print $4}')
FREE_RAM_MB=$(free -m | awk '/Mem:/{print $7}')
echo "Free disk: ${FREE_DISK_MB} MB | Free RAM: ${FREE_RAM_MB} MB"

if [ "$FREE_DISK_MB" -lt 20 ]; then
    echo "ERROR: Need ≥20 MB free disk (have ${FREE_DISK_MB} MB)"; exit 1
fi

# Download release artifact
if [ "$METICAI_VERSION" = "latest" ]; then
    RELEASE_URL=$(curl -fsSL https://api.github.com/repos/hessius/MeticAI/releases/latest \
        | grep "browser_download_url.*meticai-web.tar.gz" | cut -d'"' -f4)
else
    RELEASE_URL="https://github.com/hessius/MeticAI/releases/download/v${METICAI_VERSION}/meticai-web.tar.gz"
fi

echo "Downloading from: ${RELEASE_URL}"
curl -fsSL "$RELEASE_URL" -o /tmp/meticai-web.tar.gz
DOWNLOAD_SIZE=$(du -m /tmp/meticai-web.tar.gz | cut -f1)
echo "Download: ${DOWNLOAD_SIZE} MB"

# Backup existing
[ -d "$INSTALL_DIR" ] && mv "$INSTALL_DIR" "${INSTALL_DIR}.bak.$(date +%s)"

# Extract
mkdir -p "$INSTALL_DIR"
tar -xzf /tmp/meticai-web.tar.gz -C "$INSTALL_DIR"
rm /tmp/meticai-web.tar.gz

# Report
FILE_COUNT=$(find "$INSTALL_DIR" -type f | wc -l)
INSTALL_SIZE=$(du -sm "$INSTALL_DIR" | cut -f1)
FREE_AFTER=$(df -m / | awk 'NR==2{print $4}')
echo ""
echo "Installed: ${FILE_COUNT} files, ${INSTALL_SIZE} MB"
echo "Free disk after: ${FREE_AFTER} MB"
echo ""
echo "=== Next: Add Tornado route (see README) ==="
echo "Access at: http://meticulous.local:8080/meticai/"

7.2 — Tornado Route Configuration

Add to meticulous-backend/api/web_ui.py:

METICAI_HANDLER = [
    (r"/meticai", tornado.web.RedirectHandler, {"url": "/meticai/"}),
    (r"/meticai/(.*)", tornado.web.StaticFileHandler, {
        "default_filename": "index.html",
        "path": "/opt/meticai-web",
    }),
]

# In WEB_UI_HANDLER list, add:
# WEB_UI_HANDLER.extend(METICAI_HANDLER)

This follows the exact same pattern as the existing /debug/* static file handler.

7.3 — Validation Script (validate-meticai.sh)

#!/bin/bash
echo "=== MeticAI Installation Validation ==="
echo ""

# Disk
echo "--- Disk ---"
df -h / | awk 'NR==2{printf "Total: %s | Used: %s | Free: %s | Use: %s\n",$2,$3,$4,$5}'
du -sh /opt/meticai-web 2>/dev/null && echo "" || echo "NOT INSTALLED"

# Memory
echo "--- Memory ---"
free -m | awk '/Mem:/{printf "Total: %s MB | Used: %s MB | Available: %s MB\n",$2,$3,$7}'
echo ""

# Files
echo "--- Files ---"
if [ -f "/opt/meticai-web/index.html" ]; then
    echo "index.html: OK"
    echo "Total files: $(find /opt/meticai-web -type f | wc -l)"
    echo "JS chunks: $(find /opt/meticai-web -name '*.js' | wc -l)"
    echo "CSS files: $(find /opt/meticai-web -name '*.css' | wc -l)"
else
    echo "ERROR: index.html not found!"
fi
echo ""

# Routes
echo "--- Routes ---"
HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/meticai/ 2>/dev/null)
echo "GET /meticai/: HTTP $HTTP_CODE"
[ "$HTTP_CODE" = "200" ] && echo "  ✅ Route working" || echo "  ❌ Route not configured"

# Machine API
echo ""
echo "--- Machine API ---"
API_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/v1/profile 2>/dev/null)
echo "GET /api/v1/profile: HTTP $API_CODE"

echo ""
echo "=== Done ==="

7.4 — Update Script (update-meticai.sh)

Same as install but with automatic backup + cleanup of old backups (keep last 2).

7.5 — Uninstall Script (uninstall-meticai.sh)

#!/bin/bash
echo "Removing MeticAI PWA..."
rm -rf /opt/meticai-web /opt/meticai-web.bak.*
echo "Removed. Remember to remove the Tornado route from web_ui.py."

---

Phase 8: CI/CD Pipeline

8.1 — Release Workflow Addition

# In .github/workflows/release.yml (or new workflow)
build-machine-pwa:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - uses: oven-sh/setup-bun@v2
    - run: cd apps/web && bun install
    - run: cd apps/web && VITE_MACHINE_MODE=direct bun run build
    - run: tar -czf meticai-web.tar.gz -C apps/web/dist .
    - uses: softprops/action-gh-release@v2
      with:
        files: meticai-web.tar.gz

8.2 — Test Matrix

• Existing test suite validates proxy mode (Docker) — unchanged
• New test file: DirectAdapter.test.ts — mocks espresso-api responses
• New test file: BrowserAIService.test.ts — mocks @google/genai
• New test file: AppDatabase.test.ts — uses fake-indexeddb for IndexedDB tests
• CI runs both test:run and test:direct

---

Development Sequence & Dependencies

Phase 1.1 (Interface)  ──▶  Phase 1.2 (Proxy)     ──┐
         │                                             │
         └──▶ Phase 1.3 (Direct) ──▶ Phase 4 (SIO)   │
                                         │             │
Phase 2.1 (AI Interface) ──▶ Phase 2.2 (ProxyAI) ──┤
         │                                             │
         └──▶ Phase 2.3 (BrowserAI)                   │
         └──▶ Phase 2.4 (Prompts TS)                  │
                                                       │
Phase 3 (IndexedDB) ──────────────────────────────────┤
                                                       │
Phase 5 (Triage) ◀────────────────────────────────────┘
         │
         ▼
Phase 6 (Build Config) ──▶ Phase 7 (Install Scripts)
         │                  Phase 8 (CI/CD)
         ▼
Phase 9 (Service Worker)

Parallelizable: Phases 1, 2, 3 can all start simultaneously.

---

Shared Code with Capacitor App (#253)

Phase	Shared?	Notes
1. MachineService + DirectAdapter	✅ 100%	Same interface, same adapter
2. AIService + BrowserAI	✅ 100%	Same prompts, same SDK
3. IndexedDB persistence	✅ 100%	Same schema, same hooks
4. Socket.IO telemetry	✅ 100%	Same direct connection
5. Feature triage	✅ 100%	Same feature set
6. Build config	✅ Partially	Capacitor adds native shell
7. Install scripts	❌ PWA only	Capacitor uses app stores
8. CI/CD	✅ Partially	Capacitor adds iOS/Android builds
9. Service worker	❌ PWA only	Capacitor doesn't need SW

The Capacitor app (#253) becomes: DirectAdapter + Capacitor shell + mDNS plugin + app store packaging. All core logic is shared.

---

Open Questions / MeticulousHome Coordination

1. Tornado route: Can MeticulousHome add a /meticai/* static handler to their backend? Or do we need users to manually patch web_ui.py?
2. PNA header: Should we request adding Access-Control-Allow-Private-Network: true to base_handler.py for future-proofing?
3. App marketplace: Is MeticulousHome planning an "apps" or "plugins" system? If so, MeticAI could be distributed through it.
4. OTA updates: Could the machine's OTA system include MeticAI frontend updates?
5. Port conflict: The machine uses port 8080 for both REST and Socket.IO. Confirm this is stable and won't change.

[hessius]

Testing the Machine-Hosted PWA

Implementation Status

All 8 phases complete on feat/machine-hosted-pwa branch. 415 tests pass, 0 lint errors, both Docker and machine builds succeed.

---

Prerequisites

• SSH access to your Meticulous machine
• The machine's hostname (run hostname on the machine — it'll be something like meticulous-abc123)
• Note: The machine uses a randomized hostname (always includes "meticulous"), NOT a fixed meticulous.local

---

Step 1: Pre-Installation Benchmarks

SSH into the machine and record baseline metrics:

echo "=== PRE-INSTALL BENCHMARKS ==="
echo "--- Disk ---"
df -h /
echo "--- Memory ---"
free -m
echo "--- CPU ---"
cat /proc/loadavg
echo "--- Processes ---"
ps aux | wc -l

Save these values for comparison.

---

Step 2: Install

# From the machine:
curl -fsSL https://raw.githubusercontent.com/hessius/MeticAI/feat/machine-hosted-pwa/scripts/machine/install-meticai.sh | bash

The installer automatically:

• Checks free disk space (needs ≥20 MB)
• Downloads the latest meticai-web.tar.gz release artifact
• Backs up any existing installation
• Extracts to /opt/meticai-web
• Reports disk usage before/after

---

Step 3: Post-Installation Benchmarks

echo "=== POST-INSTALL BENCHMARKS ==="
echo "--- Disk ---"
df -h /
du -sh /opt/meticai-web
echo "--- Memory ---"
free -m
echo "--- CPU ---"
cat /proc/loadavg
echo "--- Processes ---"
ps aux | wc -l

Expected deltas:

Metric	Expected Change
Disk	~6 MB increase
RAM	0 MB (static files only)
CPU	0% (no new processes)
Processes	0 new

---

Step 4: Configure Tornado Route

Add the static file route to the machine's api/web_ui.py:

METICAI_HANDLER = [
    (r"/meticai", tornado.web.RedirectHandler, {"url": "/meticai/"}),
    (r"/meticai/(.*)", tornado.web.StaticFileHandler, {
        "default_filename": "index.html",
        "path": "/opt/meticai-web",
    }),
]

Then restart the Tornado service.

---

Step 5: Validate Installation

curl -fsSL https://raw.githubusercontent.com/hessius/MeticAI/feat/machine-hosted-pwa/scripts/machine/validate-meticai.sh | bash

Expected output: all green checks for disk, memory, CPU, files, routes, and API.

---

Step 6: Browser Testing

Open http://<your-machine-hostname>.local:8080/meticai/ and verify:

#	Test	Expected
1	App loads	Start screen with 7 navigation buttons
2	Direct mode active	Settings does NOT show Tailscale or Updates sections
3	Machine connection	Telemetry shows live temperature/pressure via Socket.IO
4	Profile catalogue	Loads profiles directly from machine API
5	Run a shot	Start/stop/tare work via direct espresso-api
6	AI features	Enter Gemini API key in Settings → test profile generation
7	PWA install prompt	Browser offers "Add to Home Screen"
8	Offline resilience	After first load, disconnect WiFi briefly — cached pages still render
9	Pour over mode	Loads correctly, remembers preferences
10	Espresso Compass	Dial-in wizard works with direct AI calls

---

Step 7: Stress Benchmarks (while using)

While actively browsing the PWA from another device:

echo "--- Under Load ---"
cat /proc/loadavg
free -m
# Monitor for 30 seconds:
vmstat 5 6

Expected: Negligible impact — Tornado serves static files, all JavaScript execution happens in the browser. The machine should see no meaningful CPU or memory increase.

---

Step 8: Uninstall (if needed)

curl -fsSL https://raw.githubusercontent.com/hessius/MeticAI/feat/machine-hosted-pwa/scripts/machine/uninstall-meticai.sh | bash

---

Architecture Summary

Before: Browser → MeticAI Docker (nginx+FastAPI+MQTT) → Machine
After:  Browser → Machine Tornado (static files + API on same origin)
        Browser → Google Gemini (direct, user's own API key)

No Python backend needed. ~6 MB on disk, zero additional RAM, zero additional CPU.

[hessius]

Updated Testing Instructions (v2)

Important: The Meticulous machine has neither curl nor wget. Use the SCP-based install method below.

---

Prerequisites

• SSH access to your Meticulous machine (find its IP on your router or via mDNS)
• The machine's hostname is randomized (e.g. meticulous-abc123.local) — run hostname on the machine to check
• A dev machine with bun installed (or use the pre-built tarball from a GitHub release)

---

Step 1: Pre-Installation Benchmarks

SSH into the machine and record baseline:

echo "=== PRE-INSTALL BENCHMARKS ==="
echo "--- Disk ---"
df -h /
echo "--- Memory ---"
free -m
echo "--- CPU ---"
cat /proc/loadavg
echo "--- Processes ---"
ps aux | wc -l

---

Step 2: Build & Transfer

On your dev machine (not the Meticulous):

cd apps/web
bun run build:machine
tar -czf meticai-web.tar.gz -C dist .

# Copy files to the machine
scp meticai-web.tar.gz root@<machine-ip>:/tmp/
scp ../../scripts/machine/install-meticai.sh root@<machine-ip>:/tmp/
scp ../../scripts/machine/validate-meticai.sh root@<machine-ip>:/tmp/

---

Step 3: Install on Machine

SSH into the machine:

bash /tmp/install-meticai.sh --local /tmp/meticai-web.tar.gz

The installer will:

• Check free disk space (needs ≥20 MB)
• Back up any existing installation
• Extract to /opt/meticai-web
• Report file count, size, and disk usage before/after
• Print the Tornado route configuration needed

---

Step 4: Post-Installation Benchmarks

echo "=== POST-INSTALL BENCHMARKS ==="
echo "--- Disk ---"
df -h /
du -sh /opt/meticai-web
echo "--- Memory ---"
free -m
echo "--- CPU ---"
cat /proc/loadavg
echo "--- Processes ---"
ps aux | wc -l

Expected deltas:

Metric	Expected Change
Disk	~6 MB increase
RAM	0 MB (static files only)
CPU	0% (no new processes)
Processes	0 new

---

Step 5: Configure Tornado Route

Add the static file route to the machine's api/web_ui.py:

METICAI_HANDLER = [
    (r"/meticai", tornado.web.RedirectHandler, {"url": "/meticai/"}),
    (r"/meticai/(.*)", tornado.web.StaticFileHandler, {
        "default_filename": "index.html",
        "path": "/opt/meticai-web",
    }),
]

Then restart the Tornado service.

---

Step 6: Validate Installation

bash /tmp/validate-meticai.sh

Expected: all green checks for disk, memory, CPU, files, routes, and API.

---

Step 7: Browser Testing

Open http://<machine-hostname>.local:8080/meticai/ (use hostname on the machine to get the actual name) and verify:

#	Test	Expected
1	App loads	Start screen with 7 navigation buttons
2	Direct mode active	Settings does NOT show Tailscale or Updates sections
3	Machine connection	Telemetry shows live temperature/pressure via Socket.IO
4	Profile catalogue	Loads profiles directly from machine API
5	Run a shot	Start/stop/tare work via direct espresso-api
6	AI features	Enter Gemini API key in Settings → test profile generation
7	PWA install prompt	Browser offers "Add to Home Screen"
8	Offline resilience	After first load, disconnect WiFi briefly — cached pages still render
9	Pour over mode	Loads correctly, remembers preferences
10	Espresso Compass	Dial-in wizard works with direct AI calls

---

Step 8: Stress Benchmarks (while browsing)

While actively using the PWA from another device:

echo "--- Under Load ---"
cat /proc/loadavg
free -m
vmstat 5 6

Expected: Negligible impact — Tornado serves static files, all JS executes in the browser.

---

Step 9: Uninstall (if needed)

# Copy uninstall script first
scp scripts/machine/uninstall-meticai.sh root@<machine-ip>:/tmp/
# On the machine:
bash /tmp/uninstall-meticai.sh

---

Architecture

Before: Browser → MeticAI Docker (nginx+FastAPI+MQTT) → Machine
After:  Browser → Machine Tornado (static files + API on same origin)
        Browser → Google Gemini (direct, user's own API key)

No Python backend. ~6 MB disk, zero RAM, zero CPU overhead.

---

Supersedes previous testing comment. Updated to use SCP-based install (machine has no curl/wget).

[hessius]

🧪 PWA Direct Mode — Testing Handover & Checklist

Branch: feat/machine-hosted-pwa @ f0a5e8e
Machine URL: http://meticulouslocalflatwhite.local:8080/meticai/
Machine SSH: root@192.168.50.168 (credentials shared separately)

---

Architecture Overview

The PWA runs in direct mode — served from the Meticulous machine's Tornado backend at /meticai/. There is no MeticAI Python backend; instead, a global fetch interceptor in main.tsx translates MeticAI proxy API calls (/api/...) to Meticulous-native endpoints (/api/v1/...).

Key files:

• apps/web/src/main.tsx — Fetch interceptor with ~30 endpoint translations
• apps/web/src/hooks/useMachineTelemetry.ts — Socket.IO telemetry mapping (direct mode section)
• apps/web/src/lib/machineMode.ts — isDirectMode() detection
• apps/web/src/lib/featureFlags.ts — Feature enable/disable for direct mode
• scripts/machine/install-meticai.sh — Deployment script

Build & Deploy

cd apps/web && bun run build:machine
tar -czf /tmp/meticai-web.tar.gz -C dist .
scp /tmp/meticai-web.tar.gz root@<MACHINE_IP>:/tmp/
scp scripts/machine/install-meticai.sh root@<MACHINE_IP>:/tmp/
ssh root@<MACHINE_IP> 'bash /tmp/install-meticai.sh --local /tmp/meticai-web.tar.gz'

What Works (Verified)

• ✅ UI loads without 404 errors
• ✅ All 18 machine profiles visible in catalogue and run-shot view
• ✅ Running a shot initiates the profile on the machine (no longer triggers a purge)
• ✅ Preheat command sent to machine (GET /api/v1/action/preheat)
• ✅ Storage stable at 2478 MB (no regression on reinstall)
• ✅ i18n translations load correctly
• ✅ Static assets (logo, config, locales) resolve with correct base URL

Known Limitations (By Design)

• No profile images (these are AI-generated by MeticAI backend, not available on machine)
• No AI shot analysis or profile descriptions
• No variable overrides when running profiles (ignored in direct mode)
• No scheduling persistence (uses setTimeout — lost on page reload)
• No profile sync (no MeticAI database to sync with)

---

🔍 Testing Checklist

1. Profile Catalogue

• Open Profile Catalogue — all 18 machine profiles should be listed
• Each profile shows name, author, temperature, final_weight
• "Import from machine" dialog shows profiles
• After importing a profile, the catalogue refreshes (note: import is a no-op since profiles are already on machine)
• Profile export downloads a JSON file

2. Run a Shot (Critical Path)

• Select a profile in Run/Schedule view
• Click "Run Now" — should NOT trigger a purge
• Machine should load the selected profile (may take 2-6 seconds if machine was busy)
• Machine should start the extraction after loading
• UI navigates to Live Shot View

3. Live Shot View — Telemetry

• Profile name shows as the title (not the stage name)
• Stage name (e.g., "heating", "Preinfusion", "Extraction") shows as subtitle
• Shot timer displays real seconds (e.g., "10.5s", not "10500s")
• Pressure reading matches machine display
• Flow rate reading matches machine display
• Weight reading updates during extraction
• Target weight shows the profile's final_weight (e.g., "50g", not "1g")
• Temperature reading is reasonable (~90°C range)
• Chart renders with correct time axis (seconds, not milliseconds)
• Chart pressure/flow/weight curves look reasonable

4. Heating & Ready States

• Heating card (orange with fire icon) appears when machine is heating
• Heating card shows current temp and target temp with progress bar
• Ready card (green with pulse) appears when machine reaches temperature
• Ready card shows "Click to Start" equivalent text
• "Lance's Standard" easter egg: enhanced green glow when temp is within 2.3°C of target

5. Preheat

• Toggle preheat ON, select a profile, click Run
• Machine should start preheating
• Check machine display — should show preheat activity
• UI should show preheat countdown timer in heating card
• After preheat completes (10 min), profile should auto-load and start
• Note: preheat_countdown may not be populated in direct mode — verify

6. Shot History

• History view loads with shot entries
• Each entry shows profile name and date
• Shot detail view loads when clicking an entry
• Shot data (pressure/flow/weight curves) renders in detail chart
• Note: No AI analysis or descriptions available in direct mode

7. Machine Commands

• Stop button works during a shot
• Tare/zero scale works
• Continue works on a paused shot (if applicable)

8. Feature Flags — Things That Should Be Hidden/Disabled

• No Tailscale setup option
• No mDNS discovery
• No scheduling tab (feature flag disabled)
• Settings page doesn't try to fetch MeticAI backend settings
• No "Connect to MeticAI" prompts

9. Storage & Performance

• Run df -m / on machine — should be ~2478 MB free
• After deploying a new version, free space should not decrease
• Page load time is reasonable (<3s on local network)
• No excessive console errors

---

⚠️ Likely Issues to Investigate

1. Profile name in LiveShotView: The machine's Socket.IO status event has name (stage name), profile (profile name string), and loaded_profile. We map profile || loaded_profile → active_profile. If profile name still shows wrong, check what the actual Socket.IO event contains by adding console.log to useMachineTelemetry.ts line ~89.

2. Target weight: We fetch final_weight from /api/v1/profile/get/:id when the profile ID changes. If target weight still shows wrong, the status event's id field might not match the profile list's id field. Debug by logging the status event data.

3. Preheat countdown: In proxy mode, preheat_countdown comes from the MeticAI backend's MQTT subscriber. In direct mode, there's no equivalent — the machine may not emit a countdown via Socket.IO. May need to implement a client-side countdown timer.

4. Heating/Ready card not showing: These check ms.state.toLowerCase() === 'heating' and 'click to start'. The machine may use different strings. Add a console.log('state:', data.name, 'machineState:', data.state) to the status handler to see actual values.

5. History shot detail: The machine stores shot data in .shot.json.zst files. The /api/v1/history endpoint returns entries with a data array of shot points. The frontend may expect a different format for the shot detail chart.

🔧 Debug Tips

• Add console.log to useMachineTelemetry.ts line 89 (machine.onStatus) to see raw Socket.IO data
• The fetch interceptor logs nothing by default — add console.log('[interceptor]', url, method) at the top of directModeFetch for debugging
• Machine API can be tested directly: http://meticulouslocalflatwhite.local:8080/api/v1/profile/list
• Build with bun run build:machine (sets VITE_MACHINE_MODE=direct and base=/meticai/)