Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tech Stack Decisions: Web Framework Analysis

Why We Removed the Web Framework

You caught an important inconsistency. The original documentation recommended Axum as the web framework, but this was from the initial API-first architecture where we planned to build:

Axum Server → REST API → Web Frontend (React/Vue)
            ↓
      TUI Client

With the shift to TUI-first, dual-target architecture, this changes completely:

New Architecture: No Web Framework Needed

Native Terminal (ratatui) ──┐
                            ├── Shared Core ──→ LLM APIs
Web Browser (WASM) ─────────┘        ↓
                              SQLite/LocalStorage

Key differences:

  • No server required for basic functionality
  • Native TUI is a standalone binary (no HTTP)
  • Web version is a static WASM app served from CDN/static host
  • Both talk directly to LLM APIs from client side

What We Actually Need

For Native TUI

  • ratatui + crossterm - UI framework
  • tokio - Async runtime for I/O
  • reqwest - HTTP client to call LLM APIs
  • sqlx - Local SQLite database
  • clap - CLI argument parsing

For Web (WASM)

  • ratzilla - DOM backend for ratatui
  • wasm-bindgen - Rust/JS bridge
  • web-sys - Browser APIs
  • gloo - Ergonomic web wrappers

Shared Core

  • serde - Serialization
  • futures - Async utilities
  • Custom LLM provider trait

When Would We Add a Web Framework?

Only if we later implement server mode for:

  1. Multi-user/team features - Centralized conversation storage
  2. Cloud sync - Sync across devices without manual export/import
  3. Enterprise deployment - Admin controls, audit logs
  4. Heavy compute - Running large models on server instead of client

Then we’d add:

  • axum or actix-web - HTTP API
  • PostgreSQL - Centralized database
  • Redis - Caching/sessions
  • Authentication/authorization layer

But this is Phase 3+ and optional. The core product works without it.

Updated Recommendation

ComponentOriginalRevisedNotes
Web FrameworkAxumNoneNot needed for TUI
Database (native)PostgreSQLSQLiteLocal, embedded
Database (web)PostgreSQLLocalStorage/IndexedDBBrowser storage
HTTP ClientreqwestreqwestDirect to LLM APIs
ServerRequiredOptionalOnly for sync features

Why This Is Better

  1. Simpler deployment: cargo install or static web hosting
  2. Privacy: Conversations stay on device by default
  3. Offline capable: Works without internet (local models)
  4. Lower latency: No HTTP hop to our own server
  5. Cheaper to run: No server infrastructure for basic users

The Mental Model Shift

Old: Web application with TUI as alternative client New: Terminal application with web as alternative deployment target

This aligns with tools like:

  • lazygit - Git TUI (terminal only, no web)
  • k9s - Kubernetes TUI (terminal only, no web)
  • opencode - AI TUI (terminal-first, web as convenience)

The web deployment via WASM is a feature, not the primary architecture.

Documentation Updates

The tech-stack-revised.md document reflects this approach. This document (decisions.md) now serves as:

  • Historical reference for the API-first approach
  • Future reference if we add server mode
  • Comparison of the two architectures

Next Steps

  1. Build harness-core - Shared business logic
  2. Build harness-tui - Native terminal app
  3. Build harness-web - WASM browser version
  4. Later: Consider harness-server only if needed

No Axum needed until we explicitly decide to add server-side features.