refactor: engineering improvements -- API versioning, structured logging, Alembic, error standardization, test coverage

- API versioning: all REST endpoints prefixed with /api/v1/
- Structured logging: replaced stdlib logging with structlog (console/JSON modes)
- Alembic migrations: versioned DB schema with initial migration
- Error standardization: global exception handlers for consistent envelope format
- Interrupt cleanup: asyncio background task for expired interrupt removal
- Integration tests: +30 tests (analytics, replay, openapi, error, session APIs)
- Frontend tests: +57 tests (all components, pages, useWebSocket hook)
- Backend: 557 tests, 89.75% coverage | Frontend: 80 tests, 16 test files

README.md

@@ -99,8 +99,12 @@ smart-support/
 ├── backend/
 │   ├── app/
 │   │   ├── main.py              # FastAPI + WebSocket entry point
-│   │   ├── graph.py             # LangGraph Supervisor
+│   │   ├── graph.py             # LangGraph Supervisor construction
+│   │   ├── graph_context.py     # Typed wrapper for graph + classifier + registry
 │   │   ├── ws_handler.py        # WebSocket message dispatch + rate limiting
+│   │   ├── ws_context.py        # WebSocket dependency bundle
+│   │   ├── auth.py              # API key authentication middleware
+│   │   ├── api_utils.py         # Shared API response helpers
 │   │   ├── safety.py            # Confirmation rules + MCP error taxonomy
 │   │   ├── agents/              # Agent definitions and tools
 │   │   ├── registry.py          # YAML agent registry loader
@@ -124,18 +128,21 @@ smart-support/
 
 ## API Endpoints
 
-| Method | Path | Description |
-|--------|------|-------------|
-| WS | `/ws` | Main WebSocket chat endpoint |
-| GET | `/api/health` | Health check |
-| GET | `/api/conversations` | List conversations (paginated) |
-| GET | `/api/replay/{thread_id}` | Replay conversation steps (paginated) |
-| GET | `/api/analytics` | Analytics summary (`?range=7d`) |
-| POST | `/api/openapi/import` | Start OpenAPI import job |
-| GET | `/api/openapi/jobs/{id}` | Check import job status |
-| GET | `/api/openapi/jobs/{id}/classifications` | Get endpoint classifications |
-| PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | Update a classification |
-| POST | `/api/openapi/jobs/{id}/approve` | Approve and generate tools |
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| WS | `/ws` | Token | Main WebSocket chat endpoint (`?token=<key>`) |
+| GET | `/api/health` | No | Health check |
+| GET | `/api/conversations` | API Key | List conversations (paginated) |
+| GET | `/api/replay/{thread_id}` | API Key | Replay conversation steps (paginated) |
+| GET | `/api/analytics` | API Key | Analytics summary (`?range=7d`) |
+| POST | `/api/openapi/import` | API Key | Start OpenAPI import job |
+| GET | `/api/openapi/jobs/{id}` | API Key | Check import job status |
+| GET | `/api/openapi/jobs/{id}/classifications` | API Key | Get endpoint classifications |
+| PUT | `/api/openapi/jobs/{id}/classifications/{idx}` | API Key | Update a classification |
+| POST | `/api/openapi/jobs/{id}/approve` | API Key | Approve and generate tools |
+
+Authentication is controlled by the `ADMIN_API_KEY` environment variable.
+API Key endpoints require the `X-API-Key` header. When `ADMIN_API_KEY` is unset, auth is disabled.
 
 ## Running Tests