Skip to content

ADR-003-streamlit-to-nextjs.md

Latest commit

 

History

History
26 lines (17 loc) · 1.61 KB

ADR-003-streamlit-to-nextjs.md

File metadata and controls

26 lines (17 loc) · 1.61 KB
Raw

ADR-003: Migrate the UI from Streamlit to Next.js

  • Status: Accepted
  • Date: 2026-07 (retroactive record — migration shipped with the v1→v2 platform rework)
  • Related: frontend.md, API-first principle in VISION.md

Context

The original UI was Streamlit: fast to build, but it coupled UI and backend logic in one process, made external integrations hard, and gave us limited control over API behavior. The API-first principle — every capability accessible via REST, the UI being just one client — was structurally impossible to honor.

Decision

Rebuild the frontend as a Next.js/React application consuming the same FastAPI REST API that external clients use. Business logic lives behind the API; the frontend is a pure client (TanStack Query + Zustand over axios).

Alternatives considered

  • Stay on Streamlit — lowest effort, but permanently blocks API-first and a polished UX.
  • Server-rendered templates (FastAPI + Jinja) — simpler stack, but poor interactivity for chat/streaming-heavy UX.
  • Other SPA frameworks (Vue, Svelte) — viable; React/Next.js won on ecosystem, component library availability (Radix/Shadcn) and contributor familiarity.

Consequences

  • The API is complete by construction — anything the UI does, an integration can do (this later enabled the MCP direction, #878).
  • Two build systems and a larger contributor surface (TypeScript + Python).
  • i18n, theming and accessibility became first-class frontend concerns (7 locales today).
  • Legacy Streamlit remnants were removed over time; migrations assume API-driven access.