0e78e5b06b
Backend: - ConversationTracker: Protocol + PostgresConversationTracker for lifecycle tracking - Error handler: ErrorCategory enum, classify_error(), with_retry() exponential backoff - Wire PostgresAnalyticsRecorder + ConversationTracker into ws_handler - Rate limiting (10 msg/10s per thread), edge case hardening - Health endpoint GET /api/health, version 0.5.0 - Demo seed data script + sample OpenAPI spec Frontend (all new): - React Router with NavBar (Chat / Replay / Dashboard / Review) - ReplayListPage + ReplayPage with ReplayTimeline component - DashboardPage with MetricCard, range selector, zero-state - ReviewPage for OpenAPI classification review - ErrorBanner for WebSocket disconnect handling - API client (api.ts) with typed fetch wrappers Infrastructure: - Frontend Dockerfile (multi-stage node -> nginx) - nginx.conf with SPA routing + API/WS proxy - docker-compose.yml with frontend service + healthchecks - .env.example files (root + backend) Documentation: - README.md with quick start and architecture - Agent configuration guide - OpenAPI import guide - Deployment guide - Demo script 48 new tests, 449 total passing, 92.87% coverage
123 lines
6.3 KiB
Markdown
123 lines
6.3 KiB
Markdown
# Phase 5: Polish + Demo Prep -- Development Log
|
|
|
|
> Status: COMPLETED
|
|
> Phase branch: `phase-5/polish-demo`
|
|
> Date started: 2026-03-30
|
|
> Date completed: 2026-03-30
|
|
> Related plan section: [Phase 5 in DEVELOPMENT-PLAN](../DEVELOPMENT-PLAN.md#phase-5-polish--demo-prep)
|
|
|
|
## What Was Built
|
|
|
|
### Backend
|
|
|
|
- `app/conversation_tracker.py` -- Protocol + `PostgresConversationTracker` + `NoOpConversationTracker` for conversation lifecycle tracking (ensure, record_turn, resolve)
|
|
- `app/tools/__init__.py` + `app/tools/error_handler.py` -- `ErrorCategory` enum, `classify_error()`, `with_retry()` with exponential backoff for RETRYABLE errors only
|
|
- `app/ws_handler.py` -- Added `analytics_recorder`, `conversation_tracker`, `pool` params to `dispatch_message`; `_fire_and_forget_tracking` helper; rate limiting (10 msg/10s per thread); whitespace-only message check; JSON array rejection; version bump to 0.5.0
|
|
- `app/main.py` -- Wired `PostgresAnalyticsRecorder` and `PostgresConversationTracker` into lifespan; added `GET /api/health`; version 0.5.0
|
|
- `backend/fixtures/demo_data.py` -- Async seed script for sample conversations and analytics events
|
|
- `backend/fixtures/sample_openapi.yaml` -- E-commerce OpenAPI 3.0 spec for demo
|
|
|
|
### Frontend
|
|
|
|
- `src/api.ts` -- Typed fetch wrappers: `fetchConversations`, `fetchReplay`, `fetchAnalytics`
|
|
- `src/components/NavBar.tsx` -- Horizontal nav with NavLink routing
|
|
- `src/components/Layout.tsx` -- App shell with NavBar + Outlet
|
|
- `src/components/ErrorBanner.tsx` -- Disconnection status banner with reconnect button
|
|
- `src/components/MetricCard.tsx` -- Reusable metric display card
|
|
- `src/components/ReplayTimeline.tsx` -- Vertical step list with expandable params/result
|
|
- `src/pages/ReplayListPage.tsx` -- Paginated conversation list
|
|
- `src/pages/ReplayPage.tsx` -- Per-thread replay with ReplayTimeline
|
|
- `src/pages/DashboardPage.tsx` -- Analytics dashboard with range selector, zero-state handling
|
|
- `src/pages/ReviewPage.tsx` -- OpenAPI import form, job polling, editable classifications table
|
|
- `src/App.tsx` -- BrowserRouter with Layout + all 5 routes
|
|
- `src/hooks/useWebSocket.ts` -- Added `reconnect()`, `onDisconnect`/`onReconnect` callbacks
|
|
- `src/pages/ChatPage.tsx` -- ErrorBanner integration
|
|
- `vite.config.ts` -- Added `/api` proxy
|
|
|
|
### Infrastructure
|
|
|
|
- `frontend/Dockerfile` -- Multi-stage build (node:20-alpine -> nginx:alpine)
|
|
- `frontend/nginx.conf` -- SPA routing with WebSocket and API proxying to backend
|
|
- `docker-compose.yml` -- Added frontend service with health-gated depends_on; backend healthcheck; app_network
|
|
- `.env.example` (root) -- Docker Compose environment template
|
|
- `backend/.env.example` -- Backend environment template with all variables documented
|
|
|
|
### Documentation
|
|
|
|
- `docs/demo-script.md` -- Step-by-step 10-minute demo walkthrough
|
|
- `docs/agent-config-guide.md` -- agents.yaml reference, permissions, escalation
|
|
- `docs/openapi-import-guide.md` -- Import workflow, REST API, SSRF protection, limitations
|
|
- `docs/deployment.md` -- Docker Compose setup, production considerations, backup, scaling
|
|
- `README.md` -- Complete project overview with quick start, architecture, API table
|
|
|
|
## Code Structure
|
|
|
|
New files:
|
|
- `backend/app/conversation_tracker.py` -- Protocol + implementations
|
|
- `backend/app/tools/__init__.py` -- Package init
|
|
- `backend/app/tools/error_handler.py` -- Error classification + retry
|
|
- `backend/fixtures/demo_data.py` -- Seed script
|
|
- `backend/fixtures/sample_openapi.yaml` -- Demo spec
|
|
- `backend/tests/unit/test_conversation_tracker.py` -- 13 tests
|
|
- `backend/tests/unit/test_error_handler.py` -- 19 tests
|
|
- `backend/tests/unit/test_edge_cases.py` -- 10 tests
|
|
- `frontend/Dockerfile`
|
|
- `frontend/nginx.conf`
|
|
- `frontend/src/api.ts`
|
|
- `frontend/src/components/NavBar.tsx`
|
|
- `frontend/src/components/Layout.tsx`
|
|
- `frontend/src/components/ErrorBanner.tsx`
|
|
- `frontend/src/components/MetricCard.tsx`
|
|
- `frontend/src/components/ReplayTimeline.tsx`
|
|
- `frontend/src/pages/ReplayListPage.tsx`
|
|
- `frontend/src/pages/ReplayPage.tsx`
|
|
- `frontend/src/pages/DashboardPage.tsx`
|
|
- `frontend/src/pages/ReviewPage.tsx`
|
|
- `docs/demo-script.md`
|
|
- `docs/agent-config-guide.md`
|
|
- `docs/openapi-import-guide.md`
|
|
- `docs/deployment.md`
|
|
|
|
Modified files:
|
|
- `backend/app/main.py` -- Wired tracker/recorder, health endpoint, version bump
|
|
- `backend/app/ws_handler.py` -- Rate limiting, tracker/recorder params, edge case hardening
|
|
- `backend/tests/conftest.py` -- autouse fixture to clear rate limit state
|
|
- `backend/tests/unit/test_main.py` -- Updated version, added health route tests
|
|
- `backend/tests/unit/test_ws_handler.py` -- Tracker/recorder integration tests, content limit update
|
|
- `backend/tests/integration/test_websocket.py` -- Content limit update
|
|
- `frontend/src/App.tsx` -- BrowserRouter + routing
|
|
- `frontend/src/hooks/useWebSocket.ts` -- reconnect, callbacks
|
|
- `frontend/src/pages/ChatPage.tsx` -- ErrorBanner
|
|
- `frontend/vite.config.ts` -- /api proxy
|
|
- `docker-compose.yml` -- frontend service, healthcheck, networking
|
|
- `README.md` -- Complete rewrite in English
|
|
- `backend/.env.example` -- Added all new variables
|
|
|
|
## Test Coverage
|
|
|
|
- Unit tests added: 42 (13 conversation_tracker + 19 error_handler + 10 edge_cases)
|
|
- Integration tests updated: 1
|
|
- Unit tests updated: 4 (version + content limit alignment)
|
|
- Total tests: 449 passing
|
|
- Overall coverage: 92.88%
|
|
|
|
## Deviations from Plan
|
|
|
|
- `MAX_CONTENT_LENGTH` changed from 8000 to 10000 to match plan spec (>10000 = too long).
|
|
Updated all tests that referenced the old 8000/9000 boundary.
|
|
- `_thread_timestamps` is module-level; added autouse pytest fixture to clear it between
|
|
tests to prevent state leakage.
|
|
- `FireAndForget` tracking uses direct `await` (not background tasks) since the
|
|
WebSocket loop is already async and fire-and-forget with proper exception suppression
|
|
is sufficient.
|
|
|
|
## Known Issues / Tech Debt
|
|
|
|
- `app/main.py` coverage is 48% -- the lifespan/startup path is not covered by unit
|
|
tests (requires a real DB). This is expected and the overall 93% coverage more than
|
|
meets the 80% threshold.
|
|
- Rate limit state (`_thread_timestamps`) is process-global and will not work correctly
|
|
with multiple workers. For multi-worker deployments, use Redis-backed rate limiting.
|
|
- The `conversations` table schema is assumed to exist; `setup_app_tables` should be
|
|
extended to create it if not present (deferred to a future patch).
|