feat(phase-3): implement authentication and real-time chat interface

.env.example

@@ -70,6 +70,17 @@ DISABLE_LEGAL_DISCLAIMERS="false"
 LANGGRAPH_MAX_ROUNDS="5"  # Maximum debate rounds before forcing consensus
 LANGGRAPH_CONSENSUS_THRESHOLD="0.8"  # Advisor agreement threshold (0.0-1.0)
 
+# ============================================================================
+# Phase 3: Authentication & Security
+# ============================================================================
+# JWT Secret Key - MUST change in production!
+# Generate a secure random key with: openssl rand -hex 32
+JWT_SECRET_KEY="changeme-generate-a-secure-random-key-in-production"
+
+# Fernet Encryption Key for API Keys (auto-generated if not provided)
+# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+# ENCRYPTION_KEY=""
+
 # ============================================================================
 # Optional: pgAdmin (Database Management UI)
 # ============================================================================

CLAUDE.md

@@ -42,10 +42,18 @@ docker-compose build        # Rebuild containers
 ## Configuration Architecture
 
 ### Environment Variables
-All secrets and API keys must be stored in `.env` (never committed). Use `.env.example` as template:
+All secrets and API keys must be stored in `.env` files (never committed).
+
+**Backend (.env)** - Use `.env.example` as template:
 - OpenAI/Anthropic API keys
 - Actual Budget API credentials
 - PostgreSQL connection details
+- JWT secret key (Phase 3)
+- Encryption key for user API keys (Phase 3)
+
+**Frontend (.env.local)** - Phase 3:
+- NextAuth.js secret
+- Backend API URL
 
 ### Advisor Configuration (`backend/advisors.yaml`)
 Defines AI advisor personas without code changes. Each advisor requires:
@@ -64,9 +72,21 @@ Defines AI advisor personas without code changes. Each advisor requires:
   /app
     /agents       # LangGraph multi-agent logic
     /api          # FastAPI routes
+      auth.py     # Authentication endpoints (Phase 3)
+      chat.py     # Multi-agent chat endpoints (Phase 2, updated Phase 3)
+      config.py   # Configuration endpoints (Phase 3)
+      financial.py # Financial data endpoints (Phase 3)
+      users.py    # User management endpoints (Phase 3)
     /core         # Config (pydantic-settings), Security, Logging
+      auth.py     # Password hashing & JWT (Phase 3)
+      encryption.py # API key encryption (Phase 3)
+      dependencies.py # JWT middleware (Phase 3)
+    /models       # SQLAlchemy ORM models (Phase 2, updated Phase 3)
     /services     # Data ingestion adapters (CSV, Actual Budget API)
   /config         # Default YAMLs (advisors.yaml)
+  /migrations     # Database migrations
+    001_init.sql  # Initial schema (Phase 2)
+    002_add_auth.sql # Auth tables (Phase 3)
   main.py         # FastAPI application entrypoint
   requirements.txt
 ```
@@ -82,9 +102,14 @@ Defines AI advisor personas without code changes. Each advisor requires:
 - `consensus_reached`: Boolean flag
 - `human_feedback`: Optional user input
 
-**API Endpoints**:
-- `POST /api/chat/start`: Start conversation thread
-- `GET /api/chat/{thread_id}/stream`: SSE stream of agent thoughts, interrupts, and final plans
+**API Endpoints** (Phase 3 - All require JWT authentication):
+- `POST /api/auth/signup`: User registration
+- `POST /api/auth/login`: Authentication with JWT token
+- `POST /api/chat/start`: Start conversation thread (requires auth)
+- `GET /api/chat/{thread_id}/stream`: SSE stream of agent thoughts, interrupts, and final plans (requires auth)
+- `GET /api/chat/conversations`: Get user's conversation history grouped by date (requires auth)
+- `GET /api/config/advisors`: Get all advisor configurations (requires auth)
+- `GET /api/financial/summary`: Calculate financial metrics from user transactions (requires auth)
 
 ### Database
 PostgreSQL with pgvector extension for semantic search:
@@ -98,13 +123,33 @@ PostgreSQL with pgvector extension for semantic search:
 /frontend
   /src
     /app          # Next.js App Router
-      page.tsx    # Home page
-      layout.tsx  # Root layout with Geist fonts
-      globals.css # Tailwind styles
+      /api/auth/[...nextauth]  # NextAuth API route (Phase 3)
+      /dashboard
+        page.tsx   # Dashboard home with financial cards (Phase 3)
+        /chat
+          page.tsx # Real-time chat interface (Phase 3)
+      /login       # Login page (Phase 3)
+      /signup      # Signup page (Phase 3)
+      layout.tsx   # Root layout with SessionProvider (Phase 3)
+      page.tsx     # Redirects to dashboard (Phase 3)
+      globals.css  # Tailwind styles with shadcn variables (Phase 3)
+    /components
+      dashboard-layout.tsx  # Main layout with sidebar (Phase 3)
+      chat-interface.tsx    # Chat with SSE streaming (Phase 3)
+      /ui          # shadcn/ui components (Phase 3)
+    /lib
+      api-client.ts # REST API client with JWT (Phase 3)
+      utils.ts     # Utilities (Phase 3)
+    auth.ts        # NextAuth configuration (Phase 3)
+    auth.config.ts # Auth route protection (Phase 3)
+    middleware.ts  # Protected routes middleware (Phase 3)
   /public         # Static assets
 ```
 
 ### Key Features
