sdb-claude/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Structure

This is a full-stack application with separate backend (Flask) and frontend (Next.js) components:

- **Backend** (`backend/`): Flask application with clean architecture
  - Entry point: `main.py`
  - App structure: `app/` with separate `routes/` and `services/` directories
  - Business logic in services, routes handle HTTP concerns only
  - Uses modern Python tooling (Black, Ruff, pytest)
  - CORS enabled for frontend integration
  - Python 3.12+ required

- **Frontend** (`frontend/`): React application with Vite
  - Uses React 19, TypeScript, React Router v7, and Tailwind CSS v4
  - Shadcn/ui components with consistent sidebar layout for authenticated users
  - Built with Vite for fast development and production builds

## Development Commands

### Backend (Flask)
```bash
cd backend
uv run python main.py         # Run the Flask development server (localhost:5000)
uv run pytest                 # Run tests
uv run pytest tests/          # Run specific test directory
uv run ruff check             # Lint code
uv run ruff format            # Format code
uv run black .                # Format code (alternative to ruff format)

# Database commands
uv run python migrate_db.py init-db    # Initialize database tables and seed data
uv run python migrate_db.py reset-db   # Reset database (drop and recreate all tables with seed data)
uv run flask --app app db init         # Initialize migrations (first time only)
uv run flask --app app db migrate      # Create new migration
uv run flask --app app db upgrade      # Apply migrations
```

#### Environment Variables
```bash
# Required for sessions and JWT
export SECRET_KEY="your_secret_key_for_sessions"
export JWT_SECRET_KEY="your_jwt_secret_key"

# OAuth Providers (configure as needed)
# Google OAuth
export GOOGLE_CLIENT_ID="your_google_client_id"
export GOOGLE_CLIENT_SECRET="your_google_client_secret"

# GitHub OAuth  
export GITHUB_CLIENT_ID="your_github_client_id"
export GITHUB_CLIENT_SECRET="your_github_client_secret"
```

### Frontend (Next.js)
```bash
cd frontend
bun dev                        # Start development server (preferred)
# Alternative package managers:
npm run dev / yarn dev / pnpm dev
bun run build                  # Build for production
bun run start                  # Start production server
bun run lint                   # Run ESLint
```

## Code Style

### Backend
- Line length: 80 characters
- Uses Ruff with comprehensive rule set (ALL rules enabled with specific ignores)
- Black formatting enforced
- Ignores: D100 (module docstrings), D104 (package docstrings)

### Frontend
- TypeScript with strict configuration
- ESLint with Next.js configuration
- Tailwind CSS for styling
- Uses Geist font family (sans and mono variants)

## Backend Architecture

The Flask backend follows a clean architecture pattern:

- **Routes** (`app/routes/`): Handle HTTP requests/responses, delegate to services
- **Services** (`app/services/`): Contain all business logic, pure functions when possible
- **Application Factory** (`app/__init__.py`): Creates and configures Flask app

Key principles:
- Routes should be thin - only handle HTTP concerns
- Business logic lives in services
- Services are testable in isolation
- Clear separation of concerns

## Authentication

The backend implements multi-provider OAuth authentication (Google, GitHub) with JWT tokens using Flask-JWT-Extended:

### Available Endpoints

**OAuth Authentication:**
- `GET /api/auth/providers` - Get list of available OAuth providers
- `GET /api/auth/login/<provider>` - Initiate OAuth login for specified provider (google, github)
- `GET /api/auth/callback/<provider>` - Handle OAuth callback from specified provider

**Password Authentication:**
- `POST /api/auth/register` - Register new user with email, password, and name
- `POST /api/auth/login` - Login with email and password

**Session Management:**
- `GET /api/auth/logout` - Logout current user (clears cookies)
- `GET /api/auth/me` - Get current user information (requires JWT)
- `POST /api/auth/refresh` - Refresh access token using refresh token

**Multi-Provider Management:**
- `GET /api/auth/link/<provider>` - Link additional OAuth provider to current user (requires JWT)
- `GET /api/auth/link/callback/<provider>` - Handle OAuth callback for linking provider
- `DELETE /api/auth/unlink/<provider>` - Unlink OAuth provider from current user (requires JWT)

**API Token Management:**
- `POST /api/auth/regenerate-api-token` - Generate new API token for current user (requires JWT)

