Skip to main content

ADR 012 — Solara deprecation in the cloud build

Context​

The legacy Solara UI (legacy_ui.app at alphaswarm/ui/) is a Python ASGI presentation layer that predates the Vite + React 19 + shadcn cutover documented in alphaswarm_client/CUTOVER.md. It is already wrapped in the legacy profile. alphaswarm/api/client_routes.py mounts it only when the solara package is importable (an ImportError skips the /legacy mount); ALPHASWARM_CLIENT_ENABLE_SOLARA is referenced in that module's log output as a way to suppress the log line, but it is not currently read as an actual gate, and it is not defined as a setting in alphaswarm/config/settings.py / alphaswarm_config.

The cloud alphaswarm_ui/ Next.js application has no need for Solara — every chart that Solara renders is already covered by the lightweight-charts / recharts stack already in alphaswarm_client/package.json and inherited by alphaswarm_ui/. Continuing to bundle Solara into the cloud image is pure dead weight (~300 MB) AND it creates a second presentation-layer state machine the BFF would otherwise have to synchronise with the React component tree.

Decision​

  1. alphaswarm_ui/ Dockerfile excludes Solara entirely (already the case). No solara-builder stage; no /legacy mount.
  2. alphaswarm_client/ retains the Solara stage for one release cycle beyond Phase 1 of the cloud-dash refactor. This preserves the ADR 002 rollback contract.
  3. After one release cycle, the Solara stage is removed from alphaswarm_client/ (Phase 7 of the cloud-dash refactor plan):
  4. No new Solara work. The legacy profile is in maintenance mode only. New visualisation lands in alphaswarm_client/ (Vite + shadcn) or alphaswarm_ui/ (Next.js + antd + recharts).

Consequences​

Positive

  • Cloud image stays small (~150 MB) and Python-free; cold-start latency is dominated by Next.js startup, not Solara warmup.
  • One less presentation-layer state machine to keep in sync with the React component tree.
  • Bundle audits stop having to explain why a TypeScript-first PaaS ships a 300 MB Python interpreter.

Negative

  • Operators who relied on Solara dashboards have to migrate before the Phase-7 removal. The migration is well-documented: every Solara surface has a Vite analog (see the cutover checklist in alphaswarm_client/CUTOVER.md).
  • Loss of Solara's Python-side reactive component model. This was an interesting prototype path but not a load-bearing operator workflow.

Alternatives considered​

  • Keep Solara indefinitely as a "second UI" — rejected. The cost of maintaining two parallel presentation stacks (React + Solara) outweighs the value of an alternate visualisation framework that no current workflow needs.
  • Port Solara to JupyterLab embed — rejected. JupyterLab is intended for notebook authoring (Lab Engine), not operator dashboards. Mixing the two surfaces would re-create the original framework-fragmentation problem ADR 002 set out to solve.

Implementation references​