+- **NextAuth.js v5**: JWT-based authentication with Credentials provider (Phase 3)
+- **shadcn/ui**: Component library built on Radix UI (Phase 3)
+- **SSE Streaming**: Real-time chat updates via Server-Sent Events (Phase 3)
 - **React Compiler**: Enabled in `next.config.ts` for automatic memoization
 - **Tailwind CSS v4**: Using PostCSS plugin
 - **Path Aliases**: `@/*` maps to `./src/*`
@@ -122,17 +167,49 @@ PostgreSQL with pgvector extension for semantic search:
 
 ## Data Flow
 
+**Phase 3 - Complete User Flow:**
+1. User visits frontend at http://localhost:3000
+2. User signs up / logs in via NextAuth.js (JWT stored in session)
+3. Dashboard displays financial summary from `/api/financial/summary`
+4. User clicks "Start New Conversation" → navigates to chat page
+5. User types a question about finances
+6. Frontend calls `POST /api/chat/start` with JWT token
+7. Backend creates LangGraph thread with configured advisors
+8. Frontend connects to `GET /api/chat/{thread_id}/stream` (SSE)
+9. Agents debate in boardroom pattern, streaming thoughts via SSE:
+   - `advisor_speaking` event → Show typing indicator
+   - `advisor_message` event → Display message bubble
+   - `plan_complete` event → Show final plan with disclaimer
+10. System may interrupt for human feedback (future enhancement)
+11. User can continue conversation or start a new one
+
+**Data Ingestion Flow (Phase 1):**
 1. User uploads financial data (CSV) or connects Actual Budget API
 2. Backend ingests transactions into PostgreSQL with vector embeddings
-3. User asks a question via Next.js frontend
-4. FastAPI creates LangGraph thread with configured advisors
-5. Agents debate in boardroom pattern, streaming thoughts via SSE
-6. System may interrupt for human feedback
-7. Final financial plan returned as Markdown
+3. Transactions available for financial summary calculations
 
 ## Testing Strategy
 
 Tests should cover:
-- **Backend**: FastAPI route tests, LangGraph state transitions, decimal precision
-- **Frontend**: Component rendering, SSE connection handling
-- **Integration**: Full flow from question → agent debate → plan output
+- **Backend**:
+  - FastAPI route tests
+  - Authentication (JWT token generation, password hashing)
+  - Protected endpoint authorization
+  - LangGraph state transitions
+  - Decimal precision for financial calculations
+  - API key encryption/decryption
+- **Frontend**:
+  - Component rendering
+  - Authentication flow (signup, login, logout)
+  - SSE connection handling
+  - Protected route middleware
+- **Integration**:
+  - Full flow from signup → login → dashboard → chat → agent debate → plan output
+  - Financial summary calculations with real transaction data
+
+## Phase Completion Status
+
+- ✅ **Phase 1**: Data ingestion, PII scrubbing, Docker deployment
+- ✅ **Phase 2**: Multi-agent LangGraph system, SSE streaming, database models
+- ✅ **Phase 3**: Authentication, dashboard, real-time chat interface
+- 🔜 **Phase 4**: Dark mode, settings UI, conversation history, advanced features