**Example Endpoints:**
- `GET /api/protected` - Example protected endpoint (requires authentication)
- `GET /api/api-protected` - Example endpoint that accepts JWT or API token authentication
- `GET /api/admin` - Example admin-only endpoint (requires admin role)
- `GET /api/use-credits/<amount>` - Example endpoint that costs 5 credits to use
- `GET /api/expensive-operation` - Example endpoint that costs 10 credits to use

### Flask-JWT-Extended Features
- **Access Token**: Short-lived (15 minutes), contains user identity and claims
- **Refresh Token**: Long-lived (7 days), used to generate new access tokens
- **HTTP-only Cookies**: Automatic secure storage with Flask-JWT-Extended
- **Built-in Security**: CSRF protection, secure cookie settings
- **Cookie Paths**: Access tokens work on `/api/`, refresh tokens on `/api/auth/refresh`

### Usage Flow

**Password Authentication:**
1. **Register**: `POST /api/auth/register` with `{"email": "...", "password": "...", "name": "..."}`
2. **Login**: `POST /api/auth/login` with `{"email": "...", "password": "..."}`
3. JWT tokens are automatically set as HTTP-only cookies
4. Access protected endpoints - Flask-JWT-Extended handles token validation

**OAuth Authentication:**
1. Call `/api/auth/providers` to get available OAuth providers
2. Call `/api/auth/login/<provider>` to initiate OAuth flow (e.g., `/api/auth/login/google` or `/api/auth/login/github`)
3. Redirect user to the returned OAuth URL
4. Provider redirects back to `/api/auth/callback/<provider>` with authorization code
5. JWT tokens are automatically set as HTTP-only cookies
6. Access protected endpoints - Flask-JWT-Extended handles token validation

**Multi-Provider Management:**
1. User authenticates with password or OAuth provider
2. Call `/api/auth/link/<provider>` to link additional OAuth providers  
3. Users can sign in with password or any linked OAuth provider
4. Call `DELETE /api/auth/unlink/<provider>` to remove OAuth providers (minimum 1 auth method required)
5. User data includes `providers` array showing all available authentication methods

### Authentication Components
- **User Model**: Stores user profile information (email, name, picture, role)
- **UserOAuth Model**: Stores provider-specific authentication data
- **AuthService**: Handles multi-provider OAuth flow and Flask-JWT-Extended integration
- **TokenService**: Simplified token generation using Flask-JWT-Extended
- **OAuthProviderRegistry**: Manages available OAuth providers based on environment variables
- **OAuthProvider**: Abstract base class for OAuth providers (Google, GitHub, etc.)
- **Decorators**: `@require_auth`, `@require_admin`, `@require_role()` for access control
- **Flask-JWT-Extended**: Handles cookie management, validation, and security

### Database Schema
- **users** table: Core user information (id, email, name, picture, password_hash, role, is_active, api_token, api_token_expires_at, timestamps)
- **user_oauth** table: Provider-specific data (user_id, provider, provider_id, email, name, picture)
- **Relationships**: One user can have multiple OAuth providers, enabling flexible authentication
- **Authentication**: Users can authenticate via password OR OAuth providers (or both)
- **User Status**: Users have an `is_active` field (default: true) for account management
- **API Tokens**: Each user automatically gets an API token with no expiration for programmatic access
- **Roles**: First user gets "admin" role, subsequent users get "user" role by default

### Supported Authentication Methods
- **Password**: Traditional email/password authentication with Werkzeug secure hashing
- **Google OAuth**: OpenID Connect with `openid email profile` scopes
- **GitHub OAuth**: OAuth 2.0 with `user:email` scope to access user profile and email
- **API Token**: Long-lived tokens for programmatic access (no expiration by default)

### Role-Based Access Control
- **Admin Role**: First user automatically gets admin privileges
- **User Role**: Default role for all subsequent users
- **Role Assignment**: Automatic during registration (password or OAuth)
- **Access Control**: Use decorators to protect routes by role
- **JWT Integration**: Role included in JWT tokens for stateless authorization

### Available Authentication Decorators
- `@require_auth` - Requires authentication (JWT or API token)
- `@require_role("role_name")` - Requires specific role (chainable with require_auth)
- `@require_credits(amount)` - Requires and deducts specified credits from user

