nanobot-voice-interface/ARCHITECTURE_TODO.md

Architecture TODO

This file tracks the current architecture cleanup work for the Nanobot web app.

Card Platform

• Move all template-backed cards to the dynamic card.js runtime.
• Remove inline-script fallback execution from the frontend shell.
• Keep the card runtime contract documented and stable.
• Validate every template card automatically in CI/local checks.
• Add lightweight fixture coverage for mount/update/destroy behavior.

Template Source Of Truth

• Treat ~/.nanobot/cards/templates as the live source of truth.
• Sync repo examples from the live template tree with a script instead of manual copying.
• Make template drift a failing quality check.

Backend Structure

• Split card persistence/materialization out of app.py.
• Split session helpers out of app.py.
• Split Nanobot transport/client code out of app.py.
• Keep HTTP routes thin and push domain logic into service modules.

Frontend Structure

• Split useWebRTC.ts into transport, sessions, cards/feed, and workbench modules.
• Reduce App.tsx to layout/navigation concerns only.
• Keep CardFeed.tsx focused on rendering, not domain mutation orchestration.

Updates And Reactivity

• Replace polling-heavy paths with evented updates where possible.
• Keep card updates localized so a live sensor refresh does not churn the whole feed.

Remaining Cleanup

• Move backend startup state into FastAPI lifespan/app state.
• Stop importing private underscore helpers across app boundaries.
• Split the backend route surface into router modules.
• Split the card runtime renderer into loader/host/renderer modules.
• Replace async tool-job polling with an evented stream.