candle-annotator/openspec/changes/user-accounts/design.md

## Context

CandleAnnotator is a single-user full-stack app: Next.js 16 (App Router) + PostgreSQL (Drizzle ORM) + Python FastAPI ML service. All data is global — no users table, no auth, no data isolation. The entire app lives at `/` as a single page with 13 API routes.

We need to add multi-user support: registration, login, per-user data isolation. Lovable design mockups exist for landing, login, and register pages. The existing app workspace moves behind auth.

**Current stack**: Next.js 16, React 19, Drizzle ORM, PostgreSQL 16, Tailwind CSS, shadcn/ui, lightweight-charts, FastAPI (Python).

## Goals / Non-Goals

**Goals:**
- Email/password registration and login
- Google OAuth login
- Per-user data isolation (charts, annotations, models, settings)
- Landing page, login page, register page (from Lovable designs)
- User settings page (change password, display name, delete account)
- Auth middleware protecting app routes and API routes
- Smooth migration path for existing single-user data

**Non-Goals:**
- Email verification (defer — add later)
- Password reset via email (defer — requires email service)
- Admin panel / user management
- Role-based access control
- Rate limiting
- Two-factor authentication
- Social login beyond Google (GitHub, Discord, etc.)
- Team/organization accounts
- API key authentication for external integrations

## Decisions

### 1. Auth library: Auth.js v5 (NextAuth v5)

**Choice**: Auth.js v5 (`next-auth@5`) with JWT strategy

**Why**: Native App Router support, built-in Credentials + Google OAuth providers, `@auth/drizzle-adapter` exists for our ORM. JWT strategy avoids extra session table and keeps the ML service integration simple (pass user ID in headers).

**Alternatives considered**:
- **Lucia Auth**: Good but deprecated in favor of rolling your own. More manual setup.
- **Clerk/Auth0**: SaaS dependency, cost, overkill for this project.
- **Custom JWT**: More control but reinventing auth middleware, CSRF protection, etc.

**Session strategy**: JWT (not database sessions). User ID embedded in token. Stateless, no session table needed.

### 2. Password hashing: bcryptjs

**Choice**: `bcryptjs` (pure JS bcrypt implementation)

**Why**: No native dependencies (works in Docker without build tools), well-tested, sufficient for this use case.

**Alternatives considered**:
- **bcrypt** (native): Requires build tools in Docker, fails on some platforms.
- **argon2**: Better algorithm but requires native bindings. Overhead not justified here.

### 3. Database schema: `users` table + `user_id` FK on all tables

**Choice**: Add `users` table. Add `user_id` column (nullable initially for migration, then NOT NULL) to: `charts`, `annotations`, `annotation_types`, `span_annotations`, `span_label_types`.

**Users table**:
```
users
├── id: uuid (PK, default gen_random_uuid())
├── name: text (nullable)
├── email: text (unique, not null)
├── email_verified: timestamp (nullable)
├── password_hash: text (nullable — null for OAuth-only users)
├── image: text (nullable)
├── provider: text (default 'credentials') — 'credentials' | 'google'
├── provider_account_id: text (nullable) — Google sub ID
├── created_at: timestamp
├── updated_at: timestamp
```

**Why UUID for user IDs**: Avoids enumeration attacks, safe to expose in URLs/tokens, standard for auth systems.

**Why NOT use Drizzle adapter's default schema**: The `@auth/drizzle-adapter` creates `users`, `accounts`, `sessions`, `verification_tokens` tables. We'll use a simplified custom schema since we're using JWT (no sessions table) and deferring email verification. We'll handle the adapter mapping manually.

**Alternatives considered**:
- **Drizzle adapter default schema**: Creates 4 tables, adds complexity for features we don't need yet (verification tokens, separate accounts table). We can adopt it later if we add email verification or more OAuth providers.
- **Serial integer IDs**: Enumerable, less secure for user-facing IDs.

### 4. Routing structure

**Choice**:
```
/           → Landing page (public)
/login      → Login page (public)
/register   → Register page (public)
/app        → Main workspace (protected, current page.tsx moves here)
/app/settings → User settings (protected)
/api/auth/* → NextAuth API routes
/api/*      → Existing API routes (protected)
```

**Why**: Clean separation of public marketing pages and protected app. `/app` prefix makes middleware rules simple. Existing API routes stay at `/api/*` — just add auth check.

**Alternatives considered**:
- **Keep app at `/` and use `/landing`**: Unconventional, confuses SEO.
- **Subdomain (`app.candleannotator.com`)**: Adds deployment complexity.

### 5. Auth middleware approach

**Choice**: Next.js `proxy.ts` at project root. Uses Auth.js `auth()` to check session. Redirects:
- Unauthenticated users hitting `/app/*` or `/api/*` (except `/api/auth/*` and `/api/health`) → redirect to `/login`
- Authenticated users hitting `/login` or `/register` → redirect to `/app`

