Epic: Evolve Open AI Chat into a robust, production-ready AI chat client #1

Overview

Turn OpenAI-Echo-Bot from a lightweight single-file streaming chat demo into a polished, reliable, maintainable AI chat client while preserving its zero-build, browser-first philosophy.

The current application already provides a responsive UI, streamed responses through Server-Sent Events, conversation context, system prompts, input validation, debug output, and a legacy mock implementation. The repository currently centers on index.html, README.md, and the preserved /legacy implementation.

Goals

• Make the chat experience more resilient to real-world API/network failures.
• Improve conversation persistence and user control over chat state.
• Make streaming behavior robust, cancellable, and easier to recover from.
• Strengthen security around API-key handling and browser-side configuration.
• Improve accessibility, mobile usability, and interaction feedback.
• Make the code easier to maintain without unnecessarily introducing a build system.
• Improve observability and debugging without exposing sensitive request data.
• Bring documentation and project structure in line with the actual application.
• Preserve the legacy Echo Bot as a clearly separated historical/testing implementation.

Scope / Workstreams

1. Streaming and API reliability

• Harden SSE/stream parsing against malformed, partial, empty, and terminal chunks.
• Handle HTTP errors, timeouts, network failures, aborted requests, and unexpected response formats gracefully.
• Add a Stop/Cancel interaction for an in-progress response.
• Prevent duplicate submissions while a request is active.
• Ensure UI state is restored correctly after success, failure, or cancellation.

2. Conversation management

• Persist conversations locally with an explicit, documented storage strategy.
• Restore the current conversation safely after refresh when enabled.
• Add controls for starting a new conversation and clearing conversation state.
• Preserve system-prompt behavior consistently across restored sessions.
• Prevent accidental loss of an active conversation.

3. Configuration and security

• Review all browser-side handling of the Pollinations API key and clearly document its security implications.
• Avoid logging secrets or sensitive authorization material in the debug console.
• Validate endpoint/model configuration before sending requests.
• Make external endpoint assumptions configurable where practical.
• Add safe handling for unexpected user-controlled values rendered into the DOM.

4. UX and accessibility

• Improve loading/streaming states and error messaging.
• Make keyboard navigation and focus behavior consistent.
• Verify ARIA semantics for the chat log, controls, expandable sections, and status indicators.
• Improve mobile composer behavior and long-message usability.
• Add useful empty-state and recovery states.
• Ensure the interface remains usable with reduced motion and different text sizes.

5. Code quality and maintainability

• Refactor the large single-file implementation into clearly separated logical modules/sections while retaining the no-build option where feasible.
• Centralize application state and request lifecycle management.
• Reduce duplicated DOM manipulation and event-handling logic.
• Introduce small, testable functions for request construction, SSE parsing, state transitions, and persistence.
• Establish consistent error-handling conventions.

6. Debugging and observability

• Make debug output useful for diagnosing request/stream failures without leaking API keys.
• Clearly distinguish request lifecycle events, server errors, parser errors, and client errors.
• Provide a way to clear debug output independently from conversation history.
• Keep verbose diagnostics opt-in.

7. Testing and compatibility

• Add a lightweight test strategy for the highest-risk JavaScript behavior, especially streaming parsing and state transitions.
• Test malformed SSE data, interrupted streams, empty responses, API errors, cancellation, and rapid user interaction.
• Verify current behavior across major desktop and mobile browsers.
• Test the application when opened directly as a local HTML file as well as when served statically.

8. Documentation and project hygiene

• Update the README to accurately document setup, configuration, API-key expectations, supported behavior, limitations, and troubleshooting.
• Document the Pollinations endpoint/model assumptions and streaming protocol.
• Clearly identify /legacy as the historical mock implementation and explain when it should be used.
• Add contribution/development guidance appropriate for a dependency-free static project.

Acceptance Criteria

• A failed or interrupted AI request never leaves the UI stuck in a loading state.
• Users can cancel an active streamed response safely.
• Partial/malformed stream data cannot crash the application.
• API keys are never written to debug output, persisted unintentionally, or exposed through rendered UI state.
• Conversation state can be intentionally cleared without stale messages being sent on subsequent requests.
• Keyboard and mobile interactions work consistently across the main chat flow.
• Core request/stream/state logic has automated or otherwise reproducible coverage.
• README and in-app behavior are consistent.
• Legacy functionality remains isolated and clearly documented.
• The resulting application remains deployable as a simple static web application without requiring a backend.

Phase Status

• Phase 1 — Reliability and chat client hardening — PR Finish reliability and chat client hardening #4
• Phase 2 — Conversation export, import, and local data controls — Issue Phase 2 — Conversation export, import, and local data controls #5 / PR feat: add conversation export import and local data controls #6
• Phase 3 — API configuration and security hardening — Issue Phase 3 — API configuration and security hardening #7 / PR feat: harden api configuration and diagnostics #8
• Phase 3 — API configuration and security hardening — Issue Phase 3 — API configuration and security hardening #7 / PR feat: harden api configuration and diagnostics #8

Suggested child issues

Create focused child issues under this epic for:

1. Streaming lifecycle and cancellation
2. Conversation persistence and state management
3. API-key/configuration hardening
4. Accessibility and mobile UX
5. JavaScript architecture/refactoring
6. Debug console and safe observability
7. Automated testing and browser compatibility
8. README/documentation and project hygiene

Definition of Done

The repository provides a dependable browser-based AI chat experience rather than only a functional demo: streaming is resilient, conversations are controllable, configuration is handled safely, accessibility is credible, failures are recoverable, core behavior is testable, and documentation accurately describes how the application works and its security/operational limitations.