Skip to content

refactor: split frontend god object #8

Description

@stackbilt-admin

Context

The frontend application is currently implemented as one 905-line file: frontend/app.js. This violates the architecture constraint in ARCHITECTURE.md that source modules stay under 400 lines.

The file owns too many responsibilities at once:

  • config and API auth helpers (frontend/app.js:8)
  • inline icon registry (frontend/app.js:30)
  • global app state (frontend/app.js:41)
  • routing and page dispatch (frontend/app.js:52, frontend/app.js:64)
  • search rendering and events (frontend/app.js:94)
  • chat rendering, events, and API calls (frontend/app.js:202, frontend/app.js:310)
  • upload rendering, multipart upload, and ingestion polling (frontend/app.js:417, frontend/app.js:562, frontend/app.js:633)
  • settings and health checks (frontend/app.js:657, frontend/app.js:713)
  • assistant markdown/think formatting (frontend/app.js:751)
  • utility formatting, toasts, and bootstrapping (frontend/app.js:808, frontend/app.js:858, frontend/app.js:884)

Recommendation

Split frontend/app.js into small responsibility-focused modules while preserving the existing static frontend approach.

Suggested first pass:

  • frontend/js/api.js for API base URL, API key access, and fetch helpers
  • frontend/js/state.js for app state and navigation/render invalidation
  • frontend/js/icons.js for inline icon templates
  • frontend/js/pages/search.js
  • frontend/js/pages/chat.js
  • frontend/js/pages/upload.js
  • frontend/js/pages/settings.js
  • frontend/js/pages/detail.js
  • frontend/js/formatting.js for markdown, message parsing, date/byte formatting, and escaping
  • frontend/js/toast.js for toast rendering/lifecycle
  • keep frontend/app.js as a thin bootstrap and page dispatcher

Acceptance criteria

  • No frontend JS module exceeds 400 lines.
  • Behavior of search, chat, upload, settings, and detail views is unchanged.
  • Existing static deployment remains simple, with no required bundler unless deliberately introduced.
  • Shared helpers are imported rather than duplicated.
  • Add at least light coverage or a manual verification checklist for the major UI flows.

Verification baseline

Current baseline from the audit:

  • npm test passes: 12 tests across 2 files.
  • npm run type-check passes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions