From f5a67d9fa402d3fc367d8824bf4681de61215002 Mon Sep 17 00:00:00 2001 From: Marko Djordjevic Date: Fri, 20 Feb 2026 18:40:52 +0100 Subject: [PATCH] Update CLAUDE_DESCRIPTION.md with auth system, routing, and schema changes (v3.2.0) - Document Auth.js v5 multi-user authentication with Credentials and Google OAuth - Add new routing structure: (public) for /, /login, /register and /app/* protected routes - Document middleware-based route protection in middleware.ts - Add new API auth endpoints: /api/auth/register, /profile, /password, /account - Document user_id foreign keys on all data tables with composite unique constraints - Add settings page at /app/settings for user profile management - Update API endpoints section to show auth endpoints and protected data endpoints - Update file structure to reflect new auth files and route groups - Update constraints to note authentication requirement and JWT session management - Update version history to reflect v3.2.0 changes Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE_DESCRIPTION.md | 122 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 105 insertions(+), 17 deletions(-) diff --git a/CLAUDE_DESCRIPTION.md b/CLAUDE_DESCRIPTION.md index 444b9e3..bb3b4aa 100644 --- a/CLAUDE_DESCRIPTION.md +++ b/CLAUDE_DESCRIPTION.md @@ -6,7 +6,52 @@ Candle Annotator is a complete machine learning platform for candlestick pattern **Current Version**: 3.1.0 (Database Consolidation - PostgreSQL for all application data) -## Recent Changes (v3.1.0) +## Recent Changes (v3.2.0) + +### Multi-User Authentication System (Auth.js v5) +- **Authentication Framework**: Auth.js v5 with JWT session strategy (30-day max age) +- **Multiple Providers**: + - **Credentials**: Email/password with bcryptjs hashing + - **Google OAuth**: Social login with automatic user creation +- **User Management**: Users table with uuid primary key, email uniqueness, provider tracking +- **Middleware Protection**: Next.js middleware in proxy.ts protects /app/* routes, redirects unauthenticated users +- **Session Management**: JWT tokens include user ID for secure API access +- **User Isolation**: All data tables (charts, candles, annotations, etc.) linked to user_id foreign key + +### New Routing Structure +- **Public Routes** (/ group): + - `/(public)/` - Landing page + - `/(public)/login` - Credentials/Google login + - `/(public)/register` - User registration with email/password +- **Protected Routes** (/app): + - `/app` - Main annotation interface (charts, candles, annotations) + - `/app/settings` - User settings and profile management +- **API Authentication Routes**: + - `POST /api/auth/register` - Register new user with email/password + - `POST /api/auth/login` - Credentials sign-in (handled by Auth.js) + - `POST /api/auth/logout` - Sign out (handled by Auth.js) + - `GET /api/auth/profile` - Get authenticated user profile + - `POST /api/auth/password` - Change user password + - `POST /api/auth/account` - Update account info (name, image) + +### Database Schema Updates +- **Users Table**: Stores email, password_hash, name, image, provider (credentials/google), provider_account_id +- **User ID Foreign Keys**: All data tables (charts, candles, annotations, annotation_types, span_label_types, span_annotations) now reference users.id +- **Composite Unique Constraints**: + - charts: (user_id, name) composite unique + - candles: (chart_id, time) composite unique + - annotation_types: (user_id, name) composite unique + - span_label_types: (user_id, name) composite unique +- **Type Enforcement**: uuid, timestamp, doublePrecision for PostgreSQL compatibility + +### Authentication & Middleware +- **Next.js Middleware** (src/middleware.ts): + - Protects /app/* routes (redirects to /login if unauthenticated) + - Protects /api/* routes except /api/auth/* and /api/health (returns 401 if not authenticated) + - Redirects authenticated users away from /login and /register to /app +- **Auth Configuration**: JWT-based sessions via Auth.js v5 + +## Previous Changes (v3.1.0) ### Database Consolidation to PostgreSQL - **Unified Database**: Migrated from SQLite to PostgreSQL for all application data (frontend + ML service) @@ -139,12 +184,30 @@ Candle Annotator is a complete machine learning platform for candlestick pattern candle_annotator/ ├── src/ # Next.js Frontend & API │ ├── app/ +│ │ ├── (public)/ # Public route group (unauthenticated) +│ │ │ ├── login/page.tsx # Login page (Credentials + Google OAuth) +│ │ │ ├── register/page.tsx # Registration page +│ │ │ ├── layout.tsx # Public layout with navbar +│ │ │ ├── navbar.tsx # Public navbar component +│ │ │ └── session-provider.tsx # NextAuth session provider +│ │ ├── app/ # Protected route group (authenticated) +│ │ │ ├── page.tsx # Main annotation interface +│ │ │ ├── layout.tsx # Protected app layout +│ │ │ └── settings/ +│ │ │ └── page.tsx # User settings & profile page │ │ ├── api/ +│ │ │ ├── auth/ +│ │ │ │ ├── [...nextauth]/route.ts # Auth.js handlers +│ │ │ │ ├── register/route.ts # POST user registration +│ │ │ │ ├── profile/route.ts # GET user profile +│ │ │ │ ├── password/route.ts # POST change password +│ │ │ │ └── account/route.ts # POST update account info │ │ │ ├── annotations/[id]/route.ts # GET label by ID, PATCH update, DELETE remove │ │ │ ├── annotations/route.ts # GET all, POST create, DELETE bulk -│ │ │ ├── candles/route.ts # GET all candles +│ │ │ ├── candles/route.ts # GET all candles for user +│ │ │ ├── charts/route.ts # GET/POST user charts │ │ │ ├── export/route.ts # GET CSV export -│ │ │ ├── health/route.ts # GET health check +│ │ │ ├── health/route.ts # GET health check (no auth required) │ │ │ ├── upload/route.ts # POST CSV file upload │ │ │ ├── predict/route.ts # POST prediction proxy │ │ │ ├── predict/batch/route.ts # POST batch prediction proxy @@ -154,7 +217,7 @@ candle_annotator/ │ │ │ └── export/route.ts # GET export for ML pipeline │ │ ├── globals.css # Hacker theme CSS variables │ │ ├── layout.tsx # Root layout with font loading -│ │ └── page.tsx # Main app (state + prediction mgmt) +│ │ └── page.tsx # Public landing page │ ├── components/ │ │ ├── CandleChart.tsx # Chart core with prediction overlay │ │ ├── PredictionPanel.tsx # Prediction controls & summary @@ -164,12 +227,15 @@ candle_annotator/ │ │ └── ui/ # shadcn/ui components │ ├── types/ │ │ └── predictions.ts # Prediction types -│ └── lib/ -│ ├── db/ -│ │ ├── index.ts # Drizzle client -│ │ ├── schema.ts # Table definitions (incl. span annotations) -│ │ └── migrate.ts # Migration runner -│ └── utils.ts # Utility functions +│ ├── lib/ +│ │ ├── db/ +│ │ │ ├── index.ts # Drizzle client +│ │ │ ├── schema.ts # Table definitions (incl. users, with FK constraints) +│ │ │ ├── migrate.ts # Migration runner +│ │ │ └── seed-user-defaults.ts # Seed default annotation types for new users +│ │ └── utils.ts # Utility functions +│ ├── auth.ts # Auth.js v5 configuration (providers, callbacks) +│ └── middleware.ts # Next.js middleware for route protection │ ├── services/ml/ # Python ML Service │ ├── app/ @@ -256,18 +322,27 @@ candle_annotator/ ## API Endpoints -### Data Operations +### Authentication +- `POST /api/auth/register` - Register new user with email and password +- `POST /api/auth/[...nextauth]` - Auth.js handlers (login, logout, callback) +- `GET /api/auth/profile` - Get authenticated user profile +- `POST /api/auth/password` - Change user password +- `POST /api/auth/account` - Update account info (name, image) + +### Data Operations (Protected - requires authentication) - `POST /api/upload` - Upload CSV with candle data -- `GET /api/candles` - Fetch all candles -- `GET /api/annotations` - Fetch all annotations +- `GET /api/candles` - Fetch all candles for authenticated user +- `GET /api/annotations` - Fetch all annotations for authenticated user - `POST /api/annotations` - Create label - `DELETE /api/annotations/[id]` - Delete label - `DELETE /api/annotations?type=break_up,break_down` - Bulk delete by type - `GET /api/export` - Download CSV export +- `GET /api/charts` - Fetch user's charts +- `POST /api/charts` - Create new chart ### Monitoring -- `GET /api/health` - Health check -- `GET /api/health?check=db` - Health check with database verification +- `GET /api/health` - Health check (no authentication required) +- `GET /api/health?check=db` - Health check with database verification (no authentication required) ## Development Workflow @@ -293,11 +368,13 @@ candle_annotator/ ## Known Constraints -- **Single User**: No authentication, local data only +- **Authentication Required**: Multi-user system requires login; public landing page but /app/* routes protected - **No Undo**: Annotations can only be deleted, not undone - **PostgreSQL Required**: Application requires PostgreSQL server to be running +- **JWT Sessions**: 30-day session max age for security - **Memory**: Large CSV files (100k+ rows) slow performance - **Lines**: Free-form drawing, no snap-to-candle +- **OAuth Setup**: Google OAuth requires AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET environment variables ## Customization Points @@ -343,7 +420,18 @@ Before marking features complete: ## Version History -### v3.1.0 (Current) +### v3.2.0 (Current) +- Multi-user authentication system with Auth.js v5 +- Credentials (email/password) and Google OAuth providers +- JWT session strategy with middleware route protection +- User isolation: all data tables linked to user_id +- New routing structure: (public) for /, /login, /register and /app/* for protected routes +- Settings page for user profile management +- New auth API endpoints: /api/auth/register, /api/auth/profile, /api/auth/password, /api/auth/account +- Composite unique constraints on charts, annotation_types, span_label_types +- User registration and account management + +### v3.1.0 - Database consolidation to PostgreSQL - Shared database between frontend and ML service - Direct database access for ML training (no CSV exports)