### Multi-Authentication Benefits
- **Flexible Registration**: Register with email/password or OAuth providers
- **Account Linking**: Link multiple authentication methods to one account
- **Flexible Sign-in**: Sign in with password, Google, or GitHub
- **API Access**: Programmatic access via API tokens for scripts and applications
- **Account Recovery**: Multiple authentication options prevent lockout
- **Data Consistency**: Single user profile updated from any authentication method
- **Security**: Werkzeug secure password hashing and OAuth security best practices
- **Role-Based Access**: Fine-grained permission control with automatic admin assignment

### API Token Usage

**Getting Your API Token:**
1. Authenticate via password or OAuth to get JWT tokens
2. Call `POST /api/auth/regenerate-api-token` to get a new API token
3. Use the returned token for programmatic access

**Using API Tokens:**
```bash
# Include API token in Authorization header
curl -H "Authorization: Bearer YOUR_API_TOKEN" http://localhost:5000/api/api-protected

# Alternative format
curl -H "Authorization: Token YOUR_API_TOKEN" http://localhost:5000/api/api-protected
```

**API Token Features:**
- **No Expiration**: Tokens don't expire by default (can be configured per token)
- **Regeneration**: Users can regenerate tokens at any time via `/api/auth/regenerate-api-token`
- **Automatic Creation**: New tokens generated automatically during user registration
- **Role Support**: Tokens inherit user's role for role-based access control
- **Security**: 32-byte URL-safe tokens using `secrets.token_urlsafe()`

## Plan System

The backend includes a subscription plan system that assigns users to different plans with varying credit limits:

### Available Plans

- **Free Plan** (`free`): 25 credits (75 max) - Default plan for new users
- **Premium Plan** (`premium`): 50 credits (150 max) - Enhanced features with increased limits  
- **Pro Plan** (`pro`): 100 credits (300 max) - Full access with unlimited usage

### Plan Assignment

- **First User**: Automatically assigned to Pro plan with admin role
- **Subsequent Users**: Automatically assigned to Free plan with user role
- **Plan Information**: Included in all authentication responses (login, register, /me endpoint)

### Database Schema

- **plans** table: id, code, name, description, credits, max_credits
- **users.plan_id**: Foreign key to plans table (required)
- **users.credits**: Current user credits (initialized from plan.credits)
- **Relationship**: Each user belongs to exactly one plan

### Automatic Initialization

The plan system is automatically initialized when the Flask app starts:

- **Database Creation**: `db.create_all()` creates all tables including plans and users
- **Plan Seeding**: Automatically seeds the three default plans if the plans table is empty
- **User Migration**: Automatically assigns plans and credits to existing users who don't have them
- **First User**: Gets Pro plan (100 credits) and admin role automatically
- **Subsequent Users**: Get Free plan (25 credits) and user role automatically

No manual migration scripts are needed - everything happens automatically on app startup.

### Plan Information in API Responses

All user data returned by authentication endpoints includes plan and credits information:

```json
{
  "user": {
    "id": "1",
    "email": "user@example.com",
    "name": "User Name",
    "role": "user",
    "credits": 25,
    "plan": {
      "id": 1,
      "code": "free",
      "name": "Free Plan", 
      "description": "Basic features with limited usage",
      "credits": 25,
      "max_credits": 75
    }
  }
}
```

### Credits System

- **User Credits**: Each user has a `credits` field tracking their current available credits
- **Initial Credits**: Set to the plan's `credits` value when user is created
- **Plan Credits**: The default credits amount for the plan (what new users get)
- **Max Credits**: The maximum credits a user on this plan can have
- **Authentication**: Credits are included in JWT tokens and all auth responses

### Credit Usage Decorator

Use the `@require_credits(amount)` decorator to protect endpoints that consume credits:

```python
from app.services.decorators import require_auth, require_credits

@bp.route("/ai-generation")
@require_auth
@require_credits(10)  # Costs 10 credits to use
def ai_generation():
    """AI generation endpoint that costs 10 credits."""
    return {"result": "AI generated content"}
```

**Features:**
- **Automatic Deduction**: Credits are deducted from user's balance before endpoint execution
- **Insufficient Credits**: Returns HTTP 402 (Payment Required) with clear error message
- **Database Updates**: Credits are updated in real-time in the database
- **Authentication**: Works with both JWT and API token authentication
- **Error Handling**: If endpoint fails, credits are still deducted (transaction-like behavior)

**Example Error Response:**
```json
{
  "error": "Insufficient credits. Required: 10, Available: 5"
}
```