**Why**: Single enforcement point, runs on edge before page/API renders. Clean and standard Next.js pattern.

### 6. API route auth pattern

**Choice**: Helper function `getAuthUser(request)` that extracts user from JWT session. Every API route calls this at the top:

```typescript
const user = await getAuthUser();
if (!user) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
// All queries filter by user.id
```

All Drizzle queries add `.where(eq(table.user_id, user.id))` for reads, and set `user_id: user.id` on inserts.

**Why**: Simple, explicit, no magic. Every route clearly shows it's user-scoped.

### 7. ML Service user context

**Choice**: Pass `X-User-ID` header from Next.js API routes to FastAPI ML service. The ML service trusts this header (internal network only, not exposed to clients).

**Why**: ML service doesn't need its own auth — it's internal. The Next.js layer validates auth and forwards user context. MLflow experiment names include user ID for isolation.

**Alternatives considered**:
- **JWT forwarding**: Requires Python JWT validation, adds complexity.
- **Separate user DB in Python**: Duplicates user management.

### 8. User data seeding on registration

**Choice**: On successful registration, seed default `annotation_types` and `span_label_types` for the new user (copy from a hardcoded default set).

**Why**: New users need at least the standard annotation types (break_up, break_down, line) and span label types to start working. Without seeding, the app would be empty/broken.

### 9. Frontend auth state

**Choice**: Use `next-auth/react` `SessionProvider` wrapping the app layout. Components use `useSession()` hook. Server components use `auth()` from `@/auth`.

**Why**: Standard Auth.js pattern. SessionProvider handles token refresh automatically.

### 10. Lovable design integration

**Choice**: Convert Lovable HTML mockups to React/Next.js components using existing Tailwind + shadcn/ui patterns. Extract the structure and classes, adapt to Next.js `<Link>`, form actions, etc. Keep the visual design but rewrite as proper React.

**Why**: Lovable generates static HTML with Tailwind. Direct reuse of CSS classes is possible, but the HTML structure needs to become React components with proper event handling.

### 11. Settings page features

**Choice**: `/app/settings` page with sections:
- **Profile**: Display name, email (read-only for OAuth users)
- **Security**: Change password (credentials users only)
- **Danger zone**: Delete account (with confirmation dialog)

**Why**: Covers essential user management needs. Change password is table stakes. Delete account is GDPR-friendly. Keep it minimal — add more settings later as needed.

## Risks / Trade-offs

**[Data migration for existing deployments]** → Create a migration script that assigns all existing data to a default "admin" user. Document in DEPLOYMENT.md. The migration adds `user_id` as nullable first, runs the script, then makes it NOT NULL.

**[OAuth users can't set password]** → If a user registers via Google, they have no password. The settings page should show "Signed in via Google" instead of password change form. If they want password login later, they'd need a "set password" flow (defer to future).

**[JWT secret rotation]** → If `AUTH_SECRET` is changed, all existing sessions invalidate. Document this. Not a risk per se, but users will be logged out.

**[ML service trusts X-User-ID header]** → The ML service is only accessible internally (bound to 127.0.0.1 in docker-compose). If it were exposed publicly, this would be a security hole. Document that ML service must never be publicly accessible.

**[No email verification initially]** → Users can register with any email. This means no password reset via email. Acceptable for initial release — add email verification later.

**[Unique constraint on annotation_types.name becomes per-user]** → Currently `annotation_types.name` has a unique constraint. With multi-user, the same name can exist for different users. Change to unique constraint on `(user_id, name)`. Same for `span_label_types.name`.

## Migration Plan

### Database migration steps:
1. Add `users` table
2. Add `user_id` column (nullable) to: `charts`, `annotation_types`, `span_label_types`, `annotations`, `span_annotations`
3. Create a default admin user
4. UPDATE all existing rows to set `user_id = admin_user_id`
5. ALTER columns to NOT NULL
6. Add foreign key constraints
7. Drop old unique constraints, add new composite unique constraints (e.g., `(user_id, name)` for annotation_types)
8. Add indexes on `user_id` columns for query performance

### Deployment steps:
1. Update `.env` with new variables: `AUTH_SECRET`, `AUTH_GOOGLE_ID`, `AUTH_GOOGLE_SECRET`
2. Run database migrations
3. Run data migration script (assign existing data to admin user)
4. Deploy new app version
5. First login as admin user to verify data

### Rollback strategy:
- Keep `user_id` nullable during testing phase
- If rollback needed: revert code, `user_id` columns remain but are ignored
- No data loss on rollback

## Open Questions

1. **Default admin credentials**: What email/password should the default admin user have for migrating existing data? Suggest: configurable via env var `DEFAULT_ADMIN_EMAIL` / `DEFAULT_ADMIN_PASSWORD`.
2. **Google OAuth project**: Do we have a Google Cloud project with OAuth credentials ready, or should we document setup steps?
3. **ML model isolation**: Should trained models be fully isolated per user (separate MLflow experiments), or is a shared model registry acceptable initially?