chore(frontend): remove unnecessary newline in overrides field of package.json

- Replaced `pytest.mark.skipif` with `pytest.skip` to better manage scenarios where `schemathesis` is not installed.
- Added a fallback test function to ensure explicit handling for missing dependencies.

.env.demo

@@ -0,0 +1,55 @@
+# Common settings
+PROJECT_NAME=App
+VERSION=1.0.0
+
+# Database settings
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=app
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+DATABASE_URL=postgresql://postgres:postgres@db:5432/app
+
+# Backend settings
+BACKEND_PORT=8000
+# CRITICAL: Generate a secure SECRET_KEY for production!
+# Generate with: python -c 'import secrets; print(secrets.token_urlsafe(32))'
+# Must be at least 32 characters
+SECRET_KEY=demo_secret_key_for_testing_only_do_not_use_in_prod
+ENVIRONMENT=development
+DEMO_MODE=true
+DEBUG=true
+BACKEND_CORS_ORIGINS=["http://localhost:3000"]
+FIRST_SUPERUSER_EMAIL=admin@example.com
+# IMPORTANT: Use a strong password (min 12 chars, mixed case, digits)
+# Default weak passwords like 'Admin123' are rejected
+FIRST_SUPERUSER_PASSWORD=Admin123!
+
+# OAuth Configuration (Social Login)
+# Set OAUTH_ENABLED=true and configure at least one provider
+OAUTH_ENABLED=false
+OAUTH_AUTO_LINK_BY_EMAIL=true
+
+# Google OAuth (from Google Cloud Console > APIs & Services > Credentials)
+# https://console.cloud.google.com/apis/credentials
+# OAUTH_GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+# OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# GitHub OAuth (from GitHub > Settings > Developer settings > OAuth Apps)
+# https://github.com/settings/developers
+# OAUTH_GITHUB_CLIENT_ID=your-github-client-id
+# OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# OAuth Provider Mode (Authorization Server for MCP/third-party clients)
+# Set OAUTH_PROVIDER_ENABLED=true to act as an OAuth 2.0 Authorization Server
+OAUTH_PROVIDER_ENABLED=true
+# IMPORTANT: Must be HTTPS in production!
+OAUTH_ISSUER=http://localhost:8000
+
+# Frontend settings
+FRONTEND_PORT=3000
+FRONTEND_URL=http://localhost:3000
+NEXT_PUBLIC_API_URL=http://localhost:8000
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NODE_ENV=development

.env.template

@@ -5,21 +5,51 @@ VERSION=1.0.0
 # Database settings
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=postgres
-POSTGRES_DB=App
+POSTGRES_DB=app
 POSTGRES_HOST=db
 POSTGRES_PORT=5432
 DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
 
 # Backend settings
 BACKEND_PORT=8000
-SECRET_KEY=your_secret_key_here
+# CRITICAL: Generate a secure SECRET_KEY for production!
+# Generate with: python -c 'import secrets; print(secrets.token_urlsafe(32))'
+# Must be at least 32 characters
+SECRET_KEY=your_secret_key_here_REPLACE_WITH_GENERATED_KEY_32_CHARS_MIN
 ENVIRONMENT=development
+DEMO_MODE=false
 DEBUG=true
 BACKEND_CORS_ORIGINS=["http://localhost:3000"]
 FIRST_SUPERUSER_EMAIL=admin@example.com
-FIRST_SUPERUSER_PASSWORD=Admin123
+# IMPORTANT: Use a strong password (min 12 chars, mixed case, digits)
+# Default weak passwords like 'Admin123' are rejected
+FIRST_SUPERUSER_PASSWORD=YourStrongPassword123!
+
+# OAuth Configuration (Social Login)
+# Set OAUTH_ENABLED=true and configure at least one provider
+OAUTH_ENABLED=false
+OAUTH_AUTO_LINK_BY_EMAIL=true
+
+# Google OAuth (from Google Cloud Console > APIs & Services > Credentials)
+# https://console.cloud.google.com/apis/credentials
+# OAUTH_GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+# OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# GitHub OAuth (from GitHub > Settings > Developer settings > OAuth Apps)
+# https://github.com/settings/developers
+# OAUTH_GITHUB_CLIENT_ID=your-github-client-id
+# OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# OAuth Provider Mode (Authorization Server for MCP/third-party clients)
+# Set OAUTH_PROVIDER_ENABLED=true to act as an OAuth 2.0 Authorization Server
+OAUTH_PROVIDER_ENABLED=false
+# IMPORTANT: Must be HTTPS in production!
+OAUTH_ISSUER=http://localhost:8000
 
 # Frontend settings
 FRONTEND_PORT=3000
+FRONTEND_URL=http://localhost:3000
 NEXT_PUBLIC_API_URL=http://localhost:8000
-NODE_ENV=development
+NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+NODE_ENV=development

.github/workflows/README.md

@@ -0,0 +1,108 @@
+# GitHub Actions Workflows
+
+This directory contains CI/CD workflow templates for automated testing and deployment.
+
+## 🚀 Quick Setup
+
+To enable CI/CD workflows:
+
+1. **Rename template files** by removing the `.template` extension:
+   ```bash
+   mv backend-tests.yml.template backend-tests.yml
+   mv frontend-tests.yml.template frontend-tests.yml
+   mv e2e-tests.yml.template e2e-tests.yml
+   ```
+
+2. **Set up Codecov** (optional, for coverage badges):
+   - Sign up at https://codecov.io
+   - Add your repository
+   - Get your `CODECOV_TOKEN`
+   - Add it to GitHub repository secrets
+
+3. **Update README badges**:
+   Replace the static badges in the main README.md with:
+   ```markdown
+   [![Backend Tests](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/backend-tests.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/backend-tests.yml)
+   [![Backend Coverage](https://codecov.io/gh/YOUR_ORG/YOUR_REPO/branch/main/graph/badge.svg?flag=backend)](https://codecov.io/gh/YOUR_ORG/YOUR_REPO)
+   [![Frontend Tests](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/frontend-tests.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/frontend-tests.yml)
+   [![Frontend Coverage](https://codecov.io/gh/YOUR_ORG/YOUR_REPO/branch/main/graph/badge.svg?flag=frontend)](https://codecov.io/gh/YOUR_ORG/YOUR_REPO)
+   [![E2E Tests](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/e2e-tests.yml/badge.svg)](https://github.com/YOUR_ORG/YOUR_REPO/actions/workflows/e2e-tests.yml)
+   ```
+
+## 📋 Workflow Descriptions
+
+### `backend-tests.yml`
+- Runs on: Push to main/develop, PRs affecting backend code
+- Tests: Backend unit and integration tests
+- Coverage: Uploads to Codecov
+- Database: Spins up PostgreSQL service
+
+### `frontend-tests.yml`
+- Runs on: Push to main/develop, PRs affecting frontend code
+- Tests: Frontend unit tests (Jest)
+- Coverage: Uploads to Codecov
+- Fast: Uses bun cache
+
+### `e2e-tests.yml`
+- Runs on: All pushes and PRs
+- Tests: End-to-end tests (Playwright)
+- Coverage: Full stack integration
+- Artifacts: Saves test reports for 30 days
+
+## 🔧 Customization
+
+### Adjust trigger paths
+Modify the `paths` section to control when workflows run:
+```yaml
+paths:
+  - 'backend/**'
+  - 'shared/**'  # Add if you have shared code
+```
+
+### Change test commands
+Update the test steps to match your needs:
+```yaml
+- name: Run tests
+  run: pytest -v --custom-flag
+```
+
+### Add deployment
+Create a new workflow for deployment:
+```yaml
+name: Deploy to Production
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+```
+
+## 🛡️ Security
+
+- Never commit secrets to workflows
+- Use GitHub Secrets for sensitive data
+- Review workflow permissions
+- Keep actions up to date
+
+## 📊 Coverage Reports
+
+With Codecov enabled, you'll get:
+- Coverage trends over time
+- PR coverage comparisons
+- Coverage per file/folder
+- Interactive coverage explorer
+
+Access at: `https://codecov.io/gh/YOUR_ORG/YOUR_REPO`
+
+## 💡 Tips
+
+- **PR checks**: Workflows run on PRs automatically
+- **Status checks**: Set as required in branch protection
+- **Debug logs**: Re-run with debug logging enabled
+- **Artifacts**: Download from workflow run page
+- **Matrix builds**: Test multiple Python/Node versions
+
+## 📚 Further Reading
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [Codecov Documentation](https://docs.codecov.com)
+- [Playwright CI Guide](https://playwright.dev/docs/ci)

.github/workflows/backend-e2e-tests.yml.template

@@ -0,0 +1,77 @@
+# Backend E2E Tests CI Pipeline
+#
+# Runs end-to-end tests with real PostgreSQL via Testcontainers
+# and validates API contracts with Schemathesis.
+#
+# To enable: Rename this file to backend-e2e-tests.yml
+
+name: Backend E2E Tests
+
+on:
+  push:
+    branches: [main, develop]
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-e2e-tests.yml'
+  pull_request:
+    branches: [main, develop]
+    paths:
+      - 'backend/**'
+  workflow_dispatch:
+
+jobs:
+  e2e-tests:
+    runs-on: ubuntu-latest
+    # E2E test failures don't block merge - they're advisory
+    continue-on-error: true
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Cache uv dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-${{ hashFiles('backend/uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-
+
+      - name: Install dependencies (with E2E)
+        working-directory: ./backend
+        run: uv sync --extra dev --extra e2e
+
+      - name: Check Docker availability
+        id: docker-check
+        run: |
+          if docker info > /dev/null 2>&1; then
+            echo "available=true" >> $GITHUB_OUTPUT
+            echo "Docker is available"
+          else
+            echo "available=false" >> $GITHUB_OUTPUT
+            echo "::warning::Docker not available - E2E tests will be skipped"
+          fi
+
+      - name: Run E2E tests
+        if: steps.docker-check.outputs.available == 'true'
+        working-directory: ./backend
+        env:
+          IS_TEST: "True"
+          SECRET_KEY: "e2e-test-secret-key-minimum-32-characters-long"
+          PYTHONPATH: "."
+        run: |
+          uv run pytest tests/e2e/ -v --tb=short
+
+      - name: E2E tests skipped
+        if: steps.docker-check.outputs.available != 'true'
+        run: echo "E2E tests were skipped due to Docker unavailability"

.github/workflows/backend-tests.yml.template

@@ -0,0 +1,86 @@
+# Backend Unit Tests CI Pipeline
+#
+# Rename this file to backend-tests.yml to enable it
+# This will make the backend test badges dynamic
+#
+# Required repository secrets:
+# - None (uses default GITHUB_TOKEN)
+
+name: Backend Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'backend/**'
+      - '.github/workflows/backend-tests.yml'
+  pull_request:
+    branches: [ main, develop ]
+    paths:
+      - 'backend/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+        cache: 'pip'
+
+    - name: Install dependencies
+      working-directory: ./backend
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+
+    - name: Run tests with coverage
+      working-directory: ./backend
+      env:
+        IS_TEST: True
+        POSTGRES_HOST: localhost
+        POSTGRES_PORT: 5432
+        POSTGRES_USER: postgres
+        POSTGRES_PASSWORD: postgres
+        POSTGRES_DB: test_db
+        SECRET_KEY: test-secret-key-for-ci-only
+      run: |
+        pytest --cov=app --cov-report=xml --cov-report=term-missing -v
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./backend/coverage.xml
+        flags: backend
+        name: backend-coverage
+        fail_ci_if_error: true
+        token: ${{ secrets.CODECOV_TOKEN }}
+
+    - name: Generate coverage badge
+      uses: schneegans/dynamic-badges-action@v1.7.0
+      with:
+        auth: ${{ secrets.GIST_SECRET }}
+        gistID: YOUR_GIST_ID_HERE
+        filename: backend-coverage.json
+        label: backend coverage
+        message: ${{ env.COVERAGE }}%
+        color: brightgreen

.github/workflows/e2e-tests.yml.template

@@ -0,0 +1,105 @@
+# End-to-End Tests CI Pipeline
+#
+# Rename this file to e2e-tests.yml to enable it
+# This will make the E2E test badges dynamic
+#
+# Required repository secrets:
+# - None (uses default GITHUB_TOKEN)
+
+name: E2E Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    services:
+      postgres:
+        image: postgres:15
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: test_db
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+        ports:
+          - 5432:5432
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+        cache: 'pip'
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        cache-dependency-path: './frontend/package-lock.json'
+
+    - name: Install backend dependencies
+      working-directory: ./backend
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+
+    - name: Setup backend database
+      working-directory: ./backend
+      env:
+        POSTGRES_HOST: localhost
+        POSTGRES_PORT: 5432
+        POSTGRES_USER: postgres
+        POSTGRES_PASSWORD: postgres
+        POSTGRES_DB: test_db
+        SECRET_KEY: test-secret-key-for-ci-only
+      run: |
+        alembic upgrade head
+        python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"
+
+    - name: Start backend server
+      working-directory: ./backend
+      env:
+        POSTGRES_HOST: localhost
+        POSTGRES_PORT: 5432
+        POSTGRES_USER: postgres
+        POSTGRES_PASSWORD: postgres
+        POSTGRES_DB: test_db
+        SECRET_KEY: test-secret-key-for-ci-only
+      run: |
+        uvicorn app.main:app --host 0.0.0.0 --port 8000 &
+        sleep 5  # Wait for server to start
+
+    - name: Install frontend dependencies
+      working-directory: ./frontend
+      run: npm ci
+
+    - name: Install Playwright browsers
+      working-directory: ./frontend
+      run: npx playwright install --with-deps chromium
+
+    - name: Run E2E tests
+      working-directory: ./frontend
+      env:
+        NEXT_PUBLIC_API_URL: http://localhost:8000/api/v1
+      run: npm run test:e2e
+
+    - name: Upload test results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: playwright-report
+        path: frontend/playwright-report/
+        retention-days: 30

.github/workflows/frontend-tests.yml.template

@@ -0,0 +1,51 @@
+# Frontend Unit Tests CI Pipeline
+#
+# Rename this file to frontend-tests.yml to enable it
+# This will make the frontend test badges dynamic
+#
+# Required repository secrets:
+# - CODECOV_TOKEN (for coverage upload)
+
+name: Frontend Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'frontend/**'
+      - '.github/workflows/frontend-tests.yml'
+  pull_request:
+    branches: [ main, develop ]
+    paths:
+      - 'frontend/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        cache-dependency-path: './frontend/package-lock.json'
+
+    - name: Install dependencies
+      working-directory: ./frontend
+      run: npm ci
+
+    - name: Run unit tests with coverage
+      working-directory: ./frontend
+      run: npm run test:coverage
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        files: ./frontend/coverage/coverage-final.json
+        flags: frontend
+        name: frontend-coverage
+        fail_ci_if_error: true
+        token: ${{ secrets.CODECOV_TOKEN }}

.gitignore

@@ -27,6 +27,10 @@ coverage
 # nyc test coverage
 .nyc_output
 
+# Playwright authentication state (contains test auth tokens)
+frontend/e2e/.auth/
+**/playwright/.auth/
+
 # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
 .grunt
 
@@ -147,7 +151,6 @@ dist/
 downloads/
 eggs/
 .eggs/
-lib/
 lib64/
 parts/
 sdist/
@@ -175,6 +178,7 @@ htmlcov/
 .nox/
 .coverage
 .coverage.*
+coverage.json
 .cache
 nosetests.xml
 coverage.xml
@@ -183,7 +187,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
-
+backend/.benchmarks
 # Translations
 *.mo
 *.pot
@@ -264,6 +268,7 @@ celerybeat.pid
 .env
 .env.*
 !.env.template
+!.env.demo
 .venv
 env/
 venv/
@@ -302,6 +307,6 @@ cython_debug/
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 .idea/
 *.iml
-
+.junie/*
 # Docker volumes
 postgres_data*/

AGENTS.md

@@ -0,0 +1,315 @@
+# AGENTS.md
+
+AI coding assistant context for FastAPI + Next.js Full-Stack Template.
+
+## Quick Start
+
+```bash
+# Backend (Python with uv)
+cd backend
+make install-dev              # Install dependencies
+make test                     # Run tests
+uv run uvicorn app.main:app --reload  # Start dev server
+
+# Frontend (Node.js)
+cd frontend
+bun install                   # Install dependencies
+bun run dev                   # Start dev server
+bun run generate:api          # Generate API client from OpenAPI
+bun run test:e2e              # Run E2E tests
+```
+
+**Access points:**
+- Frontend: **http://localhost:3000**
+- Backend API: **http://localhost:8000**
+- API Docs: **http://localhost:8000/docs**
+
+Default superuser (change in production):
+- Email: `admin@example.com`
+- Password: `admin123`
+
+## Project Architecture
+
+**Full-stack TypeScript/Python application:**
+
+```
+├── backend/                 # FastAPI backend
+│   ├── app/
+│   │   ├── api/            # API routes (auth, users, organizations, admin)
+│   │   ├── core/           # Core functionality (auth, config, database)
+│   │   ├── repositories/   # Repository pattern (database operations)
+│   │   ├── models/         # SQLAlchemy ORM models
+│   │   ├── schemas/        # Pydantic request/response schemas
+│   │   ├── services/       # Business logic layer
+│   │   └── utils/          # Utilities (security, device detection)
+│   ├── tests/              # 96% coverage, 987 tests
+│   └── alembic/            # Database migrations
+│
+└── frontend/               # Next.js 16 frontend
+    ├── src/
+    │   ├── app/           # App Router pages (Next.js 16)
+    │   ├── components/    # React components
+    │   ├── lib/
+    │   │   ├── api/       # Auto-generated API client
+    │   │   └── stores/    # Zustand state management
+    │   └── hooks/         # Custom React hooks
+    └── e2e/               # Playwright E2E tests (56 passing)
+```
+
+## Critical Implementation Notes
+
+### Authentication Flow
+- **JWT-based**: Access tokens (15 min) + refresh tokens (7 days)
+- **OAuth/Social Login**: Google and GitHub with PKCE support
+- **Session tracking**: Database-backed with device info, IP, user agent
+- **Token refresh**: Validates JTI in database, not just JWT signature
+- **Authorization**: FastAPI dependencies in `api/dependencies/auth.py`
+  - `get_current_user`: Requires valid access token
+  - `get_current_active_user`: Requires active account
+  - `get_optional_current_user`: Accepts authenticated or anonymous
+  - `get_current_superuser`: Requires superuser flag
+
+### OAuth Provider Mode (MCP Integration)
+Full OAuth 2.0 Authorization Server for MCP (Model Context Protocol) clients:
+- **Authorization Code Flow with PKCE**: RFC 7636 compliant
+- **JWT access tokens**: Self-contained, no DB lookup required
+- **Opaque refresh tokens**: Stored hashed in database, supports rotation
+- **Token introspection**: RFC 7662 compliant endpoint
+- **Token revocation**: RFC 7009 compliant endpoint
+- **Server metadata**: RFC 8414 compliant discovery endpoint
+- **Consent management**: User can review and revoke app permissions
+
+**API endpoints:**
+- `GET /.well-known/oauth-authorization-server` - Server metadata
+- `GET /oauth/provider/authorize` - Authorization endpoint
+- `POST /oauth/provider/authorize/consent` - Consent submission
+- `POST /oauth/provider/token` - Token endpoint
+- `POST /oauth/provider/revoke` - Token revocation
+- `POST /oauth/provider/introspect` - Token introspection
+- Client management endpoints (admin only)
+
+**Scopes supported:** `openid`, `profile`, `email`, `read:users`, `write:users`, `admin`
+
+**OAuth Configuration (backend `.env`):**
+```bash
+# OAuth Social Login (as OAuth Consumer)
+OAUTH_ENABLED=true                           # Enable OAuth social login
+OAUTH_AUTO_LINK_BY_EMAIL=true                # Auto-link accounts by email
+OAUTH_STATE_EXPIRE_MINUTES=10                # CSRF state expiration
+
+# Google OAuth
+OAUTH_GOOGLE_CLIENT_ID=your-google-client-id
+OAUTH_GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# GitHub OAuth
+OAUTH_GITHUB_CLIENT_ID=your-github-client-id
+OAUTH_GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# OAuth Provider Mode (as Authorization Server for MCP)
+OAUTH_PROVIDER_ENABLED=true                  # Enable OAuth provider mode
+OAUTH_ISSUER=https://api.yourdomain.com      # JWT issuer URL (must be HTTPS in production)
+```
+
+### Database Pattern
+- **Async SQLAlchemy 2.0** with PostgreSQL
+- **Connection pooling**: 20 base connections, 50 max overflow
+- **Repository base class**: `repositories/base.py` with common operations
+- **Migrations**: Alembic with helper script `migrate.py`
+  - `python migrate.py auto "message"` - Generate and apply
+  - `python migrate.py list` - View history
+
+### Frontend State Management
+- **Zustand stores**: Lightweight state management
+- **TanStack Query**: API data fetching/caching
+- **Auto-generated client**: From OpenAPI spec via `bun run generate:api`
+- **Dependency Injection**: ALWAYS use `useAuth()` from `AuthContext`, NEVER import `useAuthStore` directly
+
+### Internationalization (i18n)
+- **next-intl v4**: Type-safe internationalization library
+- **Locale routing**: `/en/*`, `/it/*` (English and Italian supported)
+- **Translation files**: `frontend/messages/en.json`, `frontend/messages/it.json`
+- **LocaleSwitcher**: Component for seamless language switching
+- **SEO-friendly**: Locale-aware metadata, sitemaps, and robots.txt
+- **Type safety**: Full TypeScript support for translations
+- **Utilities**: `frontend/src/lib/i18n/` (metadata, routing, utils)
+
+### Organization System
+Three-tier RBAC:
+- **Owner**: Full control (delete org, manage all members)
+- **Admin**: Add/remove members, assign admin role (not owner)
+- **Member**: Read-only organization access
+
+Permission dependencies in `api/dependencies/permissions.py`:
+- `require_organization_owner`
+- `require_organization_admin`
+- `require_organization_member`
+- `can_manage_organization_member`
+
+### Testing Infrastructure
+
+**Backend Unit/Integration (pytest + SQLite):**
+- 96% coverage, 987 tests
+- Security-focused: JWT attacks, session hijacking, privilege escalation
+- Async fixtures in `tests/conftest.py`
+- Run: `IS_TEST=True uv run pytest` or `make test`
+- Coverage: `make test-cov`
+
+**Backend E2E (pytest + Testcontainers + Schemathesis):**
+- Real PostgreSQL via Docker containers
+- OpenAPI contract testing with Schemathesis
+- Install: `make install-e2e`
+- Run: `make test-e2e`
+- Schema tests: `make test-e2e-schema`
+- Docs: `backend/docs/E2E_TESTING.md`
+
+**Frontend Unit Tests (Jest):**
+- 97% coverage
+- Component, hook, and utility testing
+- Run: `bun run test`
+- Coverage: `bun run test:coverage`
+
+**Frontend E2E Tests (Playwright):**
+- 56 passing, 1 skipped (zero flaky tests)
+- Complete user flows (auth, navigation, settings)
+- Run: `bun run test:e2e`
+- UI mode: `bun run test:e2e:ui`
+
+### Development Tooling
+
+**Backend:**
+- **uv**: Modern Python package manager (10-100x faster than pip)
+- **Ruff**: All-in-one linting/formatting (replaces Black, Flake8, isort)
+- **Pyright**: Static type checking (strict mode)
+- **pip-audit**: Dependency vulnerability scanning (OSV database)
+- **detect-secrets**: Hardcoded secrets detection
+- **pip-licenses**: License compliance checking
+- **pre-commit**: Git hook framework (Ruff, detect-secrets, standard checks)
+- **Makefile**: `make help` for all commands
+
+**Frontend:**
+- **Next.js 16**: App Router with React 19
+- **TypeScript**: Full type safety
+- **TailwindCSS + shadcn/ui**: Design system
+- **ESLint + Prettier**: Code quality
+
+### Environment Configuration
+
+**Backend** (`.env`):
+```bash
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=your_password
+POSTGRES_HOST=db
+POSTGRES_PORT=5432
+POSTGRES_DB=app
+
+SECRET_KEY=your-secret-key-min-32-chars
+ENVIRONMENT=development|production
+CSP_MODE=relaxed|strict|disabled
+
+FIRST_SUPERUSER_EMAIL=admin@example.com
+FIRST_SUPERUSER_PASSWORD=admin123
+
+BACKEND_CORS_ORIGINS=["http://localhost:3000"]
+```
+
+**Frontend** (`.env.local`):
+```bash
+NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
+```
+
+## Common Development Workflows
+
+### Adding a New API Endpoint
+
+1. **Define schema** in `backend/app/schemas/`
+2. **Create repository** in `backend/app/repositories/`
+3. **Implement route** in `backend/app/api/routes/`
+4. **Register router** in `backend/app/api/main.py`
+5. **Write tests** in `backend/tests/api/`
+6. **Generate frontend client**: `bun run generate:api`
+
+### Database Migrations
+
+```bash
+cd backend
+python migrate.py generate "description"  # Create migration
+python migrate.py apply                   # Apply migrations
+python migrate.py auto "description"      # Generate + apply
+```
+
+### Frontend Component Development
+
+1. **Create component** in `frontend/src/components/`
+2. **Follow design system** (see `frontend/docs/design-system/`)
+3. **Use dependency injection** for auth (`useAuth()` not `useAuthStore`)
+4. **Write tests** in `frontend/tests/` or `__tests__/`
+5. **Run type check**: `bun run type-check`
+
+## Security Features
+
+- **Password hashing**: bcrypt with salt rounds
+- **Rate limiting**: 60 req/min default, 10 req/min on auth endpoints
+- **Security headers**: CSP, X-Frame-Options, HSTS, etc.
+- **CSRF protection**: Built into FastAPI
+- **Session revocation**: Database-backed session tracking
+- **Comprehensive security tests**: JWT algorithm attacks, session hijacking, privilege escalation
+- **Dependency vulnerability scanning**: `make dep-audit` (pip-audit against OSV database)
+- **License compliance**: `make license-check` (blocks GPL-3.0/AGPL)
+- **Secrets detection**: Pre-commit hook blocks hardcoded secrets
+- **Unified security pipeline**: `make audit` (all security checks), `make check` (quality + security + tests)
+
+## Docker Deployment
+
+```bash
+# Development (with hot reload)
+docker-compose -f docker-compose.dev.yml up
+
+# Production
+docker-compose up -d
+
+# Run migrations
+docker-compose exec backend alembic upgrade head
+
+# Create first superuser
+docker-compose exec backend python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"
+```
+
+## Documentation
+
+**For comprehensive documentation, see:**
+- **[README.md](./README.md)** - User-facing project overview
+- **[CLAUDE.md](./CLAUDE.md)** - Claude Code-specific guidance
+- **Backend docs**: `backend/docs/` (Architecture, Coding Standards, Common Pitfalls, Feature Examples)
+- **Frontend docs**: `frontend/docs/` (Design System, Architecture, E2E Testing)
+- **API docs**: http://localhost:8000/docs (Swagger UI when running)
+
+## Current Status (Nov 2025)
+
+### Completed Features ✅
+- Authentication system (JWT with refresh tokens, OAuth/social login)
+- **OAuth Provider Mode (MCP-ready)**: Full OAuth 2.0 Authorization Server
+- Session management (device tracking, revocation)
+- User management (full lifecycle, password change)
+- Organization system (multi-tenant with RBAC)
+- Admin panel (user/org management, bulk operations)
+- **Internationalization (i18n)** with English and Italian
+- Comprehensive test coverage (96% backend, 97% frontend unit, 56 E2E tests)
+- Design system documentation
+- **Marketing landing page** with animations
+- **`/dev` documentation portal** with live examples
+- **Toast notifications**, charts, markdown rendering
+- **SEO optimization** (sitemap, robots.txt, locale metadata)
+- Docker deployment
+
+### In Progress 🚧
+- Frontend admin pages (70% complete)
+- Email integration (templates ready, SMTP pending)
+
+### Planned 🔮
+- GitHub Actions CI/CD
+- Additional languages (Spanish, French, German, etc.)
+- SSO/SAML authentication
+- Real-time notifications (WebSockets)
+- Webhook system
+- Background job processing
+- File upload/storage

CLAUDE.md

@@ -0,0 +1,253 @@
+# CLAUDE.md
+
+Claude Code context for FastAPI + Next.js Full-Stack Template.
+
+**See [AGENTS.md](./AGENTS.md) for project context, architecture, and development commands.**
+
+## Claude Code-Specific Guidance
+
+### Critical User Preferences
+
+#### File Operations - NEVER Use Heredoc/Cat Append
+**ALWAYS use Read/Write/Edit tools instead of `cat >> file << EOF` commands.**
+
+This triggers manual approval dialogs and disrupts workflow.
+
+```bash
+# WRONG ❌
+cat >> file.txt << EOF
+content
+EOF
+
+# CORRECT ✅ - Use Read, then Write tools
+```
+
+#### Work Style
+- User prefers autonomous operation without frequent interruptions
+- Ask for batch permissions upfront for long work sessions
+- Work independently, document decisions clearly
+- Only use emojis if the user explicitly requests it
+
+### When Working with This Stack
+
+**Dependency Management:**
+- Backend uses **uv** (modern Python package manager), not pip
+- Always use `uv run` prefix: `IS_TEST=True uv run pytest`
+- Or use Makefile commands: `make test`, `make install-dev`
+- Add dependencies: `uv add <package>` or `uv add --dev <package>`
+
+**Database Migrations:**
+- Use the `migrate.py` helper script, not Alembic directly
+- Generate + apply: `python migrate.py auto "message"`
+- Never commit migrations without testing them first
+- Check current state: `python migrate.py current`
+
+**Frontend API Client Generation:**
+- Run `bun run generate:api` after backend schema changes
+- Client is auto-generated from OpenAPI spec
+- Located in `frontend/src/lib/api/generated/`
+- NEVER manually edit generated files
+
+**Testing Commands:**
+- Backend unit/integration: `IS_TEST=True uv run pytest` (always prefix with `IS_TEST=True`)
+- Backend E2E (requires Docker): `make test-e2e`
+- Frontend unit: `bun run test`
+- Frontend E2E: `bun run test:e2e`
+- Use `make test` or `make test-cov` in backend for convenience
+
+**Security & Quality Commands (Backend):**
+- `make validate` — lint + format + type checks
+- `make audit` — dependency vulnerabilities + license compliance
+- `make validate-all` — quality + security checks
+- `make check` — **full pipeline**: quality + security + tests
+
+**Backend E2E Testing (requires Docker):**
+- Install deps: `make install-e2e`
+- Run all E2E tests: `make test-e2e`
+- Run schema tests only: `make test-e2e-schema`
+- Run all tests: `make test-all` (unit + E2E)
+- Uses Testcontainers (real PostgreSQL) + Schemathesis (OpenAPI contract testing)
+- Markers: `@pytest.mark.e2e`, `@pytest.mark.postgres`, `@pytest.mark.schemathesis`
+- See: `backend/docs/E2E_TESTING.md` for complete guide
+
+### 🔴 CRITICAL: Auth Store Dependency Injection Pattern
+
+**ALWAYS use `useAuth()` from `AuthContext`, NEVER import `useAuthStore` directly!**
+
+```typescript
+// ❌ WRONG - Bypasses dependency injection
+import { useAuthStore } from '@/lib/stores/authStore';
+const { user, isAuthenticated } = useAuthStore();
+
+// ✅ CORRECT - Uses dependency injection
+import { useAuth } from '@/lib/auth/AuthContext';
+const { user, isAuthenticated } = useAuth();
+```
+
+**Why This Matters:**
+- E2E tests inject mock stores via `window.__TEST_AUTH_STORE__`
+- Unit tests inject via `<AuthProvider store={mockStore}>`
+- Direct `useAuthStore` imports bypass this injection → **tests fail**
+- ESLint will catch violations (added Nov 2025)
+
+**Exceptions:**
+1. `AuthContext.tsx` - DI boundary, legitimately needs real store
+2. `client.ts` - Non-React context, uses dynamic import + `__TEST_AUTH_STORE__` check
+
+### E2E Test Best Practices
+
+When writing or fixing Playwright tests:
+
+**Navigation Pattern:**
+```typescript
+// ✅ CORRECT - Use Promise.all for Next.js Link clicks
+await Promise.all([
+  page.waitForURL('/target', { timeout: 10000 }),
+  link.click()
+]);
+```
+
+**Selectors:**
+- Use ID-based selectors for validation errors: `#email-error`
+- Error IDs use dashes not underscores: `#new-password-error`
+- Target `.border-destructive[role="alert"]` to avoid Next.js route announcer conflicts
+- Avoid generic `[role="alert"]` which matches multiple elements
+
+**URL Assertions:**
+```typescript
+// ✅ Use regex to handle query params
+await expect(page).toHaveURL(/\/auth\/login/);
+
+// ❌ Don't use exact strings (fails with query params)
+await expect(page).toHaveURL('/auth/login');
+```
+
+**Configuration:**
+- Uses 12 workers in non-CI mode (`playwright.config.ts`)
+- Reduces to 2 workers in CI for stability
+- Tests are designed to be non-flaky with proper waits
+
+### Important Implementation Details
+
+**Authentication Testing:**
+- Backend fixtures in `tests/conftest.py`:
+  - `async_test_db`: Fresh SQLite per test
+  - `async_test_user` / `async_test_superuser`: Pre-created users
+  - `user_token` / `superuser_token`: Access tokens for API calls
+- Always use `@pytest.mark.asyncio` for async tests
+- Use `@pytest_asyncio.fixture` for async fixtures
+
+**Database Testing:**
+```python
+# Mock database exceptions correctly
+from unittest.mock import patch, AsyncMock
+
+async def mock_commit():
+    raise OperationalError("Connection lost", {}, Exception())
+
+with patch.object(session, 'commit', side_effect=mock_commit):
+    with patch.object(session, 'rollback', new_callable=AsyncMock) as mock_rollback:
+        with pytest.raises(OperationalError):
+            await repo_method(session, obj_in=data)
+        mock_rollback.assert_called_once()
+```
+
+**Frontend Component Development:**
+- Follow design system docs in `frontend/docs/design-system/`
+- Read `08-ai-guidelines.md` for AI code generation rules
+- Use parent-controlled spacing (see `04-spacing-philosophy.md`)
+- WCAG AA compliance required (see `07-accessibility.md`)
+
+**Security Considerations:**
+- Backend has comprehensive security tests (JWT attacks, session hijacking)
+- Never skip security headers in production
+- Rate limiting is configured in route decorators: `@limiter.limit("10/minute")`
+- Session revocation is database-backed, not just JWT expiry
+- Run `make audit` to check for dependency vulnerabilities and license compliance
+- Run `make check` for the full pipeline: quality + security + tests
+- Pre-commit hooks enforce Ruff lint/format and detect-secrets on every commit
+- Setup hooks: `cd backend && uv run pre-commit install`
+
+### Common Workflows Guidance
+
+**When Adding a New Feature:**
+1. Start with backend schema and repository
+2. Implement API route with proper authorization
+3. Write backend tests (aim for >90% coverage)
+4. Generate frontend API client: `bun run generate:api`
+5. Implement frontend components
+6. Write frontend unit tests
+7. Add E2E tests for critical flows
+8. Update relevant documentation
+
+**When Fixing Tests:**
+- Backend: Check test database isolation and async fixture usage
+- Frontend unit: Verify mocking of `useAuth()` not `useAuthStore`
+- E2E: Use `Promise.all()` pattern and regex URL assertions
+
+**When Debugging:**
+- Backend: Check `IS_TEST=True` environment variable is set
+- Frontend: Run `bun run type-check` first
+- E2E: Use `bun run test:e2e:debug` for step-by-step debugging
+- Check logs: Backend has detailed error logging
+
+**Demo Mode (Frontend-Only Showcase):**
+- Enable: `echo "NEXT_PUBLIC_DEMO_MODE=true" > frontend/.env.local`
+- Uses MSW (Mock Service Worker) to intercept API calls in browser
+- Zero backend required - perfect for Vercel deployments
+- **Fully Automated**: MSW handlers auto-generated from OpenAPI spec
+  - Run `bun run generate:api` → updates both API client AND MSW handlers
+  - No manual synchronization needed!
+- Demo credentials (any password ≥8 chars works):
+  - User: `demo@example.com` / `DemoPass123`
+  - Admin: `admin@example.com` / `AdminPass123`
+- **Safe**: MSW never runs during tests (Jest or Playwright)
+- **Coverage**: Mock files excluded from linting and coverage
+- **Documentation**: `frontend/docs/DEMO_MODE.md` for complete guide
+
+### Tool Usage Preferences
+
+**Prefer specialized tools over bash:**
+- Use Read/Write/Edit tools for file operations
+- Never use `cat`, `echo >`, or heredoc for file manipulation
+- Use Task tool with `subagent_type=Explore` for codebase exploration
+- Use Grep tool for code search, not bash `grep`
+
+**When to use parallel tool calls:**
+- Independent git commands: `git status`, `git diff`, `git log`
+- Reading multiple unrelated files
+- Running multiple test suites simultaneously
+- Independent validation steps
+
+## Custom Skills
+
+No Claude Code Skills installed yet. To create one, invoke the built-in "skill-creator" skill.
+
+**Potential skill ideas for this project:**
+- API endpoint generator workflow (schema → repository → route → tests → frontend client)
+- Component generator with design system compliance
+- Database migration troubleshooting helper
+- Test coverage analyzer and improvement suggester
+- E2E test generator for new features
+
+## Additional Resources
+
+**Comprehensive Documentation:**
+- [AGENTS.md](./AGENTS.md) - Framework-agnostic AI assistant context
+- [README.md](./README.md) - User-facing project overview
+- `backend/docs/` - Backend architecture, coding standards, common pitfalls
+- `frontend/docs/design-system/` - Complete design system guide
+
+**API Documentation (when running):**
+- Swagger UI: http://localhost:8000/docs
+- ReDoc: http://localhost:8000/redoc
+- OpenAPI JSON: http://localhost:8000/api/v1/openapi.json
+
+**Testing Documentation:**
+- Backend tests: `backend/tests/` (97% coverage)
+- Frontend E2E: `frontend/e2e/README.md`
+- Design system: `frontend/docs/design-system/08-ai-guidelines.md`
+
+---
+
+**For project architecture, development commands, and general context, see [AGENTS.md](./AGENTS.md).**

CONTRIBUTING.md

@@ -0,0 +1,392 @@
+# Contributing to FastAPI + Next.js Template
+
+First off, thank you for considering contributing to this project! 🎉
+
+This template aims to be a rock-solid foundation for full-stack applications, and your contributions help make that possible.
+
+## Table of Contents
+
+- [Code of Conduct](#code-of-conduct)
+- [How Can I Contribute?](#how-can-i-contribute)
+- [Development Setup](#development-setup)
+- [Coding Standards](#coding-standards)
+- [Testing Guidelines](#testing-guidelines)
+- [Commit Messages](#commit-messages)
+- [Pull Request Process](#pull-request-process)
+
+---
+
+## Code of Conduct
+
+This project is committed to providing a welcoming and inclusive environment. We expect all contributors to:
+
+- Be respectful and considerate
+- Welcome newcomers and help them learn
+- Focus on constructive criticism
+- Accept feedback gracefully
+- Prioritize the community's well-being
+
+Unacceptable behavior includes harassment, trolling, insulting comments, and personal attacks.
+
+---
+
+## How Can I Contribute?
+
+### Reporting Bugs
+
+Found a bug? Help us fix it!
+
+1. **Check existing issues** to avoid duplicates
+2. **Create a new issue** with:
+   - Clear, descriptive title
+   - Steps to reproduce
+   - Expected vs. actual behavior
+   - Environment details (OS, Python/Node version, etc.)
+   - Screenshots/logs if applicable
+
+### Suggesting Features
+
+Have an idea for improvement?
+
+1. **Check existing issues/discussions** first
+2. **Open a discussion** to gauge interest
+3. **Explain the use case** and benefits
+4. **Consider implementation complexity**
+
+Remember: This is a *template*, not a full application. Features should be:
+- Broadly useful
+- Well-documented
+- Thoroughly tested
+- Maintainable long-term
+
+### Improving Documentation
+
+Documentation improvements are always welcome!
+
+- Fix typos or unclear explanations
+- Add examples or diagrams
+- Expand on complex topics
+- Update outdated information
+- Translate documentation (future)
+
+### Contributing Code
+
+Ready to write some code? Awesome!
+
+1. **Pick an issue** (or create one)
+2. **Comment** that you're working on it
+3. **Fork and branch** from `main`
+4. **Write code** following our standards
+5. **Add tests** (required for features)
+6. **Update docs** if needed
+7. **Submit a PR** with clear description
+
+---
+
+## Development Setup
+
+### Backend Development
+
+```bash
+cd backend
+
+# Install dependencies (uv manages virtual environment automatically)
+make install-dev
+
+# Setup pre-commit hooks
+uv run pre-commit install
+
+# Setup environment
+cp .env.example .env
+# Edit .env with your settings
+
+# Run migrations
+python migrate.py apply
+
+# Run quality + security checks
+make validate-all
+
+# Run tests
+make test
+
+# Run full pipeline (quality + security + tests)
+make check
+
+# Start dev server
+uvicorn app.main:app --reload
+```
+
+### Frontend Development
+
+```bash
+cd frontend
+
+# Install dependencies
+bun install
+
+# Setup environment
+cp .env.local.example .env.local
+
+# Generate API client
+bun run generate:api
+
+# Run tests
+bun run test
+bun run test:e2e:ui
+
+# Start dev server
+bun run dev
+```
+
+---
+
+## Coding Standards
+
+### Backend (Python)
+
+- **Style**: Follow PEP 8
+- **Type hints**: Use type annotations
+- **Async**: Use async/await for I/O operations
+- **Documentation**: Docstrings for all public functions/classes
+- **Error handling**: Use custom exceptions appropriately
+- **Security**: Never trust user input, validate everything
+
+Example:
+```python
+async def get_user_by_email(
+    db: AsyncSession,
+    *,
+    email: str
+) -> Optional[User]:
+    """
+    Get user by email address.
+
+    Args:
+        db: Database session
+        email: User's email address
+
+    Returns:
+        User if found, None otherwise
+    """
+    result = await db.execute(
+        select(User).where(User.email == email)
+    )
+    return result.scalar_one_or_none()
+```
+
+### Frontend (TypeScript/React)
+
+- **Style**: Use Prettier (configured)
+- **TypeScript**: Strict mode, no `any` types
+- **Components**: Functional components with hooks
+- **Naming**: PascalCase for components, camelCase for functions
+- **Imports**: Use absolute imports with `@/` alias
+- **Dependencies**: Use provided auth context (never import stores directly)
+
+Example:
+```typescript
+interface UserProfileProps {
+  userId: string;
+}
+
+export function UserProfile({ userId }: UserProfileProps) {
+  const { user } = useAuth();
+  const { data, isLoading } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetchUser(userId),
+  });
+
+  if (isLoading) return <LoadingSpinner />;
+
+  return <div>...</div>;
+}
+```
+
+### Key Patterns
+
+- **Backend**: Use repository pattern, keep routes thin, business logic in services
+- **Frontend**: Use React Query for server state, Zustand for client state
+- **Both**: Handle errors gracefully, log appropriately, write tests
+
+---
+
+## Testing Guidelines
+
+### Backend Tests
+
+- **Coverage target**: >90% for new code
+- **Test types**: Unit, integration, and security tests
+- **Fixtures**: Use pytest fixtures from `conftest.py`
+- **Database**: Use `async_test_db` fixture for isolation
+- **Assertions**: Be specific about what you're testing
+
+```python
+@pytest.mark.asyncio
+async def test_create_user(client, async_test_superuser, superuser_token):
+    """Test creating a new user."""
+    response = await client.post(
+        "/api/v1/admin/users",
+        headers={"Authorization": f"Bearer {superuser_token}"},
+        json={
+            "email": "newuser@example.com",
+            "password": "SecurePass123!",
+            "first_name": "New",
+            "last_name": "User"
+        }
+    )
+
+    assert response.status_code == 201
+    data = response.json()
+    assert data["email"] == "newuser@example.com"
+    assert "password" not in data  # Never expose passwords
+```
+
+### Frontend E2E Tests
+
+- **Use Playwright**: For end-to-end user flows
+- **Be specific**: Use accessible selectors (roles, labels)
+- **Be reliable**: Avoid flaky tests with proper waits
+- **Be fast**: Group related tests, use parallel execution
+
+```typescript
+test('user can login and view profile', async ({ page }) => {
+  // Login
+  await page.goto('/auth/login');
+  await page.fill('#email', 'user@example.com');
+  await page.fill('#password', 'password123');
+  await page.click('button[type="submit"]');
+
+  // Should redirect to dashboard
+  await expect(page).toHaveURL(/\/dashboard/);
+
+  // Should see user name
+  await expect(page.getByText('Welcome, John')).toBeVisible();
+});
+```
+
+### Unit Tests (Frontend)
+
+- **Test behavior**: Not implementation details
+- **Mock dependencies**: Use Jest mocks appropriately
+- **Test accessibility**: Include a11y checks when relevant
+
+---
+
+## Commit Messages
+
+Write clear, descriptive commit messages:
+
+### Format
+
+```
+<type>: <subject>
+
+<body (optional)>
+
+<footer (optional)>
+```
+
+### Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, no logic change)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+### Examples
+
+**Good:**
+```
+feat: add password reset flow
+
+Implements complete password reset with email tokens.
+Tokens expire after 1 hour for security.
+
+Closes #123
+```
+
+**Also good (simple change):**
+```
+fix: correct pagination offset calculation
+```
+
+**Not great:**
+```
+Fixed stuff
+```
+
+---
+
+## Pull Request Process
+
+### Before Submitting
+
+- [ ] Code follows project style guidelines
+- [ ] `make check` passes (quality + security + tests) in backend
+- [ ] New tests added for new features
+- [ ] Documentation updated if needed
+- [ ] No merge conflicts with `main`
+- [ ] Commits are logical and well-described
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Documentation update
+- [ ] Refactoring
+
+## Testing
+How was this tested?
+
+## Screenshots (if applicable)
+
+## Checklist
+- [ ] Tests added/updated
+- [ ] Documentation updated
+- [ ] No breaking changes
+- [ ] Follows coding standards
+```
+
+### Review Process
+
+1. **Submit PR** with clear description
+2. **CI checks** must pass (when implemented)
+3. **Code review** by maintainers
+4. **Address feedback** if requested
+5. **Approval** from at least one maintainer
+6. **Merge** by maintainer
+
+### After Merge
+
+- Your contribution will be in the next release
+- You'll be added to contributors list
+- Feel awesome! 🎉
+
+---
+
+## Questions?
+
+- **Documentation issues?** Ask in your PR or issue
+- **Unsure about implementation?** Open a discussion first
+- **Need help?** Tag maintainers in your issue/PR
+
+---
+
+## Recognition
+
+Contributors are recognized in:
+- GitHub contributors page
+- Release notes (for significant contributions)
+- README acknowledgments (for major features)
+
+---
+
+Thank you for contributing! Every contribution, no matter how small, makes this template better for everyone. 🚀

Makefile

@@ -1,27 +1,124 @@
-.PHONY: dev prod down clean
+.PHONY: help dev dev-full prod down logs logs-dev clean clean-slate drop-db reset-db push-images deploy scan-images
 
 VERSION ?= latest
-REGISTRY := gitea.pragmazest.com/cardosofelipe/app
+REGISTRY ?= ghcr.io/cardosofelipe/pragma-stack
 
+# Default target
+help:
+	@echo "FastAPI + Next.js Full-Stack Template"
+	@echo ""
+	@echo "Development:"
+	@echo "  make dev           - Start backend + db (frontend runs separately)"
+	@echo "  make dev-full      - Start all services including frontend"
+	@echo "  make down          - Stop all services"
+	@echo "  make logs-dev      - Follow dev container logs"
+	@echo ""
+	@echo "Database:"
+	@echo "  make drop-db       - Drop and recreate empty database"
+	@echo "  make reset-db      - Drop database and apply all migrations"
+	@echo ""
+	@echo "Production:"
+	@echo "  make prod          - Start production stack"
+	@echo "  make deploy        - Pull and deploy latest images"
+	@echo "  make push-images   - Build and push images to registry"
+	@echo "  make scan-images   - Scan production images for CVEs (requires trivy)"
+	@echo "  make logs          - Follow production container logs"
+	@echo ""
+	@echo "Cleanup:"
+	@echo "  make clean         - Stop containers"
+	@echo "  make clean-slate   - Stop containers AND delete volumes (DATA LOSS!)"
+	@echo ""
+	@echo "Subdirectory commands:"
+	@echo "  cd backend && make help   - Backend-specific commands"
+	@echo "  cd frontend && npm run    - Frontend-specific commands"
+
+# ============================================================================
+# Development
+# ============================================================================
 
 dev:
-	docker compose -f docker-compose.dev.yml up --build -d
+	# Bring up all dev services except the frontend
+	docker compose -f docker-compose.dev.yml up --build -d --scale frontend=0
+	@echo ""
+	@echo "Frontend is not started by 'make dev'."
+	@echo "To run the frontend locally, open a new terminal and run:"
+	@echo "    cd frontend && npm run dev"
 
-prod:
+dev-full:
-	docker compose up --build -d
+	# Bring up all dev services including the frontend (full stack)
+	docker compose -f docker-compose.dev.yml up --build -d
 
 down:
 	docker compose down
 
+logs:
+	docker compose logs -f
+
+logs-dev:
+	docker compose -f docker-compose.dev.yml logs -f
+
+# ============================================================================
+# Database Management
+# ============================================================================
+
+drop-db:
+	@echo "Dropping local database..."
+	@docker compose -f docker-compose.dev.yml exec -T db psql -U postgres -c "DROP DATABASE IF EXISTS app WITH (FORCE);" 2>/dev/null || \
+		docker compose -f docker-compose.dev.yml exec -T db psql -U postgres -c "DROP DATABASE IF EXISTS app;"
+	@docker compose -f docker-compose.dev.yml exec -T db psql -U postgres -c "CREATE DATABASE app;"
+	@echo "Database dropped and recreated (empty)"
+
+reset-db: drop-db
+	@echo "Applying migrations..."
+	@cd backend && uv run python migrate.py --local apply
+	@echo "Database reset complete!"
+
+# ============================================================================
+# Production / Deployment
+# ============================================================================
+
+prod:
+	docker compose up --build -d
+
 deploy:
 	docker compose -f docker-compose.deploy.yml pull
 	docker compose -f docker-compose.deploy.yml up -d
 
-clean:
-	docker compose down -
-
 push-images:
 	docker build -t $(REGISTRY)/backend:$(VERSION) ./backend
 	docker build -t $(REGISTRY)/frontend:$(VERSION) ./frontend
 	docker push $(REGISTRY)/backend:$(VERSION)
-	docker push $(REGISTRY)/frontend:$(VERSION)
+	docker push $(REGISTRY)/frontend:$(VERSION)
+
+scan-images:
+	@docker info > /dev/null 2>&1 || (echo "❌ Docker is not running!"; exit 1)
+	@echo "🐳 Building and scanning production images for CVEs..."
+	docker build -t $(REGISTRY)/backend:scan --target production ./backend
+	docker build -t $(REGISTRY)/frontend:scan --target runner ./frontend
+	@echo ""
+	@echo "=== Backend Image Scan ==="
+	@if command -v trivy > /dev/null 2>&1; then \
+		trivy image --severity HIGH,CRITICAL --exit-code 1 $(REGISTRY)/backend:scan; \
+	else \
+		echo "ℹ️  Trivy not found locally, using Docker to run Trivy..."; \
+		docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy image --severity HIGH,CRITICAL --exit-code 1 $(REGISTRY)/backend:scan; \
+	fi
+	@echo ""
+	@echo "=== Frontend Image Scan ==="
+	@if command -v trivy > /dev/null 2>&1; then \
+		trivy image --severity HIGH,CRITICAL --exit-code 1 $(REGISTRY)/frontend:scan; \
+	else \
+		docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy image --severity HIGH,CRITICAL --exit-code 1 $(REGISTRY)/frontend:scan; \
+	fi
+	@echo "✅ No HIGH/CRITICAL CVEs found in production images!"
+
+# ============================================================================
+# Cleanup
+# ============================================================================
+
+clean:
+	docker compose down
+
+# WARNING! THIS REMOVES CONTAINERS AND VOLUMES AS WELL - DO NOT USE THIS UNLESS YOU WANT TO START OVER WITH DATA AND ALL
+clean-slate:
+	docker compose -f docker-compose.dev.yml down -v --remove-orphans

README.md

@@ -1,59 +1,659 @@
-# FastNext Stack
+# <img src="frontend/public/logo.svg" alt="PragmaStack" width="32" height="32" style="vertical-align: middle" /> PragmaStack
 
-A modern, Docker-ready full-stack template combining FastAPI, Next.js, and PostgreSQL. Built for developers who need a robust starting point for web applications with TypeScript frontend and Python backend.
+> **The Pragmatic Full-Stack Template. Production-ready, security-first, and opinionated.**
 
-## Features
+[![Backend Coverage](https://img.shields.io/badge/backend_coverage-97%25-brightgreen)](./backend/tests)
+[![Frontend Coverage](https://img.shields.io/badge/frontend_coverage-97%25-brightgreen)](./frontend/tests)
+[![E2E Tests](https://img.shields.io/badge/e2e_tests-passing-success)](./frontend/e2e)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
-- 🐍 **FastAPI Backend**
+![Landing Page](docs/images/landing.png)
-    - Python 3.12 with modern async support
-    - SQLAlchemy ORM with async capabilities
-    - Alembic migrations
-    - JWT authentication ready
-    - Pydantic data validation
-    - Comprehensive testing setup
 
-- ⚛️ **Next.js Frontend**
+---
-    - React 19 with TypeScript
-    - Tailwind CSS for styling
-    - Modern app router architecture
-    - Built-in API route support
-    - SEO-friendly by default
 
-- 🛠️ **Development Experience**
+## Why PragmaStack?
-    - Docker-based development environment
-    - Hot-reloading for both frontend and backend
-    - Unified development workflow
-    - Comprehensive testing setup
-    - Type safety across the stack
 
-- 🚀 **Production Ready**
+Building a modern full-stack application often leads to "analysis paralysis" or "boilerplate fatigue". You spend weeks setting up authentication, testing, and linting before writing a single line of business logic.
-    - Multi-stage Docker builds
-    - Production-optimized configurations
-    - Environment-based settings
-    - Health checks and container orchestration
-    - CORS security configured
 
-## Quick Start
+**PragmaStack cuts through the noise.**
+
+We provide a **pragmatic**, opinionated foundation that prioritizes:
+- **Speed**: Ship features, not config files.
+- **Robustness**: Security and testing are not optional.
+- **Clarity**: Code that is easy to read and maintain.
+
+Whether you're building a SaaS, an internal tool, or a side project, PragmaStack gives you a solid starting point without the bloat.
+
+---
+
+## ✨ Features
+
+### 🔐 **Authentication & Security**
+- JWT-based authentication with access + refresh tokens
+- **OAuth/Social Login** (Google, GitHub) with PKCE support
+- **OAuth 2.0 Authorization Server** (MCP-ready) for third-party integrations
+- Session management with device tracking and revocation
+- Password reset flow (email integration ready)
+- Secure password hashing (bcrypt)
+- CSRF protection, rate limiting, and security headers
+- Comprehensive security tests (JWT algorithm attacks, session hijacking, privilege escalation)
+
+### 🔌 **OAuth Provider Mode (MCP Integration)**
+Full OAuth 2.0 Authorization Server for Model Context Protocol (MCP) and third-party clients:
+- **RFC 7636**: Authorization Code Flow with PKCE (S256 only)
+- **RFC 8414**: Server metadata discovery at `/.well-known/oauth-authorization-server`
+- **RFC 7662**: Token introspection endpoint
+- **RFC 7009**: Token revocation endpoint
+- **JWT access tokens**: Self-contained, configurable lifetime
+- **Opaque refresh tokens**: Secure rotation, database-backed revocation
+- **Consent management**: Users can review and revoke app permissions
+- **Client management**: Admin endpoints for registering OAuth clients
+- **Scopes**: `openid`, `profile`, `email`, `read:users`, `write:users`, `admin`
+
+### 👥 **Multi-Tenancy & Organizations**
+- Full organization system with role-based access control (Owner, Admin, Member)
+- Invite/remove members, manage permissions
+- Organization-scoped data access
+- User can belong to multiple organizations
+
+### 🛠️ **Admin Panel**
+- Complete user management (full lifecycle, activate/deactivate, bulk operations)
+- Organization management (create, edit, delete, member management)
+- Session monitoring across all users
+- Real-time statistics dashboard
+- Admin-only routes with proper authorization
+
+### 🎨 **Modern Frontend**
+- Next.js 16 with App Router and React 19
+- **PragmaStack Design System** built on shadcn/ui + TailwindCSS
+- Pre-configured theme with dark mode support (coming soon)
+- Responsive, accessible components (WCAG AA compliant)
+- Rich marketing landing page with animated components
+- Live component showcase and documentation at `/dev`
+
+### 🌍 **Internationalization (i18n)**
+- Built-in multi-language support with next-intl v4
+- Locale-based routing (`/en/*`, `/it/*`)
+- Seamless language switching with LocaleSwitcher component
+- SEO-friendly URLs and metadata per locale
+- Translation files for English and Italian (easily extensible)
+- Type-safe translations throughout the app
+
+### 🎯 **Content & UX Features**
+- **Toast notifications** with Sonner for elegant user feedback
+- **Smooth animations** powered by Framer Motion
+- **Markdown rendering** with syntax highlighting (GitHub Flavored Markdown)
+- **Charts and visualizations** ready with Recharts
+- **SEO optimization** with dynamic sitemap and robots.txt generation
+- **Session tracking UI** with device information and revocation controls
+
+### 🧪 **Comprehensive Testing**
+- **Backend Testing**: ~97% unit test coverage
+  - Unit, integration, and security tests
+  - Async database testing with SQLAlchemy
+  - API endpoint testing with fixtures
+  - Security vulnerability tests (JWT attacks, session hijacking, privilege escalation)
+- **Frontend Unit Tests**: ~97% coverage with Jest
+  - Component testing
+  - Hook testing
+  - Utility function testing
+- **End-to-End Tests**: Playwright with zero flaky tests
+  - Complete user flows (auth, navigation, settings)
+  - Parallel execution for speed
+  - Visual regression testing ready
+
+### 📚 **Developer Experience**
+- Auto-generated TypeScript API client from OpenAPI spec
+- Interactive API documentation (Swagger + ReDoc)
+- Database migrations with Alembic helper script
+- Hot reload in development for both frontend and backend
+- Comprehensive code documentation and design system docs
+- Live component playground at `/dev` with code examples
+- Docker support for easy deployment
+- VSCode workspace settings included
+
+### 📊 **Ready for Production**
+- Docker + docker-compose setup
+- Environment-based configuration
+- Database connection pooling
+- Error handling and logging
+- Health check endpoints
+- Production security headers
+- Rate limiting on sensitive endpoints
+- SEO optimization with dynamic sitemaps and robots.txt
+- Multi-language SEO with locale-specific metadata
+- Performance monitoring and bundle analysis
+
+---
+
+## 📸 Screenshots
+
+<details>
+<summary>Click to view screenshots</summary>
+
+### Landing Page
+![Landing Page](docs/images/landing.png)
+
+
+
+### Authentication
+![Login Page](docs/images/login.png)
+
+
+
+### Admin Dashboard
+![Admin Dashboard](docs/images/admin-dashboard.png)
+
+
+
+### Design System
+![Components](docs/images/design-system.png)
+
+</details>
+
+---
+
+## 🎭 Demo Mode
+
+**Try the frontend without a backend!** Perfect for:
+- **Free deployment** on Vercel (no backend costs)
+- **Portfolio showcasing** with live demos
+- **Client presentations** without infrastructure setup
+
+### Quick Start
 
-1. Clone the template:
 ```bash
-git clone https://github.com/yourusername/fastnext-stack myproject
+cd frontend
-cd myproject
+echo "NEXT_PUBLIC_DEMO_MODE=true" > .env.local
+bun run dev
 ```
 
-2. Create environment files:
+**Demo Credentials:**
+- Regular user: `demo@example.com` / `DemoPass123`
+- Admin user: `admin@example.com` / `AdminPass123`
+
+Demo mode uses [Mock Service Worker (MSW)](https://mswjs.io/) to intercept API calls in the browser. Your code remains unchanged - the same components work with both real and mocked backends.
+
+**Key Features:**
+- ✅ Zero backend required
+- ✅ All features functional (auth, admin, stats)
+- ✅ Realistic network delays and errors
+- ✅ Does NOT interfere with tests (97%+ coverage maintained)
+- ✅ One-line toggle: `NEXT_PUBLIC_DEMO_MODE=true`
+
+📖 **[Complete Demo Mode Documentation](./frontend/docs/DEMO_MODE.md)**
+
+---
+
+## 🚀 Tech Stack
+
+### Backend
+- **[FastAPI](https://fastapi.tiangolo.com/)** - Modern async Python web framework
+- **[SQLAlchemy 2.0](https://www.sqlalchemy.org/)** - Powerful ORM with async support
+- **[PostgreSQL](https://www.postgresql.org/)** - Robust relational database
+- **[Alembic](https://alembic.sqlalchemy.org/)** - Database migrations
+- **[Pydantic v2](https://docs.pydantic.dev/)** - Data validation with type hints
+- **[pytest](https://pytest.org/)** - Testing framework with async support
+
+### Frontend
+- **[Next.js 16](https://nextjs.org/)** - React framework with App Router
+- **[React 19](https://react.dev/)** - UI library
+- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
+- **[TailwindCSS](https://tailwindcss.com/)** - Utility-first CSS framework
+- **[shadcn/ui](https://ui.shadcn.com/)** - Beautiful, accessible component library
+- **[next-intl](https://next-intl.dev/)** - Internationalization (i18n) with type safety
+- **[TanStack Query](https://tanstack.com/query)** - Powerful data fetching/caching
+- **[Zustand](https://zustand-demo.pmnd.rs/)** - Lightweight state management
+- **[Framer Motion](https://www.framer.com/motion/)** - Production-ready animation library
+- **[Sonner](https://sonner.emilkowal.ski/)** - Beautiful toast notifications
+- **[Recharts](https://recharts.org/)** - Composable charting library
+- **[React Markdown](https://github.com/remarkjs/react-markdown)** - Markdown rendering with GFM support
+- **[Playwright](https://playwright.dev/)** - End-to-end testing
+
+### DevOps
+- **[Docker](https://www.docker.com/)** - Containerization
+- **[docker-compose](https://docs.docker.com/compose/)** - Multi-container orchestration
+- **GitHub Actions** (coming soon) - CI/CD pipelines
+
+---
+
+## 📋 Prerequisites
+
+- **Docker & Docker Compose** (recommended) - [Install Docker](https://docs.docker.com/get-docker/)
+- **OR manually:**
+  - Python 3.12+
+  - Node.js 18+ (Node 20+ recommended)
+  - PostgreSQL 15+
+
+---
+
+## 🏃 Quick Start (Docker)
+
+The fastest way to get started is with Docker:
+
 ```bash
+# Clone the repository
+git clone https://github.com/cardosofelipe/pragma-stack.git
+cd fast-next-template
+
+# Copy environment file
 cp .env.template .env
+
+# Start all services (backend, frontend, database)
+docker-compose up
+
+# In another terminal, run database migrations
+docker-compose exec backend alembic upgrade head
+
+# Create first superuser (optional)
+docker-compose exec backend python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"
 ```
 
-3. Start development environment:
+**That's it! 🎉**
-```bash
-make dev
-```
 
-4. Access the applications:
 - Frontend: http://localhost:3000
-- Backend: http://localhost:8000
+- Backend API: http://localhost:8000
 - API Docs: http://localhost:8000/docs
 
-## Project Structure
+Default superuser credentials:
+- Email: `admin@example.com`
+- Password: `admin123`
+
+**⚠️ Change these immediately in production!**
+
+---
+
+## 🛠️ Manual Setup (Development)
+
+### Backend Setup
+
+```bash
+cd backend
+
+# Create virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Setup environment
+cp .env.example .env
+# Edit .env with your database credentials
+
+# Run migrations
+alembic upgrade head
+
+# Initialize database with first superuser
+python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"
+
+# Start development server
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+### Frontend Setup
+
+```bash
+cd frontend
+
+# Install dependencies
+bun install
+
+# Setup environment
+cp .env.local.example .env.local
+# Edit .env.local with your backend URL
+
+# Generate API client
+bun run generate:api
+
+# Start development server
+bun run dev
+```
+
+Visit http://localhost:3000 to see your app!
+
+---
+
+## 📂 Project Structure
+
+```
+├── backend/                 # FastAPI backend
+│   ├── app/
+│   │   ├── api/            # API routes and dependencies
+│   │   ├── core/           # Core functionality (auth, config, database)
+│   │   ├── repositories/   # Repository pattern (database operations)
+│   │   ├── models/         # SQLAlchemy models
+│   │   ├── schemas/        # Pydantic schemas
+│   │   ├── services/       # Business logic
+│   │   └── utils/          # Utilities
+│   ├── tests/              # Backend tests (97% coverage)
+│   ├── alembic/            # Database migrations
+│   └── docs/               # Backend documentation
+│
+├── frontend/               # Next.js frontend
+│   ├── src/
+│   │   ├── app/           # Next.js App Router pages
+│   │   ├── components/    # React components
+│   │   ├── lib/           # Libraries and utilities
+│   │   │   ├── api/       # API client (auto-generated)
+│   │   │   └── stores/    # Zustand stores
+│   │   └── hooks/         # Custom React hooks
+│   ├── e2e/               # Playwright E2E tests
+│   ├── tests/             # Unit tests (Jest)
+│   └── docs/              # Frontend documentation
+│       └── design-system/ # Comprehensive design system docs
+│
+├── docker-compose.yml      # Docker orchestration
+├── docker-compose.dev.yml  # Development with hot reload
+└── README.md              # You are here!
+```
+
+---
+
+## 🧪 Testing
+
+This template takes testing seriously with comprehensive coverage across all layers:
+
+### Backend Unit & Integration Tests
+
+**High coverage (~97%)** across all critical paths including security-focused tests.
+
+```bash
+cd backend
+
+# Run all tests
+IS_TEST=True pytest
+
+# Run with coverage report
+IS_TEST=True pytest --cov=app --cov-report=term-missing
+
+# Run specific test file
+IS_TEST=True pytest tests/api/test_auth.py -v
+
+# Generate HTML coverage report
+IS_TEST=True pytest --cov=app --cov-report=html
+open htmlcov/index.html
+```
+
+**Test types:**
+- **Unit tests**: Repository operations, utilities, business logic
+- **Integration tests**: API endpoints with database
+- **Security tests**: JWT algorithm attacks, session hijacking, privilege escalation
+- **Error handling tests**: Database failures, validation errors
+
+### Frontend Unit Tests
+
+**High coverage (~97%)** with Jest and React Testing Library.
+
+```bash
+cd frontend
+
+# Run unit tests
+bun run test
+
+# Run with coverage
+bun run test:coverage
+
+# Watch mode
+bun run test:watch
+```
+
+**Test types:**
+- Component rendering and interactions
+- Custom hooks behavior
+- State management
+- Utility functions
+- API integration mocks
+
+### End-to-End Tests
+
+**Zero flaky tests** with Playwright covering complete user journeys.
+
+```bash
+cd frontend
+
+# Run E2E tests
+bun run test:e2e
+
+# Run E2E tests in UI mode (recommended for development)
+bun run test:e2e:ui
+
+# Run specific test file
+npx playwright test auth-login.spec.ts
+
+# Generate test report
+npx playwright show-report
+```
+
+**Test coverage:**
+- Complete authentication flows
+- Navigation and routing
+- Form submissions and validation
+- Settings and profile management
+- Session management
+- Admin panel workflows (in progress)
+
+---
+
+## 🤖 AI-Friendly Documentation
+
+This project includes comprehensive documentation designed for AI coding assistants:
+
+- **[AGENTS.md](./AGENTS.md)** - Framework-agnostic AI assistant context for PragmaStack
+- **[CLAUDE.md](./CLAUDE.md)** - Claude Code-specific guidance
+
+These files provide AI assistants with the **PragmaStack** architecture, patterns, and best practices.
+
+---
+
+## 🗄️ Database Migrations
+
+The template uses Alembic for database migrations:
+
+```bash
+cd backend
+
+# Generate migration from model changes
+python migrate.py generate "description of changes"
+
+# Apply migrations
+python migrate.py apply
+
+# Or do both in one command
+python migrate.py auto "description"
+
+# View migration history
+python migrate.py list
+
+# Check current revision
+python migrate.py current
+```
+
+---
+
+## 📖 Documentation
+
+### AI Assistant Documentation
+
+- **[AGENTS.md](./AGENTS.md)** - Framework-agnostic AI coding assistant context
+- **[CLAUDE.md](./CLAUDE.md)** - Claude Code-specific guidance and preferences
+
+### Backend Documentation
+
+- **[ARCHITECTURE.md](./backend/docs/ARCHITECTURE.md)** - System architecture and design patterns
+- **[CODING_STANDARDS.md](./backend/docs/CODING_STANDARDS.md)** - Code quality standards
+- **[COMMON_PITFALLS.md](./backend/docs/COMMON_PITFALLS.md)** - Common mistakes to avoid
+- **[FEATURE_EXAMPLE.md](./backend/docs/FEATURE_EXAMPLE.md)** - Step-by-step feature guide
+
+### Frontend Documentation
+
+- **[PragmaStack Design System](./frontend/docs/design-system/)** - Complete design system guide
+  - Quick start, foundations (colors, typography, spacing)
+  - Component library guide
+  - Layout patterns, spacing philosophy
+  - Forms, accessibility, AI guidelines
+- **[E2E Testing Guide](./frontend/e2e/README.md)** - E2E testing setup and best practices
+
+### API Documentation
+
+When the backend is running:
+- **Swagger UI**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+- **OpenAPI JSON**: http://localhost:8000/api/v1/openapi.json
+
+---
+
+## 🚢 Deployment
+
+### Docker Production Deployment
+
+```bash
+# Build and start all services
+docker-compose up -d
+
+# Run migrations
+docker-compose exec backend alembic upgrade head
+
+# View logs
+docker-compose logs -f
+
+# Stop services
+docker-compose down
+```
+
+### Production Checklist
+
+- [ ] Change default superuser credentials
+- [ ] Set strong `SECRET_KEY` in backend `.env`
+- [ ] Configure production database (PostgreSQL)
+- [ ] Set `ENVIRONMENT=production` in backend
+- [ ] Configure CORS origins for your domain
+- [ ] Setup SSL/TLS certificates
+- [ ] Configure email service for password resets
+- [ ] Setup monitoring and logging
+- [ ] Configure backup strategy
+- [ ] Review and adjust rate limits
+- [ ] Test security headers
+
+---
+
+## 🛣️ Roadmap & Status
+
+### ✅ Completed
+- [x] Authentication system (JWT, refresh tokens, session management, OAuth)
+- [x] User management (full lifecycle, profile, password change)
+- [x] Organization system with RBAC (Owner, Admin, Member)
+- [x] Admin panel (users, organizations, sessions, statistics)
+- [x] **Internationalization (i18n)** with next-intl (English + Italian)
+- [x] Backend testing infrastructure (~97% coverage)
+- [x] Frontend unit testing infrastructure (~97% coverage)
+- [x] Frontend E2E testing (Playwright, zero flaky tests)
+- [x] Design system documentation
+- [x] **Marketing landing page** with animated components
+- [x] **`/dev` documentation portal** with live component examples
+- [x] **Toast notifications** system (Sonner)
+- [x] **Charts and visualizations** (Recharts)
+- [x] **Animation system** (Framer Motion)
+- [x] **Markdown rendering** with syntax highlighting
+- [x] **SEO optimization** (sitemap, robots.txt, locale-aware metadata)
+- [x] Database migrations with helper script
+- [x] Docker deployment
+- [x] API documentation (OpenAPI/Swagger)
+
+### 🚧 In Progress
+- [ ] Email integration (templates ready, SMTP pending)
+
+### 🔮 Planned
+- [ ] GitHub Actions CI/CD pipelines
+- [ ] Dynamic test coverage badges from CI
+- [ ] E2E test coverage reporting
+- [ ] OAuth token encryption at rest (security hardening)
+- [ ] Additional languages (Spanish, French, German, etc.)
+- [ ] SSO/SAML authentication
+- [ ] Real-time notifications with WebSockets
+- [ ] Webhook system
+- [ ] File upload/storage (S3-compatible)
+- [ ] Audit logging system
+- [ ] API versioning example
+
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Whether you're fixing bugs, improving documentation, or proposing new features, we'd love your help.
+
+### How to Contribute
+
+1. **Fork the repository**
+2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
+3. **Make your changes**
+   - Follow existing code style
+   - Add tests for new features
+   - Update documentation as needed
+4. **Run tests** to ensure everything works
+5. **Commit your changes** (`git commit -m 'Add amazing feature'`)
+6. **Push to your branch** (`git push origin feature/amazing-feature`)
+7. **Open a Pull Request**
+
+### Development Guidelines
+
+- Write tests for new features (aim for >90% coverage)
+- Follow the existing architecture patterns
+- Update documentation when adding features
+- Keep commits atomic and well-described
+- Be respectful and constructive in discussions
+
+### Reporting Issues
+
+Found a bug? Have a suggestion? [Open an issue](https://github.com/cardosofelipe/pragma-stack/issues)!
+
+Please include:
+- Clear description of the issue/suggestion
+- Steps to reproduce (for bugs)
+- Expected vs. actual behavior
+- Environment details (OS, Python/Node version, etc.)
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](./LICENSE) file for details.
+
+**TL;DR**: You can use this template for any purpose, commercial or non-commercial. Attribution is appreciated but not required!
+
+---
+
+## 🙏 Acknowledgments
+
+This template is built on the shoulders of giants:
+
+- [FastAPI](https://fastapi.tiangolo.com/) by Sebastián Ramírez
+- [Next.js](https://nextjs.org/) by Vercel
+- [shadcn/ui](https://ui.shadcn.com/) by shadcn
+- [TanStack Query](https://tanstack.com/query) by Tanner Linsley
+- [Playwright](https://playwright.dev/) by Microsoft
+- And countless other open-source projects that make modern development possible
+
+---
+
+## 💬 Questions?
+
+- **Documentation**: Check the `/docs` folders in backend and frontend
+- **Issues**: [GitHub Issues](https://github.com/cardosofelipe/pragma-stack/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/cardosofelipe/pragma-stack/discussions)
+
+---
+
+## ⭐ Star This Repo
+
+If this template saves you time, consider giving it a star! It helps others discover the project and motivates continued development.
+
+**Happy coding! 🚀**
+
+---
+
+<div align="center">
+Made with ❤️ by a developer who got tired of rebuilding the same boilerplate
+</div>

backend/.coveragerc

@@ -0,0 +1,76 @@
+[run]
+source = app
+concurrency = thread,greenlet
+omit =
+    # Migration files - these are generated code and shouldn't be tested
+    app/alembic/versions/*
+    app/alembic/env.py
+
+    # Test utilities - these are used BY tests, not tested themselves
+    app/utils/test_utils.py
+    app/utils/auth_test_utils.py
+
+    # Async implementations not yet in use
+    app/repositories/base_async.py
+    app/core/database_async.py
+
+    # CLI scripts - run manually, not tested
+    app/init_db.py
+
+    # __init__ files with no logic
+    app/__init__.py
+    app/api/__init__.py
+    app/api/routes/__init__.py
+    app/api/dependencies/__init__.py
+    app/core/__init__.py
+    app/repositories/__init__.py
+    app/models/__init__.py
+    app/schemas/__init__.py
+    app/services/__init__.py
+    app/utils/__init__.py
+    app/alembic/__init__.py
+    app/alembic/versions/__init__.py
+
+[report]
+# Show missing lines in the report
+show_missing = True
+
+# Exclude lines with these patterns
+exclude_lines =
+    # Have to re-enable the standard pragma
+    pragma: no cover
+
+    # Don't complain about missing debug-only code
+    def __repr__
+    def __str__
+
+    # Don't complain if tests don't hit defensive assertion code
+    raise AssertionError
+    raise NotImplementedError
+
+    # Don't complain if non-runnable code isn't run
+    if __name__ == .__main__.:
+    if TYPE_CHECKING:
+
+    # Don't complain about abstract methods
+    @abstractmethod
+    @abc.abstractmethod
+
+    # Don't complain about ellipsis in protocols/stubs
+    \.\.\.
+
+    # Don't complain about logger debug statements in production
+    logger\.debug
+
+    # Pass statements (often in abstract base classes or placeholders)
+    pass
+
+    # Skip test environment checks (production-only code)
+    if os\.getenv\("IS_TEST".*\) == "True":
+    if os\.getenv\("IS_TEST".*\) != "True":
+
+[html]
+directory = htmlcov
+
+[xml]
+output = coverage.xml

backend/.dockerignore

@@ -1,2 +1,17 @@
 .venv
-*.iml
+*.iml
+
+# Python build and cache artifacts
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.pyc
+*.pyo
+
+# Packaging artifacts
+*.egg-info/
+build/
+dist/
+htmlcov/
+.uv_cache/

backend/.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+# Pre-commit hooks for backend quality and security checks.
+#
+# Install:
+#   cd backend && uv run pre-commit install
+#
+# Run manually on all files:
+#   cd backend && uv run pre-commit run --all-files
+#
+# Skip hooks temporarily:
+#   git commit --no-verify
+#
+repos:
+  # ── Code Quality ──────────────────────────────────────────────────────────
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.4
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  # ── General File Hygiene ──────────────────────────────────────────────────
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: debug-statements
+
+  # ── Security ──────────────────────────────────────────────────────────────
+  - repo: https://github.com/Yelp/detect-secrets
+    rev: v1.5.0
+    hooks:
+      - id: detect-secrets
+        args: ['--baseline', '.secrets.baseline']
+        exclude: |
+          (?x)^(
+            .*\.lock$|
+            .*\.svg$
+          )$

backend/=1.14.1

@@ -1,6 +0,0 @@
-Requirement already satisfied: alembic in ./.venv/lib/python3.12/site-packages (1.14.1)
-Requirement already satisfied: SQLAlchemy>=1.3.0 in ./.venv/lib/python3.12/site-packages (from alembic) (2.0.38)
-Requirement already satisfied: Mako in ./.venv/lib/python3.12/site-packages (from alembic) (1.3.9)
-Requirement already satisfied: typing-extensions>=4 in ./.venv/lib/python3.12/site-packages (from alembic) (4.12.2)
-Requirement already satisfied: greenlet!=0.4.17 in ./.venv/lib/python3.12/site-packages (from SQLAlchemy>=1.3.0->alembic) (3.1.1)
-Requirement already satisfied: MarkupSafe>=0.9.2 in ./.venv/lib/python3.12/site-packages (from Mako->alembic) (3.0.2)

backend/Dockerfile

@@ -1,34 +1,80 @@
 # Development stage
 FROM python:3.12-slim AS development
+
 WORKDIR /app
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
-    PYTHONPATH=/app
+    PYTHONPATH=/app \
+    UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_NO_CACHE=1
+
+# Install system dependencies and uv
 RUN apt-get update && \
-    apt-get install -y --no-install-recommends gcc postgresql-client && \
+    apt-get install -y --no-install-recommends gcc postgresql-client curl ca-certificates && \
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    mv /root/.local/bin/uv* /usr/local/bin/ && \
     apt-get clean && \
     rm -rf /var/lib/apt/lists/*
-COPY requirements.txt .
+
-RUN pip install --no-cache-dir -r requirements.txt
+# Copy dependency files
+COPY pyproject.toml uv.lock ./
+
+# Install dependencies using uv (development mode with dev dependencies)
+RUN uv sync --extra dev --frozen
+
+# Copy application code
 COPY . .
 COPY entrypoint.sh /usr/local/bin/
 RUN chmod +x /usr/local/bin/entrypoint.sh
+
+# Note: Running as root in development for bind mount compatibility
+# Production stage uses non-root user for security
+
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 
-# Production stage
+# Production stage — Alpine eliminates glibc CVEs (e.g. CVE-2026-0861)
-FROM python:3.12-slim AS production
+FROM python:3.12-alpine AS production
+
+# Create non-root user
+RUN addgroup -S appuser && adduser -S -G appuser appuser
+
 WORKDIR /app
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
-    PYTHONPATH=/app
+    PYTHONPATH=/app \
-RUN apt-get update && \
+    UV_COMPILE_BYTECODE=1 \
-    apt-get install -y --no-install-recommends postgresql-client && \
+    UV_LINK_MODE=copy \
-    apt-get clean && \
+    UV_NO_CACHE=1
-    rm -rf /var/lib/apt/lists/*
+
-COPY requirements.txt .
+# Install system dependencies and uv
-RUN pip install --no-cache-dir -r requirements.txt
+RUN apk add --no-cache postgresql-client curl ca-certificates && \
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    mv /root/.local/bin/uv* /usr/local/bin/
+
+# Copy dependency files
+COPY pyproject.toml uv.lock ./
+
+# Install build dependencies, compile Python packages, then remove build deps
+RUN apk add --no-cache --virtual .build-deps \
+        gcc g++ musl-dev python3-dev linux-headers libffi-dev openssl-dev && \
+    uv sync --frozen --no-dev && \
+    apk del .build-deps
+
+# Copy application code
 COPY . .
 COPY entrypoint.sh /usr/local/bin/
 RUN chmod +x /usr/local/bin/entrypoint.sh
+
+# Set ownership to non-root user
+RUN chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+# Add health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \
+    CMD curl -f http://localhost:8000/health || exit 1
+
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/Makefile

@@ -0,0 +1,220 @@
+.PHONY: help lint lint-fix format format-check type-check test test-cov validate clean install-dev sync check-docker install-e2e test-e2e test-e2e-schema test-all dep-audit license-check audit validate-all check benchmark benchmark-check benchmark-save scan-image test-api-security
+
+# Prevent a stale VIRTUAL_ENV in the caller's shell from confusing uv
+unexport VIRTUAL_ENV
+
+# Default target
+help:
+	@echo "🚀 FastAPI Backend - Development Commands"
+	@echo ""
+	@echo "Setup:"
+	@echo "  make install-dev   - Install all dependencies with uv (includes dev)"
+	@echo "  make install-e2e   - Install E2E test dependencies (requires Docker)"
+	@echo "  make sync          - Sync dependencies from uv.lock"
+	@echo ""
+	@echo "Quality Checks:"
+	@echo "  make lint          - Run Ruff linter (check only)"
+	@echo "  make lint-fix      - Run Ruff linter with auto-fix"
+	@echo "  make format        - Format code with Ruff"
+	@echo "  make format-check  - Check if code is formatted"
+	@echo "  make type-check    - Run pyright type checking"
+	@echo "  make validate      - Run all checks (lint + format + types + schema fuzz)"
+	@echo ""
+	@echo "Performance:"
+	@echo "  make benchmark       - Run performance benchmarks"
+	@echo "  make benchmark-save  - Run benchmarks and save as baseline"
+	@echo "  make benchmark-check - Run benchmarks and compare against baseline"
+	@echo ""
+	@echo "Security & Audit:"
+	@echo "  make dep-audit     - Scan dependencies for known vulnerabilities"
+	@echo "  make license-check - Check dependency license compliance"
+	@echo "  make audit         - Run all security audits (deps + licenses)"
+	@echo "  make scan-image    - Scan Docker image for CVEs (requires trivy)"
+	@echo "  make validate-all  - Run all quality + security checks"
+	@echo "  make check         - Full pipeline: quality + security + tests"
+	@echo ""
+	@echo "Testing:"
+	@echo "  make test          - Run pytest (unit/integration, SQLite)"
+	@echo "  make test-cov      - Run pytest with coverage report"
+	@echo "  make test-e2e      - Run E2E tests (PostgreSQL, requires Docker)"
+	@echo "  make test-e2e-schema - Run Schemathesis API schema tests"
+	@echo "  make test-all      - Run all tests (unit + E2E)"
+	@echo "  make check-docker  - Check if Docker is available"
+	@echo "  make check         - Full pipeline: quality + security + tests"
+	@echo ""
+	@echo "Cleanup:"
+	@echo "  make clean         - Remove cache and build artifacts"
+
+# ============================================================================
+# Setup & Cleanup
+# ============================================================================
+
+install-dev:
+	@echo "📦 Installing all dependencies with uv (includes dev)..."
+	@uv sync --extra dev
+	@echo "✅ Development environment ready!"
+
+sync:
+	@echo "🔄 Syncing dependencies from uv.lock..."
+	@uv sync --extra dev
+	@echo "✅ Dependencies synced!"
+
+# ============================================================================
+# Code Quality
+# ============================================================================
+
+lint:
+	@echo "🔍 Running Ruff linter..."
+	@uv run ruff check app/ tests/
+
+lint-fix:
+	@echo "🔧 Running Ruff linter with auto-fix..."
+	@uv run ruff check --fix app/ tests/
+
+format:
+	@echo "✨ Formatting code with Ruff..."
+	@uv run ruff format app/ tests/
+
+format-check:
+	@echo "📋 Checking code formatting..."
+	@uv run ruff format --check app/ tests/
+
+type-check:
+	@echo "🔎 Running pyright type checking..."
+	@uv run pyright app/
+
+validate: lint format-check type-check test-api-security
+	@echo "✅ All quality checks passed!"
+
+# API Security Testing (Schemathesis property-based fuzzing)
+test-api-security: check-docker
+	@echo "🔐 Running Schemathesis API security fuzzing..."
+	@IS_TEST=True PYTHONPATH=. uv run pytest tests/e2e/ -v -m "schemathesis" --tb=short -n 0
+	@echo "✅ API schema security tests passed!"
+
+# ============================================================================
+# Security & Audit
+# ============================================================================
+
+dep-audit:
+	@echo "🔒 Scanning dependencies for known vulnerabilities..."
+	@uv run pip-audit --desc --skip-editable
+	@echo "✅ No known vulnerabilities found!"
+
+license-check:
+	@echo "📜 Checking dependency license compliance..."
+	@uv run pip-licenses --fail-on="GPL-3.0-or-later;AGPL-3.0-or-later" --format=plain > /dev/null
+	@echo "✅ All dependency licenses are compliant!"
+
+audit: dep-audit license-check
+	@echo "✅ All security audits passed!"
+
+scan-image: check-docker
+	@echo "🐳 Scanning Docker image for OS-level CVEs with Trivy..."
+	@docker build -t pragma-backend:scan -q --target production .
+	@if command -v trivy > /dev/null 2>&1; then \
+		trivy image --severity HIGH,CRITICAL --exit-code 1 pragma-backend:scan; \
+	else \
+		echo "ℹ️  Trivy not found locally, using Docker to run Trivy..."; \
+		docker run --rm -v /var/run/docker.sock:/var/run/docker.sock aquasec/trivy image --severity HIGH,CRITICAL --exit-code 1 pragma-backend:scan; \
+	fi
+	@echo "✅ No HIGH/CRITICAL CVEs found in Docker image!"
+
+validate-all: validate audit
+	@echo "✅ All quality + security checks passed!"
+
+check: validate-all test
+	@echo "✅ Full validation pipeline complete!"
+
+# ============================================================================
+# Testing
+# ============================================================================
+
+test:
+	@echo "🧪 Running tests..."
+	@IS_TEST=True PYTHONPATH=. uv run pytest
+
+test-cov:
+	@echo "🧪 Running tests with coverage..."
+	@IS_TEST=True PYTHONPATH=. uv run pytest --cov=app --cov-report=term-missing --cov-report=html -n 16
+	@echo "📊 Coverage report generated in htmlcov/index.html"
+
+# ============================================================================
+# E2E Testing (requires Docker)
+# ============================================================================
+
+check-docker:
+	@docker info > /dev/null 2>&1 || (echo ""; \
+		echo "Docker is not running!"; \
+		echo ""; \
+		echo "E2E tests require Docker to be running."; \
+		echo "Please start Docker Desktop or Docker Engine and try again."; \
+		echo ""; \
+		echo "Quick start:"; \
+		echo "  macOS/Windows: Open Docker Desktop"; \
+		echo "  Linux: sudo systemctl start docker"; \
+		echo ""; \
+		exit 1)
+	@echo "Docker is available"
+
+install-e2e:
+	@echo "📦 Installing E2E test dependencies..."
+	@uv sync --extra dev --extra e2e
+	@echo "✅ E2E dependencies installed!"
+
+test-e2e: check-docker
+	@echo "🧪 Running E2E tests with PostgreSQL..."
+	@IS_TEST=True PYTHONPATH=. uv run pytest tests/e2e/ -v --tb=short -n 0
+	@echo "✅ E2E tests complete!"
+
+test-e2e-schema: check-docker
+	@echo "🧪 Running Schemathesis API schema tests..."
+	@IS_TEST=True PYTHONPATH=. uv run pytest tests/e2e/ -v -m "schemathesis" --tb=short -n 0
+
+# ============================================================================
+# Performance Benchmarks
+# ============================================================================
+
+benchmark:
+	@echo "⏱️  Running performance benchmarks..."
+	@IS_TEST=True PYTHONPATH=. uv run pytest tests/benchmarks/ -v --benchmark-only --benchmark-sort=mean -p no:xdist --override-ini='addopts='
+
+benchmark-save:
+	@echo "⏱️  Running benchmarks and saving baseline..."
+	@IS_TEST=True PYTHONPATH=. uv run pytest tests/benchmarks/ -v --benchmark-only --benchmark-save=baseline --benchmark-sort=mean -p no:xdist --override-ini='addopts='
+	@echo "✅ Benchmark baseline saved to .benchmarks/"
+
+benchmark-check:
+	@echo "⏱️  Running benchmarks and comparing against baseline..."
+	@if find .benchmarks -name '*_baseline*' -print -quit 2>/dev/null | grep -q .; then \
+		IS_TEST=True PYTHONPATH=. uv run pytest tests/benchmarks/ -v --benchmark-only --benchmark-compare=0001_baseline --benchmark-sort=mean --benchmark-compare-fail=mean:200% -p no:xdist --override-ini='addopts='; \
+		echo "✅ No performance regressions detected!"; \
+	else \
+		echo "⚠️  No benchmark baseline found. Run 'make benchmark-save' first to create one."; \
+		echo "   Running benchmarks without comparison..."; \
+		IS_TEST=True PYTHONPATH=. uv run pytest tests/benchmarks/ -v --benchmark-only --benchmark-save=baseline --benchmark-sort=mean -p no:xdist --override-ini='addopts='; \
+		echo "✅ Benchmark baseline created. Future runs of 'make benchmark-check' will compare against it."; \
+	fi
+
+test-all:
+	@echo "🧪 Running ALL tests (unit + E2E)..."
+	@$(MAKE) test
+	@$(MAKE) test-e2e
+
+# ============================================================================
+# Cleanup
+# ============================================================================
+
+clean:
+	@echo "🧹 Cleaning up..."
+	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".pyright" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".ruff_cache" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name "htmlcov" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name "build" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type d -name ".uv_cache" -exec rm -rf {} + 2>/dev/null || true
+	@find . -type f -name ".coverage" -delete 2>/dev/null || true
+	@find . -type f -name "*.pyc" -delete 2>/dev/null || true
+	@echo "✅ Cleanup complete!"

backend/README.md

@@ -0,0 +1,707 @@
+# PragmaStack Backend API
+
+> The pragmatic, production-ready FastAPI backend for PragmaStack.
+
+## Overview
+
+Opinionated, secure, and fast. This backend provides the solid foundation you need to ship features, not boilerplate.
+
+Features:
+
+- **Authentication**: JWT with refresh tokens, session management, device tracking
+- **Database**: Async PostgreSQL with SQLAlchemy 2.0, Alembic migrations
+- **Security**: Rate limiting, CORS, CSP headers, password hashing (bcrypt)
+- **Multi-tenancy**: Organization-based access control with roles (Owner/Admin/Member)
+- **Testing**: 97%+ coverage with security-focused test suite
+- **Performance**: Async throughout, connection pooling, optimized queries
+- **Modern Tooling**: uv for dependencies, Ruff for linting/formatting, Pyright for type checking
+- **Security Auditing**: Automated dependency vulnerability scanning, license compliance, secrets detection
+- **Pre-commit Hooks**: Ruff, detect-secrets, and standard checks on every commit
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- PostgreSQL 14+ (or SQLite for development)
+- **[uv](https://docs.astral.sh/uv/)** - Modern Python package manager (replaces pip)
+
+### Installation
+
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install all dependencies (production + dev)
+cd backend
+uv sync --extra dev
+
+# Or use the Makefile
+make install-dev
+
+# Copy environment template
+cp .env.example .env
+# Edit .env with your configuration
+```
+
+**Why uv?**
+- 🚀 10-100x faster than pip
+- 🔒 Reproducible builds via `uv.lock` lockfile
+- 📦 Better dependency resolution
+- ⚡ Built by Astral (creators of Ruff)
+
+### Database Setup
+
+```bash
+# Run migrations
+python migrate.py apply
+
+# Or use Alembic directly
+alembic upgrade head
+```
+
+### Run Development Server
+
+```bash
+# Using uv
+uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+
+# Or activate environment first
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+API will be available at:
+- **API**: http://localhost:8000
+- **Swagger Docs**: http://localhost:8000/docs
+- **ReDoc**: http://localhost:8000/redoc
+
+---
+
+## Dependency Management with uv
+
+### Understanding uv
+
+**uv** is the modern standard for Python dependency management, built in Rust for speed and reliability.
+
+**Key files:**
+- `pyproject.toml` - Declares dependencies and tool configurations
+- `uv.lock` - Locks exact versions for reproducible builds (commit to git)
+
+### Common Commands
+
+#### Installing Dependencies
+
+```bash
+# Install all dependencies from lockfile
+uv sync --extra dev
+
+# Install only production dependencies (no dev tools)
+uv sync
+
+# Or use the Makefile
+make install-dev    # Install with dev dependencies
+make sync           # Sync from lockfile
+```
+
+#### Adding Dependencies
+
+```bash
+# Add a production dependency
+uv add httpx
+
+# Add a development dependency
+uv add --dev pytest-mock
+
+# Add with version constraint
+uv add "fastapi>=0.115.0,<0.116.0"
+
+# Add exact version
+uv add "pydantic==2.10.6"
+```
+
+After adding dependencies, **commit both `pyproject.toml` and `uv.lock`** to git.
+
+#### Removing Dependencies
+
+```bash
+# Remove a package
+uv remove httpx
+
+# Remove a dev dependency
+uv remove --dev pytest-mock
+```
+
+#### Updating Dependencies
+
+```bash
+# Update all packages to latest compatible versions
+uv sync --upgrade
+
+# Update a specific package
+uv add --upgrade fastapi
+
+# Check for outdated packages
+uv pip list --outdated
+```
+
+#### Running Commands in uv Environment
+
+```bash
+# Run any Python command via uv (no activation needed)
+uv run python script.py
+uv run pytest
+uv run pyright app/
+
+# Or activate the virtual environment
+source .venv/bin/activate
+python script.py
+pytest
+```
+
+### Makefile Commands
+
+We provide convenient Makefile commands that use uv:
+
+```bash
+# Setup
+make install-dev   # Install all dependencies (prod + dev)
+make sync          # Sync from lockfile
+
+# Code Quality
+make lint          # Run Ruff linter (check only)
+make lint-fix      # Run Ruff with auto-fix
+make format        # Format code with Ruff
+make format-check  # Check if code is formatted
+make type-check    # Run Pyright type checking
+make validate      # Run all checks (lint + format + types)
+
+# Security & Audit
+make dep-audit     # Scan dependencies for known vulnerabilities (CVEs)
+make license-check # Check dependency license compliance
+make audit         # Run all security audits (deps + licenses)
+make validate-all  # Run all quality + security checks
+make check         # Full pipeline: quality + security + tests
+
+# Testing
+make test          # Run all tests
+make test-cov      # Run tests with coverage report
+make test-e2e      # Run E2E tests (PostgreSQL, requires Docker)
+make test-e2e-schema # Run Schemathesis API schema tests
+make test-all      # Run all tests (unit + E2E)
+
+# Utilities
+make clean         # Remove cache and build artifacts
+make help          # Show all commands
+```
+
+### Dependency Workflow Example
+
+```bash
+# 1. Clone repository
+git clone <repo-url>
+cd backend
+
+# 2. Install dependencies
+make install-dev
+
+# 3. Make changes, add a new dependency
+uv add httpx
+
+# 4. Test your changes
+make test
+
+# 5. Commit (includes uv.lock)
+git add pyproject.toml uv.lock
+git commit -m "Add httpx dependency"
+
+# 6. Other developers pull and sync
+git pull
+make sync  # Uses the committed uv.lock
+```
+
+### Troubleshooting uv
+
+**Dependencies not found after install:**
+```bash
+# Make sure you're using uv run or activated environment
+uv run pytest          # Option 1: Run via uv
+source .venv/bin/activate  # Option 2: Activate first
+pytest
+```
+
+**Lockfile out of sync:**
+```bash
+# Regenerate lockfile
+uv lock
+
+# Force reinstall from lockfile
+uv sync --reinstall
+```
+
+**uv not found:**
+```bash
+# Install uv globally
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Add to PATH if needed
+export PATH="$HOME/.cargo/bin:$PATH"
+```
+
+---
+
+## Development
+
+### Project Structure
+
+```
+app/
+├── api/              # API routes and dependencies
+│   ├── routes/       # Endpoint implementations
+│   └── dependencies/ # Auth, permissions, etc.
+├── core/             # Core functionality
+│   ├── config.py     # Settings management
+│   ├── database.py   # Database engine setup
+│   ├── auth.py       # JWT token handling
+│   └── exceptions.py # Custom exceptions
+├── repositories/     # Repository pattern (database operations)
+├── models/           # SQLAlchemy ORM models
+├── schemas/          # Pydantic request/response schemas
+├── services/         # Business logic layer
+└── utils/            # Utility functions
+```
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture documentation.
+
+### Configuration
+
+Environment variables (`.env`):
+
+```bash
+# Database
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=your_password
+POSTGRES_HOST=localhost
+POSTGRES_PORT=5432
+POSTGRES_DB=app_db
+
+# Security (IMPORTANT: Change these!)
+SECRET_KEY=your-secret-key-min-32-chars-change-in-production
+ENVIRONMENT=development  # development | production
+
+# Optional
+BACKEND_CORS_ORIGINS=["http://localhost:3000"]
+CSP_MODE=relaxed  # strict | relaxed | disabled
+
+# First superuser (auto-created on startup)
+FIRST_SUPERUSER_EMAIL=admin@example.com
+FIRST_SUPERUSER_PASSWORD=SecurePass123!
+```
+
+⚠️ **Security Note**: Never commit `.env` files. Use strong, unique values in production.
+
+### Database Migrations
+
+We use Alembic for database migrations with a helper script:
+
+```bash
+# Generate migration from model changes
+python migrate.py generate "add user preferences"
+
+# Apply migrations
+python migrate.py apply
+
+# Generate and apply in one step
+python migrate.py auto "add user preferences"
+
+# Check current version
+python migrate.py current
+
+# List all migrations
+python migrate.py list
+```
+
+Manual Alembic usage:
+
+```bash
+# Generate migration
+alembic revision --autogenerate -m "description"
+
+# Apply migrations
+alembic upgrade head
+
+# Rollback one migration
+alembic downgrade -1
+```
+
+### Testing
+
+```bash
+# Using Makefile (recommended)
+make test              # Run all tests
+make test-cov          # Run with coverage report
+
+# Using uv directly
+IS_TEST=True uv run pytest
+IS_TEST=True uv run pytest --cov=app --cov-report=term-missing -n 0
+
+# Run specific test file
+IS_TEST=True uv run pytest tests/api/test_auth.py -v
+
+# Run single test
+IS_TEST=True uv run pytest tests/api/test_auth.py::TestLogin::test_login_success -v
+
+# Generate HTML coverage report
+IS_TEST=True uv run pytest --cov=app --cov-report=html -n 0
+open htmlcov/index.html
+```
+
+**Test Environment**: Uses SQLite in-memory database. Tests run in parallel via pytest-xdist.
+
+### Code Quality
+
+```bash
+# Using Makefile (recommended)
+make lint          # Ruff linting
+make format        # Ruff formatting
+make type-check    # Pyright type checking
+make validate      # All checks at once
+
+# Security audits
+make dep-audit     # Scan dependencies for CVEs
+make license-check # Check license compliance
+make audit         # All security audits
+make validate-all  # Quality + security checks
+make check         # Full pipeline: quality + security + tests
+
+# Using uv directly
+uv run ruff check app/ tests/
+uv run ruff format app/ tests/
+uv run pyright app/
+```
+
+**Tools:**
+- **Ruff**: All-in-one linting, formatting, and import sorting (replaces Black, Flake8, isort)
+- **Pyright**: Static type checking (strict mode)
+- **pip-audit**: Dependency vulnerability scanning against the OSV database
+- **pip-licenses**: Dependency license compliance checking
+- **detect-secrets**: Hardcoded secrets/credentials detection
+- **pre-commit**: Git hook framework for automated checks on every commit
+
+All configurations are in `pyproject.toml`.
+
+---
+
+## API Documentation
+
+Once the server is running, interactive API documentation is available:
+
+- **Swagger UI**: http://localhost:8000/docs
+  - Try out endpoints directly
+  - See request/response schemas
+  - View authentication requirements
+
+- **ReDoc**: http://localhost:8000/redoc
+  - Alternative documentation interface
+  - Better for reading/printing
+
+- **OpenAPI JSON**: http://localhost:8000/api/v1/openapi.json
+  - Raw OpenAPI 3.0 specification
+  - Use for client generation
+
+---
+
+## Authentication
+
+### Token-Based Authentication
+
+The API uses JWT tokens for authentication:
+
+1. **Login**: `POST /api/v1/auth/login`
+   - Returns access token (15 min expiry) and refresh token (7 day expiry)
+   - Session tracked with device information
+
+2. **Refresh**: `POST /api/v1/auth/refresh`
+   - Exchange refresh token for new access token
+   - Validates session is still active
+
+3. **Logout**: `POST /api/v1/auth/logout`
+   - Invalidates current session
+   - Use `logout-all` to invalidate all user sessions
+
+### Using Protected Endpoints
+
+Include access token in Authorization header:
+
+```bash
+curl -H "Authorization: Bearer <access_token>" \
+  http://localhost:8000/api/v1/users/me
+```
+
+### Roles & Permissions
+
+- **Superuser**: Full system access (user/org management)
+- **Organization Roles**:
+  - `Owner`: Full control of organization
+  - `Admin`: Can manage members (except owners)
+  - `Member`: Read-only access
+
+---
+
+## Common Tasks
+
+### Create a Superuser
+
+Superusers are created automatically on startup using `FIRST_SUPERUSER_EMAIL` and `FIRST_SUPERUSER_PASSWORD` from `.env`.
+
+To create additional superusers, update a user via SQL or admin API.
+
+### Add a New API Endpoint
+
+See [docs/FEATURE_EXAMPLE.md](docs/FEATURE_EXAMPLE.md) for step-by-step guide.
+
+Quick overview:
+1. Create Pydantic schemas in `app/schemas/`
+2. Create repository in `app/repositories/`
+3. Create route in `app/api/routes/`
+4. Register router in `app/api/main.py`
+5. Write tests in `tests/api/`
+
+### Database Health Check
+
+```bash
+# Check database connection
+python migrate.py check
+
+# Health endpoint
+curl http://localhost:8000/health
+```
+
+---
+
+## Docker Support
+
+The Dockerfile uses **uv** for fast, reproducible builds:
+
+```bash
+# Development with hot reload
+docker-compose -f docker-compose.dev.yml up
+
+# Production
+docker-compose up -d
+
+# Rebuild after changes
+docker-compose build backend
+```
+
+**Docker features:**
+- Multi-stage builds (development + production)
+- uv for fast dependency installation
+- `uv.lock` ensures exact versions in containers
+- Development stage includes dev dependencies
+- Production stage optimized for size and security
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Module Import Errors**
+```bash
+# Ensure dependencies are installed
+make install-dev
+
+# Or sync from lockfile
+make sync
+
+# Verify Python environment
+uv run python --version
+```
+
+**uv command not found**
+```bash
+# Install uv globally
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Add to PATH (add to ~/.bashrc or ~/.zshrc)
+export PATH="$HOME/.cargo/bin:$PATH"
+```
+
+**Database Connection Failed**
+```bash
+# Check PostgreSQL is running
+sudo systemctl status postgresql
+
+# Verify credentials in .env
+cat .env | grep POSTGRES
+```
+
+**Migration Conflicts**
+```bash
+# Check migration history
+python migrate.py list
+
+# Downgrade and retry
+alembic downgrade -1
+alembic upgrade head
+```
+
+**Tests Failing**
+```bash
+# Run with verbose output
+make test
+
+# Run single test to isolate issue
+IS_TEST=True uv run pytest tests/api/test_auth.py::TestLogin::test_login_success -vv
+```
+
+**Dependencies out of sync**
+```bash
+# Regenerate lockfile from pyproject.toml
+uv lock
+
+# Reinstall everything
+make install-dev
+```
+
+### Getting Help
+
+See our detailed documentation:
+
+- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - System design and patterns
+- [CODING_STANDARDS.md](docs/CODING_STANDARDS.md) - Code quality guidelines
+- [COMMON_PITFALLS.md](docs/COMMON_PITFALLS.md) - Mistakes to avoid
+- [FEATURE_EXAMPLE.md](docs/FEATURE_EXAMPLE.md) - Adding new features
+
+---
+
+## Performance
+
+### Database Connection Pooling
+
+Configured in `app/core/config.py`:
+- Pool size: 20 connections
+- Max overflow: 50 connections
+- Pool timeout: 30 seconds
+- Connection recycling: 1 hour
+
+### Async Operations
+
+- All I/O operations use async/await
+- CPU-intensive operations (bcrypt) run in thread pool
+- No blocking calls in request handlers
+
+### Query Optimization
+
+- N+1 query prevention via eager loading
+- Bulk operations for admin actions
+- Indexed foreign keys and common lookups
+
+---
+
+## Security
+
+### Built-in Security Features
+
+- **Password Security**: bcrypt hashing, strength validation, common password blocking
+- **Token Security**: HMAC-SHA256 signed, short-lived access tokens, algorithm validation
+- **Session Management**: Database-backed, device tracking, revocation support
+- **Rate Limiting**: Per-endpoint limits on auth/sensitive operations
+- **CORS**: Explicit origins, methods, and headers only
+- **Security Headers**: CSP, HSTS, X-Frame-Options, etc.
+- **Input Validation**: Pydantic schemas, SQL injection prevention (ORM)
+
+### Security Auditing
+
+Automated, deterministic security checks are built into the development workflow:
+
+```bash
+# Scan dependencies for known vulnerabilities (CVEs)
+make dep-audit
+
+# Check dependency license compliance (blocks GPL-3.0/AGPL)
+make license-check
+
+# Run all security audits
+make audit
+
+# Full pipeline: quality + security + tests
+make check
+```
+
+**Pre-commit hooks** automatically run on every commit:
+- **Ruff** lint + format checks
+- **detect-secrets** blocks commits containing hardcoded secrets
+- **Standard checks**: trailing whitespace, YAML/TOML validation, merge conflict detection, large file prevention
+
+Setup pre-commit hooks:
+```bash
+uv run pre-commit install
+```
+
+### Security Best Practices
+
+1. **Never commit secrets**: Use `.env` files (git-ignored), enforced by detect-secrets pre-commit hook
+2. **Strong SECRET_KEY**: Min 32 chars, cryptographically random
+3. **HTTPS in production**: Required for token security
+4. **Regular updates**: Keep dependencies current (`uv sync --upgrade`), run `make dep-audit` to check for CVEs
+5. **Audit logs**: Monitor authentication events
+6. **Run `make check` before pushing**: Validates quality, security, and tests in one command
+
+---
+
+## Monitoring
+
+### Health Check
+
+```bash
+curl http://localhost:8000/health
+```
+
+Returns:
+- API version
+- Environment
+- Database connectivity
+- Timestamp
+
+### Logging
+
+Logs are written to stdout with structured format:
+
+```python
+# Configure log level
+logging.basicConfig(level=logging.INFO)
+
+# In production, use JSON logs for log aggregation
+```
+
+---
+
+## Additional Resources
+
+### Official Documentation
+- **uv**: https://docs.astral.sh/uv/
+- **FastAPI**: https://fastapi.tiangolo.com
+- **SQLAlchemy 2.0**: https://docs.sqlalchemy.org/en/20/
+- **Pydantic**: https://docs.pydantic.dev/
+- **Alembic**: https://alembic.sqlalchemy.org/
+- **Ruff**: https://docs.astral.sh/ruff/
+
+### Our Documentation
+- [Root README](../README.md) - Project-wide information
+- [CLAUDE.md](../CLAUDE.md) - Comprehensive development guide
+
+---
+
+**Built with modern Python tooling:**
+- 🚀 **uv** - 10-100x faster dependency management
+- ⚡ **Ruff** - 10-100x faster linting & formatting
+- 🔍 **Pyright** - Static type checking (strict mode)
+- ✅ **pytest** - Comprehensive test suite
+- 🔒 **pip-audit** - Dependency vulnerability scanning
+- 🔑 **detect-secrets** - Hardcoded secrets detection
+- 📜 **pip-licenses** - License compliance checking
+- 🪝 **pre-commit** - Automated git hooks
+
+**All configured in a single `pyproject.toml` file!**

backend/alembic.ini

@@ -2,6 +2,13 @@
 script_location = app/alembic
 sqlalchemy.url = postgresql://postgres:postgres@db:5432/app
 
+# Use sequential naming: 0001_message.py, 0002_message.py, etc.
+# The rev_id is still used internally but filename is cleaner
+file_template = %%(rev)s_%%(slug)s
+
+# Allow specifying custom revision IDs via --rev-id flag
+revision_environment = true
+
 [loggers]
 keys = root,sqlalchemy,alembic
 

backend/app/alembic/env.py

@@ -2,10 +2,10 @@ import sys
 from logging.config import fileConfig
 from pathlib import Path
 
-from sqlalchemy import engine_from_config
-from sqlalchemy import pool
-
 from alembic import context
+from sqlalchemy import create_engine, engine_from_config, pool, text
+from sqlalchemy.engine.url import make_url
+from sqlalchemy.exc import OperationalError
 
 # Get the path to the app directory (parent of 'alembic')
 app_dir = Path(__file__).resolve().parent.parent
@@ -14,7 +14,6 @@ sys.path.append(str(app_dir.parent))
 
 # Import Core modules
 from app.core.config import settings
-from app.core.database import Base
 
 # Import all models to ensure they're registered with SQLAlchemy
 from app.models import *
@@ -23,6 +22,25 @@ from app.models import *
 # access to the values within the .ini file in use.
 config = context.config
 
+
+def include_object(object, name, type_, reflected, compare_to):
+    """
+    Filter objects for autogenerate.
+
+    Skip comparing functional indexes (like LOWER(column)) and partial indexes
+    (with WHERE clauses) as Alembic cannot reliably detect these from models.
+    These should be managed manually via dedicated performance migrations.
+
+    Convention: Any index starting with "ix_perf_" is automatically excluded.
+    This allows adding new performance indexes without updating this file.
+    """
+    if type_ == "index" and name:
+        # Convention-based: any index prefixed with ix_perf_ is manual
+        if name.startswith("ix_perf_"):
+            return False
+    return True
+
+
 # Interpret the config file for Python logging.
 # This line sets up loggers basically.
 if config.config_file_name is not None:
@@ -36,6 +54,53 @@ target_metadata = Base.metadata
 config.set_main_option("sqlalchemy.url", settings.database_url)
 
 
+def ensure_database_exists(db_url: str) -> None:
+    """
+    Ensure the target PostgreSQL database exists.
+    If connection to the target DB fails because it doesn't exist, connect to the
+    default 'postgres' database and create it. Safe to call multiple times.
+    """
+    try:
+        # First, try connecting to the target database
+        test_engine = create_engine(db_url, poolclass=pool.NullPool)
+        with test_engine.connect() as conn:
+            conn.execute(text("SELECT 1"))
+        test_engine.dispose()
+        return
+    except OperationalError:
+        # Likely the database does not exist; proceed to create it
+        pass
+
+    url = make_url(db_url)
+    # Only handle PostgreSQL here
+    if url.get_backend_name() != "postgresql":
+        return
+
+    target_db = url.database
+    if not target_db:
+        return
+
+    # Build admin URL pointing to the default 'postgres' database
+    admin_url = url.set(database="postgres")
+
+    # CREATE DATABASE cannot run inside a transaction
+    admin_engine = create_engine(
+        str(admin_url), isolation_level="AUTOCOMMIT", poolclass=pool.NullPool
+    )
+    try:
+        with admin_engine.connect() as conn:
+            exists = conn.execute(
+                text("SELECT 1 FROM pg_database WHERE datname = :dbname"),
+                {"dbname": target_db},
+            ).scalar()
+            if not exists:
+                # Quote the database name safely
+                dbname_quoted = '"' + target_db.replace('"', '""') + '"'
+                conn.execute(text(f"CREATE DATABASE {dbname_quoted}"))
+    finally:
+        admin_engine.dispose()
+
+
 def run_migrations_offline() -> None:
     """Run migrations in 'offline' mode.
 
@@ -54,6 +119,8 @@ def run_migrations_offline() -> None:
         target_metadata=target_metadata,
         literal_binds=True,
         dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+        include_object=include_object,
     )
 
     with context.begin_transaction():
@@ -67,6 +134,9 @@ def run_migrations_online() -> None:
     and associate a connection with the context.
 
     """
+    # Ensure the target database exists (handles first-run cases)
+    ensure_database_exists(settings.database_url)
+
     connectable = engine_from_config(
         config.get_section(config.config_ini_section, {}),
         prefix="sqlalchemy.",
@@ -75,7 +145,10 @@ def run_migrations_online() -> None:
 
     with connectable.connect() as connection:
         context.configure(
-            connection=connection, target_metadata=target_metadata
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+            include_object=include_object,
         )
 
         with context.begin_transaction():
@@ -85,4 +158,4 @@ def run_migrations_online() -> None:
 if context.is_offline_mode():
     run_migrations_offline()
 else:
-    run_migrations_online()
+    run_migrations_online()

backend/app/alembic/versions/0001_initial_models.py

@@ -0,0 +1,446 @@
+"""initial models
+
+Revision ID: 0001
+Revises:
+Create Date: 2025-11-27 09:08:09.464506
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = "0001"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "oauth_states",
+        sa.Column("state", sa.String(length=255), nullable=False),
+        sa.Column("code_verifier", sa.String(length=128), nullable=True),
+        sa.Column("nonce", sa.String(length=255), nullable=True),
+        sa.Column("provider", sa.String(length=50), nullable=False),
+        sa.Column("redirect_uri", sa.String(length=500), nullable=True),
+        sa.Column("user_id", sa.UUID(), nullable=True),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_oauth_states_state"), "oauth_states", ["state"], unique=True
+    )
+    op.create_table(
+        "organizations",
+        sa.Column("name", sa.String(length=255), nullable=False),
+        sa.Column("slug", sa.String(length=255), nullable=False),
+        sa.Column("description", sa.Text(), nullable=True),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("settings", postgresql.JSONB(astext_type=sa.Text()), nullable=True),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_organizations_is_active"), "organizations", ["is_active"], unique=False
+    )
+    op.create_index(
+        op.f("ix_organizations_name"), "organizations", ["name"], unique=False
+    )
+    op.create_index(
+        "ix_organizations_name_active",
+        "organizations",
+        ["name", "is_active"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_organizations_slug"), "organizations", ["slug"], unique=True
+    )
+    op.create_index(
+        "ix_organizations_slug_active",
+        "organizations",
+        ["slug", "is_active"],
+        unique=False,
+    )
+    op.create_table(
+        "users",
+        sa.Column("email", sa.String(length=255), nullable=False),
+        sa.Column("password_hash", sa.String(length=255), nullable=True),
+        sa.Column("first_name", sa.String(length=100), nullable=False),
+        sa.Column("last_name", sa.String(length=100), nullable=True),
+        sa.Column("phone_number", sa.String(length=20), nullable=True),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("is_superuser", sa.Boolean(), nullable=False),
+        sa.Column(
+            "preferences", postgresql.JSONB(astext_type=sa.Text()), nullable=True
+        ),
+        sa.Column("locale", sa.String(length=10), nullable=True),
+        sa.Column("deleted_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(op.f("ix_users_deleted_at"), "users", ["deleted_at"], unique=False)
+    op.create_index(op.f("ix_users_email"), "users", ["email"], unique=True)
+    op.create_index(op.f("ix_users_is_active"), "users", ["is_active"], unique=False)
+    op.create_index(
+        op.f("ix_users_is_superuser"), "users", ["is_superuser"], unique=False
+    )
+    op.create_index(op.f("ix_users_locale"), "users", ["locale"], unique=False)
+    op.create_table(
+        "oauth_accounts",
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("provider", sa.String(length=50), nullable=False),
+        sa.Column("provider_user_id", sa.String(length=255), nullable=False),
+        sa.Column("provider_email", sa.String(length=255), nullable=True),
+        sa.Column("access_token_encrypted", sa.String(length=2048), nullable=True),
+        sa.Column("refresh_token_encrypted", sa.String(length=2048), nullable=True),
+        sa.Column("token_expires_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint(
+            "provider", "provider_user_id", name="uq_oauth_provider_user"
+        ),
+    )
+    op.create_index(
+        op.f("ix_oauth_accounts_provider"), "oauth_accounts", ["provider"], unique=False
+    )
+    op.create_index(
+        op.f("ix_oauth_accounts_provider_email"),
+        "oauth_accounts",
+        ["provider_email"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_oauth_accounts_user_id"), "oauth_accounts", ["user_id"], unique=False
+    )
+    op.create_index(
+        "ix_oauth_accounts_user_provider",
+        "oauth_accounts",
+        ["user_id", "provider"],
+        unique=False,
+    )
+    op.create_table(
+        "oauth_clients",
+        sa.Column("client_id", sa.String(length=64), nullable=False),
+        sa.Column("client_secret_hash", sa.String(length=255), nullable=True),
+        sa.Column("client_name", sa.String(length=255), nullable=False),
+        sa.Column("client_description", sa.String(length=1000), nullable=True),
+        sa.Column("client_type", sa.String(length=20), nullable=False),
+        sa.Column(
+            "redirect_uris", postgresql.JSONB(astext_type=sa.Text()), nullable=False
+        ),
+        sa.Column(
+            "allowed_scopes", postgresql.JSONB(astext_type=sa.Text()), nullable=False
+        ),
+        sa.Column("access_token_lifetime", sa.String(length=10), nullable=False),
+        sa.Column("refresh_token_lifetime", sa.String(length=10), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("owner_user_id", sa.UUID(), nullable=True),
+        sa.Column("mcp_server_url", sa.String(length=2048), nullable=True),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["owner_user_id"], ["users.id"], ondelete="SET NULL"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_oauth_clients_client_id"), "oauth_clients", ["client_id"], unique=True
+    )
+    op.create_index(
+        op.f("ix_oauth_clients_is_active"), "oauth_clients", ["is_active"], unique=False
+    )
+    op.create_table(
+        "user_organizations",
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("organization_id", sa.UUID(), nullable=False),
+        sa.Column(
+            "role",
+            sa.Enum("OWNER", "ADMIN", "MEMBER", "GUEST", name="organizationrole"),
+            nullable=False,
+        ),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("custom_permissions", sa.String(length=500), nullable=True),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["organization_id"], ["organizations.id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("user_id", "organization_id"),
+    )
+    op.create_index(
+        "ix_user_org_org_active",
+        "user_organizations",
+        ["organization_id", "is_active"],
+        unique=False,
+    )
+    op.create_index("ix_user_org_role", "user_organizations", ["role"], unique=False)
+    op.create_index(
+        "ix_user_org_user_active",
+        "user_organizations",
+        ["user_id", "is_active"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_user_organizations_is_active"),
+        "user_organizations",
+        ["is_active"],
+        unique=False,
+    )
+    op.create_table(
+        "user_sessions",
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("refresh_token_jti", sa.String(length=255), nullable=False),
+        sa.Column("device_name", sa.String(length=255), nullable=True),
+        sa.Column("device_id", sa.String(length=255), nullable=True),
+        sa.Column("ip_address", sa.String(length=45), nullable=True),
+        sa.Column("user_agent", sa.String(length=500), nullable=True),
+        sa.Column("last_used_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("is_active", sa.Boolean(), nullable=False),
+        sa.Column("location_city", sa.String(length=100), nullable=True),
+        sa.Column("location_country", sa.String(length=100), nullable=True),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        op.f("ix_user_sessions_is_active"), "user_sessions", ["is_active"], unique=False
+    )
+    op.create_index(
+        "ix_user_sessions_jti_active",
+        "user_sessions",
+        ["refresh_token_jti", "is_active"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_user_sessions_refresh_token_jti"),
+        "user_sessions",
+        ["refresh_token_jti"],
+        unique=True,
+    )
+    op.create_index(
+        "ix_user_sessions_user_active",
+        "user_sessions",
+        ["user_id", "is_active"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_user_sessions_user_id"), "user_sessions", ["user_id"], unique=False
+    )
+    op.create_table(
+        "oauth_authorization_codes",
+        sa.Column("code", sa.String(length=128), nullable=False),
+        sa.Column("client_id", sa.String(length=64), nullable=False),
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("redirect_uri", sa.String(length=2048), nullable=False),
+        sa.Column("scope", sa.String(length=1000), nullable=False),
+        sa.Column("code_challenge", sa.String(length=128), nullable=True),
+        sa.Column("code_challenge_method", sa.String(length=10), nullable=True),
+        sa.Column("state", sa.String(length=256), nullable=True),
+        sa.Column("nonce", sa.String(length=256), nullable=True),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("used", sa.Boolean(), nullable=False),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["client_id"], ["oauth_clients.client_id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_oauth_authorization_codes_client_user",
+        "oauth_authorization_codes",
+        ["client_id", "user_id"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_oauth_authorization_codes_code"),
+        "oauth_authorization_codes",
+        ["code"],
+        unique=True,
+    )
+    op.create_index(
+        "ix_oauth_authorization_codes_expires_at",
+        "oauth_authorization_codes",
+        ["expires_at"],
+        unique=False,
+    )
+    op.create_table(
+        "oauth_consents",
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("client_id", sa.String(length=64), nullable=False),
+        sa.Column("granted_scopes", sa.String(length=1000), nullable=False),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["client_id"], ["oauth_clients.client_id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_oauth_consents_user_client",
+        "oauth_consents",
+        ["user_id", "client_id"],
+        unique=True,
+    )
+    op.create_table(
+        "oauth_provider_refresh_tokens",
+        sa.Column("token_hash", sa.String(length=64), nullable=False),
+        sa.Column("jti", sa.String(length=64), nullable=False),
+        sa.Column("client_id", sa.String(length=64), nullable=False),
+        sa.Column("user_id", sa.UUID(), nullable=False),
+        sa.Column("scope", sa.String(length=1000), nullable=False),
+        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("revoked", sa.Boolean(), nullable=False),
+        sa.Column("last_used_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("device_info", sa.String(length=500), nullable=True),
+        sa.Column("ip_address", sa.String(length=45), nullable=True),
+        sa.Column("id", sa.UUID(), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=False),
+        sa.ForeignKeyConstraint(
+            ["client_id"], ["oauth_clients.client_id"], ondelete="CASCADE"
+        ),
+        sa.ForeignKeyConstraint(["user_id"], ["users.id"], ondelete="CASCADE"),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    op.create_index(
+        "ix_oauth_provider_refresh_tokens_client_user",
+        "oauth_provider_refresh_tokens",
+        ["client_id", "user_id"],
+        unique=False,
+    )
+    op.create_index(
+        "ix_oauth_provider_refresh_tokens_expires_at",
+        "oauth_provider_refresh_tokens",
+        ["expires_at"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_oauth_provider_refresh_tokens_jti"),
+        "oauth_provider_refresh_tokens",
+        ["jti"],
+        unique=True,
+    )
+    op.create_index(
+        op.f("ix_oauth_provider_refresh_tokens_revoked"),
+        "oauth_provider_refresh_tokens",
+        ["revoked"],
+        unique=False,
+    )
+    op.create_index(
+        op.f("ix_oauth_provider_refresh_tokens_token_hash"),
+        "oauth_provider_refresh_tokens",
+        ["token_hash"],
+        unique=True,
+    )
+    op.create_index(
+        "ix_oauth_provider_refresh_tokens_user_revoked",
+        "oauth_provider_refresh_tokens",
+        ["user_id", "revoked"],
+        unique=False,
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_index(
+        "ix_oauth_provider_refresh_tokens_user_revoked",
+        table_name="oauth_provider_refresh_tokens",
+    )
+    op.drop_index(
+        op.f("ix_oauth_provider_refresh_tokens_token_hash"),
+        table_name="oauth_provider_refresh_tokens",
+    )
+    op.drop_index(
+        op.f("ix_oauth_provider_refresh_tokens_revoked"),
+        table_name="oauth_provider_refresh_tokens",
+    )
+    op.drop_index(
+        op.f("ix_oauth_provider_refresh_tokens_jti"),
+        table_name="oauth_provider_refresh_tokens",
+    )
+    op.drop_index(
+        "ix_oauth_provider_refresh_tokens_expires_at",
+        table_name="oauth_provider_refresh_tokens",
+    )
+    op.drop_index(
+        "ix_oauth_provider_refresh_tokens_client_user",
+        table_name="oauth_provider_refresh_tokens",
+    )
+    op.drop_table("oauth_provider_refresh_tokens")
+    op.drop_index("ix_oauth_consents_user_client", table_name="oauth_consents")
+    op.drop_table("oauth_consents")
+    op.drop_index(
+        "ix_oauth_authorization_codes_expires_at",
+        table_name="oauth_authorization_codes",
+    )
+    op.drop_index(
+        op.f("ix_oauth_authorization_codes_code"),
+        table_name="oauth_authorization_codes",
+    )
+    op.drop_index(
+        "ix_oauth_authorization_codes_client_user",
+        table_name="oauth_authorization_codes",
+    )
+    op.drop_table("oauth_authorization_codes")
+    op.drop_index(op.f("ix_user_sessions_user_id"), table_name="user_sessions")
+    op.drop_index("ix_user_sessions_user_active", table_name="user_sessions")
+    op.drop_index(
+        op.f("ix_user_sessions_refresh_token_jti"), table_name="user_sessions"
+    )
+    op.drop_index("ix_user_sessions_jti_active", table_name="user_sessions")
+    op.drop_index(op.f("ix_user_sessions_is_active"), table_name="user_sessions")
+    op.drop_table("user_sessions")
+    op.drop_index(
+        op.f("ix_user_organizations_is_active"), table_name="user_organizations"
+    )
+    op.drop_index("ix_user_org_user_active", table_name="user_organizations")
+    op.drop_index("ix_user_org_role", table_name="user_organizations")
+    op.drop_index("ix_user_org_org_active", table_name="user_organizations")
+    op.drop_table("user_organizations")
+    op.drop_index(op.f("ix_oauth_clients_is_active"), table_name="oauth_clients")
+    op.drop_index(op.f("ix_oauth_clients_client_id"), table_name="oauth_clients")
+    op.drop_table("oauth_clients")
+    op.drop_index("ix_oauth_accounts_user_provider", table_name="oauth_accounts")
+    op.drop_index(op.f("ix_oauth_accounts_user_id"), table_name="oauth_accounts")
+    op.drop_index(op.f("ix_oauth_accounts_provider_email"), table_name="oauth_accounts")
+    op.drop_index(op.f("ix_oauth_accounts_provider"), table_name="oauth_accounts")
+    op.drop_table("oauth_accounts")
+    op.drop_index(op.f("ix_users_locale"), table_name="users")
+    op.drop_index(op.f("ix_users_is_superuser"), table_name="users")
+    op.drop_index(op.f("ix_users_is_active"), table_name="users")
+    op.drop_index(op.f("ix_users_email"), table_name="users")
+    op.drop_index(op.f("ix_users_deleted_at"), table_name="users")
+    op.drop_table("users")
+    op.drop_index("ix_organizations_slug_active", table_name="organizations")
+    op.drop_index(op.f("ix_organizations_slug"), table_name="organizations")
+    op.drop_index("ix_organizations_name_active", table_name="organizations")
+    op.drop_index(op.f("ix_organizations_name"), table_name="organizations")
+    op.drop_index(op.f("ix_organizations_is_active"), table_name="organizations")
+    op.drop_table("organizations")
+    op.drop_index(op.f("ix_oauth_states_state"), table_name="oauth_states")
+    op.drop_table("oauth_states")
+    # ### end Alembic commands ###

backend/app/alembic/versions/0002_add_performance_indexes.py

@@ -0,0 +1,127 @@
+"""Add performance indexes
+
+Revision ID: 0002
+Revises: 0001
+Create Date: 2025-11-27
+
+Performance indexes that Alembic cannot auto-detect:
+- Functional indexes (LOWER expressions)
+- Partial indexes (WHERE clauses)
+
+These indexes use the ix_perf_ prefix and are excluded from autogenerate
+via the include_object() function in env.py.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "0002"
+down_revision: str | None = "0001"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ==========================================================================
+    # USERS TABLE - Performance indexes for authentication
+    # ==========================================================================
+
+    # Case-insensitive email lookup for login/registration
+    # Query: SELECT * FROM users WHERE LOWER(email) = LOWER(:email) AND deleted_at IS NULL
+    # Impact: High - every login, registration check, password reset
+    op.create_index(
+        "ix_perf_users_email_lower",
+        "users",
+        [sa.text("LOWER(email)")],
+        unique=False,
+        postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+
+    # Active users lookup (non-soft-deleted)
+    # Query: SELECT * FROM users WHERE deleted_at IS NULL AND ...
+    # Impact: Medium - user listings, admin queries
+    op.create_index(
+        "ix_perf_users_active",
+        "users",
+        ["is_active"],
+        unique=False,
+        postgresql_where=sa.text("deleted_at IS NULL"),
+    )
+
+    # ==========================================================================
+    # ORGANIZATIONS TABLE - Performance indexes for multi-tenant lookups
+    # ==========================================================================
+
+    # Case-insensitive slug lookup for URL routing
+    # Query: SELECT * FROM organizations WHERE LOWER(slug) = LOWER(:slug) AND is_active = true
+    # Impact: Medium - every organization page load
+    op.create_index(
+        "ix_perf_organizations_slug_lower",
+        "organizations",
+        [sa.text("LOWER(slug)")],
+        unique=False,
+        postgresql_where=sa.text("is_active = true"),
+    )
+
+    # ==========================================================================
+    # USER SESSIONS TABLE - Performance indexes for session management
+    # ==========================================================================
+
+    # Expired session cleanup
+    # Query: SELECT * FROM user_sessions WHERE expires_at < NOW() AND is_active = true
+    # Impact: Medium - background cleanup jobs
+    op.create_index(
+        "ix_perf_user_sessions_expires",
+        "user_sessions",
+        ["expires_at"],
+        unique=False,
+        postgresql_where=sa.text("is_active = true"),
+    )
+
+    # ==========================================================================
+    # OAUTH PROVIDER TOKENS - Performance indexes for token management
+    # ==========================================================================
+
+    # Expired refresh token cleanup
+    # Query: SELECT * FROM oauth_provider_refresh_tokens WHERE expires_at < NOW() AND revoked = false
+    # Impact: Medium - OAuth token cleanup, validation
+    op.create_index(
+        "ix_perf_oauth_refresh_tokens_expires",
+        "oauth_provider_refresh_tokens",
+        ["expires_at"],
+        unique=False,
+        postgresql_where=sa.text("revoked = false"),
+    )
+
+    # ==========================================================================
+    # OAUTH AUTHORIZATION CODES - Performance indexes for auth flow
+    # ==========================================================================
+
+    # Expired authorization code cleanup
+    # Query: DELETE FROM oauth_authorization_codes WHERE expires_at < NOW() AND used = false
+    # Impact: Low-Medium - OAuth cleanup jobs
+    op.create_index(
+        "ix_perf_oauth_auth_codes_expires",
+        "oauth_authorization_codes",
+        ["expires_at"],
+        unique=False,
+        postgresql_where=sa.text("used = false"),
+    )
+
+
+def downgrade() -> None:
+    # Drop indexes in reverse order
+    op.drop_index(
+        "ix_perf_oauth_auth_codes_expires", table_name="oauth_authorization_codes"
+    )
+    op.drop_index(
+        "ix_perf_oauth_refresh_tokens_expires",
+        table_name="oauth_provider_refresh_tokens",
+    )
+    op.drop_index("ix_perf_user_sessions_expires", table_name="user_sessions")
+    op.drop_index("ix_perf_organizations_slug_lower", table_name="organizations")
+    op.drop_index("ix_perf_users_active", table_name="users")
+    op.drop_index("ix_perf_users_email_lower", table_name="users")

backend/app/alembic/versions/0003_rename_oauth_account_token_fields_drop_encrypted_suffix.py

@@ -0,0 +1,35 @@
+"""rename oauth account token fields drop encrypted suffix
+
+Revision ID: 0003
+Revises: 0002
+Create Date: 2026-02-27 01:03:18.869178
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "0003"
+down_revision: str | None = "0002"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.alter_column(
+        "oauth_accounts", "access_token_encrypted", new_column_name="access_token"
+    )
+    op.alter_column(
+        "oauth_accounts", "refresh_token_encrypted", new_column_name="refresh_token"
+    )
+
+
+def downgrade() -> None:
+    op.alter_column(
+        "oauth_accounts", "access_token", new_column_name="access_token_encrypted"
+    )
+    op.alter_column(
+        "oauth_accounts", "refresh_token", new_column_name="refresh_token_encrypted"
+    )

backend/app/alembic/versions/38bf9e7e74b3_add_all_initial_models.py

@@ -1,46 +0,0 @@
-"""Add all initial models
-
-Revision ID: 38bf9e7e74b3
-Revises: 7396957cbe80
-Create Date: 2025-02-28 09:19:33.212278
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-from sqlalchemy.dialects import postgresql
-
-# revision identifiers, used by Alembic.
-revision: str = '38bf9e7e74b3'
-down_revision: Union[str, None] = '7396957cbe80'
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-
-    op.create_table('users',
-    sa.Column('email', sa.String(), nullable=False),
-    sa.Column('password_hash', sa.String(), nullable=False),
-    sa.Column('first_name', sa.String(), nullable=False),
-    sa.Column('last_name', sa.String(), nullable=True),
-    sa.Column('phone_number', sa.String(), nullable=True),
-    sa.Column('is_active', sa.Boolean(), nullable=False),
-    sa.Column('is_superuser', sa.Boolean(), nullable=False),
-    sa.Column('preferences', sa.JSON(), nullable=True),
-    sa.Column('id', sa.UUID(), nullable=False),
-    sa.Column('created_at', sa.DateTime(timezone=True), nullable=False),
-    sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False),
-    sa.PrimaryKeyConstraint('id')
-    )
-    op.create_index(op.f('ix_users_email'), 'users', ['email'], unique=True)
-
-    # ### end Alembic commands ###
-
-
-def downgrade() -> None:
-    # ### commands auto generated by Alembic - please adjust! ###
-    op.drop_index(op.f('ix_users_email'), table_name='users')
-    op.drop_table('users')
-    # ### end Alembic commands ###

backend/app/alembic/versions/7396957cbe80_initial_empty_migration.py

@@ -1,26 +0,0 @@
-"""Initial empty migration
-
-Revision ID: 7396957cbe80
-Revises: 
-Create Date: 2025-02-27 12:47:46.445313
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = '7396957cbe80'
-down_revision: Union[str, None] = None
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    pass
-
-
-def downgrade() -> None:
-    pass

backend/app/api/dependencies/auth.py

@@ -1,20 +1,19 @@
-from typing import Optional
+from fastapi import Depends, Header, HTTPException, status
-
-from fastapi import Depends, HTTPException, status
 from fastapi.security import OAuth2PasswordBearer
-from sqlalchemy.orm import Session
+from fastapi.security.utils import get_authorization_scheme_param
+from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.core.auth import get_token_data, TokenExpiredError, TokenInvalidError
+from app.core.auth import TokenExpiredError, TokenInvalidError, get_token_data
 from app.core.database import get_db
 from app.models.user import User
+from app.repositories.user import user_repo
 
 # OAuth2 configuration
 oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
 
 
-def get_current_user(
+async def get_current_user(
-        db: Session = Depends(get_db),
+    db: AsyncSession = Depends(get_db), token: str = Depends(oauth2_scheme)
-        token: str = Depends(oauth2_scheme)
 ) -> User:
     """
     Get the current authenticated user.
@@ -33,18 +32,17 @@ def get_current_user(
         # Decode token and get user ID
         token_data = get_token_data(token)
 
-        # Get user from database
+        # Get user from database via repository
-        user = db.query(User).filter(User.id == token_data.user_id).first()
+        user = await user_repo.get(db, id=str(token_data.user_id))
+
         if not user:
             raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND,
+                status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
-                detail="User not found"
             )
 
         if not user.is_active:
             raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN,
+                status_code=status.HTTP_403_FORBIDDEN, detail="Inactive user"
-                detail="Inactive user"
             )
 
         return user
@@ -53,19 +51,17 @@ def get_current_user(
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Token expired",
-            headers={"WWW-Authenticate": "Bearer"}
+            headers={"WWW-Authenticate": "Bearer"},
         )
     except TokenInvalidError:
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail="Could not validate credentials",
-            headers={"WWW-Authenticate": "Bearer"}
+            headers={"WWW-Authenticate": "Bearer"},
         )
 
 
-def get_current_active_user(
+def get_current_active_user(current_user: User = Depends(get_current_user)) -> User:
-        current_user: User = Depends(get_current_user)
-) -> User:
     """
     Check if the current user is active.
 
@@ -80,15 +76,12 @@ def get_current_active_user(
     """
     if not current_user.is_active:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
+            status_code=status.HTTP_403_FORBIDDEN, detail="Inactive user"
-            detail="Inactive user"
         )
     return current_user
 
 
-def get_current_superuser(
+def get_current_superuser(current_user: User = Depends(get_current_user)) -> User:
-        current_user: User = Depends(get_current_user)
-) -> User:
     """
     Check if the current user is a superuser.
 
@@ -103,16 +96,37 @@ def get_current_superuser(
     """
     if not current_user.is_superuser:
         raise HTTPException(
-            status_code=status.HTTP_403_FORBIDDEN,
+            status_code=status.HTTP_403_FORBIDDEN, detail="Not enough permissions"
-            detail="Not enough permissions"
         )
     return current_user
 
 
-def get_optional_current_user(
+async def get_optional_token(authorization: str = Header(None)) -> str | None:
-        db: Session = Depends(get_db),
+    """
-        token: Optional[str] = Depends(oauth2_scheme)
+    Get the token from the Authorization header without requiring it.
-) -> Optional[User]:
+
+    This is a custom dependency that doesn't raise an exception when no token is provided,
+    unlike the standard OAuth2PasswordBearer.
+
+    Args:
+        authorization: Authorization header value
+
+    Returns:
+        The token string if valid Bearer token is provided, None otherwise
+    """
+    if not authorization:
+        return None
+
+    scheme, token = get_authorization_scheme_param(authorization)
+    if scheme.lower() != "bearer":
+        return None
+
+    return token
+
+
+async def get_optional_current_user(
+    db: AsyncSession = Depends(get_db), token: str | None = Depends(get_optional_token)
+) -> User | None:
     """
     Get the current user if authenticated, otherwise return None.
     Useful for endpoints that work with both authenticated and unauthenticated users.
@@ -129,9 +143,9 @@ def get_optional_current_user(
 
     try:
         token_data = get_token_data(token)
-        user = db.query(User).filter(User.id == token_data.user_id).first()
+        user = await user_repo.get(db, id=str(token_data.user_id))
         if not user or not user.is_active:
             return None
         return user
     except (TokenExpiredError, TokenInvalidError):
-        return None
+        return None

backend/app/api/dependencies/locale.py

@@ -0,0 +1,132 @@
+# app/api/dependencies/locale.py
+"""
+Locale detection dependency for internationalization (i18n).
+
+Implements a three-tier fallback system:
+1. User's saved preference (if authenticated and user.locale is set)
+2. Accept-Language header (for unauthenticated users or no saved preference)
+3. Default to English ("en")
+"""
+
+from fastapi import Depends, Request
+
+from app.api.dependencies.auth import get_optional_current_user
+from app.models.user import User
+
+# Supported locales (BCP 47 format)
+# Template showcases English and Italian
+# Users can extend by adding more locales here
+# Note: Stored in lowercase for case-insensitive matching
+SUPPORTED_LOCALES = {"en", "it", "en-us", "en-gb", "it-it"}
+DEFAULT_LOCALE = "en"
+
+
+def parse_accept_language(accept_language: str) -> str | None:
+    """
+    Parse the Accept-Language header and return the best matching supported locale.
+
+    The Accept-Language header format is:
+    "it-IT,it;q=0.9,en-US;q=0.8,en;q=0.7"
+
+    This function extracts locales in priority order (by quality value) and returns
+    the first one that matches our supported locales.
+
+    Args:
+        accept_language: The Accept-Language header value
+
+    Returns:
+        The best matching locale code, or None if no match found
+
+    Examples:
+        >>> parse_accept_language("it-IT,it;q=0.9,en;q=0.8")
+        "it-IT"  # or "it" if it-IT is not supported
+        >>> parse_accept_language("fr-FR,fr;q=0.9")
+        None  # French not supported
+    """
+    if not accept_language:
+        return None
+
+    # Split by comma to get individual locale entries
+    # Format: "locale;q=weight" or just "locale"
+    locales = []
+    for entry in accept_language.split(","):
+        # Remove quality value (;q=0.9) if present
+        locale = entry.split(";")[0].strip()
+        if locale:
+            locales.append(locale)
+
+    # Check each locale in priority order
+    for locale in locales:
+        locale_lower = locale.lower()
+
+        # Try exact match first (e.g., "it-IT")
+        if locale_lower in SUPPORTED_LOCALES:
+            return locale_lower
+
+        # Try language code only (e.g., "it" from "it-IT")
+        lang_code = locale_lower.split("-")[0]
+        if lang_code in SUPPORTED_LOCALES:
+            return lang_code
+
+    return None
+
+
+async def get_locale(
+    request: Request,
+    current_user: User | None = Depends(get_optional_current_user),
+) -> str:
+    """
+    Detect and return the appropriate locale for the current request.
+
+    Three-tier fallback system:
+    1. **User Preference** (highest priority)
+       - If user is authenticated and has a saved locale preference, use it
+       - This persists across sessions and devices
+
+    2. **Accept-Language Header** (second priority)
+       - Parse the Accept-Language header from the request
+       - Match against supported locales
+       - Common for browser requests
+
+    3. **Default Locale** (fallback)
+       - Return "en" (English) if no user preference and no header match
+
+    Args:
+        request: The FastAPI request object (for accessing headers)
+        current_user: The current authenticated user (optional)
+
+    Returns:
+        A valid locale code from SUPPORTED_LOCALES (guaranteed to be supported)
+
+    Examples:
+        >>> # Authenticated user with saved preference
+        >>> await get_locale(request, user_with_locale_it)
+        "it"
+
+        >>> # Unauthenticated user with Italian browser
+        >>> # (request has Accept-Language: it-IT,it;q=0.9)
+        >>> await get_locale(request, None)
+        "it"
+
+        >>> # Unauthenticated user with unsupported language
+        >>> # (request has Accept-Language: fr-FR,fr;q=0.9)
+        >>> await get_locale(request, None)
+        "en"
+    """
+    # Priority 1: User's saved preference
+    if current_user and current_user.locale:
+        # Validate that saved locale is still supported
+        # (in case SUPPORTED_LOCALES changed after user set preference)
+        locale_value = str(current_user.locale)
+        if locale_value in SUPPORTED_LOCALES:
+            return locale_value
+
+    # Priority 2: Accept-Language header
+    accept_language = request.headers.get("accept-language", "")
+    if accept_language:
+        detected_locale = parse_accept_language(accept_language)
+        if detected_locale:
+            return detected_locale
+
+    # Priority 3: Default fallback
+    return DEFAULT_LOCALE

backend/app/api/dependencies/permissions.py

@@ -0,0 +1,136 @@
+# app/api/dependencies/permissions.py
+"""
+Permission checking dependencies for admin and organization-based access control.
+
+These dependencies are optional and flexible:
+- Use require_superuser for global admin access
+- Use require_org_role for organization-specific access control
+- Projects can choose to use these or implement their own permission system
+"""
+
+from uuid import UUID
+
+from fastapi import Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.auth import get_current_user
+from app.core.database import get_db
+from app.models.user import User
+from app.models.user_organization import OrganizationRole
+from app.services.organization_service import organization_service
+
+
+def require_superuser(current_user: User = Depends(get_current_user)) -> User:
+    """
+    Dependency to ensure the current user is a superuser.
+
+    Use this for admin-only endpoints that require global access.
+
+    Example:
+        @router.get("/admin/users")
+        def list_users(admin: User = Depends(require_superuser)):
+            ...
+    """
+    if not current_user.is_superuser:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Superuser privileges required",
+        )
+    return current_user
+
+
+class OrganizationPermission:
+    """
+    Factory for organization-based permission checking.
+
+    This allows flexible role-based access control within organizations.
+    Projects can extend this or implement custom permission logic.
+    """
+
+    def __init__(self, allowed_roles: list[OrganizationRole]):
+        """
+        Initialize with list of allowed roles.
+
+        Args:
+            allowed_roles: List of roles that can access the endpoint
+        """
+        self.allowed_roles = allowed_roles
+
+    async def __call__(
+        self,
+        organization_id: UUID,
+        current_user: User = Depends(get_current_user),
+        db: AsyncSession = Depends(get_db),
+    ) -> User:
+        """
+        Check if user has required role in the organization.
+
+        Args:
+            organization_id: The organization to check access for
+            current_user: The authenticated user
+            db: Database session
+
+        Returns:
+            The current user if they have permission
+
+        Raises:
+            HTTPException: If user lacks permission
+        """
+        # Superusers bypass organization checks
+        if current_user.is_superuser:
+            return current_user
+
+        # Get user's role in organization
+        user_role = await organization_service.get_user_role_in_org(
+            db, user_id=current_user.id, organization_id=organization_id
+        )
+
+        if not user_role:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail="Not a member of this organization",
+            )
+
+        if user_role not in self.allowed_roles:
+            raise HTTPException(
+                status_code=status.HTTP_403_FORBIDDEN,
+                detail=f"Role {user_role} not authorized. Required: {self.allowed_roles}",
+            )
+
+        return current_user
+
+
+# Common permission presets for convenience
+require_org_owner = OrganizationPermission([OrganizationRole.OWNER])
+require_org_admin = OrganizationPermission(
+    [OrganizationRole.OWNER, OrganizationRole.ADMIN]
+)
+require_org_member = OrganizationPermission(
+    [OrganizationRole.OWNER, OrganizationRole.ADMIN, OrganizationRole.MEMBER]
+)
+
+
+async def require_org_membership(
+    organization_id: UUID,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> User:
+    """
+    Ensure user is a member of the organization (any role).
+
+    Use this for endpoints that any organization member can access.
+    """
+    if current_user.is_superuser:
+        return current_user
+
+    user_role = await organization_service.get_user_role_in_org(
+        db, user_id=current_user.id, organization_id=organization_id
+    )
+
+    if not user_role:
+        raise HTTPException(
+            status_code=status.HTTP_403_FORBIDDEN,
+            detail="Not a member of this organization",
+        )
+
+    return current_user

backend/app/api/dependencies/services.py

@@ -0,0 +1,41 @@
+# app/api/dependencies/services.py
+"""FastAPI dependency functions for service singletons."""
+
+from app.services import oauth_provider_service
+from app.services.auth_service import AuthService
+from app.services.oauth_service import OAuthService
+from app.services.organization_service import OrganizationService, organization_service
+from app.services.session_service import SessionService, session_service
+from app.services.user_service import UserService, user_service
+
+
+def get_auth_service() -> AuthService:
+    """Return the AuthService singleton for dependency injection."""
+    from app.services.auth_service import AuthService as _AuthService
+
+    return _AuthService()
+
+
+def get_user_service() -> UserService:
+    """Return the UserService singleton for dependency injection."""
+    return user_service
+
+
+def get_organization_service() -> OrganizationService:
+    """Return the OrganizationService singleton for dependency injection."""
+    return organization_service
+
+
+def get_session_service() -> SessionService:
+    """Return the SessionService singleton for dependency injection."""
+    return session_service
+
+
+def get_oauth_service() -> OAuthService:
+    """Return OAuthService for dependency injection."""
+    return OAuthService()
+
+
+def get_oauth_provider_service():
+    """Return the oauth_provider_service module for dependency injection."""
+    return oauth_provider_service

backend/app/api/main.py

@@ -1,6 +1,24 @@
 from fastapi import APIRouter
 
-from app.api.routes import auth
+from app.api.routes import (
+    admin,
+    auth,
+    oauth,
+    oauth_provider,
+    organizations,
+    sessions,
+    users,
+)
 
 api_router = APIRouter()
-api_router.include_router(auth.router, prefix="/auth", tags=["auth"])
+api_router.include_router(auth.router, prefix="/auth", tags=["Authentication"])
+api_router.include_router(oauth.router, prefix="/oauth", tags=["OAuth"])
+api_router.include_router(
+    oauth_provider.router, prefix="/oauth", tags=["OAuth Provider"]
+)
+api_router.include_router(users.router, prefix="/users", tags=["Users"])
+api_router.include_router(sessions.router, prefix="/sessions", tags=["Sessions"])
+api_router.include_router(admin.router, prefix="/admin", tags=["Admin"])
+api_router.include_router(
+    organizations.router, prefix="/organizations", tags=["Organizations"]
+)

backend/app/api/routes/admin.py

@@ -0,0 +1,976 @@
+# app/api/routes/admin.py
+"""
+Admin-specific endpoints for managing users and organizations.
+
+These endpoints require superuser privileges and provide CMS-like functionality
+for managing the application.
+"""
+
+import logging
+from datetime import UTC, datetime, timedelta
+from enum import Enum
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, status
+from pydantic import BaseModel, Field
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.permissions import require_superuser
+from app.core.database import get_db
+from app.core.exceptions import (
+    AuthorizationError,
+    DuplicateError,
+    ErrorCode,
+    NotFoundError,
+)
+from app.core.repository_exceptions import DuplicateEntryError
+from app.models.user import User
+from app.models.user_organization import OrganizationRole
+from app.schemas.common import (
+    MessageResponse,
+    PaginatedResponse,
+    PaginationParams,
+    SortParams,
+    create_pagination_meta,
+)
+from app.schemas.organizations import (
+    OrganizationCreate,
+    OrganizationMemberResponse,
+    OrganizationResponse,
+    OrganizationUpdate,
+)
+from app.schemas.sessions import AdminSessionResponse
+from app.schemas.users import UserCreate, UserResponse, UserUpdate
+from app.services.organization_service import organization_service
+from app.services.session_service import session_service
+from app.services.user_service import user_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+# Schemas for bulk operations
+class BulkAction(str, Enum):
+    """Supported bulk actions."""
+
+    ACTIVATE = "activate"
+    DEACTIVATE = "deactivate"
+    DELETE = "delete"
+
+
+class BulkUserAction(BaseModel):
+    """Schema for bulk user actions."""
+
+    action: BulkAction = Field(..., description="Action to perform on selected users")
+    user_ids: list[UUID] = Field(
+        ..., min_length=1, max_length=100, description="List of user IDs (max 100)"
+    )
+
+
+class BulkActionResult(BaseModel):
+    """Result of a bulk action."""
+
+    success: bool
+    affected_count: int
+    failed_count: int
+    message: str
+    failed_ids: list[UUID] | None = []
+
+
+# ===== User Management Endpoints =====
+
+
+class UserGrowthData(BaseModel):
+    date: str
+    total_users: int
+    active_users: int
+
+
+class OrgDistributionData(BaseModel):
+    name: str
+    value: int
+
+
+class RegistrationActivityData(BaseModel):
+    date: str
+    registrations: int
+
+
+class UserStatusData(BaseModel):
+    name: str
+    value: int
+
+
+class AdminStatsResponse(BaseModel):
+    user_growth: list[UserGrowthData]
+    organization_distribution: list[OrgDistributionData]
+    registration_activity: list[RegistrationActivityData]
+    user_status: list[UserStatusData]
+
+
+def _generate_demo_stats() -> AdminStatsResponse:  # pragma: no cover
+    """Generate demo statistics for empty databases."""
+    from random import randint
+
+    # Demo user growth (last 30 days)
+    user_growth = []
+    total = 10
+    for i in range(29, -1, -1):
+        date = datetime.now(UTC) - timedelta(days=i)
+        total += randint(0, 3)  # noqa: S311
+        user_growth.append(
+            UserGrowthData(
+                date=date.strftime("%b %d"),
+                total_users=total,
+                active_users=int(total * 0.85),
+            )
+        )
+
+    # Demo organization distribution
+    org_dist = [
+        OrgDistributionData(name="Engineering", value=12),
+        OrgDistributionData(name="Product", value=8),
+        OrgDistributionData(name="Sales", value=15),
+        OrgDistributionData(name="Marketing", value=6),
+        OrgDistributionData(name="Support", value=5),
+        OrgDistributionData(name="Operations", value=4),
+    ]
+
+    # Demo registration activity (last 14 days)
+    registration_activity = []
+    for i in range(13, -1, -1):
+        date = datetime.now(UTC) - timedelta(days=i)
+        registration_activity.append(
+            RegistrationActivityData(
+                date=date.strftime("%b %d"),
+                registrations=randint(0, 5),  # noqa: S311
+            )
+        )
+
+    # Demo user status
+    user_status = [
+        UserStatusData(name="Active", value=45),
+        UserStatusData(name="Inactive", value=5),
+    ]
+
+    return AdminStatsResponse(
+        user_growth=user_growth,
+        organization_distribution=org_dist,
+        registration_activity=registration_activity,
+        user_status=user_status,
+    )
+
+
+@router.get(
+    "/stats",
+    response_model=AdminStatsResponse,
+    summary="Admin: Get Dashboard Stats",
+    description="Get aggregated statistics for the admin dashboard (admin only)",
+    operation_id="admin_get_stats",
+)
+async def admin_get_stats(
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Get admin dashboard statistics with real data from database."""
+    from app.core.config import settings
+
+    stats = await user_service.get_stats(db)
+    total_users = stats["total_users"]
+    active_count = stats["active_count"]
+    inactive_count = stats["inactive_count"]
+    all_users = stats["all_users"]
+
+    # If database is essentially empty (only admin user), return demo data
+    if total_users <= 1 and settings.DEMO_MODE:  # pragma: no cover
+        logger.info("Returning demo stats data (empty database in demo mode)")
+        return _generate_demo_stats()
+
+    # 1. User Growth (Last 30 days)
+    user_growth = []
+    for i in range(29, -1, -1):
+        date = datetime.now(UTC) - timedelta(days=i)
+        date_start = date.replace(hour=0, minute=0, second=0, microsecond=0, tzinfo=UTC)
+        date_end = date_start + timedelta(days=1)
+
+        total_users_on_date = sum(
+            1
+            for u in all_users
+            if u.created_at and u.created_at.replace(tzinfo=UTC) < date_end
+        )
+        active_users_on_date = sum(
+            1
+            for u in all_users
+            if u.created_at
+            and u.created_at.replace(tzinfo=UTC) < date_end
+            and u.is_active
+        )
+
+        user_growth.append(
+            UserGrowthData(
+                date=date.strftime("%b %d"),
+                total_users=total_users_on_date,
+                active_users=active_users_on_date,
+            )
+        )
+
+    # 2. Organization Distribution - Top 6 organizations by member count
+    org_rows = await organization_service.get_org_distribution(db, limit=6)
+    org_dist = [OrgDistributionData(name=r["name"], value=r["value"]) for r in org_rows]
+
+    # 3. User Registration Activity (Last 14 days)
+    registration_activity = []
+    for i in range(13, -1, -1):
+        date = datetime.now(UTC) - timedelta(days=i)
+        date_start = date.replace(hour=0, minute=0, second=0, microsecond=0, tzinfo=UTC)
+        date_end = date_start + timedelta(days=1)
+
+        day_registrations = sum(
+            1
+            for u in all_users
+            if u.created_at
+            and date_start <= u.created_at.replace(tzinfo=UTC) < date_end
+        )
+
+        registration_activity.append(
+            RegistrationActivityData(
+                date=date.strftime("%b %d"),
+                registrations=day_registrations,
+            )
+        )
+
+    # 4. User Status - Active vs Inactive
+    logger.info(
+        "User status counts - Active: %s, Inactive: %s", active_count, inactive_count
+    )
+
+    user_status = [
+        UserStatusData(name="Active", value=active_count),
+        UserStatusData(name="Inactive", value=inactive_count),
+    ]
+
+    return AdminStatsResponse(
+        user_growth=user_growth,
+        organization_distribution=org_dist,
+        registration_activity=registration_activity,
+        user_status=user_status,
+    )
+
+
+# ===== User Management Endpoints =====
+
+
+@router.get(
+    "/users",
+    response_model=PaginatedResponse[UserResponse],
+    summary="Admin: List All Users",
+    description="Get paginated list of all users with filtering and search (admin only)",
+    operation_id="admin_list_users",
+)
+async def admin_list_users(
+    pagination: PaginationParams = Depends(),
+    sort: SortParams = Depends(),
+    is_active: bool | None = Query(None, description="Filter by active status"),
+    is_superuser: bool | None = Query(None, description="Filter by superuser status"),
+    search: str | None = Query(None, description="Search by email, name"),
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    List all users with comprehensive filtering and search.
+
+    Requires superuser privileges.
+    """
+    try:
+        # Build filters
+        filters = {}
+        if is_active is not None:
+            filters["is_active"] = is_active
+        if is_superuser is not None:
+            filters["is_superuser"] = is_superuser
+
+        # Get users with search
+        users, total = await user_service.list_users(
+            db,
+            skip=pagination.offset,
+            limit=pagination.limit,
+            sort_by=sort.sort_by or "created_at",
+            sort_order=sort.sort_order.value if sort.sort_order else "desc",
+            filters=filters if filters else None,
+            search=search,
+        )
+
+        pagination_meta = create_pagination_meta(
+            total=total,
+            page=pagination.page,
+            limit=pagination.limit,
+            items_count=len(users),
+        )
+
+        return PaginatedResponse(data=users, pagination=pagination_meta)
+
+    except Exception as e:
+        logger.exception("Error listing users (admin): %s", e)
+        raise
+
+
+@router.post(
+    "/users",
+    response_model=UserResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Admin: Create User",
+    description="Create a new user (admin only)",
+    operation_id="admin_create_user",
+)
+async def admin_create_user(
+    user_in: UserCreate,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Create a new user with admin privileges.
+
+    Allows setting is_superuser and other fields.
+    """
+    try:
+        user = await user_service.create_user(db, user_in)
+        logger.info("Admin %s created user %s", admin.email, user.email)
+        return user
+    except DuplicateEntryError as e:
+        logger.warning("Failed to create user: %s", e)
+        raise DuplicateError(message=str(e), error_code=ErrorCode.USER_ALREADY_EXISTS)
+    except Exception as e:
+        logger.exception("Error creating user (admin): %s", e)
+        raise
+
+
+@router.get(
+    "/users/{user_id}",
+    response_model=UserResponse,
+    summary="Admin: Get User Details",
+    description="Get detailed user information (admin only)",
+    operation_id="admin_get_user",
+)
+async def admin_get_user(
+    user_id: UUID,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Get detailed information about a specific user."""
+    user = await user_service.get_user(db, str(user_id))
+    return user
+
+
+@router.put(
+    "/users/{user_id}",
+    response_model=UserResponse,
+    summary="Admin: Update User",
+    description="Update user information (admin only)",
+    operation_id="admin_update_user",
+)
+async def admin_update_user(
+    user_id: UUID,
+    user_in: UserUpdate,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Update user information with admin privileges."""
+    try:
+        user = await user_service.get_user(db, str(user_id))
+        updated_user = await user_service.update_user(db, user=user, obj_in=user_in)
+        logger.info("Admin %s updated user %s", admin.email, updated_user.email)
+        return updated_user
+
+    except Exception as e:
+        logger.exception("Error updating user (admin): %s", e)
+        raise
+
+
+@router.delete(
+    "/users/{user_id}",
+    response_model=MessageResponse,
+    summary="Admin: Delete User",
+    description="Soft delete a user (admin only)",
+    operation_id="admin_delete_user",
+)
+async def admin_delete_user(
+    user_id: UUID,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Soft delete a user (sets deleted_at timestamp)."""
+    try:
+        user = await user_service.get_user(db, str(user_id))
+
+        # Prevent deleting yourself
+        if user.id == admin.id:
+            # Use AuthorizationError for permission/operation restrictions
+            raise AuthorizationError(
+                message="Cannot delete your own account",
+                error_code=ErrorCode.OPERATION_FORBIDDEN,
+            )
+
+        await user_service.soft_delete_user(db, str(user_id))
+        logger.info("Admin %s deleted user %s", admin.email, user.email)
+
+        return MessageResponse(
+            success=True, message=f"User {user.email} has been deleted"
+        )
+
+    except Exception as e:
+        logger.exception("Error deleting user (admin): %s", e)
+        raise
+
+
+@router.post(
+    "/users/{user_id}/activate",
+    response_model=MessageResponse,
+    summary="Admin: Activate User",
+    description="Activate a user account (admin only)",
+    operation_id="admin_activate_user",
+)
+async def admin_activate_user(
+    user_id: UUID,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Activate a user account."""
+    try:
+        user = await user_service.get_user(db, str(user_id))
+        await user_service.update_user(db, user=user, obj_in={"is_active": True})
+        logger.info("Admin %s activated user %s", admin.email, user.email)
+
+        return MessageResponse(
+            success=True, message=f"User {user.email} has been activated"
+        )
+
+    except Exception as e:
+        logger.exception("Error activating user (admin): %s", e)
+        raise
+
+
+@router.post(
+    "/users/{user_id}/deactivate",
+    response_model=MessageResponse,
+    summary="Admin: Deactivate User",
+    description="Deactivate a user account (admin only)",
+    operation_id="admin_deactivate_user",
+)
+async def admin_deactivate_user(
+    user_id: UUID,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Deactivate a user account."""
+    try:
+        user = await user_service.get_user(db, str(user_id))
+
+        # Prevent deactivating yourself
+        if user.id == admin.id:
+            # Use AuthorizationError for permission/operation restrictions
+            raise AuthorizationError(
+                message="Cannot deactivate your own account",
+                error_code=ErrorCode.OPERATION_FORBIDDEN,
+            )
+
+        await user_service.update_user(db, user=user, obj_in={"is_active": False})
+        logger.info("Admin %s deactivated user %s", admin.email, user.email)
+
+        return MessageResponse(
+            success=True, message=f"User {user.email} has been deactivated"
+        )
+
+    except Exception as e:
+        logger.exception("Error deactivating user (admin): %s", e)
+        raise
+
+
+@router.post(
+    "/users/bulk-action",
+    response_model=BulkActionResult,
+    summary="Admin: Bulk User Action",
+    description="Perform bulk actions on multiple users (admin only)",
+    operation_id="admin_bulk_user_action",
+)
+async def admin_bulk_user_action(
+    bulk_action: BulkUserAction,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Perform bulk actions on multiple users using optimized bulk operations.
+
+    Uses single UPDATE query instead of N individual queries for efficiency.
+    Supported actions: activate, deactivate, delete
+    """
+    try:
+        # Use efficient bulk operations instead of loop
+        if bulk_action.action == BulkAction.ACTIVATE:
+            affected_count = await user_service.bulk_update_status(
+                db, user_ids=bulk_action.user_ids, is_active=True
+            )
+        elif bulk_action.action == BulkAction.DEACTIVATE:
+            affected_count = await user_service.bulk_update_status(
+                db, user_ids=bulk_action.user_ids, is_active=False
+            )
+        elif bulk_action.action == BulkAction.DELETE:
+            # bulk_soft_delete automatically excludes the admin user
+            affected_count = await user_service.bulk_soft_delete(
+                db, user_ids=bulk_action.user_ids, exclude_user_id=admin.id
+            )
+        else:  # pragma: no cover
+            raise ValueError(f"Unsupported bulk action: {bulk_action.action}")
+
+        # Calculate failed count (requested - affected)
+        requested_count = len(bulk_action.user_ids)
+        failed_count = requested_count - affected_count
+
+        logger.info(
+            "Admin %s performed bulk %s on %s users (%s skipped/failed)",
+            admin.email,
+            bulk_action.action.value,
+            affected_count,
+            failed_count,
+        )
+
+        return BulkActionResult(
+            success=failed_count == 0,
+            affected_count=affected_count,
+            failed_count=failed_count,
+            message=f"Bulk {bulk_action.action.value}: {affected_count} users affected, {failed_count} skipped",
+            failed_ids=None,  # Bulk operations don't track individual failures
+        )
+
+    except Exception as e:  # pragma: no cover
+        logger.exception("Error in bulk user action: %s", e)
+        raise
+
+
+# ===== Organization Management Endpoints =====
+
+
+@router.get(
+    "/organizations",
+    response_model=PaginatedResponse[OrganizationResponse],
+    summary="Admin: List Organizations",
+    description="Get paginated list of all organizations (admin only)",
+    operation_id="admin_list_organizations",
+)
+async def admin_list_organizations(
+    pagination: PaginationParams = Depends(),
+    is_active: bool | None = Query(None, description="Filter by active status"),
+    search: str | None = Query(None, description="Search by name, slug, description"),
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """List all organizations with filtering and search."""
+    try:
+        # Use optimized method that gets member counts in single query (no N+1)
+        orgs_with_data, total = await organization_service.get_multi_with_member_counts(
+            db,
+            skip=pagination.offset,
+            limit=pagination.limit,
+            is_active=is_active,
+            search=search,
+        )
+
+        # Build response objects from optimized query results
+        orgs_with_count = []
+        for item in orgs_with_data:
+            org = item["organization"]
+            member_count = item["member_count"]
+
+            org_dict = {
+                "id": org.id,
+                "name": org.name,
+                "slug": org.slug,
+                "description": org.description,
+                "is_active": org.is_active,
+                "settings": org.settings,
+                "created_at": org.created_at,
+                "updated_at": org.updated_at,
+                "member_count": member_count,
+            }
+            orgs_with_count.append(OrganizationResponse(**org_dict))
+
+        pagination_meta = create_pagination_meta(
+            total=total,
+            page=pagination.page,
+            limit=pagination.limit,
+            items_count=len(orgs_with_count),
+        )
+
+        return PaginatedResponse(data=orgs_with_count, pagination=pagination_meta)
+
+    except Exception as e:
+        logger.exception("Error listing organizations (admin): %s", e)
+        raise
+
+
+@router.post(
+    "/organizations",
+    response_model=OrganizationResponse,
+    status_code=status.HTTP_201_CREATED,
+    summary="Admin: Create Organization",
+    description="Create a new organization (admin only)",
+    operation_id="admin_create_organization",
+)
+async def admin_create_organization(
+    org_in: OrganizationCreate,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Create a new organization."""
+    try:
+        org = await organization_service.create_organization(db, obj_in=org_in)
+        logger.info("Admin %s created organization %s", admin.email, org.name)
+
+        # Add member count
+        org_dict = {
+            "id": org.id,
+            "name": org.name,
+            "slug": org.slug,
+            "description": org.description,
+            "is_active": org.is_active,
+            "settings": org.settings,
+            "created_at": org.created_at,
+            "updated_at": org.updated_at,
+            "member_count": 0,
+        }
+        return OrganizationResponse(**org_dict)
+
+    except DuplicateEntryError as e:
+        logger.warning("Failed to create organization: %s", e)
+        raise DuplicateError(message=str(e), error_code=ErrorCode.ALREADY_EXISTS)
+    except Exception as e:
+        logger.exception("Error creating organization (admin): %s", e)
+        raise
+
+
+@router.get(
+    "/organizations/{org_id}",
+    response_model=OrganizationResponse,
+    summary="Admin: Get Organization Details",
+    description="Get detailed organization information (admin only)",
+    operation_id="admin_get_organization",
+)
+async def admin_get_organization(
+    org_id: UUID,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Get detailed information about a specific organization."""
+    org = await organization_service.get_organization(db, str(org_id))
+    org_dict = {
+        "id": org.id,
+        "name": org.name,
+        "slug": org.slug,
+        "description": org.description,
+        "is_active": org.is_active,
+        "settings": org.settings,
+        "created_at": org.created_at,
+        "updated_at": org.updated_at,
+        "member_count": await organization_service.get_member_count(
+            db, organization_id=org.id
+        ),
+    }
+    return OrganizationResponse(**org_dict)
+
+
+@router.put(
+    "/organizations/{org_id}",
+    response_model=OrganizationResponse,
+    summary="Admin: Update Organization",
+    description="Update organization information (admin only)",
+    operation_id="admin_update_organization",
+)
+async def admin_update_organization(
+    org_id: UUID,
+    org_in: OrganizationUpdate,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Update organization information."""
+    try:
+        org = await organization_service.get_organization(db, str(org_id))
+        updated_org = await organization_service.update_organization(
+            db, org=org, obj_in=org_in
+        )
+        logger.info("Admin %s updated organization %s", admin.email, updated_org.name)
+
+        org_dict = {
+            "id": updated_org.id,
+            "name": updated_org.name,
+            "slug": updated_org.slug,
+            "description": updated_org.description,
+            "is_active": updated_org.is_active,
+            "settings": updated_org.settings,
+            "created_at": updated_org.created_at,
+            "updated_at": updated_org.updated_at,
+            "member_count": await organization_service.get_member_count(
+                db, organization_id=updated_org.id
+            ),
+        }
+        return OrganizationResponse(**org_dict)
+
+    except Exception as e:
+        logger.exception("Error updating organization (admin): %s", e)
+        raise
+
+
+@router.delete(
+    "/organizations/{org_id}",
+    response_model=MessageResponse,
+    summary="Admin: Delete Organization",
+    description="Delete an organization (admin only)",
+    operation_id="admin_delete_organization",
+)
+async def admin_delete_organization(
+    org_id: UUID,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Delete an organization and all its relationships."""
+    try:
+        org = await organization_service.get_organization(db, str(org_id))
+        await organization_service.remove_organization(db, str(org_id))
+        logger.info("Admin %s deleted organization %s", admin.email, org.name)
+
+        return MessageResponse(
+            success=True, message=f"Organization {org.name} has been deleted"
+        )
+
+    except Exception as e:
+        logger.exception("Error deleting organization (admin): %s", e)
+        raise
+
+
+@router.get(
+    "/organizations/{org_id}/members",
+    response_model=PaginatedResponse[OrganizationMemberResponse],
+    summary="Admin: List Organization Members",
+    description="Get all members of an organization (admin only)",
+    operation_id="admin_list_organization_members",
+)
+async def admin_list_organization_members(
+    org_id: UUID,
+    pagination: PaginationParams = Depends(),
+    is_active: bool | None = Query(True, description="Filter by active status"),
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """List all members of an organization."""
+    try:
+        await organization_service.get_organization(db, str(org_id))  # validates exists
+        members, total = await organization_service.get_organization_members(
+            db,
+            organization_id=org_id,
+            skip=pagination.offset,
+            limit=pagination.limit,
+            is_active=is_active,
+        )
+
+        # Convert to response models
+        member_responses = [OrganizationMemberResponse(**member) for member in members]
+
+        pagination_meta = create_pagination_meta(
+            total=total,
+            page=pagination.page,
+            limit=pagination.limit,
+            items_count=len(member_responses),
+        )
+
+        return PaginatedResponse(data=member_responses, pagination=pagination_meta)
+
+    except NotFoundError:
+        raise
+    except Exception as e:
+        logger.exception("Error listing organization members (admin): %s", e)
+        raise
+
+
+class AddMemberRequest(BaseModel):
+    """Request to add a member to an organization."""
+
+    user_id: UUID = Field(..., description="User ID to add")
+    role: OrganizationRole = Field(
+        OrganizationRole.MEMBER, description="Role in organization"
+    )
+
+
+@router.post(
+    "/organizations/{org_id}/members",
+    response_model=MessageResponse,
+    summary="Admin: Add Member to Organization",
+    description="Add a user to an organization (admin only)",
+    operation_id="admin_add_organization_member",
+)
+async def admin_add_organization_member(
+    org_id: UUID,
+    request: AddMemberRequest,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Add a user to an organization."""
+    try:
+        org = await organization_service.get_organization(db, str(org_id))
+        user = await user_service.get_user(db, str(request.user_id))
+
+        await organization_service.add_member(
+            db, organization_id=org_id, user_id=request.user_id, role=request.role
+        )
+
+        logger.info(
+            "Admin %s added user %s to organization %s with role %s",
+            admin.email,
+            user.email,
+            org.name,
+            request.role.value,
+        )
+
+        return MessageResponse(
+            success=True, message=f"User {user.email} added to organization {org.name}"
+        )
+
+    except DuplicateEntryError as e:
+        logger.warning("Failed to add user to organization: %s", e)
+        raise DuplicateError(
+            message=str(e), error_code=ErrorCode.USER_ALREADY_EXISTS, field="user_id"
+        )
+    except Exception as e:
+        logger.exception("Error adding member to organization (admin): %s", e)
+        raise
+
+
+@router.delete(
+    "/organizations/{org_id}/members/{user_id}",
+    response_model=MessageResponse,
+    summary="Admin: Remove Member from Organization",
+    description="Remove a user from an organization (admin only)",
+    operation_id="admin_remove_organization_member",
+)
+async def admin_remove_organization_member(
+    org_id: UUID,
+    user_id: UUID,
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """Remove a user from an organization."""
+    try:
+        org = await organization_service.get_organization(db, str(org_id))
+        user = await user_service.get_user(db, str(user_id))
+
+        success = await organization_service.remove_member(
+            db, organization_id=org_id, user_id=user_id
+        )
+
+        if not success:
+            raise NotFoundError(
+                message="User is not a member of this organization",
+                error_code=ErrorCode.NOT_FOUND,
+            )
+
+        logger.info(
+            "Admin %s removed user %s from organization %s",
+            admin.email,
+            user.email,
+            org.name,
+        )
+
+        return MessageResponse(
+            success=True,
+            message=f"User {user.email} removed from organization {org.name}",
+        )
+
+    except NotFoundError:
+        raise
+    except Exception as e:  # pragma: no cover
+        logger.exception("Error removing member from organization (admin): %s", e)
+        raise
+
+
+# ============================================================================
+# Session Management Endpoints
+# ============================================================================
+
+
+@router.get(
+    "/sessions",
+    response_model=PaginatedResponse[AdminSessionResponse],
+    summary="Admin: List All Sessions",
+    description="""
+    List all sessions across all users (admin only).
+
+    Returns paginated list of sessions with user information.
+    Useful for admin dashboard statistics and session monitoring.
+    """,
+    operation_id="admin_list_sessions",
+)
+async def admin_list_sessions(
+    pagination: PaginationParams = Depends(),
+    is_active: bool | None = Query(None, description="Filter by active status"),
+    admin: User = Depends(require_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """List all sessions across all users with filtering and pagination."""
+    try:
+        # Get sessions with user info (eager loaded to prevent N+1)
+        sessions, total = await session_service.get_all_sessions(
+            db,
+            skip=pagination.offset,
+            limit=pagination.limit,
+            active_only=is_active if is_active is not None else True,
+            with_user=True,
+        )
+
+        # Build response objects with user information
+        session_responses = []
+        for session in sessions:
+            # Get user full name
+            user_full_name = None
+            if session.user.first_name or session.user.last_name:
+                parts = []
+                if session.user.first_name:
+                    parts.append(session.user.first_name)
+                if session.user.last_name:
+                    parts.append(session.user.last_name)
+                user_full_name = " ".join(parts)
+
+            session_response = AdminSessionResponse(
+                id=session.id,
+                user_id=session.user_id,
+                user_email=session.user.email,
+                user_full_name=user_full_name,
+                device_name=session.device_name,
+                device_id=session.device_id,
+                ip_address=session.ip_address,
+                location_city=session.location_city,
+                location_country=session.location_country,
+                last_used_at=session.last_used_at,
+                created_at=session.created_at,
+                expires_at=session.expires_at,
+                is_active=session.is_active,
+            )
+            session_responses.append(session_response)
+
+        logger.info(
+            "Admin %s listed %s sessions (total: %s)",
+            admin.email,
+            len(session_responses),
+            total,
+        )
+
+        pagination_meta = create_pagination_meta(
+            total=total,
+            page=pagination.page,
+            limit=pagination.limit,
+            items_count=len(session_responses),
+        )
+
+        return PaginatedResponse(data=session_responses, pagination=pagination_meta)
+
+    except Exception as e:  # pragma: no cover
+        logger.exception("Error listing sessions (admin): %s", e)
+        raise

backend/app/api/routes/auth.py

@@ -1,32 +1,119 @@
 # app/api/routes/auth.py
 import logging
+import os
+from datetime import UTC, datetime
 from typing import Any
 
-from fastapi import APIRouter, Depends, HTTPException, status, Body
+from fastapi import APIRouter, Depends, HTTPException, Request, status
 from fastapi.security import OAuth2PasswordRequestForm
-from sqlalchemy.orm import Session
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.dependencies.auth import get_current_user
-from app.core.auth import TokenExpiredError, TokenInvalidError
+from app.core.auth import (
+    TokenExpiredError,
+    TokenInvalidError,
+    decode_token,
+)
 from app.core.database import get_db
+from app.core.exceptions import (
+    AuthenticationError as AuthError,
+    DatabaseError,
+    DuplicateError,
+    ErrorCode,
+)
 from app.models.user import User
+from app.schemas.common import MessageResponse
+from app.schemas.sessions import LogoutRequest, SessionCreate
 from app.schemas.users import (
+    LoginRequest,
+    PasswordResetConfirm,
+    PasswordResetRequest,
+    RefreshTokenRequest,
+    Token,
     UserCreate,
     UserResponse,
-    Token,
-    LoginRequest,
-    RefreshTokenRequest
 )
-from app.services.auth_service import AuthService, AuthenticationError
+from app.services.auth_service import AuthenticationError, AuthService
+from app.services.email_service import email_service
+from app.services.session_service import session_service
+from app.services.user_service import user_service
+from app.utils.device import extract_device_info
+from app.utils.security import create_password_reset_token, verify_password_reset_token
 
 router = APIRouter()
 logger = logging.getLogger(__name__)
 
+# Initialize limiter for this router
+limiter = Limiter(key_func=get_remote_address)
 
-@router.post("/register", response_model=UserResponse, status_code=status.HTTP_201_CREATED, operation_id="register")
+# Use higher rate limits in test environment
+IS_TEST = os.getenv("IS_TEST", "False") == "True"
+RATE_MULTIPLIER = 100 if IS_TEST else 1
+
+
+async def _create_login_session(
+    db: AsyncSession,
+    request: Request,
+    user: User,
+    tokens: Token,
+    login_type: str = "login",
+) -> None:
+    """
+    Create a session record for successful login.
+
+    This is a best-effort operation - login succeeds even if session creation fails.
+
+    Args:
+        db: Database session
+        request: FastAPI request object for device info extraction
+        user: Authenticated user
+        tokens: Token object containing refresh token with JTI
+        login_type: Type of login for logging ("login" or "oauth")
+    """
+    try:
+        device_info = extract_device_info(request)
+
+        # Decode refresh token to get JTI and expiration
+        refresh_payload = decode_token(tokens.refresh_token, verify_type="refresh")
+
+        session_data = SessionCreate(
+            user_id=user.id,
+            refresh_token_jti=refresh_payload.jti,
+            device_name=device_info.device_name or "API Client",
+            device_id=device_info.device_id,
+            ip_address=device_info.ip_address,
+            user_agent=device_info.user_agent,
+            last_used_at=datetime.now(UTC),
+            expires_at=datetime.fromtimestamp(refresh_payload.exp, tz=UTC),
+            location_city=device_info.location_city,
+            location_country=device_info.location_country,
+        )
+
+        await session_service.create_session(db, obj_in=session_data)
+
+        logger.info(
+            "%s successful: %s from %s (IP: %s)",
+            login_type.capitalize(),
+            user.email,
+            device_info.device_name,
+            device_info.ip_address,
+        )
+    except Exception as session_err:
+        # Log but don't fail login if session creation fails
+        logger.exception("Failed to create session for %s: %s", user.email, session_err)
+
+
+@router.post(
+    "/register",
+    response_model=UserResponse,
+    status_code=status.HTTP_201_CREATED,
+    operation_id="register",
+)
+@limiter.limit(f"{5 * RATE_MULTIPLIER}/minute")
 async def register_user(
-        user_data: UserCreate,
+    request: Request, user_data: UserCreate, db: AsyncSession = Depends(get_db)
-        db: Session = Depends(get_db)
 ) -> Any:
     """
     Register a new user.
@@ -35,132 +122,177 @@ async def register_user(
         The created user information.
     """
     try:
-        user = AuthService.create_user(db, user_data)
+        user = await AuthService.create_user(db, user_data)
         return user
-    except AuthenticationError as e:
+    except DuplicateError:
-        logger.warning(f"Registration failed: {str(e)}")
+        # SECURITY: Don't reveal if email exists - generic error message
+        logger.warning("Registration failed: duplicate email %s", user_data.email)
         raise HTTPException(
-            status_code=status.HTTP_409_CONFLICT,
+            status_code=status.HTTP_400_BAD_REQUEST,
-            detail=str(e)
+            detail="Registration failed. Please check your information and try again.",
+        )
+    except AuthError as e:
+        logger.warning("Registration failed: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="Registration failed. Please check your information and try again.",
         )
     except Exception as e:
-        logger.error(f"Unexpected error during registration: {str(e)}")
+        logger.exception("Unexpected error during registration: %s", e)
-        raise HTTPException(
+        raise DatabaseError(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            message="An unexpected error occurred. Please try again later.",
-            detail="An unexpected error occurred. Please try again later."
+            error_code=ErrorCode.INTERNAL_ERROR,
         )
 
 
 @router.post("/login", response_model=Token, operation_id="login")
+@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
 async def login(
-        login_data: LoginRequest,
+    request: Request, login_data: LoginRequest, db: AsyncSession = Depends(get_db)
-        db: Session = Depends(get_db)
 ) -> Any:
     """
     Login with username and password.
 
+    Creates a new session for this device.
+
     Returns:
         Access and refresh tokens.
     """
     try:
         # Attempt to authenticate the user
-        user = AuthService.authenticate_user(db, login_data.email, login_data.password)
+        user = await AuthService.authenticate_user(
+            db, login_data.email, login_data.password
+        )
 
         # Explicitly check for None result and raise correct exception
         if user is None:
-            logger.warning(f"Invalid login attempt for: {login_data.email}")
+            logger.warning("Invalid login attempt for: %s", login_data.email)
-            raise HTTPException(
+            raise AuthError(
-                status_code=status.HTTP_401_UNAUTHORIZED,
+                message="Invalid email or password",
-                detail="Invalid email or password",
+                error_code=ErrorCode.INVALID_CREDENTIALS,
-                headers={"WWW-Authenticate": "Bearer"},
             )
 
         # User is authenticated, generate tokens
         tokens = AuthService.create_tokens(user)
-        logger.info(f"User login successful: {user.email}")
+
+        # Create session record (best-effort, doesn't fail login)
+        await _create_login_session(db, request, user, tokens, login_type="login")
+
         return tokens
 
-    except HTTPException:
-        # Re-raise HTTP exceptions without modification
-        raise
     except AuthenticationError as e:
         # Handle specific authentication errors like inactive accounts
-        logger.warning(f"Authentication failed: {str(e)}")
+        logger.warning("Authentication failed: %s", e)
-        raise HTTPException(
+        raise AuthError(message=str(e), error_code=ErrorCode.INVALID_CREDENTIALS)
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail=str(e),
-            headers={"WWW-Authenticate": "Bearer"},
-        )
     except Exception as e:
         # Handle unexpected errors
-        logger.error(f"Unexpected error during login: {str(e)}")
+        logger.exception("Unexpected error during login: %s", e)
-        raise HTTPException(
+        raise DatabaseError(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            message="An unexpected error occurred. Please try again later.",
-            detail="An unexpected error occurred. Please try again later."
+            error_code=ErrorCode.INTERNAL_ERROR,
         )
 
 
-@router.post("/login/oauth", response_model=Token, operation_id='login_oauth')
+@router.post("/login/oauth", response_model=Token, operation_id="login_oauth")
+@limiter.limit("10/minute")
 async def login_oauth(
-        form_data: OAuth2PasswordRequestForm = Depends(),
+    request: Request,
-        db: Session = Depends(get_db)
+    form_data: OAuth2PasswordRequestForm = Depends(),
+    db: AsyncSession = Depends(get_db),
 ) -> Any:
     """
     OAuth2-compatible login endpoint, used by the OpenAPI UI.
 
+    Creates a new session for this device.
+
     Returns:
         Access and refresh tokens.
     """
     try:
-        user = AuthService.authenticate_user(db, form_data.username, form_data.password)
+        user = await AuthService.authenticate_user(
+            db, form_data.username, form_data.password
+        )
 
         if user is None:
-            raise HTTPException(
+            raise AuthError(
-                status_code=status.HTTP_401_UNAUTHORIZED,
+                message="Invalid email or password",
-                detail="Invalid email or password",
+                error_code=ErrorCode.INVALID_CREDENTIALS,
-                headers={"WWW-Authenticate": "Bearer"},
             )
 
         # Generate tokens
         tokens = AuthService.create_tokens(user)
 
-        # Format response for OAuth compatibility
+        # Create session record (best-effort, doesn't fail login)
-        return {
+        await _create_login_session(db, request, user, tokens, login_type="oauth")
-            "access_token": tokens.access_token,
+
-            "refresh_token": tokens.refresh_token,
+        # Return full token response with user data
-            "token_type": tokens.token_type
+        return tokens
-        }
-    except HTTPException:
-        raise
     except AuthenticationError as e:
-        logger.warning(f"OAuth authentication failed: {str(e)}")
+        logger.warning("OAuth authentication failed: %s", e)
-        raise HTTPException(
+        raise AuthError(message=str(e), error_code=ErrorCode.INVALID_CREDENTIALS)
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail=str(e),
-            headers={"WWW-Authenticate": "Bearer"},
-        )
     except Exception as e:
-        logger.error(f"Unexpected error during OAuth login: {str(e)}")
+        logger.exception("Unexpected error during OAuth login: %s", e)
-        raise HTTPException(
+        raise DatabaseError(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            message="An unexpected error occurred. Please try again later.",
-            detail="An unexpected error occurred. Please try again later."
+            error_code=ErrorCode.INTERNAL_ERROR,
         )
 
 
 @router.post("/refresh", response_model=Token, operation_id="refresh_token")
+@limiter.limit("30/minute")
 async def refresh_token(
-        refresh_data: RefreshTokenRequest,
+    request: Request,
-        db: Session = Depends(get_db)
+    refresh_data: RefreshTokenRequest,
+    db: AsyncSession = Depends(get_db),
 ) -> Any:
     """
     Refresh access token using a refresh token.
 
+    Validates that the session is still active before issuing new tokens.
+
     Returns:
         New access and refresh tokens.
     """
     try:
-        tokens = AuthService.refresh_tokens(db, refresh_data.refresh_token)
+        # Decode the refresh token to get the JTI
+        refresh_payload = decode_token(
+            refresh_data.refresh_token, verify_type="refresh"
+        )
+
+        # Check if session exists and is active
+        session = await session_service.get_active_by_jti(db, jti=refresh_payload.jti)
+
+        if not session:
+            logger.warning(
+                "Refresh token used for inactive or non-existent session: %s",
+                refresh_payload.jti,
+            )
+            raise HTTPException(
+                status_code=status.HTTP_401_UNAUTHORIZED,
+                detail="Session has been revoked. Please log in again.",
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+
+        # Generate new tokens
+        tokens = await AuthService.refresh_tokens(db, refresh_data.refresh_token)
+
+        # Decode new refresh token to get new JTI
+        new_refresh_payload = decode_token(tokens.refresh_token, verify_type="refresh")
+
+        # Update session with new refresh token JTI and expiration
+        try:
+            await session_service.update_refresh_token(
+                db,
+                session=session,
+                new_jti=new_refresh_payload.jti,
+                new_expires_at=datetime.fromtimestamp(new_refresh_payload.exp, tz=UTC),
+            )
+        except Exception as session_err:
+            logger.exception("Failed to update session %s: %s", session.id, session_err)
+            # Continue anyway - tokens are already issued
+
         return tokens
+
     except TokenExpiredError:
         logger.warning("Token refresh failed: Token expired")
         raise HTTPException(
@@ -175,57 +307,298 @@ async def refresh_token(
             detail="Invalid refresh token",
             headers={"WWW-Authenticate": "Bearer"},
         )
+    except HTTPException:
+        # Re-raise HTTP exceptions (like session revoked)
+        raise
     except Exception as e:
-        logger.error(f"Unexpected error during token refresh: {str(e)}")
+        logger.error("Unexpected error during token refresh: %s", e)
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail="An unexpected error occurred. Please try again later."
+            detail="An unexpected error occurred. Please try again later.",
         )
 
 
-@router.post("/change-password", status_code=status.HTTP_200_OK, operation_id="change_password")
+@router.post(
-async def change_password(
+    "/password-reset/request",
-        current_password: str = Body(..., embed=True),
+    response_model=MessageResponse,
-        new_password: str = Body(..., embed=True),
+    status_code=status.HTTP_200_OK,
-        current_user: User = Depends(get_current_user),
+    summary="Request Password Reset",
-        db: Session = Depends(get_db)
+    description="""
+    Request a password reset link.
+
+    An email will be sent with a reset link if the email exists.
+    Always returns success to prevent email enumeration.
+
+    **Rate Limit**: 3 requests/minute
+    """,
+    operation_id="request_password_reset",
+)
+@limiter.limit("3/minute")
+async def request_password_reset(
+    request: Request,
+    reset_request: PasswordResetRequest,
+    db: AsyncSession = Depends(get_db),
 ) -> Any:
     """
-    Change current user's password.
+    Request a password reset.
 
-    Requires authentication.
+    Sends an email with a password reset link.
+    Always returns success to prevent email enumeration.
     """
     try:
-        success = AuthService.change_password(
+        # Look up user by email
-            db=db,
+        user = await user_service.get_by_email(db, email=reset_request.email)
-            user_id=current_user.id,
-            current_password=current_password,
-            new_password=new_password
-        )
 
-        if success:
+        # Only send email if user exists and is active
-            return {"message": "Password changed successfully"}
+        if user and user.is_active:
-    except AuthenticationError as e:
+            # Generate reset token
-        logger.warning(f"Password change failed: {str(e)}")
+            reset_token = create_password_reset_token(user.email)
-        raise HTTPException(
+
-            status_code=status.HTTP_400_BAD_REQUEST,
+            # Send password reset email
-            detail=str(e)
+            await email_service.send_password_reset_email(
+                to_email=user.email, reset_token=reset_token, user_name=user.first_name
+            )
+            logger.info("Password reset requested for %s", user.email)
+        else:
+            # Log attempt but don't reveal if email exists
+            logger.warning(
+                "Password reset requested for non-existent or inactive email: %s",
+                reset_request.email,
+            )
+
+        # Always return success to prevent email enumeration
+        return MessageResponse(
+            success=True,
+            message="If your email is registered, you will receive a password reset link shortly",
         )
     except Exception as e:
-        logger.error(f"Unexpected error during password change: {str(e)}")
+        logger.exception("Error processing password reset request: %s", e)
-        raise HTTPException(
+        # Still return success to prevent information leakage
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        return MessageResponse(
-            detail="An unexpected error occurred. Please try again later."
+            success=True,
+            message="If your email is registered, you will receive a password reset link shortly",
         )
 
 
-@router.get("/me", response_model=UserResponse, operation_id="get_current_user_info")
+@router.post(
-async def get_current_user_info(
+    "/password-reset/confirm",
-        current_user: User = Depends(get_current_user)
+    response_model=MessageResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Confirm Password Reset",
+    description="""
+    Reset password using a token from email.
+
+    **Rate Limit**: 5 requests/minute
+    """,
+    operation_id="confirm_password_reset",
+)
+@limiter.limit("5/minute")
+async def confirm_password_reset(
+    request: Request,
+    reset_confirm: PasswordResetConfirm,
+    db: AsyncSession = Depends(get_db),
 ) -> Any:
     """
-    Get current user information.
+    Confirm password reset with token.
-    
+
-    Requires authentication.
+    Verifies the token and updates the user's password.
     """
-    return current_user
+    try:
+        # Verify the reset token
+        email = verify_password_reset_token(reset_confirm.token)
+
+        if not email:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="Invalid or expired password reset token",
+            )
+
+        # Reset password via service (validates user exists and is active)
+        try:
+            user = await AuthService.reset_password(
+                db, email=email, new_password=reset_confirm.new_password
+            )
+        except AuthenticationError as e:
+            err_msg = str(e)
+            if "inactive" in err_msg.lower():
+                raise HTTPException(
+                    status_code=status.HTTP_400_BAD_REQUEST, detail=err_msg
+                )
+            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail=err_msg)
+
+        # SECURITY: Invalidate all existing sessions after password reset
+        # This prevents stolen sessions from being used after password change
+        try:
+            deactivated_count = await session_service.deactivate_all_user_sessions(
+                db, user_id=str(user.id)
+            )
+            logger.info(
+                "Password reset successful for %s, invalidated %s sessions",
+                user.email,
+                deactivated_count,
+            )
+        except Exception as session_error:
+            # Log but don't fail password reset if session invalidation fails
+            logger.error(
+                "Failed to invalidate sessions after password reset: %s", session_error
+            )
+
+        return MessageResponse(
+            success=True,
+            message="Password has been reset successfully. All devices have been logged out for security. You can now log in with your new password.",
+        )
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception("Error confirming password reset: %s", e)
+        await db.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An error occurred while resetting your password",
+        )
+
+
+@router.post(
+    "/logout",
+    response_model=MessageResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Logout from Current Device",
+    description="""
+    Logout from the current device only.
+
+    Other devices will remain logged in.
+
+    Requires the refresh token to identify which session to terminate.
+
+    **Rate Limit**: 10 requests/minute
+    """,
+    operation_id="logout",
+)
+@limiter.limit("10/minute")
+async def logout(
+    request: Request,
+    logout_request: LogoutRequest,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Logout from current device by deactivating the session.
+
+    Args:
+        logout_request: Contains the refresh token for this session
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Success message
+    """
+    try:
+        # Decode refresh token to get JTI
+        try:
+            refresh_payload = decode_token(
+                logout_request.refresh_token, verify_type="refresh"
+            )
+        except (TokenExpiredError, TokenInvalidError) as e:
+            # Even if token is expired/invalid, try to deactivate session
+            logger.warning("Logout with invalid/expired token: %s", e)
+            # Don't fail - return success anyway
+            return MessageResponse(success=True, message="Logged out successfully")
+
+        # Find the session by JTI
+        session = await session_service.get_by_jti(db, jti=refresh_payload.jti)
+
+        if session:
+            # Verify session belongs to current user (security check)
+            if str(session.user_id) != str(current_user.id):
+                logger.warning(
+                    "User %s attempted to logout session %s belonging to user %s",
+                    current_user.id,
+                    session.id,
+                    session.user_id,
+                )
+                raise HTTPException(
+                    status_code=status.HTTP_403_FORBIDDEN,
+                    detail="You can only logout your own sessions",
+                )
+
+            # Deactivate the session
+            await session_service.deactivate(db, session_id=str(session.id))
+
+            logger.info(
+                "User %s logged out from %s (session %s)",
+                current_user.id,
+                session.device_name,
+                session.id,
+            )
+        else:
+            # Session not found - maybe already deleted or never existed
+            # Return success anyway (idempotent)
+            logger.info(
+                "Logout requested for non-existent session (JTI: %s)",
+                refresh_payload.jti,
+            )
+
+        return MessageResponse(success=True, message="Logged out successfully")
+
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.exception("Error during logout for user %s: %s", current_user.id, e)
+        # Don't expose error details
+        return MessageResponse(success=True, message="Logged out successfully")
+
+
+@router.post(
+    "/logout-all",
+    response_model=MessageResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Logout from All Devices",
+    description="""
+    Logout from ALL devices.
+
+    This will terminate all active sessions for the current user.
+    You will need to log in again on all devices.
+
+    **Rate Limit**: 5 requests/minute
+    """,
+    operation_id="logout_all",
+)
+@limiter.limit("5/minute")
+async def logout_all(
+    request: Request,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Logout from all devices by deactivating all user sessions.
+
+    Args:
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Success message with count of sessions terminated
+    """
+    try:
+        # Deactivate all sessions for this user
+        count = await session_service.deactivate_all_user_sessions(
+            db, user_id=str(current_user.id)
+        )
+
+        logger.info(
+            "User %s logged out from all devices (%s sessions)", current_user.id, count
+        )
+
+        return MessageResponse(
+            success=True,
+            message=f"Successfully logged out from all devices ({count} sessions terminated)",
+        )
+
+    except Exception as e:
+        logger.exception("Error during logout-all for user %s: %s", current_user.id, e)
+        await db.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="An error occurred while logging out",
+        )

backend/app/api/routes/oauth.py

@@ -0,0 +1,434 @@
+# app/api/routes/oauth.py
+"""
+OAuth routes for social authentication.
+
+Endpoints:
+- GET /oauth/providers - List enabled OAuth providers
+- GET /oauth/authorize/{provider} - Get authorization URL
+- POST /oauth/callback/{provider} - Handle OAuth callback
+- GET /oauth/accounts - List linked OAuth accounts
+- DELETE /oauth/accounts/{provider} - Unlink an OAuth account
+"""
+
+import logging
+import os
+from datetime import UTC, datetime
+from typing import Any
+
+from fastapi import APIRouter, Depends, HTTPException, Query, Request, status
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.auth import get_current_user, get_optional_current_user
+from app.core.auth import decode_token
+from app.core.config import settings
+from app.core.database import get_db
+from app.core.exceptions import AuthenticationError as AuthError
+from app.models.user import User
+from app.schemas.oauth import (
+    OAuthAccountsListResponse,
+    OAuthCallbackRequest,
+    OAuthCallbackResponse,
+    OAuthProvidersResponse,
+    OAuthUnlinkResponse,
+)
+from app.schemas.sessions import SessionCreate
+from app.schemas.users import Token
+from app.services.oauth_service import OAuthService
+from app.services.session_service import session_service
+from app.utils.device import extract_device_info
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+# Initialize limiter for this router
+limiter = Limiter(key_func=get_remote_address)
+
+# Use higher rate limits in test environment
+IS_TEST = os.getenv("IS_TEST", "False") == "True"
+RATE_MULTIPLIER = 100 if IS_TEST else 1
+
+
+async def _create_oauth_login_session(
+    db: AsyncSession,
+    request: Request,
+    user: User,
+    tokens: Token,
+    provider: str,
+) -> None:
+    """
+    Create a session record for successful OAuth login.
+
+    This is a best-effort operation - login succeeds even if session creation fails.
+    """
+    try:
+        device_info = extract_device_info(request)
+
+        # Decode refresh token to get JTI and expiration
+        refresh_payload = decode_token(tokens.refresh_token, verify_type="refresh")
+
+        session_data = SessionCreate(
+            user_id=user.id,
+            refresh_token_jti=refresh_payload.jti,
+            device_name=device_info.device_name or f"OAuth ({provider})",
+            device_id=device_info.device_id,
+            ip_address=device_info.ip_address,
+            user_agent=device_info.user_agent,
+            last_used_at=datetime.now(UTC),
+            expires_at=datetime.fromtimestamp(refresh_payload.exp, tz=UTC),
+            location_city=device_info.location_city,
+            location_country=device_info.location_country,
+        )
+
+        await session_service.create_session(db, obj_in=session_data)
+
+        logger.info(
+            "OAuth login successful: %s via %s from %s (IP: %s)",
+            user.email,
+            provider,
+            device_info.device_name,
+            device_info.ip_address,
+        )
+    except Exception as session_err:
+        # Log but don't fail login if session creation fails
+        logger.exception(
+            "Failed to create session for OAuth login %s: %s", user.email, session_err
+        )
+
+
+@router.get(
+    "/providers",
+    response_model=OAuthProvidersResponse,
+    summary="List OAuth Providers",
+    description="""
+    Get list of enabled OAuth providers for the login/register UI.
+
+    Returns:
+        List of enabled providers with display info.
+    """,
+    operation_id="list_oauth_providers",
+)
+async def list_providers() -> Any:
+    """
+    Get list of enabled OAuth providers.
+
+    This endpoint is public (no authentication required) as it's needed
+    for the login/register UI to display available social login options.
+    """
+    return OAuthService.get_enabled_providers()
+
+
+@router.get(
+    "/authorize/{provider}",
+    response_model=dict,
+    summary="Get OAuth Authorization URL",
+    description="""
+    Get the authorization URL to redirect the user to the OAuth provider.
+
+    The frontend should redirect the user to the returned URL.
+    After authentication, the provider will redirect back to the callback URL.
+
+    **Rate Limit**: 10 requests/minute
+    """,
+    operation_id="get_oauth_authorization_url",
+)
+@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
+async def get_authorization_url(
+    request: Request,
+    provider: str,
+    redirect_uri: str = Query(
+        ..., description="Frontend callback URL after OAuth completes"
+    ),
+    current_user: User | None = Depends(get_optional_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Get OAuth authorization URL.
+
+    Args:
+        provider: OAuth provider (google, github)
+        redirect_uri: Frontend callback URL
+        current_user: Current user (optional, for account linking)
+        db: Database session
+
+    Returns:
+        dict with authorization_url and state
+    """
+    if not settings.OAUTH_ENABLED:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="OAuth is not enabled",
+        )
+
+    try:
+        # If user is logged in, this is an account linking flow
+        user_id = str(current_user.id) if current_user else None
+
+        url, state = await OAuthService.create_authorization_url(
+            db,
+            provider=provider,
+            redirect_uri=redirect_uri,
+            user_id=user_id,
+        )
+
+        return {
+            "authorization_url": url,
+            "state": state,
+        }
+
+    except AuthError as e:
+        logger.warning("OAuth authorization failed: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        )
+    except Exception as e:
+        logger.exception("OAuth authorization error: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create authorization URL",
+        )
+
+
+@router.post(
+    "/callback/{provider}",
+    response_model=OAuthCallbackResponse,
+    summary="OAuth Callback",
+    description="""
+    Handle OAuth callback from provider.
+
+    The frontend should call this endpoint with the code and state
+    parameters received from the OAuth provider redirect.
+
+    Returns:
+        JWT tokens for the authenticated user.
+
+    **Rate Limit**: 10 requests/minute
+    """,
+    operation_id="handle_oauth_callback",
+)
+@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
+async def handle_callback(
+    request: Request,
+    provider: str,
+    callback_data: OAuthCallbackRequest,
+    redirect_uri: str = Query(
+        ..., description="Must match the redirect_uri used in authorization"
+    ),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Handle OAuth callback.
+
+    Args:
+        provider: OAuth provider (google, github)
+        callback_data: Code and state from provider
+        redirect_uri: Original redirect URI (for validation)
+        db: Database session
+
+    Returns:
+        OAuthCallbackResponse with tokens
+    """
+    if not settings.OAUTH_ENABLED:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="OAuth is not enabled",
+        )
+
+    try:
+        result = await OAuthService.handle_callback(
+            db,
+            code=callback_data.code,
+            state=callback_data.state,
+            redirect_uri=redirect_uri,
+        )
+
+        # Create session for the login (need to get the user first)
+        # Note: This requires fetching the user from the token
+        # For now, we skip session creation here as the result doesn't include user info
+        # The session will be created on next request if needed
+
+        return result
+
+    except AuthError as e:
+        logger.warning("OAuth callback failed: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=str(e),
+        )
+    except Exception as e:
+        logger.exception("OAuth callback error: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="OAuth authentication failed",
+        )
+
+
+@router.get(
+    "/accounts",
+    response_model=OAuthAccountsListResponse,
+    summary="List Linked OAuth Accounts",
+    description="""
+    Get list of OAuth accounts linked to the current user.
+
+    Requires authentication.
+    """,
+    operation_id="list_oauth_accounts",
+)
+async def list_accounts(
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    List OAuth accounts linked to the current user.
+
+    Args:
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        List of linked OAuth accounts
+    """
+    accounts = await OAuthService.get_user_accounts(db, user_id=current_user.id)
+    return OAuthAccountsListResponse(accounts=accounts)
+
+
+@router.delete(
+    "/accounts/{provider}",
+    response_model=OAuthUnlinkResponse,
+    summary="Unlink OAuth Account",
+    description="""
+    Unlink an OAuth provider from the current user.
+
+    The user must have either a password set or another OAuth provider
+    linked to ensure they can still log in.
+
+    **Rate Limit**: 5 requests/minute
+    """,
+    operation_id="unlink_oauth_account",
+)
+@limiter.limit(f"{5 * RATE_MULTIPLIER}/minute")
+async def unlink_account(
+    request: Request,
+    provider: str,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Unlink an OAuth provider from the current user.
+
+    Args:
+        provider: Provider to unlink (google, github)
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Success message
+    """
+    try:
+        await OAuthService.unlink_provider(
+            db,
+            user=current_user,
+            provider=provider,
+        )
+
+        return OAuthUnlinkResponse(
+            success=True,
+            message=f"{provider.capitalize()} account unlinked successfully",
+        )
+
+    except AuthError as e:
+        logger.warning("OAuth unlink failed for %s: %s", current_user.email, e)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        )
+    except Exception as e:
+        logger.exception("OAuth unlink error: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to unlink OAuth account",
+        )
+
+
+@router.post(
+    "/link/{provider}",
+    response_model=dict,
+    summary="Start Account Linking",
+    description="""
+    Start the OAuth flow to link a new provider to the current user.
+
+    This is a convenience endpoint that redirects to /authorize/{provider}
+    with the current user context.
+
+    **Rate Limit**: 10 requests/minute
+    """,
+    operation_id="start_oauth_link",
+)
+@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
+async def start_link(
+    request: Request,
+    provider: str,
+    redirect_uri: str = Query(
+        ..., description="Frontend callback URL after OAuth completes"
+    ),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Start OAuth account linking flow.
+
+    This endpoint requires authentication and will initiate an OAuth flow
+    to link a new provider to the current user's account.
+
+    Args:
+        provider: OAuth provider to link (google, github)
+        redirect_uri: Frontend callback URL
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        dict with authorization_url and state
+    """
+    if not settings.OAUTH_ENABLED:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="OAuth is not enabled",
+        )
+
+    # Check if user already has this provider linked
+    existing = await OAuthService.get_user_account_by_provider(
+        db, user_id=current_user.id, provider=provider
+    )
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"You already have a {provider} account linked",
+        )
+
+    try:
+        url, state = await OAuthService.create_authorization_url(
+            db,
+            provider=provider,
+            redirect_uri=redirect_uri,
+            user_id=str(current_user.id),
+        )
+
+        return {
+            "authorization_url": url,
+            "state": state,
+        }
+
+    except AuthError as e:
+        logger.warning("OAuth link authorization failed: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        )
+    except Exception as e:
+        logger.exception("OAuth link error: %s", e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to create authorization URL",
+        )

backend/app/api/routes/oauth_provider.py

@@ -0,0 +1,824 @@
+# app/api/routes/oauth_provider.py
+"""
+OAuth Provider routes (Authorization Server mode) for MCP integration.
+
+Implements OAuth 2.0 Authorization Server endpoints:
+- GET /.well-known/oauth-authorization-server - Server metadata (RFC 8414)
+- GET /oauth/provider/authorize - Authorization endpoint
+- POST /oauth/provider/token - Token endpoint
+- POST /oauth/provider/revoke - Token revocation (RFC 7009)
+- POST /oauth/provider/introspect - Token introspection (RFC 7662)
+- Client management endpoints
+
+Security features:
+- PKCE required for public clients (S256)
+- CSRF protection via state parameter
+- Secure token handling
+- Rate limiting on sensitive endpoints
+"""
+
+import logging
+from typing import Any
+from urllib.parse import urlencode
+
+from fastapi import APIRouter, Depends, Form, HTTPException, Query, Request, status
+from fastapi.responses import RedirectResponse
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.auth import (
+    get_current_active_user,
+    get_current_superuser,
+    get_optional_current_user,
+)
+from app.core.config import settings
+from app.core.database import get_db
+from app.models.user import User
+from app.schemas.oauth import (
+    OAuthClientCreate,
+    OAuthClientResponse,
+    OAuthServerMetadata,
+    OAuthTokenIntrospectionResponse,
+    OAuthTokenResponse,
+)
+from app.services import oauth_provider_service as provider_service
+
+router = APIRouter()
+# Separate router for RFC 8414 well-known endpoint (registered at root level)
+wellknown_router = APIRouter()
+logger = logging.getLogger(__name__)
+limiter = Limiter(key_func=get_remote_address)
+
+
+def require_provider_enabled():
+    """Dependency to check if OAuth provider mode is enabled."""
+    if not settings.OAUTH_PROVIDER_ENABLED:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="OAuth provider mode is not enabled. Set OAUTH_PROVIDER_ENABLED=true",
+        )
+
+
+# ============================================================================
+# Server Metadata (RFC 8414)
+# ============================================================================
+
+
+@wellknown_router.get(
+    "/.well-known/oauth-authorization-server",
+    response_model=OAuthServerMetadata,
+    summary="OAuth Server Metadata",
+    description="""
+    OAuth 2.0 Authorization Server Metadata (RFC 8414).
+
+    Returns server metadata including supported endpoints, scopes,
+    and capabilities. MCP clients use this to discover the server.
+
+    Note: This endpoint is at the root level per RFC 8414.
+    """,
+    operation_id="get_oauth_server_metadata",
+    tags=["OAuth Provider"],
+)
+async def get_server_metadata(
+    _: None = Depends(require_provider_enabled),
+) -> OAuthServerMetadata:
+    """Get OAuth 2.0 server metadata."""
+    base_url = settings.OAUTH_ISSUER.rstrip("/")
+
+    return OAuthServerMetadata(
+        issuer=base_url,
+        authorization_endpoint=f"{base_url}/api/v1/oauth/provider/authorize",
+        token_endpoint=f"{base_url}/api/v1/oauth/provider/token",
+        revocation_endpoint=f"{base_url}/api/v1/oauth/provider/revoke",
+        introspection_endpoint=f"{base_url}/api/v1/oauth/provider/introspect",
+        registration_endpoint=None,  # Dynamic registration not supported
+        scopes_supported=[
+            "openid",
+            "profile",
+            "email",
+            "read:users",
+            "write:users",
+            "read:organizations",
+            "write:organizations",
+            "admin",
+        ],
+        response_types_supported=["code"],
+        grant_types_supported=["authorization_code", "refresh_token"],
+        code_challenge_methods_supported=["S256"],
+        token_endpoint_auth_methods_supported=[
+            "client_secret_basic",
+            "client_secret_post",
+            "none",  # For public clients with PKCE
+        ],
+    )
+
+
+# ============================================================================
+# Authorization Endpoint
+# ============================================================================
+
+
+@router.get(
+    "/provider/authorize",
+    summary="Authorization Endpoint",
+    description="""
+    OAuth 2.0 Authorization Endpoint.
+
+    Initiates the authorization code flow:
+    1. Validates client and parameters
+    2. Checks if user is authenticated (redirects to login if not)
+    3. Checks existing consent
+    4. Redirects to consent page if needed
+    5. Issues authorization code and redirects back to client
+
+    Required parameters:
+    - response_type: Must be "code"
+    - client_id: Registered client ID
+    - redirect_uri: Must match registered URI
+
+    Recommended parameters:
+    - state: CSRF protection
+    - code_challenge + code_challenge_method: PKCE (required for public clients)
+    - scope: Requested permissions
+    """,
+    operation_id="oauth_provider_authorize",
+    tags=["OAuth Provider"],
+)
+@limiter.limit("30/minute")
+async def authorize(
+    request: Request,
+    response_type: str = Query(..., description="Must be 'code'"),
+    client_id: str = Query(..., description="OAuth client ID"),
+    redirect_uri: str = Query(..., description="Redirect URI"),
+    scope: str = Query(default="", description="Requested scopes (space-separated)"),
+    state: str = Query(default="", description="CSRF state parameter"),
+    code_challenge: str | None = Query(default=None, description="PKCE code challenge"),
+    code_challenge_method: str | None = Query(
+        default=None, description="PKCE method (S256)"
+    ),
+    nonce: str | None = Query(default=None, description="OpenID Connect nonce"),
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+    current_user: User | None = Depends(get_optional_current_user),
+) -> Any:
+    """
+    Authorization endpoint - initiates OAuth flow.
+
+    If user is not authenticated, redirects to login with return URL.
+    If user has not consented, redirects to consent page.
+    If all checks pass, generates code and redirects to client.
+    """
+    # Validate response_type
+    if response_type != "code":
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="invalid_request: response_type must be 'code'",
+        )
+
+    # Validate PKCE method if provided - ONLY S256 is allowed (RFC 7636 Section 4.3)
+    # "plain" method provides no security benefit and MUST NOT be used
+    if code_challenge_method and code_challenge_method != "S256":
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="invalid_request: code_challenge_method must be 'S256' (plain is not supported)",
+        )
+
+    # Validate client
+    try:
+        client = await provider_service.get_client(db, client_id)
+        if not client:
+            raise provider_service.InvalidClientError("Unknown client_id")
+        provider_service.validate_redirect_uri(client, redirect_uri)
+    except provider_service.OAuthProviderError as e:
+        # For client/redirect errors, we can't safely redirect - show error
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"{e.error}: {e.error_description}",
+        )
+
+    # Validate and filter scopes
+    try:
+        requested_scopes = provider_service.parse_scope(scope)
+        valid_scopes = provider_service.validate_scopes(client, requested_scopes)
+    except provider_service.InvalidScopeError as e:
+        # Redirect with error
+        scope_error_params: dict[str, str] = {"error": e.error}
+        if e.error_description:
+            scope_error_params["error_description"] = e.error_description
+        if state:
+            scope_error_params["state"] = state
+        return RedirectResponse(
+            url=f"{redirect_uri}?{urlencode(scope_error_params)}",
+            status_code=status.HTTP_302_FOUND,
+        )
+
+    # Public clients MUST use PKCE
+    if client.client_type == "public":
+        if not code_challenge or code_challenge_method != "S256":
+            pkce_error_params: dict[str, str] = {
+                "error": "invalid_request",
+                "error_description": "PKCE with S256 is required for public clients",
+            }
+            if state:
+                pkce_error_params["state"] = state
+            return RedirectResponse(
+                url=f"{redirect_uri}?{urlencode(pkce_error_params)}",
+                status_code=status.HTTP_302_FOUND,
+            )
+
+    # If user is not authenticated, redirect to login
+    if not current_user:
+        # Store authorization request in session and redirect to login
+        # The frontend will handle the return URL
+        login_url = f"{settings.FRONTEND_URL}/login"
+        return_params = urlencode(
+            {
+                "oauth_authorize": "true",
+                "client_id": client_id,
+                "redirect_uri": redirect_uri,
+                "scope": " ".join(valid_scopes),
+                "state": state,
+                "code_challenge": code_challenge or "",
+                "code_challenge_method": code_challenge_method or "",
+                "nonce": nonce or "",
+            }
+        )
+        return RedirectResponse(
+            url=f"{login_url}?return_to=/auth/consent?{return_params}",
+            status_code=status.HTTP_302_FOUND,
+        )
+
+    # Check if user has already consented
+    has_consent = await provider_service.check_consent(
+        db, current_user.id, client_id, valid_scopes
+    )
+
+    if not has_consent:
+        # Redirect to consent page
+        consent_params = urlencode(
+            {
+                "client_id": client_id,
+                "client_name": client.client_name,
+                "redirect_uri": redirect_uri,
+                "scope": " ".join(valid_scopes),
+                "state": state,
+                "code_challenge": code_challenge or "",
+                "code_challenge_method": code_challenge_method or "",
+                "nonce": nonce or "",
+            }
+        )
+        return RedirectResponse(
+            url=f"{settings.FRONTEND_URL}/auth/consent?{consent_params}",
+            status_code=status.HTTP_302_FOUND,
+        )
+
+    # User is authenticated and has consented - issue authorization code
+    try:
+        code = await provider_service.create_authorization_code(
+            db=db,
+            client=client,
+            user=current_user,
+            redirect_uri=redirect_uri,
+            scope=" ".join(valid_scopes),
+            code_challenge=code_challenge,
+            code_challenge_method=code_challenge_method,
+            state=state,
+            nonce=nonce,
+        )
+    except provider_service.OAuthProviderError as e:
+        error_params: dict[str, str] = {"error": e.error}
+        if e.error_description:
+            error_params["error_description"] = e.error_description
+        if state:
+            error_params["state"] = state
+        return RedirectResponse(
+            url=f"{redirect_uri}?{urlencode(error_params)}",
+            status_code=status.HTTP_302_FOUND,
+        )
+
+    # Success - redirect with code
+    success_params = {"code": code}
+    if state:
+        success_params["state"] = state
+
+    return RedirectResponse(
+        url=f"{redirect_uri}?{urlencode(success_params)}",
+        status_code=status.HTTP_302_FOUND,
+    )
+
+
+@router.post(
+    "/provider/authorize/consent",
+    summary="Submit Authorization Consent",
+    description="""
+    Submit user consent for OAuth authorization.
+
+    Called by the consent page after user approves or denies.
+    """,
+    operation_id="oauth_provider_consent",
+    tags=["OAuth Provider"],
+)
+@limiter.limit("30/minute")
+async def submit_consent(
+    request: Request,
+    approved: bool = Form(..., description="Whether user approved"),
+    client_id: str = Form(..., description="OAuth client ID"),
+    redirect_uri: str = Form(..., description="Redirect URI"),
+    scope: str = Form(default="", description="Granted scopes"),
+    state: str = Form(default="", description="CSRF state parameter"),
+    code_challenge: str | None = Form(default=None),
+    code_challenge_method: str | None = Form(default=None),
+    nonce: str | None = Form(default=None),
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+    current_user: User = Depends(get_current_active_user),
+) -> Any:
+    """Process consent form submission."""
+    # Validate client
+    try:
+        client = await provider_service.get_client(db, client_id)
+        if not client:
+            raise provider_service.InvalidClientError("Unknown client_id")
+        provider_service.validate_redirect_uri(client, redirect_uri)
+    except provider_service.OAuthProviderError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"{e.error}: {e.error_description}",
+        )
+
+    # If user denied, redirect with error
+    if not approved:
+        denied_params: dict[str, str] = {
+            "error": "access_denied",
+            "error_description": "User denied authorization",
+        }
+        if state:
+            denied_params["state"] = state
+        return RedirectResponse(
+            url=f"{redirect_uri}?{urlencode(denied_params)}",
+            status_code=status.HTTP_302_FOUND,
+        )
+
+    # Parse and validate scopes
+    granted_scopes = provider_service.parse_scope(scope)
+    valid_scopes = provider_service.validate_scopes(client, granted_scopes)
+
+    # Record consent
+    await provider_service.grant_consent(db, current_user.id, client_id, valid_scopes)
+
+    # Generate authorization code
+    try:
+        code = await provider_service.create_authorization_code(
+            db=db,
+            client=client,
+            user=current_user,
+            redirect_uri=redirect_uri,
+            scope=" ".join(valid_scopes),
+            code_challenge=code_challenge,
+            code_challenge_method=code_challenge_method,
+            state=state,
+            nonce=nonce,
+        )
+    except provider_service.OAuthProviderError as e:
+        error_params: dict[str, str] = {"error": e.error}
+        if e.error_description:
+            error_params["error_description"] = e.error_description
+        if state:
+            error_params["state"] = state
+        return RedirectResponse(
+            url=f"{redirect_uri}?{urlencode(error_params)}",
+            status_code=status.HTTP_302_FOUND,
+        )
+
+    # Success
+    success_params = {"code": code}
+    if state:
+        success_params["state"] = state
+
+    return RedirectResponse(
+        url=f"{redirect_uri}?{urlencode(success_params)}",
+        status_code=status.HTTP_302_FOUND,
+    )
+
+
+# ============================================================================
+# Token Endpoint
+# ============================================================================
+
+
+@router.post(
+    "/provider/token",
+    response_model=OAuthTokenResponse,
+    summary="Token Endpoint",
+    description="""
+    OAuth 2.0 Token Endpoint.
+
+    Supports:
+    - authorization_code: Exchange code for tokens
+    - refresh_token: Refresh access token
+
+    Client authentication:
+    - Confidential clients: client_secret (Basic auth or POST body)
+    - Public clients: No secret, but PKCE code_verifier required
+    """,
+    operation_id="oauth_provider_token",
+    tags=["OAuth Provider"],
+)
+@limiter.limit("60/minute")
+async def token(
+    request: Request,
+    grant_type: str = Form(..., description="Grant type"),
+    code: str | None = Form(default=None, description="Authorization code"),
+    redirect_uri: str | None = Form(default=None, description="Redirect URI"),
+    client_id: str | None = Form(default=None, description="Client ID"),
+    client_secret: str | None = Form(default=None, description="Client secret"),
+    code_verifier: str | None = Form(default=None, description="PKCE code verifier"),
+    refresh_token: str | None = Form(default=None, description="Refresh token"),
+    scope: str | None = Form(default=None, description="Scope (for refresh)"),
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+) -> OAuthTokenResponse:
+    """Token endpoint - exchange code for tokens or refresh."""
+    # Extract client credentials from Basic auth if not in body
+    if not client_id:
+        auth_header = request.headers.get("Authorization", "")
+        if auth_header.startswith("Basic "):
+            import base64
+
+            try:
+                decoded = base64.b64decode(auth_header[6:]).decode()
+                client_id, client_secret = decoded.split(":", 1)
+            except Exception as e:
+                # Log malformed Basic auth for security monitoring
+                logger.warning(
+                    "Malformed Basic auth header in token request: %s", type(e).__name__
+                )
+                # Fall back to form body
+
+    if not client_id:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="invalid_client: client_id required",
+            headers={"WWW-Authenticate": "Basic"},
+        )
+
+    # Get device info
+    device_info = request.headers.get("User-Agent", "")[:500]
+    ip_address = get_remote_address(request)
+
+    try:
+        if grant_type == "authorization_code":
+            if not code:
+                raise provider_service.InvalidRequestError("code required")
+            if not redirect_uri:
+                raise provider_service.InvalidRequestError("redirect_uri required")
+
+            result = await provider_service.exchange_authorization_code(
+                db=db,
+                code=code,
+                client_id=client_id,
+                redirect_uri=redirect_uri,
+                code_verifier=code_verifier,
+                client_secret=client_secret,
+                device_info=device_info,
+                ip_address=ip_address,
+            )
+
+        elif grant_type == "refresh_token":
+            if not refresh_token:
+                raise provider_service.InvalidRequestError("refresh_token required")
+
+            result = await provider_service.refresh_tokens(
+                db=db,
+                refresh_token=refresh_token,
+                client_id=client_id,
+                client_secret=client_secret,
+                scope=scope,
+                device_info=device_info,
+                ip_address=ip_address,
+            )
+
+        else:
+            raise HTTPException(
+                status_code=status.HTTP_400_BAD_REQUEST,
+                detail="unsupported_grant_type: Must be authorization_code or refresh_token",
+            )
+
+        return OAuthTokenResponse(**result)
+
+    except provider_service.InvalidClientError as e:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail=f"{e.error}: {e.error_description}",
+            headers={"WWW-Authenticate": "Basic"},
+        )
+    except provider_service.OAuthProviderError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=f"{e.error}: {e.error_description}",
+        )
+
+
+# ============================================================================
+# Token Revocation (RFC 7009)
+# ============================================================================
+
+
+@router.post(
+    "/provider/revoke",
+    status_code=status.HTTP_200_OK,
+    summary="Token Revocation Endpoint",
+    description="""
+    OAuth 2.0 Token Revocation Endpoint (RFC 7009).
+
+    Revokes an access token or refresh token.
+    Always returns 200 OK (even if token is invalid) per spec.
+    """,
+    operation_id="oauth_provider_revoke",
+    tags=["OAuth Provider"],
+)
+@limiter.limit("30/minute")
+async def revoke(
+    request: Request,
+    token: str = Form(..., description="Token to revoke"),
+    token_type_hint: str | None = Form(
+        default=None, description="Token type hint (access_token, refresh_token)"
+    ),
+    client_id: str | None = Form(default=None, description="Client ID"),
+    client_secret: str | None = Form(default=None, description="Client secret"),
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+) -> dict[str, str]:
+    """Revoke a token."""
+    # Extract client credentials from Basic auth if not in body
+    if not client_id:
+        auth_header = request.headers.get("Authorization", "")
+        if auth_header.startswith("Basic "):
+            import base64
+
+            try:
+                decoded = base64.b64decode(auth_header[6:]).decode()
+                client_id, client_secret = decoded.split(":", 1)
+            except Exception as e:
+                # Log malformed Basic auth for security monitoring
+                logger.warning(
+                    "Malformed Basic auth header in revoke request: %s",
+                    type(e).__name__,
+                )
+                # Fall back to form body
+
+    try:
+        await provider_service.revoke_token(
+            db=db,
+            token=token,
+            token_type_hint=token_type_hint,
+            client_id=client_id,
+            client_secret=client_secret,
+        )
+    except provider_service.InvalidClientError:
+        # Per RFC 7009, we should return 200 OK even for errors
+        # But client authentication errors can return 401
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="invalid_client",
+            headers={"WWW-Authenticate": "Basic"},
+        )
+    except Exception as e:
+        # Log but don't expose errors per RFC 7009
+        logger.warning("Token revocation error: %s", e)
+
+    # Always return 200 OK per RFC 7009
+    return {"status": "ok"}
+
+
+# ============================================================================
+# Token Introspection (RFC 7662)
+# ============================================================================
+
+
+@router.post(
+    "/provider/introspect",
+    response_model=OAuthTokenIntrospectionResponse,
+    summary="Token Introspection Endpoint",
+    description="""
+    OAuth 2.0 Token Introspection Endpoint (RFC 7662).
+
+    Allows resource servers to query the authorization server
+    to determine the active state and metadata of a token.
+    """,
+    operation_id="oauth_provider_introspect",
+    tags=["OAuth Provider"],
+)
+@limiter.limit("120/minute")
+async def introspect(
+    request: Request,
+    token: str = Form(..., description="Token to introspect"),
+    token_type_hint: str | None = Form(
+        default=None, description="Token type hint (access_token, refresh_token)"
+    ),
+    client_id: str | None = Form(default=None, description="Client ID"),
+    client_secret: str | None = Form(default=None, description="Client secret"),
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+) -> OAuthTokenIntrospectionResponse:
+    """Introspect a token."""
+    # Extract client credentials from Basic auth if not in body
+    if not client_id:
+        auth_header = request.headers.get("Authorization", "")
+        if auth_header.startswith("Basic "):
+            import base64
+
+            try:
+                decoded = base64.b64decode(auth_header[6:]).decode()
+                client_id, client_secret = decoded.split(":", 1)
+            except Exception as e:
+                # Log malformed Basic auth for security monitoring
+                logger.warning(
+                    "Malformed Basic auth header in introspect request: %s",
+                    type(e).__name__,
+                )
+                # Fall back to form body
+
+    try:
+        result = await provider_service.introspect_token(
+            db=db,
+            token=token,
+            token_type_hint=token_type_hint,
+            client_id=client_id,
+            client_secret=client_secret,
+        )
+        return OAuthTokenIntrospectionResponse(**result)
+    except provider_service.InvalidClientError:
+        raise HTTPException(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            detail="invalid_client",
+            headers={"WWW-Authenticate": "Basic"},
+        )
+    except Exception as e:
+        logger.warning("Token introspection error: %s", e)
+        return OAuthTokenIntrospectionResponse(active=False)  # pyright: ignore[reportCallIssue]
+
+
+# ============================================================================
+# Client Management (Admin)
+# ============================================================================
+
+
+@router.post(
+    "/provider/clients",
+    response_model=dict,
+    summary="Register OAuth Client",
+    description="""
+    Register a new OAuth client (admin only).
+
+    Creates an MCP client that can authenticate against this API.
+    Returns client_id and client_secret (for confidential clients).
+
+    **Important:** Store the client_secret securely - it won't be shown again!
+    """,
+    operation_id="register_oauth_client",
+    tags=["OAuth Provider Admin"],
+)
+async def register_client(
+    client_name: str = Form(..., description="Client application name"),
+    redirect_uris: str = Form(..., description="Comma-separated redirect URIs"),
+    client_type: str = Form(default="public", description="public or confidential"),
+    scopes: str = Form(
+        default="openid profile email",
+        description="Allowed scopes (space-separated)",
+    ),
+    mcp_server_url: str | None = Form(default=None, description="MCP server URL"),
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+    current_user: User = Depends(get_current_superuser),
+) -> dict:
+    """Register a new OAuth client."""
+    # Parse redirect URIs
+    uris = [uri.strip() for uri in redirect_uris.split(",") if uri.strip()]
+    if not uris:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail="At least one redirect_uri is required",
+        )
+
+    # Parse scopes
+    allowed_scopes = [s.strip() for s in scopes.split() if s.strip()]
+
+    client_data = OAuthClientCreate(
+        client_name=client_name,
+        client_description=None,
+        redirect_uris=uris,
+        allowed_scopes=allowed_scopes,
+        client_type=client_type,
+    )
+
+    client, secret = await provider_service.register_client(db, client_data)
+
+    # Update MCP server URL if provided
+    if mcp_server_url:
+        client.mcp_server_url = mcp_server_url
+        await db.commit()
+
+    result = {
+        "client_id": client.client_id,
+        "client_name": client.client_name,
+        "client_type": client.client_type,
+        "redirect_uris": client.redirect_uris,
+        "allowed_scopes": client.allowed_scopes,
+    }
+
+    if secret:
+        result["client_secret"] = secret
+        result["warning"] = (
+            "Store the client_secret securely! It will not be shown again."
+        )
+
+    return result
+
+
+@router.get(
+    "/provider/clients",
+    response_model=list[OAuthClientResponse],
+    summary="List OAuth Clients",
+    description="List all registered OAuth clients (admin only).",
+    operation_id="list_oauth_clients",
+    tags=["OAuth Provider Admin"],
+)
+async def list_clients(
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+    current_user: User = Depends(get_current_superuser),
+) -> list[OAuthClientResponse]:
+    """List all OAuth clients."""
+    clients = await provider_service.list_clients(db)
+    return [OAuthClientResponse.model_validate(c) for c in clients]
+
+
+@router.delete(
+    "/provider/clients/{client_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Delete OAuth Client",
+    description="Delete an OAuth client (admin only). Revokes all tokens.",
+    operation_id="delete_oauth_client",
+    tags=["OAuth Provider Admin"],
+)
+async def delete_client(
+    client_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+    current_user: User = Depends(get_current_superuser),
+) -> None:
+    """Delete an OAuth client."""
+    client = await provider_service.get_client(db, client_id)
+    if not client:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="Client not found",
+        )
+
+    await provider_service.delete_client_by_id(db, client_id=client_id)
+
+
+# ============================================================================
+# User Consent Management
+# ============================================================================
+
+
+@router.get(
+    "/provider/consents",
+    summary="List My Consents",
+    description="List OAuth applications the current user has authorized.",
+    operation_id="list_my_oauth_consents",
+    tags=["OAuth Provider"],
+)
+async def list_my_consents(
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+    current_user: User = Depends(get_current_active_user),
+) -> list[dict]:
+    """List applications the user has authorized."""
+    return await provider_service.list_user_consents(db, user_id=current_user.id)
+
+
+@router.delete(
+    "/provider/consents/{client_id}",
+    status_code=status.HTTP_204_NO_CONTENT,
+    summary="Revoke My Consent",
+    description="Revoke authorization for an OAuth application. Also revokes all tokens.",
+    operation_id="revoke_my_oauth_consent",
+    tags=["OAuth Provider"],
+)
+async def revoke_my_consent(
+    client_id: str,
+    db: AsyncSession = Depends(get_db),
+    _: None = Depends(require_provider_enabled),
+    current_user: User = Depends(get_current_active_user),
+) -> None:
+    """Revoke consent for an application."""
+    revoked = await provider_service.revoke_consent(db, current_user.id, client_id)
+    if not revoked:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND,
+            detail="No consent found for this client",
+        )

backend/app/api/routes/organizations.py

@@ -0,0 +1,211 @@
+# app/api/routes/organizations.py
+"""
+Organization endpoints for regular users.
+
+These endpoints allow users to view and manage organizations they belong to.
+"""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.auth import get_current_user
+from app.api.dependencies.permissions import require_org_admin, require_org_membership
+from app.core.database import get_db
+from app.models.user import User
+from app.schemas.common import (
+    PaginatedResponse,
+    PaginationParams,
+    create_pagination_meta,
+)
+from app.schemas.organizations import (
+    OrganizationMemberResponse,
+    OrganizationResponse,
+    OrganizationUpdate,
+)
+from app.services.organization_service import organization_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+
+
+@router.get(
+    "/me",
+    response_model=list[OrganizationResponse],
+    summary="Get My Organizations",
+    description="Get all organizations the current user belongs to",
+    operation_id="get_my_organizations",
+)
+async def get_my_organizations(
+    is_active: bool = Query(True, description="Filter by active membership"),
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Get all organizations the current user belongs to.
+
+    Returns organizations with member count for each.
+    Uses optimized single query to avoid N+1 problem.
+    """
+    try:
+        # Get all org data in single query with JOIN and subquery
+        orgs_data = await organization_service.get_user_organizations_with_details(
+            db, user_id=current_user.id, is_active=is_active
+        )
+
+        # Transform to response objects
+        orgs_with_data = []
+        for item in orgs_data:
+            org = item["organization"]
+            org_dict = {
+                "id": org.id,
+                "name": org.name,
+                "slug": org.slug,
+                "description": org.description,
+                "is_active": org.is_active,
+                "settings": org.settings,
+                "created_at": org.created_at,
+                "updated_at": org.updated_at,
+                "member_count": item["member_count"],
+            }
+            orgs_with_data.append(OrganizationResponse(**org_dict))
+
+        return orgs_with_data
+
+    except Exception as e:
+        logger.exception("Error getting user organizations: %s", e)
+        raise
+
+
+@router.get(
+    "/{organization_id}",
+    response_model=OrganizationResponse,
+    summary="Get Organization Details",
+    description="Get details of an organization the user belongs to",
+    operation_id="get_organization",
+)
+async def get_organization(
+    organization_id: UUID,
+    current_user: User = Depends(require_org_membership),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Get details of a specific organization.
+
+    User must be a member of the organization.
+    """
+    try:
+        org = await organization_service.get_organization(db, str(organization_id))
+        org_dict = {
+            "id": org.id,
+            "name": org.name,
+            "slug": org.slug,
+            "description": org.description,
+            "is_active": org.is_active,
+            "settings": org.settings,
+            "created_at": org.created_at,
+            "updated_at": org.updated_at,
+            "member_count": await organization_service.get_member_count(
+                db, organization_id=org.id
+            ),
+        }
+        return OrganizationResponse(**org_dict)
+
+    except Exception as e:
+        logger.exception("Error getting organization: %s", e)
+        raise
+
+
+@router.get(
+    "/{organization_id}/members",
+    response_model=PaginatedResponse[OrganizationMemberResponse],
+    summary="Get Organization Members",
+    description="Get all members of an organization (members can view)",
+    operation_id="get_organization_members",
+)
+async def get_organization_members(
+    organization_id: UUID,
+    pagination: PaginationParams = Depends(),
+    is_active: bool = Query(True, description="Filter by active status"),
+    current_user: User = Depends(require_org_membership),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Get all members of an organization.
+
+    User must be a member of the organization to view members.
+    """
+    try:
+        members, total = await organization_service.get_organization_members(
+            db,
+            organization_id=organization_id,
+            skip=pagination.offset,
+            limit=pagination.limit,
+            is_active=is_active,
+        )
+
+        member_responses = [OrganizationMemberResponse(**member) for member in members]
+
+        pagination_meta = create_pagination_meta(
+            total=total,
+            page=pagination.page,
+            limit=pagination.limit,
+            items_count=len(member_responses),
+        )
+
+        return PaginatedResponse(data=member_responses, pagination=pagination_meta)
+
+    except Exception as e:
+        logger.exception("Error getting organization members: %s", e)
+        raise
+
+
+@router.put(
+    "/{organization_id}",
+    response_model=OrganizationResponse,
+    summary="Update Organization",
+    description="Update organization details (admin/owner only)",
+    operation_id="update_organization",
+)
+async def update_organization(
+    organization_id: UUID,
+    org_in: OrganizationUpdate,
+    current_user: User = Depends(require_org_admin),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Update organization details.
+
+    Requires owner or admin role in the organization.
+    """
+    try:
+        org = await organization_service.get_organization(db, str(organization_id))
+        updated_org = await organization_service.update_organization(
+            db, org=org, obj_in=org_in
+        )
+        logger.info(
+            "User %s updated organization %s", current_user.email, updated_org.name
+        )
+
+        org_dict = {
+            "id": updated_org.id,
+            "name": updated_org.name,
+            "slug": updated_org.slug,
+            "description": updated_org.description,
+            "is_active": updated_org.is_active,
+            "settings": updated_org.settings,
+            "created_at": updated_org.created_at,
+            "updated_at": updated_org.updated_at,
+            "member_count": await organization_service.get_member_count(
+                db, organization_id=updated_org.id
+            ),
+        }
+        return OrganizationResponse(**org_dict)
+
+    except Exception as e:
+        logger.exception("Error updating organization: %s", e)
+        raise

backend/app/api/routes/sessions.py

@@ -0,0 +1,247 @@
+"""
+Session management endpoints.
+
+Allows users to view and manage their active sessions across devices.
+"""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Request, status
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.auth import get_current_user
+from app.core.auth import decode_token
+from app.core.database import get_db
+from app.core.exceptions import AuthorizationError, ErrorCode, NotFoundError
+from app.models.user import User
+from app.schemas.common import MessageResponse
+from app.schemas.sessions import SessionListResponse, SessionResponse
+from app.services.session_service import session_service
+
+router = APIRouter()
+logger = logging.getLogger(__name__)
+
+# Initialize limiter
+limiter = Limiter(key_func=get_remote_address)
+
+
+@router.get(
+    "/me",
+    response_model=SessionListResponse,
+    summary="List My Active Sessions",
+    description="""
+    Get a list of all active sessions for the current user.
+
+    This shows where you're currently logged in.
+
+    **Rate Limit**: 30 requests/minute
+    """,
+    operation_id="list_my_sessions",
+)
+@limiter.limit("30/minute")
+async def list_my_sessions(
+    request: Request,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    List all active sessions for the current user.
+
+    Args:
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        List of active sessions
+    """
+    try:
+        # Get all active sessions for user
+        sessions = await session_service.get_user_sessions(
+            db, user_id=str(current_user.id), active_only=True
+        )
+
+        # Try to identify current session from Authorization header
+        auth_header = request.headers.get("authorization")
+        if auth_header and auth_header.startswith("Bearer "):
+            try:
+                access_token = auth_header.split(" ")[1]
+                decode_token(access_token)
+                # Note: Access tokens don't have JTI by default, but we can try
+                # For now, we'll mark current based on most recent activity
+            except Exception as e:
+                # Optional token parsing - silently ignore failures
+                logger.debug("Failed to decode access token for session marking: %s", e)
+
+        # Convert to response format
+        session_responses = []
+        for s in sessions:
+            session_response = SessionResponse(
+                id=s.id,
+                device_name=s.device_name,
+                device_id=s.device_id,
+                ip_address=s.ip_address,
+                location_city=s.location_city,
+                location_country=s.location_country,
+                last_used_at=s.last_used_at,
+                created_at=s.created_at,
+                expires_at=s.expires_at,
+                is_current=(
+                    s == sessions[0] if sessions else False
+                ),  # Most recent = current
+            )
+            session_responses.append(session_response)
+
+        logger.info(
+            "User %s listed %s active sessions", current_user.id, len(session_responses)
+        )
+
+        return SessionListResponse(
+            sessions=session_responses, total=len(session_responses)
+        )
+
+    except Exception as e:
+        logger.exception("Error listing sessions for user %s: %s", current_user.id, e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to retrieve sessions",
+        )
+
+
+@router.delete(
+    "/{session_id}",
+    response_model=MessageResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Revoke Specific Session",
+    description="""
+    Revoke a specific session by ID.
+
+    This logs you out from that particular device.
+    You can only revoke your own sessions.
+
+    **Rate Limit**: 10 requests/minute
+    """,
+    operation_id="revoke_session",
+)
+@limiter.limit("10/minute")
+async def revoke_session(
+    request: Request,
+    session_id: UUID,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Revoke a specific session by ID.
+
+    Args:
+        session_id: UUID of the session to revoke
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Success message
+    """
+    try:
+        # Get the session
+        session = await session_service.get_session(db, str(session_id))
+
+        if not session:
+            raise NotFoundError(
+                message=f"Session {session_id} not found",
+                error_code=ErrorCode.NOT_FOUND,
+            )
+
+        # Verify session belongs to current user
+        if str(session.user_id) != str(current_user.id):
+            logger.warning(
+                "User %s attempted to revoke session %s belonging to user %s",
+                current_user.id,
+                session_id,
+                session.user_id,
+            )
+            raise AuthorizationError(
+                message="You can only revoke your own sessions",
+                error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
+            )
+
+        # Deactivate the session
+        await session_service.deactivate(db, session_id=str(session_id))
+
+        logger.info(
+            "User %s revoked session %s (%s)",
+            current_user.id,
+            session_id,
+            session.device_name,
+        )
+
+        return MessageResponse(
+            success=True,
+            message=f"Session revoked: {session.device_name or 'Unknown device'}",
+        )
+
+    except (NotFoundError, AuthorizationError):
+        raise
+    except Exception as e:
+        logger.exception("Error revoking session %s: %s", session_id, e)
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to revoke session",
+        )
+
+
+@router.delete(
+    "/me/expired",
+    response_model=MessageResponse,
+    status_code=status.HTTP_200_OK,
+    summary="Cleanup Expired Sessions",
+    description="""
+    Remove expired sessions for the current user.
+
+    This is a cleanup operation to remove old session records.
+
+    **Rate Limit**: 5 requests/minute
+    """,
+    operation_id="cleanup_expired_sessions",
+)
+@limiter.limit("5/minute")
+async def cleanup_expired_sessions(
+    request: Request,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Cleanup expired sessions for the current user.
+
+    Args:
+        current_user: Current authenticated user
+        db: Database session
+
+    Returns:
+        Success message with count of sessions cleaned
+    """
+    try:
+        # Use optimized bulk DELETE instead of N individual deletes
+        deleted_count = await session_service.cleanup_expired_for_user(
+            db, user_id=str(current_user.id)
+        )
+
+        logger.info(
+            "User %s cleaned up %s expired sessions", current_user.id, deleted_count
+        )
+
+        return MessageResponse(
+            success=True, message=f"Cleaned up {deleted_count} expired sessions"
+        )
+
+    except Exception as e:
+        logger.exception(
+            "Error cleaning up sessions for user %s: %s", current_user.id, e
+        )
+        await db.rollback()
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to cleanup sessions",
+        )

backend/app/api/routes/users.py

@@ -0,0 +1,357 @@
+"""
+User management endpoints for database operations.
+"""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, Query, Request, status
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.api.dependencies.auth import get_current_superuser, get_current_user
+from app.core.database import get_db
+from app.core.exceptions import AuthorizationError, ErrorCode
+from app.models.user import User
+from app.schemas.common import (
+    MessageResponse,
+    PaginatedResponse,
+    PaginationParams,
+    SortParams,
+    create_pagination_meta,
+)
+from app.schemas.users import PasswordChange, UserResponse, UserUpdate
+from app.services.auth_service import AuthenticationError, AuthService
+from app.services.user_service import user_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+limiter = Limiter(key_func=get_remote_address)
+
+
+@router.get(
+    "",
+    response_model=PaginatedResponse[UserResponse],
+    summary="List Users",
+    description="""
+    List all users with pagination, filtering, and sorting (admin only).
+
+    **Authentication**: Required (Bearer token)
+    **Authorization**: Superuser only
+
+    **Filtering**: is_active, is_superuser
+    **Sorting**: Any user field (email, first_name, last_name, created_at, etc.)
+
+    **Rate Limit**: 60 requests/minute
+    """,
+    operation_id="list_users",
+)
+async def list_users(
+    pagination: PaginationParams = Depends(),
+    sort: SortParams = Depends(),
+    is_active: bool | None = Query(None, description="Filter by active status"),
+    is_superuser: bool | None = Query(None, description="Filter by superuser status"),
+    current_user: User = Depends(get_current_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    List all users with pagination, filtering, and sorting.
+
+    Only accessible by superusers.
+    """
+    try:
+        # Build filters
+        filters = {}
+        if is_active is not None:
+            filters["is_active"] = is_active
+        if is_superuser is not None:
+            filters["is_superuser"] = is_superuser
+
+        # Get paginated users with total count
+        users, total = await user_service.list_users(
+            db,
+            skip=pagination.offset,
+            limit=pagination.limit,
+            sort_by=sort.sort_by,
+            sort_order=sort.sort_order.value if sort.sort_order else "asc",
+            filters=filters if filters else None,
+        )
+
+        # Create pagination metadata
+        pagination_meta = create_pagination_meta(
+            total=total,
+            page=pagination.page,
+            limit=pagination.limit,
+            items_count=len(users),
+        )
+
+        return PaginatedResponse(data=users, pagination=pagination_meta)
+    except Exception as e:
+        logger.exception("Error listing users: %s", e)
+        raise
+
+
+@router.get(
+    "/me",
+    response_model=UserResponse,
+    summary="Get Current User",
+    description="""
+    Get the current authenticated user's profile.
+
+    **Authentication**: Required (Bearer token)
+
+    **Rate Limit**: 60 requests/minute
+    """,
+    operation_id="get_current_user_profile",
+)
+async def get_current_user_profile(
+    current_user: User = Depends(get_current_user),
+) -> Any:
+    """Get current user's profile."""
+    return current_user
+
+
+@router.patch(
+    "/me",
+    response_model=UserResponse,
+    summary="Update Current User",
+    description="""
+    Update the current authenticated user's profile.
+
+    Users can update their own profile information (except is_superuser).
+
+    **Authentication**: Required (Bearer token)
+
+    **Rate Limit**: 30 requests/minute
+    """,
+    operation_id="update_current_user",
+)
+async def update_current_user(
+    user_update: UserUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Update current user's profile.
+
+    Users cannot elevate their own permissions (protected by UserUpdate schema validator).
+    """
+    try:
+        updated_user = await user_service.update_user(
+            db, user=current_user, obj_in=user_update
+        )
+        logger.info("User %s updated their profile", current_user.id)
+        return updated_user
+    except ValueError as e:
+        logger.error("Error updating user %s: %s", current_user.id, e)
+        raise
+    except Exception as e:
+        logger.exception("Unexpected error updating user %s: %s", current_user.id, e)
+        raise
+
+
+@router.get(
+    "/{user_id}",
+    response_model=UserResponse,
+    summary="Get User by ID",
+    description="""
+    Get a specific user by their ID.
+
+    **Authentication**: Required (Bearer token)
+    **Authorization**:
+    - Regular users: Can only access their own profile
+    - Superusers: Can access any profile
+
+    **Rate Limit**: 60 requests/minute
+    """,
+    operation_id="get_user_by_id",
+)
+async def get_user_by_id(
+    user_id: UUID,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Get user by ID.
+
+    Users can only view their own profile unless they are superusers.
+    """
+    # Check permissions
+    if str(user_id) != str(current_user.id) and not current_user.is_superuser:
+        logger.warning(
+            "User %s attempted to access user %s without permission",
+            current_user.id,
+            user_id,
+        )
+        raise AuthorizationError(
+            message="Not enough permissions to view this user",
+            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
+        )
+
+    # Get user
+    user = await user_service.get_user(db, str(user_id))
+    return user
+
+
+@router.patch(
+    "/{user_id}",
+    response_model=UserResponse,
+    summary="Update User",
+    description="""
+    Update a specific user by their ID.
+
+    **Authentication**: Required (Bearer token)
+    **Authorization**:
+    - Regular users: Can only update their own profile (except is_superuser)
+    - Superusers: Can update any profile
+
+    **Rate Limit**: 30 requests/minute
+    """,
+    operation_id="update_user",
+)
+async def update_user(
+    user_id: UUID,
+    user_update: UserUpdate,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Update user by ID.
+
+    Users can update their own profile. Superusers can update any profile.
+    Superuser field modification is prevented by UserUpdate schema validator.
+    """
+    # Check permissions
+    is_own_profile = str(user_id) == str(current_user.id)
+
+    if not is_own_profile and not current_user.is_superuser:
+        logger.warning(
+            "User %s attempted to update user %s without permission",
+            current_user.id,
+            user_id,
+        )
+        raise AuthorizationError(
+            message="Not enough permissions to update this user",
+            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
+        )
+
+    # Get user
+    user = await user_service.get_user(db, str(user_id))
+
+    try:
+        updated_user = await user_service.update_user(db, user=user, obj_in=user_update)
+        logger.info("User %s updated by %s", user_id, current_user.id)
+        return updated_user
+    except ValueError as e:
+        logger.error("Error updating user %s: %s", user_id, e)
+        raise
+    except Exception as e:
+        logger.exception("Unexpected error updating user %s: %s", user_id, e)
+        raise
+
+
+@router.patch(
+    "/me/password",
+    response_model=MessageResponse,
+    summary="Change Current User Password",
+    description="""
+    Change the current authenticated user's password.
+
+    Requires the current password for verification.
+
+    **Authentication**: Required (Bearer token)
+
+    **Rate Limit**: 5 requests/minute
+    """,
+    operation_id="change_current_user_password",
+)
+@limiter.limit("5/minute")
+async def change_current_user_password(
+    request: Request,
+    password_change: PasswordChange,
+    current_user: User = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Change current user's password.
+
+    Requires current password for verification.
+    """
+    try:
+        success = await AuthService.change_password(
+            db=db,
+            user_id=current_user.id,
+            current_password=password_change.current_password,
+            new_password=password_change.new_password,
+        )
+
+        if success:
+            logger.info("User %s changed their password", current_user.id)
+            return MessageResponse(
+                success=True, message="Password changed successfully"
+            )
+    except AuthenticationError as e:
+        logger.warning(
+            "Failed password change attempt for user %s: %s", current_user.id, e
+        )
+        raise AuthorizationError(
+            message=str(e), error_code=ErrorCode.INVALID_CREDENTIALS
+        )
+    except Exception as e:
+        logger.error("Error changing password for user %s: %s", current_user.id, e)
+        raise
+
+
+@router.delete(
+    "/{user_id}",
+    status_code=status.HTTP_200_OK,
+    response_model=MessageResponse,
+    summary="Delete User",
+    description="""
+    Delete a specific user by their ID.
+
+    **Authentication**: Required (Bearer token)
+    **Authorization**: Superuser only
+
+    **Rate Limit**: 10 requests/minute
+
+    **Note**: This performs a hard delete. Consider implementing soft deletes for production.
+    """,
+    operation_id="delete_user",
+)
+async def delete_user(
+    user_id: UUID,
+    current_user: User = Depends(get_current_superuser),
+    db: AsyncSession = Depends(get_db),
+) -> Any:
+    """
+    Delete user by ID (superuser only).
+
+    This is a hard delete operation.
+    """
+    # Prevent self-deletion
+    if str(user_id) == str(current_user.id):
+        raise AuthorizationError(
+            message="Cannot delete your own account",
+            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
+        )
+
+    # Get user (raises NotFoundError if not found)
+    await user_service.get_user(db, str(user_id))
+
+    try:
+        # Use soft delete instead of hard delete
+        await user_service.soft_delete_user(db, str(user_id))
+        logger.info("User %s soft-deleted by %s", user_id, current_user.id)
+        return MessageResponse(
+            success=True, message=f"User {user_id} deleted successfully"
+        )
+    except ValueError as e:
+        logger.error("Error deleting user %s: %s", user_id, e)
+        raise
+    except Exception as e:
+        logger.exception("Unexpected error deleting user %s: %s", user_id, e)
+        raise

backend/app/core/auth.py

@@ -1,53 +1,94 @@
-import logging
+import asyncio
-logging.getLogger('passlib').setLevel(logging.ERROR)
-
-from datetime import datetime, timedelta, timezone
-from typing import Any, Dict, Optional, Union
 import uuid
+from datetime import UTC, datetime, timedelta
+from functools import partial
+from typing import Any
 
-from jose import jwt, JWTError
+import bcrypt
-from passlib.context import CryptContext
+import jwt
+from jwt.exceptions import (
+    ExpiredSignatureError,
+    InvalidTokenError,
+    MissingRequiredClaimError,
+)
 from pydantic import ValidationError
 
 from app.core.config import settings
 from app.schemas.users import TokenData, TokenPayload
 
 
-# Password hashing context
-pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
-
 # Custom exceptions for auth
 class AuthError(Exception):
     """Base authentication error"""
-    pass
+
 
 class TokenExpiredError(AuthError):
     """Token has expired"""
-    pass
+
 
 class TokenInvalidError(AuthError):
     """Token is invalid"""
-    pass
+
 
 class TokenMissingClaimError(AuthError):
     """Token is missing a required claim"""
-    pass
 
 
 def verify_password(plain_password: str, hashed_password: str) -> bool:
-    """Verify a password against a hash."""
+    """Verify a password against a bcrypt hash."""
-    return pwd_context.verify(plain_password, hashed_password)
+    return bcrypt.checkpw(
+        plain_password.encode("utf-8"), hashed_password.encode("utf-8")
+    )
 
 
 def get_password_hash(password: str) -> str:
-    """Generate a password hash."""
+    """Generate a bcrypt password hash."""
-    return pwd_context.hash(password)
+    salt = bcrypt.gensalt()
+    return bcrypt.hashpw(password.encode("utf-8"), salt).decode("utf-8")
+
+
+async def verify_password_async(plain_password: str, hashed_password: str) -> bool:
+    """
+    Verify a password against a hash asynchronously.
+
+    Runs the CPU-intensive bcrypt operation in a thread pool to avoid
+    blocking the event loop.
+
+    Args:
+        plain_password: Plain text password to verify
+        hashed_password: Hashed password to verify against
+
+    Returns:
+        True if password matches, False otherwise
+    """
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(
+        None, partial(verify_password, plain_password, hashed_password)
+    )
+
+
+async def get_password_hash_async(password: str) -> str:
+    """
+    Generate a password hash asynchronously.
+
+    Runs the CPU-intensive bcrypt operation in a thread pool to avoid
+    blocking the event loop. This is especially important during user
+    registration and password changes.
+
+    Args:
+        password: Plain text password to hash
+
+    Returns:
+        Hashed password string
+    """
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, get_password_hash, password)
 
 
 def create_access_token(
-        subject: Union[str, Any],
+    subject: str | Any,
-        expires_delta: Optional[timedelta] = None,
+    expires_delta: timedelta | None = None,
-        claims: Optional[Dict[str, Any]] = None
+    claims: dict[str, Any] | None = None,
 ) -> str:
     """
     Create a JWT access token.
@@ -61,17 +102,19 @@ def create_access_token(
         Encoded JWT token
     """
     if expires_delta:
-        expire = datetime.now(timezone.utc) + expires_delta
+        expire = datetime.now(UTC) + expires_delta
     else:
-        expire = datetime.now(timezone.utc) + timedelta(minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES)
+        expire = datetime.now(UTC) + timedelta(
+            minutes=settings.ACCESS_TOKEN_EXPIRE_MINUTES
+        )
 
     # Base token data
     to_encode = {
         "sub": str(subject),
         "exp": expire,
-        "iat": datetime.now(tz=timezone.utc),
+        "iat": datetime.now(tz=UTC),
         "jti": str(uuid.uuid4()),
-        "type": "access"
+        "type": "access",
     }
 
     # Add custom claims
@@ -79,18 +122,11 @@ def create_access_token(
         to_encode.update(claims)
 
     # Create the JWT
-    encoded_jwt = jwt.encode(
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
-        to_encode,
-        settings.SECRET_KEY,
-        algorithm=settings.ALGORITHM
-    )
-
-    return encoded_jwt
 
 
 def create_refresh_token(
-        subject: Union[str, Any],
+    subject: str | Any, expires_delta: timedelta | None = None
-        expires_delta: Optional[timedelta] = None
 ) -> str:
     """
     Create a JWT refresh token.
@@ -103,28 +139,22 @@ def create_refresh_token(
         Encoded JWT refresh token
     """
     if expires_delta:
-        expire = datetime.now(timezone.utc) + expires_delta
+        expire = datetime.now(UTC) + expires_delta
     else:
-        expire = datetime.now(timezone.utc) + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS)
+        expire = datetime.now(UTC) + timedelta(days=settings.REFRESH_TOKEN_EXPIRE_DAYS)
 
     to_encode = {
         "sub": str(subject),
         "exp": expire,
-        "iat": datetime.now(timezone.utc),
+        "iat": datetime.now(UTC),
         "jti": str(uuid.uuid4()),
-        "type": "refresh"
+        "type": "refresh",
     }
 
-    encoded_jwt = jwt.encode(
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
-        to_encode,
-        settings.SECRET_KEY,
-        algorithm=settings.ALGORITHM
-    )
-
-    return encoded_jwt
 
 
-def decode_token(token: str, verify_type: Optional[str] = None) -> TokenPayload:
+def decode_token(token: str, verify_type: str | None = None) -> TokenPayload:
     """
     Decode and verify a JWT token.
 
@@ -141,12 +171,35 @@ def decode_token(token: str, verify_type: Optional[str] = None) -> TokenPayload:
         TokenMissingClaimError: If a required claim is missing
     """
     try:
+        # Decode token with strict algorithm validation
         payload = jwt.decode(
             token,
             settings.SECRET_KEY,
-            algorithms=[settings.ALGORITHM]
+            algorithms=[settings.ALGORITHM],
+            options={
+                "verify_signature": True,
+                "verify_exp": True,
+                "verify_iat": True,
+                "require": ["exp", "sub", "iat"],
+            },
         )
 
+        # SECURITY: Explicitly verify the algorithm to prevent algorithm confusion attacks
+        # Decode header to check algorithm (without verification, just to inspect)
+        header = jwt.get_unverified_header(token)
+        token_algorithm = header.get("alg", "").upper()
+
+        # Reject weak or unexpected algorithms
+        # NOTE: These are defensive checks that provide defense-in-depth.
+        # PyJWT rejects these tokens BEFORE we reach here,
+        # but we keep these checks in case the library changes or is misconfigured.
+        # Coverage: Marked as pragma since library catches first (see tests/core/test_auth_security.py)
+        if token_algorithm == "NONE":  # pragma: no cover
+            raise TokenInvalidError("Algorithm 'none' is not allowed")
+
+        if token_algorithm != settings.ALGORITHM.upper():  # pragma: no cover
+            raise TokenInvalidError(f"Invalid algorithm: {token_algorithm}")
+
         # Check required claims before Pydantic validation
         if not payload.get("sub"):
             raise TokenMissingClaimError("Token missing 'sub' claim")
@@ -159,10 +212,11 @@ def decode_token(token: str, verify_type: Optional[str] = None) -> TokenPayload:
         token_data = TokenPayload(**payload)
         return token_data
 
-    except JWTError as e:
+    except ExpiredSignatureError:
-        # Check if the error is due to an expired token
+        raise TokenExpiredError("Token has expired")
-        if "expired" in str(e).lower():
+    except MissingRequiredClaimError as e:
-            raise TokenExpiredError("Token has expired")
+        raise TokenMissingClaimError(f"Token missing required claim: {e}")
+    except InvalidTokenError:
         raise TokenInvalidError("Invalid authentication token")
     except ValidationError:
         raise TokenInvalidError("Invalid token payload")
@@ -182,4 +236,4 @@ def get_token_data(token: str) -> TokenData:
     user_id = payload.sub
     is_superuser = payload.is_superuser or False
 
-    return TokenData(user_id=uuid.UUID(user_id), is_superuser=is_superuser)
+    return TokenData(user_id=uuid.UUID(user_id), is_superuser=is_superuser)

backend/app/core/config.py

@@ -1,20 +1,39 @@
+import logging
+
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings
-from typing import Optional, List
 
 
 class Settings(BaseSettings):
-    PROJECT_NAME: str = "EventSpace"
+    PROJECT_NAME: str = "PragmaStack"
     VERSION: str = "1.0.0"
     API_V1_STR: str = "/api/v1"
 
+    # Environment (must be before SECRET_KEY for validation)
+    ENVIRONMENT: str = Field(
+        default="development",
+        description="Environment: development, staging, or production",
+    )
+    DEMO_MODE: bool = Field(
+        default=False,
+        description="Enable demo mode (relaxed security, demo users)",
+    )
+
+    # Security: Content Security Policy
+    # Set to False to disable CSP entirely (not recommended)
+    # Set to True for strict CSP (blocks most external resources)
+    # Set to "relaxed" for modern frontend development
+    CSP_MODE: str = Field(
+        default="relaxed", description="CSP mode: 'strict', 'relaxed', or 'disabled'"
+    )
+
     # Database configuration
     POSTGRES_USER: str = "postgres"
     POSTGRES_PASSWORD: str = "postgres"
     POSTGRES_HOST: str = "localhost"
     POSTGRES_PORT: str = "5432"
     POSTGRES_DB: str = "app"
-    DATABASE_URL: Optional[str] = None
+    DATABASE_URL: str | None = None
-    REFRESH_TOKEN_EXPIRE_DAYS: int = 60
     db_pool_size: int = 20  # Default connection pool size
     db_max_overflow: int = 50  # Maximum overflow connections
     db_pool_timeout: int = 30  # Seconds to wait for a connection
@@ -39,21 +58,166 @@ class Settings(BaseSettings):
         return self.DATABASE_URL
 
     # JWT configuration
-    SECRET_KEY: str = "your_secret_key_here"
+    SECRET_KEY: str = Field(
+        default="dev_only_insecure_key_change_in_production_32chars_min",
+        min_length=32,
+        description="JWT signing key. MUST be changed in production. Generate with: python -c 'import secrets; print(secrets.token_urlsafe(32))'",
+    )
     ALGORITHM: str = "HS256"
-    ACCESS_TOKEN_EXPIRE_MINUTES: int = 1440 # 1 day
+    ACCESS_TOKEN_EXPIRE_MINUTES: int = 15  # 15 minutes (production standard)
+    REFRESH_TOKEN_EXPIRE_DAYS: int = 7  # 7 days
 
     # CORS configuration
-    BACKEND_CORS_ORIGINS: List[str] = ["http://localhost:3000"]
+    BACKEND_CORS_ORIGINS: list[str] = ["http://localhost:3000"]
+
+    # Frontend URL for email links
+    FRONTEND_URL: str = Field(
+        default="http://localhost:3000",
+        description="Frontend application URL for email links",
+    )
+
+    # OAuth Configuration
+    OAUTH_ENABLED: bool = Field(
+        default=False,
+        description="Enable OAuth authentication (social login)",
+    )
+    OAUTH_AUTO_LINK_BY_EMAIL: bool = Field(
+        default=True,
+        description="Automatically link OAuth accounts to existing users with matching email",
+    )
+    OAUTH_STATE_EXPIRE_MINUTES: int = Field(
+        default=10,
+        description="OAuth state parameter expiration time in minutes",
+    )
+
+    # Google OAuth
+    OAUTH_GOOGLE_CLIENT_ID: str | None = Field(
+        default=None,
+        description="Google OAuth client ID from Google Cloud Console",
+    )
+    OAUTH_GOOGLE_CLIENT_SECRET: str | None = Field(
+        default=None,
+        description="Google OAuth client secret from Google Cloud Console",
+    )
+
+    # GitHub OAuth
+    OAUTH_GITHUB_CLIENT_ID: str | None = Field(
+        default=None,
+        description="GitHub OAuth client ID from GitHub Developer Settings",
+    )
+    OAUTH_GITHUB_CLIENT_SECRET: str | None = Field(
+        default=None,
+        description="GitHub OAuth client secret from GitHub Developer Settings",
+    )
+
+    # OAuth Provider Mode (for MCP clients - skeleton)
+    OAUTH_PROVIDER_ENABLED: bool = Field(
+        default=False,
+        description="Enable OAuth provider mode (act as authorization server for MCP clients)",
+    )
+    OAUTH_ISSUER: str = Field(
+        default="http://localhost:8000",
+        description="OAuth issuer URL (your API base URL)",
+    )
+
+    @property
+    def enabled_oauth_providers(self) -> list[str]:
+        """Get list of enabled OAuth providers based on configured credentials."""
+        providers = []
+        if self.OAUTH_GOOGLE_CLIENT_ID and self.OAUTH_GOOGLE_CLIENT_SECRET:
+            providers.append("google")
+        if self.OAUTH_GITHUB_CLIENT_ID and self.OAUTH_GITHUB_CLIENT_SECRET:
+            providers.append("github")
+        return providers
 
     # Admin user
-    FIRST_SUPERUSER_EMAIL: Optional[str] = None
+    FIRST_SUPERUSER_EMAIL: str | None = Field(
-    FIRST_SUPERUSER_PASSWORD: Optional[str] = None
+        default=None, description="Email for first superuser account"
+    )
+    FIRST_SUPERUSER_PASSWORD: str | None = Field(
+        default=None, description="Password for first superuser (min 12 characters)"
+    )
 
-    class Config:
+    @field_validator("SECRET_KEY")
-        env_file = ".env"
+    @classmethod
-        env_file_encoding = "utf-8"
+    def validate_secret_key(cls, v: str, info) -> str:
-        case_sensitive = True
+        """Validate SECRET_KEY is secure, especially in production."""
+        # Get environment from values if available
+        values_data = info.data if info.data else {}
+        env = values_data.get("ENVIRONMENT", "development")
+
+        if v.startswith("your_secret_key_here"):
+            if env == "production":
+                raise ValueError(
+                    "SECRET_KEY must be set to a secure random value in production. "
+                    "Generate one with: python -c 'import secrets; print(secrets.token_urlsafe(32))'"
+                )
+            # Warn in development but allow
+            logger = logging.getLogger(__name__)
+            logger.warning(
+                "⚠️  Using default SECRET_KEY. This is ONLY acceptable in development. "
+                "Generate a secure key with: python -c 'import secrets; print(secrets.token_urlsafe(32))'"
+            )
+
+        if len(v) < 32:
+            raise ValueError(
+                "SECRET_KEY must be at least 32 characters long for security"
+            )
+
+        return v
+
+    @field_validator("FIRST_SUPERUSER_PASSWORD")
+    @classmethod
+    def validate_superuser_password(cls, v: str | None, info) -> str | None:
+        """Validate superuser password strength."""
+        if v is None:
+            return v
+
+        # Get environment from values if available
+        values_data = info.data if info.data else {}
+        demo_mode = values_data.get("DEMO_MODE", False)
+
+        if demo_mode:
+            # In demo mode, allow specific weak passwords for demo accounts
+            demo_passwords = {"Demo123!", "Admin123!"}
+            if v in demo_passwords:
+                return v
+
+        if len(v) < 12:
+            raise ValueError("FIRST_SUPERUSER_PASSWORD must be at least 12 characters")
+
+        # Check for common weak passwords
+        weak_passwords = {
+            "admin123",
+            "Admin123",
+            "password123",
+            "Password123",
+            "123456789012",
+        }
+        if v in weak_passwords:
+            raise ValueError(
+                "FIRST_SUPERUSER_PASSWORD is too weak. "
+                "Use a strong, unique password with mixed case, numbers, and symbols."
+            )
+
+        # Basic strength check
+        has_lower = any(c.islower() for c in v)
+        has_upper = any(c.isupper() for c in v)
+        has_digit = any(c.isdigit() for c in v)
+
+        if not (has_lower and has_upper and has_digit):
+            raise ValueError(
+                "FIRST_SUPERUSER_PASSWORD must contain lowercase, uppercase, and digits"
+            )
+
+        return v
+
+    model_config = {
+        "env_file": "../.env",
+        "env_file_encoding": "utf-8",
+        "case_sensitive": True,
+        "extra": "ignore",  # Ignore extra fields from .env (e.g., frontend-specific vars)
+    }
 
 
-settings = Settings()
+settings = Settings()

backend/app/core/database.py

@@ -1,60 +1,186 @@
 # app/core/database.py
+"""
+Database configuration using SQLAlchemy 2.0 and asyncpg.
+
+This module provides async database connectivity with proper connection pooling
+and session management for FastAPI endpoints.
+"""
+
 import logging
-from sqlalchemy import create_engine
+from collections.abc import AsyncGenerator
-from sqlalchemy.ext.declarative import declarative_base
+from contextlib import asynccontextmanager
-from sqlalchemy.orm import sessionmaker
+
-from sqlalchemy.ext.compiler import compiles
+from sqlalchemy import text
 from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+from sqlalchemy.ext.compiler import compiles
+from sqlalchemy.orm import DeclarativeBase
 
 from app.core.config import settings
 
 # Configure logging
 logger = logging.getLogger(__name__)
 
+
 # SQLite compatibility for testing
-@compiles(JSONB, 'sqlite')
+@compiles(JSONB, "sqlite")
 def compile_jsonb_sqlite(type_, compiler, **kw):
     return "TEXT"
 
-@compiles(UUID, 'sqlite')
+
+@compiles(UUID, "sqlite")
 def compile_uuid_sqlite(type_, compiler, **kw):
     return "TEXT"
 
-# Declarative base for models
-Base = declarative_base()
 
-# Create engine with optimized settings for PostgreSQL
+# Declarative base for models (SQLAlchemy 2.0 style)
-def create_production_engine():
+class Base(DeclarativeBase):
-    return create_engine(
+    """Base class for all database models."""
-        settings.database_url,
-        # Connection pool settings
-        pool_size=settings.db_pool_size,
-        max_overflow=settings.db_max_overflow,
-        pool_timeout=settings.db_pool_timeout,
-        pool_recycle=settings.db_pool_recycle,
-        pool_pre_ping=True,
-        # Query execution settings
-        connect_args={
-            "application_name": "eventspace",
-            "keepalives": 1,
-            "keepalives_idle": 60,
-            "keepalives_interval": 10,
-            "keepalives_count": 5,
-            "options": "-c timezone=UTC",
-        },
-        isolation_level="READ COMMITTED",
-        echo=settings.sql_echo,
-        echo_pool=settings.sql_echo_pool,
-    )
 
-# Default production engine and session factory
-engine = create_production_engine()
-SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
 
-# FastAPI dependency
+def get_async_database_url(url: str) -> str:
-def get_db():
+    """
-    db = SessionLocal()
+    Convert sync database URL to async URL.
+
+    postgresql:// -> postgresql+asyncpg://
+    sqlite:// -> sqlite+aiosqlite://
+    """
+    if url.startswith("postgresql://"):
+        return url.replace("postgresql://", "postgresql+asyncpg://")
+    elif url.startswith("sqlite://"):
+        return url.replace("sqlite://", "sqlite+aiosqlite://")
+    return url
+
+
+# Create async engine with optimized settings
+def create_async_production_engine() -> AsyncEngine:
+    """Create an async database engine with production settings."""
+    async_url = get_async_database_url(settings.database_url)
+
+    # Base engine config
+    engine_config = {
+        "pool_size": settings.db_pool_size,
+        "max_overflow": settings.db_max_overflow,
+        "pool_timeout": settings.db_pool_timeout,
+        "pool_recycle": settings.db_pool_recycle,
+        "pool_pre_ping": True,
+        "echo": settings.sql_echo,
+        "echo_pool": settings.sql_echo_pool,
+    }
+
+    # Add PostgreSQL-specific connect_args
+    if "postgresql" in async_url:
+        engine_config["connect_args"] = {  # type: ignore[assignment]
+            "server_settings": {
+                "application_name": settings.PROJECT_NAME,
+                "timezone": "UTC",
+            },
+            # asyncpg-specific settings
+            "command_timeout": 60,
+            "timeout": 10,
+        }
+
+    return create_async_engine(async_url, **engine_config)
+
+
+# Create async engine and session factory
+engine = create_async_production_engine()
+SessionLocal = async_sessionmaker(
+    engine,
+    class_=AsyncSession,
+    autocommit=False,
+    autoflush=False,
+    expire_on_commit=False,  # Prevent unnecessary queries after commit
+)
+
+
+# FastAPI dependency for async database sessions
+async def get_db() -> AsyncGenerator[AsyncSession, None]:
+    """
+    FastAPI dependency that provides an async database session.
+    Automatically closes the session after the request completes.
+
+    Usage:
+        @router.get("/users")
+        async def get_users(db: AsyncSession = Depends(get_db)):
+            result = await db.execute(select(User))
+            return result.scalars().all()
+    """
+    async with SessionLocal() as session:
+        try:
+            yield session
+        finally:
+            await session.close()
+
+
+@asynccontextmanager
+async def async_transaction_scope() -> AsyncGenerator[AsyncSession, None]:
+    """
+    Provide an async transactional scope for database operations.
+
+    Automatically commits on success or rolls back on exception.
+    Useful for grouping multiple operations in a single transaction.
+
+    Usage:
+        async with async_transaction_scope() as db:
+            user = await user_repo.create(db, obj_in=user_create)
+            profile = await profile_repo.create(db, obj_in=profile_create)
+            # Both operations committed together
+    """
+    async with SessionLocal() as session:
+        try:
+            yield session
+            await session.commit()
+            logger.debug("Async transaction committed successfully")
+        except Exception as e:
+            await session.rollback()
+            logger.error("Async transaction failed, rolling back: %s", e)
+            raise
+        finally:
+            await session.close()
+
+
+async def check_async_database_health() -> bool:
+    """
+    Check if async database connection is healthy.
+    Returns True if connection is successful, False otherwise.
+    """
     try:
-        yield db
+        async with async_transaction_scope() as db:
-    finally:
+            await db.execute(text("SELECT 1"))
-        db.close()
+        return True
+    except Exception as e:
+        logger.error("Async database health check failed: %s", e)
+        return False
+
+
+# Alias for consistency with main.py
+check_database_health = check_async_database_health
+
+
+async def init_async_db() -> None:
+    """
+    Initialize async database tables.
+
+    This creates all tables defined in the models.
+    Should only be used in development or testing.
+    In production, use Alembic migrations.
+    """
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+    logger.info("Async database tables created")
+
+
+async def close_async_db() -> None:
+    """
+    Close all async database connections.
+
+    Should be called during application shutdown.
+    """
+    await engine.dispose()
+    logger.info("Async database connections closed")

backend/app/core/demo_data.json

@@ -0,0 +1,366 @@
+{
+    "organizations": [
+        {
+            "name": "Acme Corp",
+            "slug": "acme-corp",
+            "description": "A leading provider of coyote-catching equipment."
+        },
+        {
+            "name": "Globex Corporation",
+            "slug": "globex",
+            "description": "We own the East Coast."
+        },
+        {
+            "name": "Soylent Corp",
+            "slug": "soylent",
+            "description": "Making food for the future."
+        },
+        {
+            "name": "Initech",
+            "slug": "initech",
+            "description": "Software for the soul."
+        },
+        {
+            "name": "Umbrella Corporation",
+            "slug": "umbrella",
+            "description": "Our business is life itself."
+        },
+        {
+            "name": "Massive Dynamic",
+            "slug": "massive-dynamic",
+            "description": "What don't we do?"
+        }
+    ],
+    "users": [
+        {
+            "email": "demo@example.com",
+            "password": "DemoPass1234!",
+            "first_name": "Demo",
+            "last_name": "User",
+            "is_superuser": false,
+            "organization_slug": "acme-corp",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "alice@acme.com",
+            "password": "Demo123!",
+            "first_name": "Alice",
+            "last_name": "Smith",
+            "is_superuser": false,
+            "organization_slug": "acme-corp",
+            "role": "admin",
+            "is_active": true
+        },
+        {
+            "email": "bob@acme.com",
+            "password": "Demo123!",
+            "first_name": "Bob",
+            "last_name": "Jones",
+            "is_superuser": false,
+            "organization_slug": "acme-corp",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "charlie@acme.com",
+            "password": "Demo123!",
+            "first_name": "Charlie",
+            "last_name": "Brown",
+            "is_superuser": false,
+            "organization_slug": "acme-corp",
+            "role": "member",
+            "is_active": false
+        },
+        {
+            "email": "diana@acme.com",
+            "password": "Demo123!",
+            "first_name": "Diana",
+            "last_name": "Prince",
+            "is_superuser": false,
+            "organization_slug": "acme-corp",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "carol@globex.com",
+            "password": "Demo123!",
+            "first_name": "Carol",
+            "last_name": "Williams",
+            "is_superuser": false,
+            "organization_slug": "globex",
+            "role": "owner",
+            "is_active": true
+        },
+        {
+            "email": "dan@globex.com",
+            "password": "Demo123!",
+            "first_name": "Dan",
+            "last_name": "Miller",
+            "is_superuser": false,
+            "organization_slug": "globex",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "ellen@globex.com",
+            "password": "Demo123!",
+            "first_name": "Ellen",
+            "last_name": "Ripley",
+            "is_superuser": false,
+            "organization_slug": "globex",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "fred@globex.com",
+            "password": "Demo123!",
+            "first_name": "Fred",
+            "last_name": "Flintstone",
+            "is_superuser": false,
+            "organization_slug": "globex",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "dave@soylent.com",
+            "password": "Demo123!",
+            "first_name": "Dave",
+            "last_name": "Brown",
+            "is_superuser": false,
+            "organization_slug": "soylent",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "gina@soylent.com",
+            "password": "Demo123!",
+            "first_name": "Gina",
+            "last_name": "Torres",
+            "is_superuser": false,
+            "organization_slug": "soylent",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "harry@soylent.com",
+            "password": "Demo123!",
+            "first_name": "Harry",
+            "last_name": "Potter",
+            "is_superuser": false,
+            "organization_slug": "soylent",
+            "role": "admin",
+            "is_active": true
+        },
+        {
+            "email": "eve@initech.com",
+            "password": "Demo123!",
+            "first_name": "Eve",
+            "last_name": "Davis",
+            "is_superuser": false,
+            "organization_slug": "initech",
+            "role": "admin",
+            "is_active": true
+        },
+        {
+            "email": "iris@initech.com",
+            "password": "Demo123!",
+            "first_name": "Iris",
+            "last_name": "West",
+            "is_superuser": false,
+            "organization_slug": "initech",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "jack@initech.com",
+            "password": "Demo123!",
+            "first_name": "Jack",
+            "last_name": "Sparrow",
+            "is_superuser": false,
+            "organization_slug": "initech",
+            "role": "member",
+            "is_active": false
+        },
+        {
+            "email": "frank@umbrella.com",
+            "password": "Demo123!",
+            "first_name": "Frank",
+            "last_name": "Miller",
+            "is_superuser": false,
+            "organization_slug": "umbrella",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "george@umbrella.com",
+            "password": "Demo123!",
+            "first_name": "George",
+            "last_name": "Costanza",
+            "is_superuser": false,
+            "organization_slug": "umbrella",
+            "role": "member",
+            "is_active": false
+        },
+        {
+            "email": "kate@umbrella.com",
+            "password": "Demo123!",
+            "first_name": "Kate",
+            "last_name": "Bishop",
+            "is_superuser": false,
+            "organization_slug": "umbrella",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "leo@massive.com",
+            "password": "Demo123!",
+            "first_name": "Leo",
+            "last_name": "Messi",
+            "is_superuser": false,
+            "organization_slug": "massive-dynamic",
+            "role": "owner",
+            "is_active": true
+        },
+        {
+            "email": "mary@massive.com",
+            "password": "Demo123!",
+            "first_name": "Mary",
+            "last_name": "Jane",
+            "is_superuser": false,
+            "organization_slug": "massive-dynamic",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "nathan@massive.com",
+            "password": "Demo123!",
+            "first_name": "Nathan",
+            "last_name": "Drake",
+            "is_superuser": false,
+            "organization_slug": "massive-dynamic",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "olivia@massive.com",
+            "password": "Demo123!",
+            "first_name": "Olivia",
+            "last_name": "Dunham",
+            "is_superuser": false,
+            "organization_slug": "massive-dynamic",
+            "role": "admin",
+            "is_active": true
+        },
+        {
+            "email": "peter@massive.com",
+            "password": "Demo123!",
+            "first_name": "Peter",
+            "last_name": "Parker",
+            "is_superuser": false,
+            "organization_slug": "massive-dynamic",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "quinn@massive.com",
+            "password": "Demo123!",
+            "first_name": "Quinn",
+            "last_name": "Mallory",
+            "is_superuser": false,
+            "organization_slug": "massive-dynamic",
+            "role": "member",
+            "is_active": true
+        },
+        {
+            "email": "grace@example.com",
+            "password": "Demo123!",
+            "first_name": "Grace",
+            "last_name": "Hopper",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": true
+        },
+        {
+            "email": "heidi@example.com",
+            "password": "Demo123!",
+            "first_name": "Heidi",
+            "last_name": "Klum",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": true
+        },
+        {
+            "email": "ivan@example.com",
+            "password": "Demo123!",
+            "first_name": "Ivan",
+            "last_name": "Drago",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": false
+        },
+        {
+            "email": "rachel@example.com",
+            "password": "Demo123!",
+            "first_name": "Rachel",
+            "last_name": "Green",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": true
+        },
+        {
+            "email": "sam@example.com",
+            "password": "Demo123!",
+            "first_name": "Sam",
+            "last_name": "Wilson",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": true
+        },
+        {
+            "email": "tony@example.com",
+            "password": "Demo123!",
+            "first_name": "Tony",
+            "last_name": "Stark",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": true
+        },
+        {
+            "email": "una@example.com",
+            "password": "Demo123!",
+            "first_name": "Una",
+            "last_name": "Chin-Riley",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": false
+        },
+        {
+            "email": "victor@example.com",
+            "password": "Demo123!",
+            "first_name": "Victor",
+            "last_name": "Von Doom",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": true
+        },
+        {
+            "email": "wanda@example.com",
+            "password": "Demo123!",
+            "first_name": "Wanda",
+            "last_name": "Maximoff",
+            "is_superuser": false,
+            "organization_slug": null,
+            "role": null,
+            "is_active": true
+        }
+    ]
+}

backend/app/core/exceptions.py

@@ -0,0 +1,272 @@
+"""
+Custom exceptions and global exception handlers for the API.
+"""
+
+import logging
+
+from fastapi import HTTPException, Request, status
+from fastapi.exceptions import RequestValidationError
+from fastapi.responses import JSONResponse
+from pydantic import ValidationError
+
+from app.schemas.errors import ErrorCode, ErrorDetail, ErrorResponse
+
+logger = logging.getLogger(__name__)
+
+
+class APIException(HTTPException):
+    """
+    Base exception class with error code support.
+
+    This exception provides a standardized way to raise HTTP exceptions
+    with machine-readable error codes.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        error_code: ErrorCode,
+        message: str,
+        field: str | None = None,
+        headers: dict | None = None,
+    ):
+        self.error_code = error_code
+        self.field = field
+        self.message = message
+        super().__init__(status_code=status_code, detail=message, headers=headers)
+
+
+class AuthenticationError(APIException):
+    """Raised when authentication fails."""
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        error_code: ErrorCode = ErrorCode.INVALID_CREDENTIALS,
+        field: str | None = None,
+    ):
+        super().__init__(
+            status_code=status.HTTP_401_UNAUTHORIZED,
+            error_code=error_code,
+            message=message,
+            field=field,
+            headers={"WWW-Authenticate": "Bearer"},
+        )
+
+
+class AuthorizationError(APIException):
+    """Raised when user lacks required permissions."""
+
+    def __init__(
+        self,
+        message: str = "Insufficient permissions",
+        error_code: ErrorCode = ErrorCode.INSUFFICIENT_PERMISSIONS,
+    ):
+        super().__init__(
+            status_code=status.HTTP_403_FORBIDDEN,
+            error_code=error_code,
+            message=message,
+        )
+
+
+class NotFoundError(APIException):
+    """Raised when a resource is not found."""
+
+    def __init__(
+        self,
+        message: str = "Resource not found",
+        error_code: ErrorCode = ErrorCode.NOT_FOUND,
+    ):
+        super().__init__(
+            status_code=status.HTTP_404_NOT_FOUND,
+            error_code=error_code,
+            message=message,
+        )
+
+
+class DuplicateError(APIException):
+    """Raised when attempting to create a duplicate resource."""
+
+    def __init__(
+        self,
+        message: str = "Resource already exists",
+        error_code: ErrorCode = ErrorCode.DUPLICATE_ENTRY,
+        field: str | None = None,
+    ):
+        super().__init__(
+            status_code=status.HTTP_409_CONFLICT,
+            error_code=error_code,
+            message=message,
+            field=field,
+        )
+
+
+class ValidationException(APIException):
+    """Raised when input validation fails."""
+
+    def __init__(
+        self,
+        message: str = "Validation error",
+        error_code: ErrorCode = ErrorCode.VALIDATION_ERROR,
+        field: str | None = None,
+    ):
+        super().__init__(
+            status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+            error_code=error_code,
+            message=message,
+            field=field,
+        )
+
+
+class DatabaseError(APIException):
+    """Raised when a database operation fails."""
+
+    def __init__(
+        self,
+        message: str = "Database operation failed",
+        error_code: ErrorCode = ErrorCode.DATABASE_ERROR,
+    ):
+        super().__init__(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            error_code=error_code,
+            message=message,
+        )
+
+
+# Global exception handlers
+
+
+async def api_exception_handler(request: Request, exc: APIException) -> JSONResponse:
+    """
+    Handler for APIException and its subclasses.
+
+    Returns a standardized error response with error code and message.
+    """
+    logger.warning(
+        "API exception: %s - %s (status: %s, path: %s)",
+        exc.error_code,
+        exc.message,
+        exc.status_code,
+        request.url.path,
+    )
+
+    error_response = ErrorResponse(
+        errors=[ErrorDetail(code=exc.error_code, message=exc.message, field=exc.field)]
+    )
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response.model_dump(),
+        headers=exc.headers,
+    )
+
+
+async def validation_exception_handler(
+    request: Request, exc: RequestValidationError | ValidationError
+) -> JSONResponse:
+    """
+    Handler for Pydantic validation errors.
+
+    Converts Pydantic validation errors to standardized error response format.
+    """
+    errors = []
+
+    if isinstance(exc, RequestValidationError):
+        validation_errors = exc.errors()
+    else:
+        validation_errors = exc.errors()
+
+    for error in validation_errors:
+        # Extract field name from error location
+        field = None
+        if error.get("loc") and len(error["loc"]) > 1:
+            # Skip 'body' or 'query' prefix in location
+            field = ".".join(str(x) for x in error["loc"][1:])
+
+        errors.append(
+            ErrorDetail(
+                code=ErrorCode.VALIDATION_ERROR, message=error["msg"], field=field
+            )
+        )
+
+    logger.warning(
+        "Validation error: %s errors (path: %s)", len(errors), request.url.path
+    )
+
+    error_response = ErrorResponse(errors=errors)
+
+    return JSONResponse(
+        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
+        content=error_response.model_dump(),
+    )
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> JSONResponse:
+    """
+    Handler for standard HTTPException.
+
+    Converts standard FastAPI HTTPException to standardized error response format.
+    """
+    # Map status codes to error codes
+    status_code_to_error_code = {
+        400: ErrorCode.INVALID_INPUT,
+        401: ErrorCode.AUTHENTICATION_REQUIRED,
+        403: ErrorCode.INSUFFICIENT_PERMISSIONS,
+        404: ErrorCode.NOT_FOUND,
+        405: ErrorCode.METHOD_NOT_ALLOWED,
+        429: ErrorCode.RATE_LIMIT_EXCEEDED,
+        500: ErrorCode.INTERNAL_ERROR,
+    }
+
+    error_code = status_code_to_error_code.get(
+        exc.status_code, ErrorCode.INTERNAL_ERROR
+    )
+
+    logger.warning(
+        "HTTP exception: %s - %s (path: %s)",
+        exc.status_code,
+        exc.detail,
+        request.url.path,
+    )
+
+    error_response = ErrorResponse(
+        errors=[ErrorDetail(code=error_code, message=str(exc.detail), field=None)]
+    )
+
+    return JSONResponse(
+        status_code=exc.status_code,
+        content=error_response.model_dump(),
+        headers=exc.headers,
+    )
+
+
+async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONResponse:
+    """
+    Handler for unhandled exceptions.
+
+    Logs the full exception and returns a generic error response to avoid
+    leaking sensitive information in production.
+    """
+    logger.exception(
+        "Unhandled exception: %s - %s (path: %s)",
+        type(exc).__name__,
+        exc,
+        request.url.path,
+    )
+
+    # In production, don't expose internal error details
+    from app.core.config import settings
+
+    if settings.ENVIRONMENT == "production":
+        message = "An internal error occurred. Please try again later."
+    else:
+        message = f"{type(exc).__name__}: {exc!s}"
+
+    error_response = ErrorResponse(
+        errors=[ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=message, field=None)]
+    )
+
+    return JSONResponse(
+        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+        content=error_response.model_dump(),
+    )

backend/app/core/repository_exceptions.py

@@ -0,0 +1,26 @@
+"""
+Custom exceptions for the repository layer.
+
+These exceptions allow services and routes to handle database-level errors
+with proper semantics, without leaking SQLAlchemy internals.
+"""
+
+
+class RepositoryError(Exception):
+    """Base for all repository-layer errors."""
+
+
+class DuplicateEntryError(RepositoryError):
+    """Raised on unique constraint violations. Maps to HTTP 409 Conflict."""
+
+
+class IntegrityConstraintError(RepositoryError):
+    """Raised on FK or check constraint violations."""
+
+
+class RecordNotFoundError(RepositoryError):
+    """Raised when an expected record doesn't exist."""
+
+
+class InvalidInputError(RepositoryError):
+    """Raised on bad pagination params, invalid UUIDs, or other invalid inputs."""

backend/app/crud/base.py

@@ -1,62 +0,0 @@
-from typing import Any, Dict, Generic, List, Optional, Type, TypeVar, Union
-from fastapi.encoders import jsonable_encoder
-from pydantic import BaseModel
-from sqlalchemy.orm import Session
-from app.core.database import Base
-
-ModelType = TypeVar("ModelType", bound=Base)
-CreateSchemaType = TypeVar("CreateSchemaType", bound=BaseModel)
-UpdateSchemaType = TypeVar("UpdateSchemaType", bound=BaseModel)
-
-
-class CRUDBase(Generic[ModelType, CreateSchemaType, UpdateSchemaType]):
-    def __init__(self, model: Type[ModelType]):
-        """
-        CRUD object with default methods to Create, Read, Update, Delete (CRUD).
-
-        Parameters:
-            model: A SQLAlchemy model class
-        """
-        self.model = model
-
-    def get(self, db: Session, id: str) -> Optional[ModelType]:
-        return db.query(self.model).filter(self.model.id == id).first()
-
-    def get_multi(
-            self, db: Session, *, skip: int = 0, limit: int = 100
-    ) -> List[ModelType]:
-        return db.query(self.model).offset(skip).limit(limit).all()
-
-    def create(self, db: Session, *, obj_in: CreateSchemaType) -> ModelType:
-        obj_in_data = jsonable_encoder(obj_in)
-        db_obj = self.model(**obj_in_data)
-        db.add(db_obj)
-        db.commit()
-        db.refresh(db_obj)
-        return db_obj
-
-    def update(
-            self,
-            db: Session,
-            *,
-            db_obj: ModelType,
-            obj_in: Union[UpdateSchemaType, Dict[str, Any]]
-    ) -> ModelType:
-        obj_data = jsonable_encoder(db_obj)
-        if isinstance(obj_in, dict):
-            update_data = obj_in
-        else:
-            update_data = obj_in.model_dump(exclude_unset=True)
-        for field in obj_data:
-            if field in update_data:
-                setattr(db_obj, field, update_data[field])
-        db.add(db_obj)
-        db.commit()
-        db.refresh(db_obj)
-        return db_obj
-
-    def remove(self, db: Session, *, id: str) -> ModelType:
-        obj = db.query(self.model).get(id)
-        db.delete(obj)
-        db.commit()
-        return obj

backend/app/crud/user.py

@@ -1,56 +0,0 @@
-# app/crud/user.py
-from typing import Optional, Union, Dict, Any
-from sqlalchemy.orm import Session
-from app.crud.base import CRUDBase
-from app.models.user import User
-from app.schemas.users import UserCreate, UserUpdate
-from app.core.auth import get_password_hash
-
-
-class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
-    def get_by_email(self, db: Session, *, email: str) -> Optional[User]:
-        return db.query(User).filter(User.email == email).first()
-
-    def create(self, db: Session, *, obj_in: UserCreate) -> User:
-        db_obj = User(
-            email=obj_in.email,
-            password_hash=get_password_hash(obj_in.password),
-            first_name=obj_in.first_name,
-            last_name=obj_in.last_name,
-            phone_number=obj_in.phone_number if hasattr(obj_in, 'phone_number') else None,
-            is_superuser=obj_in.is_superuser if hasattr(obj_in, 'is_superuser') else False,
-            preferences={}
-        )
-        db.add(db_obj)
-        db.commit()
-        db.refresh(db_obj)
-        return db_obj
-
-    def update(
-            self,
-            db: Session,
-            *,
-            db_obj: User,
-            obj_in: Union[UserUpdate, Dict[str, Any]]
-    ) -> User:
-        if isinstance(obj_in, dict):
-            update_data = obj_in
-        else:
-            update_data = obj_in.model_dump(exclude_unset=True)
-
-        # Handle password separately if it exists in update data
-        if "password" in update_data:
-            update_data["password_hash"] = get_password_hash(update_data["password"])
-            del update_data["password"]
-
-        return super().update(db, db_obj=db_obj, obj_in=update_data)
-
-    def is_active(self, user: User) -> bool:
-        return user.is_active
-
-    def is_superuser(self, user: User) -> bool:
-        return user.is_superuser
-
-
-# Create a singleton instance for use across the application
-user = CRUDUser(User)

backend/app/init_db.py

@@ -0,0 +1,230 @@
+# app/init_db.py
+"""
+Async database initialization script.
+
+Creates the first superuser if configured and doesn't already exist.
+"""
+
+import asyncio
+import json
+import logging
+import random
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from sqlalchemy import select, text
+
+from app.core.config import settings
+from app.core.database import SessionLocal, engine
+from app.models.organization import Organization
+from app.models.user import User
+from app.models.user_organization import UserOrganization
+from app.repositories.user import user_repo as user_repo
+from app.schemas.users import UserCreate
+
+logger = logging.getLogger(__name__)
+
+
+async def init_db() -> User | None:
+    """
+    Initialize database with first superuser if settings are configured and user doesn't exist.
+
+    Returns:
+        The created or existing superuser, or None if creation fails
+    """
+    # Use default values if not set in environment variables
+    superuser_email = settings.FIRST_SUPERUSER_EMAIL or "admin@example.com"
+
+    default_password = "AdminPassword123!"
+    if settings.DEMO_MODE:
+        default_password = "AdminPass1234!"
+
+    superuser_password = settings.FIRST_SUPERUSER_PASSWORD or default_password
+
+    if not settings.FIRST_SUPERUSER_EMAIL or not settings.FIRST_SUPERUSER_PASSWORD:
+        logger.warning(
+            "First superuser credentials not configured in settings. "
+            "Using defaults: %s",
+            superuser_email,
+        )
+
+    async with SessionLocal() as session:
+        try:
+            # Check if superuser already exists
+            existing_user = await user_repo.get_by_email(session, email=superuser_email)
+
+            if existing_user:
+                logger.info("Superuser already exists: %s", existing_user.email)
+                return existing_user
+
+            # Create superuser if doesn't exist
+            user_in = UserCreate(
+                email=superuser_email,
+                password=superuser_password,
+                first_name="Admin",
+                last_name="User",
+                is_superuser=True,
+            )
+
+            user = await user_repo.create(session, obj_in=user_in)
+            await session.commit()
+            await session.refresh(user)
+
+            logger.info("Created first superuser: %s", user.email)
+
+            # Create demo data if in demo mode
+            if settings.DEMO_MODE:
+                await load_demo_data(session)
+
+            return user
+
+        except Exception as e:
+            await session.rollback()
+            logger.error("Error initializing database: %s", e)
+            raise
+
+
+def _load_json_file(path: Path):
+    with open(path) as f:
+        return json.load(f)
+
+
+async def load_demo_data(session):
+    """Load demo data from JSON file."""
+    demo_data_path = Path(__file__).parent / "core" / "demo_data.json"
+    if not demo_data_path.exists():
+        logger.warning("Demo data file not found: %s", demo_data_path)
+        return
+
+    try:
+        # Use asyncio.to_thread to avoid blocking the event loop
+        data = await asyncio.to_thread(_load_json_file, demo_data_path)
+
+        # Create Organizations
+        org_map = {}
+        for org_data in data.get("organizations", []):
+            # Check if org exists
+            result = await session.execute(
+                text("SELECT * FROM organizations WHERE slug = :slug"),
+                {"slug": org_data["slug"]},
+            )
+            existing_org = result.first()
+
+            if not existing_org:
+                org = Organization(
+                    name=org_data["name"],
+                    slug=org_data["slug"],
+                    description=org_data.get("description"),
+                    is_active=True,
+                )
+                session.add(org)
+                await session.flush()  # Flush to get ID
+                org_map[org.slug] = org
+                logger.info("Created demo organization: %s", org.name)
+            else:
+                # We can't easily get the ORM object from raw SQL result for map without querying again or mapping
+                # So let's just query it properly if we need it for relationships
+                # But for simplicity in this script, let's just assume we created it or it exists.
+                # To properly map for users, we need the ID.
+                # Let's use a simpler approach: just try to create, if slug conflict, skip.
+                pass
+
+        # Re-query all orgs to build map for users
+        result = await session.execute(select(Organization))
+        orgs = result.scalars().all()
+        org_map = {org.slug: org for org in orgs}
+
+        # Create Users
+        for user_data in data.get("users", []):
+            existing_user = await user_repo.get_by_email(
+                session, email=user_data["email"]
+            )
+            if not existing_user:
+                # Create user
+                user_in = UserCreate(
+                    email=user_data["email"],
+                    password=user_data["password"],
+                    first_name=user_data["first_name"],
+                    last_name=user_data["last_name"],
+                    is_superuser=user_data["is_superuser"],
+                    is_active=user_data.get("is_active", True),
+                )
+                user = await user_repo.create(session, obj_in=user_in)
+
+                # Randomize created_at for demo data (last 30 days)
+                # This makes the charts look more realistic
+                days_ago = random.randint(0, 30)  # noqa: S311
+                random_time = datetime.now(UTC) - timedelta(days=days_ago)
+                # Add some random hours/minutes variation
+                random_time = random_time.replace(
+                    hour=random.randint(0, 23),  # noqa: S311
+                    minute=random.randint(0, 59),  # noqa: S311
+                )
+
+                # Update the timestamp and is_active directly in the database
+                # We do this to ensure the values are persisted correctly
+                await session.execute(
+                    text(
+                        "UPDATE users SET created_at = :created_at, is_active = :is_active WHERE id = :user_id"
+                    ),
+                    {
+                        "created_at": random_time,
+                        "is_active": user_data.get("is_active", True),
+                        "user_id": user.id,
+                    },
+                )
+
+                logger.info(
+                    "Created demo user: %s (created %s days ago, active=%s)",
+                    user.email,
+                    days_ago,
+                    user_data.get("is_active", True),
+                )
+
+                # Add to organization if specified
+                org_slug = user_data.get("organization_slug")
+                role = user_data.get("role")
+                if org_slug and org_slug in org_map and role:
+                    org = org_map[org_slug]
+                    # Check if membership exists (it shouldn't for new user)
+                    member = UserOrganization(
+                        user_id=user.id, organization_id=org.id, role=role
+                    )
+                    session.add(member)
+                    logger.info("Added %s to %s as %s", user.email, org.name, role)
+            else:
+                logger.info("Demo user already exists: %s", existing_user.email)
+
+        await session.commit()
+        logger.info("Demo data loaded successfully")
+
+    except Exception as e:
+        logger.error("Error loading demo data: %s", e)
+        raise
+
+
+async def main():
+    """Main entry point for database initialization."""
+    # Configure logging to show info logs
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    )
+
+    try:
+        user = await init_db()
+        if user:
+            print("✓ Database initialized successfully")
+            print(f"✓ Superuser: {user.email}")
+        else:
+            print("✗ Failed to initialize database")
+    except Exception as e:
+        print(f"✗ Error initializing database: {e}")
+        raise
+    finally:
+        # Close the engine
+        await engine.dispose()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/app/main.py

@@ -1,34 +1,262 @@
 import logging
+import os
+from contextlib import asynccontextmanager
+from datetime import UTC, datetime
+from typing import Any
 
 from apscheduler.schedulers.asyncio import AsyncIOScheduler
-from fastapi import FastAPI
+from fastapi import FastAPI, HTTPException, Request, status
+from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import HTMLResponse
+from fastapi.responses import HTMLResponse, JSONResponse
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from slowapi.util import get_remote_address
 
 from app.api.main import api_router
+from app.api.routes.oauth_provider import wellknown_router as oauth_wellknown_router
 from app.core.config import settings
+from app.core.database import check_database_health, close_async_db
+from app.core.exceptions import (
+    APIException,
+    api_exception_handler,
+    http_exception_handler,
+    unhandled_exception_handler,
+    validation_exception_handler,
+)
 
 scheduler = AsyncIOScheduler()
 
 logger = logging.getLogger(__name__)
 
-logger.info(f"Starting app!!!")
+# Initialize rate limiter
+limiter = Limiter(key_func=get_remote_address)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Application lifespan context manager.
+
+    Handles startup and shutdown events for the application.
+    Sets up background jobs and scheduled tasks on startup,
+    cleans up resources on shutdown.
+    """
+    # Startup
+    logger.info("Application starting up...")
+
+    # Skip scheduler in test environment
+    if os.getenv("IS_TEST", "False") != "True":
+        from app.services.session_cleanup import cleanup_expired_sessions
+
+        # Schedule session cleanup job
+        # Runs daily at 2:00 AM server time
+        scheduler.add_job(
+            cleanup_expired_sessions,
+            "cron",
+            hour=2,
+            minute=0,
+            id="cleanup_expired_sessions",
+            replace_existing=True,
+        )
+
+        scheduler.start()
+        logger.info("Scheduled jobs started: session cleanup (daily at 2 AM)")
+    else:
+        logger.info("Test environment detected - skipping scheduler")
+
+    yield
+
+    # Shutdown
+    logger.info("Application shutting down...")
+    if os.getenv("IS_TEST", "False") != "True":
+        scheduler.shutdown()
+        logger.info("Scheduled jobs stopped")
+    await close_async_db()
+
+
+logger.info("Starting app!!!")
 app = FastAPI(
     title=settings.PROJECT_NAME,
     version=settings.VERSION,
-    openapi_url=f"{settings.API_V1_STR}/openapi.json"
+    openapi_url=f"{settings.API_V1_STR}/openapi.json",
+    lifespan=lifespan,
 )
 
-# Set up CORS middleware
+# Add rate limiter state to app
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+# Register custom exception handlers (order matters - most specific first)
+app.add_exception_handler(APIException, api_exception_handler)
+app.add_exception_handler(RequestValidationError, validation_exception_handler)
+app.add_exception_handler(HTTPException, http_exception_handler)
+app.add_exception_handler(Exception, unhandled_exception_handler)
+
+# Set up CORS middleware with explicit allowed methods and headers
 app.add_middleware(
     CORSMiddleware,
     allow_origins=settings.BACKEND_CORS_ORIGINS,
     allow_credentials=True,
-    allow_methods=["*"],
+    allow_methods=[
-    allow_headers=["*"],
+        "GET",
+        "POST",
+        "PUT",
+        "PATCH",
+        "DELETE",
+        "OPTIONS",
+    ],  # Explicit methods only
+    allow_headers=[
+        "Content-Type",
+        "Authorization",
+        "Accept",
+        "Origin",
+        "User-Agent",
+        "DNT",
+        "Cache-Control",
+        "X-Requested-With",
+        "X-Device-Id",  # For session management
+    ],  # Explicit headers only
+    expose_headers=["Content-Length"],
+    max_age=600,  # Cache preflight requests for 10 minutes
 )
 
 
+# Add request size limit middleware
+@app.middleware("http")
+async def limit_request_size(request: Request, call_next):
+    """
+    Limit request body size to prevent DoS attacks via large payloads.
+
+    Max size: 10MB for file uploads and large payloads.
+    """
+    MAX_REQUEST_SIZE = 10 * 1024 * 1024  # 10MB in bytes
+
+    content_length = request.headers.get("content-length")
+    if content_length and int(content_length) > MAX_REQUEST_SIZE:
+        return JSONResponse(
+            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
+            content={
+                "success": False,
+                "errors": [
+                    {
+                        "code": "REQUEST_TOO_LARGE",
+                        "message": f"Request body too large. Maximum size is {MAX_REQUEST_SIZE // (1024 * 1024)}MB",
+                        "field": None,
+                    }
+                ],
+            },
+        )
+
+    response = await call_next(request)
+    return response
+
+
+# Add security headers middleware
+@app.middleware("http")
+async def add_security_headers(request: Request, call_next):
+    """
+    Add security headers to all responses.
+
+    CSP modes (set via CSP_MODE env var):
+    - 'strict': Maximum security, blocks most external resources (default for production)
+    - 'relaxed': Allows common CDNs and modern frontend features (default for development)
+    - 'disabled': No CSP (not recommended, use only for debugging)
+    """
+    response = await call_next(request)
+
+    # Prevent clickjacking
+    response.headers["X-Frame-Options"] = "DENY"
+
+    # Prevent MIME type sniffing
+    response.headers["X-Content-Type-Options"] = "nosniff"
+
+    # Enable XSS protection
+    response.headers["X-XSS-Protection"] = "1; mode=block"
+
+    # Enforce HTTPS in production
+    if settings.ENVIRONMENT == "production":
+        response.headers["Strict-Transport-Security"] = (
+            "max-age=31536000; includeSubDomains"
+        )
+
+    # Content Security Policy
+    csp_mode = settings.CSP_MODE.lower()
+
+    # Special handling for API docs
+    is_docs = (
+        request.url.path in ["/docs", "/redoc"]
+        or request.url.path.startswith("/docs/")
+        or request.url.path.startswith("/redoc/")
+    )
+
+    if csp_mode == "disabled":
+        # No CSP (only for local development/debugging)
+        pass
+    elif is_docs:
+        # Always allow Swagger UI/ReDoc resources on docs pages
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; "
+            "script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; "
+            "style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net https://fonts.googleapis.com; "
+            "font-src 'self' https://fonts.gstatic.com; "
+            "img-src 'self' data: https://fastapi.tiangolo.com; "
+            "frame-ancestors 'none'"
+        )
+    elif csp_mode == "strict":
+        # Maximum security - blocks most external resources
+        # Use this in production if you don't need external CDNs
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; "
+            "script-src 'self'; "
+            "style-src 'self'; "
+            "img-src 'self' data:; "
+            "font-src 'self'; "
+            "connect-src 'self'; "
+            "frame-ancestors 'none'; "
+            "base-uri 'self'; "
+            "form-action 'self'"
+        )
+    else:  # 'relaxed' mode (default)
+        # Modern frontend development - allows common CDNs and features
+        # Safe for most production apps that use external resources
+        response.headers["Content-Security-Policy"] = (
+            "default-src 'self'; "
+            # Allow common script sources
+            "script-src 'self' 'unsafe-inline' 'unsafe-eval' "
+            "https://cdn.jsdelivr.net https://unpkg.com https://cdnjs.cloudflare.com "
+            "https://www.googletagmanager.com https://www.google-analytics.com; "
+            # Allow common style sources
+            "style-src 'self' 'unsafe-inline' "
+            "https://cdn.jsdelivr.net https://unpkg.com https://cdnjs.cloudflare.com "
+            "https://fonts.googleapis.com; "
+            # Allow common font sources
+            "font-src 'self' data: "
+            "https://fonts.gstatic.com https://cdn.jsdelivr.net; "
+            # Allow images from self, data URIs, and common CDNs
+            "img-src 'self' data: blob: https:; "
+            # Allow API calls to self and common services
+            "connect-src 'self' "
+            "https://www.google-analytics.com https://analytics.google.com; "
+            # Media from self and data URIs
+            "media-src 'self' data: blob:; "
+            # Prevent framing
+            "frame-ancestors 'none'; "
+            # Restrict base URI
+            "base-uri 'self'; "
+            # Restrict form submissions
+            "form-action 'self'"
+        )
+
+    # Permissions Policy (formerly Feature Policy)
+    response.headers["Permissions-Policy"] = "geolocation=(), microphone=(), camera=()"
+
+    # Referrer Policy
+    response.headers["Referrer-Policy"] = "strict-origin-when-cross-origin"
+
+    return response
+
+
 @app.get("/", response_class=HTMLResponse)
 async def root():
     return """
@@ -45,4 +273,60 @@ async def root():
     """
 
 
+@app.get(
+    "/health",
+    summary="Health Check",
+    description="Check the health status of the API and its dependencies",
+    response_description="Health status information",
+    tags=["Health"],
+    operation_id="health_check",
+)
+async def health_check() -> JSONResponse:
+    """
+    Health check endpoint for monitoring and load balancers.
+
+    Returns:
+        JSONResponse: Health status with the following information:
+            - status: Overall health status ("healthy" or "unhealthy")
+            - timestamp: Current server timestamp (ISO 8601 format)
+            - version: API version
+            - environment: Current environment (development, staging, production)
+            - database: Database connectivity status
+    """
+    health_status: dict[str, Any] = {
+        "status": "healthy",
+        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+        "version": settings.VERSION,
+        "environment": settings.ENVIRONMENT,
+        "checks": {},
+    }
+
+    response_status = status.HTTP_200_OK
+
+    # Database health check using dedicated health check function
+    try:
+        db_healthy = await check_database_health()
+        if db_healthy:
+            health_status["checks"]["database"] = {
+                "status": "healthy",
+                "message": "Database connection successful",
+            }
+        else:
+            raise Exception("Database health check returned unhealthy status")
+    except Exception as e:
+        health_status["status"] = "unhealthy"
+        health_status["checks"]["database"] = {
+            "status": "unhealthy",
+            "message": f"Database connection failed: {e!s}",
+        }
+        response_status = status.HTTP_503_SERVICE_UNAVAILABLE
+        logger.error("Health check failed - database error: %s", e)
+
+    return JSONResponse(status_code=response_status, content=health_status)
+
+
 app.include_router(api_router, prefix=settings.API_V1_STR)
+
+# OAuth 2.0 well-known endpoint at root level per RFC 8414
+# This allows MCP clients to discover the OAuth server metadata at /.well-known/oauth-authorization-server
+app.include_router(oauth_wellknown_router)

backend/app/models/__init__.py

@@ -2,13 +2,40 @@
 Models package initialization.
 Imports all models to ensure they're registered with SQLAlchemy.
 """
+
 # First import Base to avoid circular imports
 from app.core.database import Base
+
 from .base import TimestampMixin, UUIDMixin
 
-# Import user model
+# OAuth models (client mode - authenticate via Google/GitHub)
+from .oauth_account import OAuthAccount
+
+# OAuth provider models (server mode - act as authorization server for MCP)
+from .oauth_authorization_code import OAuthAuthorizationCode
+from .oauth_client import OAuthClient
+from .oauth_provider_token import OAuthConsent, OAuthProviderRefreshToken
+from .oauth_state import OAuthState
+from .organization import Organization
+
+# Import models
 from .user import User
+from .user_organization import OrganizationRole, UserOrganization
+from .user_session import UserSession
+
 __all__ = [
-    'Base', 'TimestampMixin', 'UUIDMixin',
+    "Base",
-    'User',
+    "OAuthAccount",
-]
+    "OAuthAuthorizationCode",
+    "OAuthClient",
+    "OAuthConsent",
+    "OAuthProviderRefreshToken",
+    "OAuthState",
+    "Organization",
+    "OrganizationRole",
+    "TimestampMixin",
+    "UUIDMixin",
+    "User",
+    "UserOrganization",
+    "UserSession",
+]

backend/app/models/base.py

@@ -1,20 +1,28 @@
 import uuid
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 
 from sqlalchemy import Column, DateTime
 from sqlalchemy.dialects.postgresql import UUID
 
 # noinspection PyUnresolvedReferences
-from app.core.database import Base
+from app.core.database import Base  # Re-exported for other models
 
 
 class TimestampMixin:
     """Mixin to add created_at and updated_at timestamps to models"""
-    created_at = Column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc), nullable=False)
+
-    updated_at = Column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc),
+    created_at = Column(
-                        onupdate=lambda: datetime.now(timezone.utc), nullable=False)
+        DateTime(timezone=True), default=lambda: datetime.now(UTC), nullable=False
+    )
+    updated_at = Column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+        nullable=False,
+    )
 
 
 class UUIDMixin:
     """Mixin to add UUID primary keys to models"""
+
     id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)

backend/app/models/oauth_account.py

@@ -0,0 +1,55 @@
+"""OAuth account model for linking external OAuth providers to users."""
+
+from sqlalchemy import Column, DateTime, ForeignKey, Index, String, UniqueConstraint
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from .base import Base, TimestampMixin, UUIDMixin
+
+
+class OAuthAccount(Base, UUIDMixin, TimestampMixin):
+    """
+    Links OAuth provider accounts to users.
+
+    Supports multiple OAuth providers per user (e.g., user can have both
+    Google and GitHub connected). Each provider account is uniquely identified
+    by (provider, provider_user_id).
+    """
+
+    __tablename__ = "oauth_accounts"
+
+    # Link to user
+    user_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+
+    # OAuth provider identification
+    provider = Column(
+        String(50), nullable=False, index=True
+    )  # google, github, microsoft
+    provider_user_id = Column(String(255), nullable=False)  # Provider's unique user ID
+    provider_email = Column(
+        String(255), nullable=True, index=True
+    )  # Email from provider (for reference)
+
+    # Optional: store provider tokens for API access
+    # TODO: Encrypt these at rest in production (requires key management infrastructure)
+    access_token = Column(String(2048), nullable=True)
+    refresh_token = Column(String(2048), nullable=True)
+    token_expires_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Relationship
+    user = relationship("User", back_populates="oauth_accounts")
+
+    __table_args__ = (
+        # Each provider account can only be linked to one user
+        UniqueConstraint("provider", "provider_user_id", name="uq_oauth_provider_user"),
+        # Index for finding all OAuth accounts for a user + provider
+        Index("ix_oauth_accounts_user_provider", "user_id", "provider"),
+    )
+
+    def __repr__(self):
+        return f"<OAuthAccount {self.provider}:{self.provider_user_id}>"

backend/app/models/oauth_authorization_code.py

@@ -0,0 +1,100 @@
+"""OAuth authorization code model for OAuth provider mode."""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Index, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from .base import Base, TimestampMixin, UUIDMixin
+
+
+class OAuthAuthorizationCode(Base, UUIDMixin, TimestampMixin):
+    """
+    OAuth 2.0 Authorization Code for the authorization code flow.
+
+    Authorization codes are:
+    - Single-use (marked as used after exchange)
+    - Short-lived (10 minutes default)
+    - Bound to specific client, user, redirect_uri
+    - Support PKCE (code_challenge/code_challenge_method)
+
+    Security considerations:
+    - Code must be cryptographically random (64 chars, URL-safe)
+    - Must validate redirect_uri matches exactly
+    - Must verify PKCE code_verifier for public clients
+    - Must be consumed within expiration time
+
+    Performance indexes (defined in migration 0002_add_performance_indexes.py):
+    - ix_perf_oauth_auth_codes_expires: expires_at WHERE used = false
+    """
+
+    __tablename__ = "oauth_authorization_codes"
+
+    # The authorization code (cryptographically random, URL-safe)
+    code = Column(String(128), unique=True, nullable=False, index=True)
+
+    # Client that requested the code
+    client_id = Column(
+        String(64),
+        ForeignKey("oauth_clients.client_id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # User who authorized the request
+    user_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # Redirect URI (must match exactly on token exchange)
+    redirect_uri = Column(String(2048), nullable=False)
+
+    # Granted scopes (space-separated)
+    scope = Column(String(1000), nullable=False, default="")
+
+    # PKCE support (required for public clients)
+    code_challenge = Column(String(128), nullable=True)
+    code_challenge_method = Column(String(10), nullable=True)  # "S256" or "plain"
+
+    # State parameter (for CSRF protection, returned to client)
+    state = Column(String(256), nullable=True)
+
+    # Nonce (for OpenID Connect, included in ID token)
+    nonce = Column(String(256), nullable=True)
+
+    # Expiration (codes are short-lived, typically 10 minutes)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+
+    # Single-use flag (set to True after successful exchange)
+    used = Column(Boolean, default=False, nullable=False)
+
+    # Relationships
+    client = relationship("OAuthClient", backref="authorization_codes")
+    user = relationship("User", backref="oauth_authorization_codes")
+
+    # Indexes for efficient cleanup queries
+    __table_args__ = (
+        Index("ix_oauth_authorization_codes_expires_at", "expires_at"),
+        Index("ix_oauth_authorization_codes_client_user", "client_id", "user_id"),
+    )
+
+    def __repr__(self):
+        return f"<OAuthAuthorizationCode {self.code[:8]}... for {self.client_id}>"
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the authorization code has expired."""
+        # Use timezone-aware comparison (datetime.utcnow() is deprecated)
+        now = datetime.now(UTC)
+        expires_at = self.expires_at
+        # Handle both timezone-aware and naive datetimes from DB
+        if expires_at.tzinfo is None:
+            expires_at = expires_at.replace(tzinfo=UTC)
+        return bool(now > expires_at)
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if the authorization code is valid (not used, not expired)."""
+        return not self.used and not self.is_expired

backend/app/models/oauth_client.py

@@ -0,0 +1,67 @@
+"""OAuth client model for OAuth provider mode (MCP clients)."""
+
+from sqlalchemy import Boolean, Column, ForeignKey, String
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import relationship
+
+from .base import Base, TimestampMixin, UUIDMixin
+
+
+class OAuthClient(Base, UUIDMixin, TimestampMixin):
+    """
+    Registered OAuth clients (for OAuth provider mode).
+
+    This model stores third-party applications that can authenticate
+    against this API using OAuth 2.0. Used for MCP (Model Context Protocol)
+    client authentication and API access.
+
+    NOTE: This is a skeleton implementation. The full OAuth provider
+    functionality (authorization endpoint, token endpoint, etc.) can be
+    expanded when needed.
+    """
+
+    __tablename__ = "oauth_clients"
+
+    # Client credentials
+    client_id = Column(String(64), unique=True, nullable=False, index=True)
+    client_secret_hash = Column(
+        String(255), nullable=True
+    )  # NULL for public clients (PKCE)
+
+    # Client metadata
+    client_name = Column(String(255), nullable=False)
+    client_description = Column(String(1000), nullable=True)
+
+    # Client type: "public" (SPA, mobile) or "confidential" (server-side)
+    client_type = Column(String(20), nullable=False, default="public")
+
+    # Allowed redirect URIs (JSON array)
+    redirect_uris = Column(JSONB, nullable=False, default=list)
+
+    # Allowed scopes (JSON array of scope names)
+    allowed_scopes = Column(JSONB, nullable=False, default=list)
+
+    # Token lifetimes (in seconds)
+    access_token_lifetime = Column(String(10), nullable=False, default="3600")  # 1 hour
+    refresh_token_lifetime = Column(
+        String(10), nullable=False, default="604800"
+    )  # 7 days
+
+    # Status
+    is_active = Column(Boolean, default=True, nullable=False, index=True)
+
+    # Optional: owner user (for user-registered applications)
+    owner_user_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="SET NULL"),
+        nullable=True,
+    )
+
+    # MCP-specific: URL of the MCP server this client represents
+    mcp_server_url = Column(String(2048), nullable=True)
+
+    # Relationship
+    owner = relationship("User", backref="owned_oauth_clients")
+
+    def __repr__(self):
+        return f"<OAuthClient {self.client_name} ({self.client_id[:8]}...)>"

backend/app/models/oauth_provider_token.py

@@ -0,0 +1,162 @@
+"""OAuth provider token models for OAuth provider mode."""
+
+from datetime import UTC, datetime
+
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Index, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from .base import Base, TimestampMixin, UUIDMixin
+
+
+class OAuthProviderRefreshToken(Base, UUIDMixin, TimestampMixin):
+    """
+    OAuth 2.0 Refresh Token for the OAuth provider.
+
+    Refresh tokens are:
+    - Opaque (stored as hash in DB, actual token given to client)
+    - Long-lived (configurable, default 30 days)
+    - Revocable (via revoked flag or deletion)
+    - Bound to specific client, user, and scope
+
+    Access tokens are JWTs and not stored in DB (self-contained).
+    This model only tracks refresh tokens for revocation support.
+
+    Security considerations:
+    - Store token hash, not plaintext
+    - Support token rotation (new refresh token on use)
+    - Track last used time for security auditing
+    - Support revocation by user, client, or admin
+
+    Performance indexes (defined in migration 0002_add_performance_indexes.py):
+    - ix_perf_oauth_refresh_tokens_expires: expires_at WHERE revoked = false
+    """
+
+    __tablename__ = "oauth_provider_refresh_tokens"
+
+    # Hash of the refresh token (SHA-256)
+    # We store hash, not plaintext, for security
+    token_hash = Column(String(64), unique=True, nullable=False, index=True)
+
+    # Unique token ID (JTI) - used in JWT access tokens to reference this refresh token
+    jti = Column(String(64), unique=True, nullable=False, index=True)
+
+    # Client that owns this token
+    client_id = Column(
+        String(64),
+        ForeignKey("oauth_clients.client_id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # User who authorized this token
+    user_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # Granted scopes (space-separated)
+    scope = Column(String(1000), nullable=False, default="")
+
+    # Token expiration
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+
+    # Revocation flag
+    revoked = Column(Boolean, default=False, nullable=False, index=True)
+
+    # Last used timestamp (for security auditing)
+    last_used_at = Column(DateTime(timezone=True), nullable=True)
+
+    # Device/session info (optional, for user visibility)
+    device_info = Column(String(500), nullable=True)
+    ip_address = Column(String(45), nullable=True)
+
+    # Relationships
+    client = relationship("OAuthClient", backref="refresh_tokens")
+    user = relationship("User", backref="oauth_provider_refresh_tokens")
+
+    # Indexes
+    __table_args__ = (
+        Index("ix_oauth_provider_refresh_tokens_expires_at", "expires_at"),
+        Index("ix_oauth_provider_refresh_tokens_client_user", "client_id", "user_id"),
+        Index(
+            "ix_oauth_provider_refresh_tokens_user_revoked",
+            "user_id",
+            "revoked",
+        ),
+    )
+
+    def __repr__(self):
+        status = "revoked" if self.revoked else "active"
+        return f"<OAuthProviderRefreshToken {self.jti[:8]}... ({status})>"
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if the refresh token has expired."""
+        # Use timezone-aware comparison (datetime.utcnow() is deprecated)
+        now = datetime.now(UTC)
+        expires_at = self.expires_at
+        # Handle both timezone-aware and naive datetimes from DB
+        if expires_at.tzinfo is None:
+            expires_at = expires_at.replace(tzinfo=UTC)
+        return bool(now > expires_at)
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if the refresh token is valid (not revoked, not expired)."""
+        return not self.revoked and not self.is_expired
+
+
+class OAuthConsent(Base, UUIDMixin, TimestampMixin):
+    """
+    OAuth consent record - remembers user consent for a client.
+
+    When a user grants consent to an OAuth client, we store the record
+    so they don't have to re-consent on subsequent authorizations
+    (unless scopes change).
+
+    This enables a better UX - users only see consent screen once per client,
+    unless the client requests additional scopes.
+    """
+
+    __tablename__ = "oauth_consents"
+
+    # User who granted consent
+    user_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # Client that received consent
+    client_id = Column(
+        String(64),
+        ForeignKey("oauth_clients.client_id", ondelete="CASCADE"),
+        nullable=False,
+    )
+
+    # Granted scopes (space-separated)
+    granted_scopes = Column(String(1000), nullable=False, default="")
+
+    # Relationships
+    client = relationship("OAuthClient", backref="consents")
+    user = relationship("User", backref="oauth_consents")
+
+    # Unique constraint: one consent record per user+client
+    __table_args__ = (
+        Index(
+            "ix_oauth_consents_user_client",
+            "user_id",
+            "client_id",
+            unique=True,
+        ),
+    )
+
+    def __repr__(self):
+        return f"<OAuthConsent user={self.user_id} client={self.client_id}>"
+
+    def has_scopes(self, requested_scopes: list[str]) -> bool:
+        """Check if all requested scopes are already granted."""
+        granted = set(self.granted_scopes.split()) if self.granted_scopes else set()
+        requested = set(requested_scopes)
+        return requested.issubset(granted)

backend/app/models/oauth_state.py

@@ -0,0 +1,45 @@
+"""OAuth state model for CSRF protection during OAuth flows."""
+
+from sqlalchemy import Column, DateTime, String
+from sqlalchemy.dialects.postgresql import UUID
+
+from .base import Base, TimestampMixin, UUIDMixin
+
+
+class OAuthState(Base, UUIDMixin, TimestampMixin):
+    """
+    Temporary storage for OAuth state parameters.
+
+    Prevents CSRF attacks during OAuth flows by storing a random state
+    value that must match on callback. Also stores PKCE code_verifier
+    for the Authorization Code flow with PKCE.
+
+    These records are short-lived (10 minutes by default) and should
+    be deleted after use or expiration.
+    """
+
+    __tablename__ = "oauth_states"
+
+    # Random state parameter (CSRF protection)
+    state = Column(String(255), unique=True, nullable=False, index=True)
+
+    # PKCE code_verifier (used to generate code_challenge)
+    code_verifier = Column(String(128), nullable=True)
+
+    # OIDC nonce for ID token replay protection
+    nonce = Column(String(255), nullable=True)
+
+    # OAuth provider (google, github, etc.)
+    provider = Column(String(50), nullable=False)
+
+    # Original redirect URI (for callback validation)
+    redirect_uri = Column(String(500), nullable=True)
+
+    # User ID if this is an account linking flow (user is already logged in)
+    user_id = Column(UUID(as_uuid=True), nullable=True)
+
+    # Expiration time
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+
+    def __repr__(self):
+        return f"<OAuthState {self.state[:8]}... ({self.provider})>"

backend/app/models/organization.py

@@ -0,0 +1,37 @@
+# app/models/organization.py
+from sqlalchemy import Boolean, Column, Index, String, Text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import relationship
+
+from .base import Base, TimestampMixin, UUIDMixin
+
+
+class Organization(Base, UUIDMixin, TimestampMixin):
+    """
+    Organization model for multi-tenant support.
+    Users can belong to multiple organizations with different roles.
+
+    Performance indexes (defined in migration 0002_add_performance_indexes.py):
+    - ix_perf_organizations_slug_lower: LOWER(slug) WHERE is_active = true
+    """
+
+    __tablename__ = "organizations"
+
+    name = Column(String(255), nullable=False, index=True)
+    slug = Column(String(255), unique=True, nullable=False, index=True)
+    description = Column(Text, nullable=True)
+    is_active = Column(Boolean, default=True, nullable=False, index=True)
+    settings = Column(JSONB, default={})
+
+    # Relationships
+    user_organizations = relationship(
+        "UserOrganization", back_populates="organization", cascade="all, delete-orphan"
+    )
+
+    __table_args__ = (
+        Index("ix_organizations_name_active", "name", "is_active"),
+        Index("ix_organizations_slug_active", "slug", "is_active"),
+    )
+
+    def __repr__(self):
+        return f"<Organization {self.name} ({self.slug})>"

backend/app/models/user.py

@@ -1,19 +1,50 @@
-from sqlalchemy import Column, String, JSON, Boolean
+from sqlalchemy import Boolean, Column, DateTime, String
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import relationship
 
 from .base import Base, TimestampMixin, UUIDMixin
 
 
 class User(Base, UUIDMixin, TimestampMixin):
-    __tablename__ = 'users'
+    """
+    User model for authentication and profile data.
 
-    email = Column(String, unique=True, nullable=False, index=True)
+    Performance indexes (defined in migration 0002_add_performance_indexes.py):
-    password_hash = Column(String, nullable=False)
+    - ix_perf_users_email_lower: LOWER(email) WHERE deleted_at IS NULL
-    first_name = Column(String, nullable=False, default="user")
+    - ix_perf_users_active: is_active WHERE deleted_at IS NULL
-    last_name = Column(String, nullable=True)
+    """
-    phone_number = Column(String)
+
-    is_active = Column(Boolean, default=True, nullable=False)
+    __tablename__ = "users"
-    is_superuser = Column(Boolean, default=False, nullable=False)
+
-    preferences = Column(JSON)
+    email = Column(String(255), unique=True, nullable=False, index=True)
+    # Nullable to support OAuth-only users who never set a password
+    password_hash = Column(String(255), nullable=True)
+    first_name = Column(String(100), nullable=False, default="user")
+    last_name = Column(String(100), nullable=True)
+    phone_number = Column(String(20))
+    is_active = Column(Boolean, default=True, nullable=False, index=True)
+    is_superuser = Column(Boolean, default=False, nullable=False, index=True)
+    preferences = Column(JSONB)
+    locale = Column(String(10), nullable=True, index=True)
+    deleted_at = Column(DateTime(timezone=True), nullable=True, index=True)
+
+    # Relationships
+    user_organizations = relationship(
+        "UserOrganization", back_populates="user", cascade="all, delete-orphan"
+    )
+    oauth_accounts = relationship(
+        "OAuthAccount", back_populates="user", cascade="all, delete-orphan"
+    )
+
+    @property
+    def has_password(self) -> bool:
+        """Check if user can login with password (not OAuth-only)."""
+        return self.password_hash is not None
+
+    @property
+    def can_remove_oauth(self) -> bool:
+        """Check if user can safely remove an OAuth account link."""
+        return self.has_password or len(self.oauth_accounts) > 1
 
     def __repr__(self):
-        return f"<User {self.email}>"
+        return f"<User {self.email}>"

backend/app/models/user_organization.py

@@ -0,0 +1,67 @@
+# app/models/user_organization.py
+from enum import Enum as PyEnum
+
+from sqlalchemy import Boolean, Column, Enum, ForeignKey, Index, String
+from sqlalchemy.dialects.postgresql import UUID as PGUUID
+from sqlalchemy.orm import relationship
+
+from .base import Base, TimestampMixin
+
+
+class OrganizationRole(str, PyEnum):
+    """
+    Built-in organization roles.
+    These provide a baseline role system that can be optionally used.
+    Projects can extend this or implement their own permission system.
+    """
+
+    OWNER = "owner"  # Full control over organization
+    ADMIN = "admin"  # Can manage users and settings
+    MEMBER = "member"  # Regular member with standard access
+    GUEST = "guest"  # Limited read-only access
+
+
+class UserOrganization(Base, TimestampMixin):
+    """
+    Junction table for many-to-many relationship between Users and Organizations.
+    Includes role information for flexible RBAC.
+    """
+
+    __tablename__ = "user_organizations"
+
+    user_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+    organization_id = Column(
+        PGUUID(as_uuid=True),
+        ForeignKey("organizations.id", ondelete="CASCADE"),
+        primary_key=True,
+    )
+
+    role: Column[OrganizationRole] = Column(
+        Enum(OrganizationRole),
+        default=OrganizationRole.MEMBER,
+        nullable=False,
+        # Note: index defined in __table_args__ as ix_user_org_role
+    )
+    is_active = Column(Boolean, default=True, nullable=False, index=True)
+
+    # Optional: Custom permissions override for specific users
+    custom_permissions = Column(
+        String(500), nullable=True
+    )  # JSON array of permission strings
+
+    # Relationships
+    user = relationship("User", back_populates="user_organizations")
+    organization = relationship("Organization", back_populates="user_organizations")
+
+    __table_args__ = (
+        Index("ix_user_org_user_active", "user_id", "is_active"),
+        Index("ix_user_org_org_active", "organization_id", "is_active"),
+        Index("ix_user_org_role", "role"),
+    )
+
+    def __repr__(self):
+        return f"<UserOrganization user={self.user_id} org={self.organization_id} role={self.role}>"

backend/app/models/user_session.py

@@ -0,0 +1,101 @@
+"""
+User session model for tracking per-device authentication sessions.
+
+This allows users to:
+- See where they're logged in
+- Logout from specific devices
+- Manage their active sessions
+"""
+
+from datetime import UTC
+
+from sqlalchemy import Boolean, Column, DateTime, ForeignKey, Index, String
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import relationship
+
+from .base import Base, TimestampMixin, UUIDMixin
+
+
+class UserSession(Base, UUIDMixin, TimestampMixin):
+    """
+    Tracks individual user sessions (per-device).
+
+    Each time a user logs in from a device, a new session is created.
+    Sessions are identified by the refresh token JTI (JWT ID).
+
+    Performance indexes (defined in migration 0002_add_performance_indexes.py):
+    - ix_perf_user_sessions_expires: expires_at WHERE is_active = true
+    """
+
+    __tablename__ = "user_sessions"
+
+    # Foreign key to user
+    user_id = Column(
+        UUID(as_uuid=True),
+        ForeignKey("users.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+
+    # Refresh token identifier (JWT ID from the refresh token)
+    refresh_token_jti = Column(String(255), unique=True, nullable=False, index=True)
+
+    # Device information
+    device_name = Column(String(255), nullable=True)  # "iPhone 14", "Chrome on MacBook"
+    device_id = Column(
+        String(255), nullable=True
+    )  # Persistent device identifier (from client)
+    ip_address = Column(String(45), nullable=True)  # IPv4 (15 chars) or IPv6 (45 chars)
+    user_agent = Column(String(500), nullable=True)  # Browser/app user agent
+
+    # Session timing
+    last_used_at = Column(DateTime(timezone=True), nullable=False)
+    expires_at = Column(DateTime(timezone=True), nullable=False)
+
+    # Session state
+    is_active = Column(Boolean, default=True, nullable=False, index=True)
+
+    # Geographic information (optional, can be populated from IP)
+    location_city = Column(String(100), nullable=True)
+    location_country = Column(String(100), nullable=True)
+
+    # Relationship to user
+    user = relationship("User", backref="sessions")
+
+    # Composite indexes for performance (defined in migration)
+    __table_args__ = (
+        Index("ix_user_sessions_user_active", "user_id", "is_active"),
+        Index("ix_user_sessions_jti_active", "refresh_token_jti", "is_active"),
+    )
+
+    def __repr__(self):
+        return f"<UserSession {self.device_name} ({self.ip_address})>"
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if session has expired."""
+        from datetime import datetime
+
+        now = datetime.now(UTC)
+        expires_at = self.expires_at
+        if expires_at.tzinfo is None:
+            expires_at = expires_at.replace(tzinfo=UTC)
+        return bool(expires_at < now)
+
+    def to_dict(self):
+        """Convert session to dictionary for serialization."""
+        return {
+            "id": str(self.id),
+            "user_id": str(self.user_id),
+            "device_name": self.device_name,
+            "device_id": self.device_id,
+            "ip_address": self.ip_address,
+            "last_used_at": self.last_used_at.isoformat()
+            if self.last_used_at
+            else None,
+            "expires_at": self.expires_at.isoformat() if self.expires_at else None,
+            "is_active": self.is_active,
+            "location_city": self.location_city,
+            "location_country": self.location_country,
+            "created_at": self.created_at.isoformat() if self.created_at else None,
+        }

backend/app/repositories/__init__.py

@@ -0,0 +1,39 @@
+# app/repositories/__init__.py
+"""Repository layer — all database access goes through these classes."""
+
+from app.repositories.oauth_account import OAuthAccountRepository, oauth_account_repo
+from app.repositories.oauth_authorization_code import (
+    OAuthAuthorizationCodeRepository,
+    oauth_authorization_code_repo,
+)
+from app.repositories.oauth_client import OAuthClientRepository, oauth_client_repo
+from app.repositories.oauth_consent import OAuthConsentRepository, oauth_consent_repo
+from app.repositories.oauth_provider_token import (
+    OAuthProviderTokenRepository,
+    oauth_provider_token_repo,
+)
+from app.repositories.oauth_state import OAuthStateRepository, oauth_state_repo
+from app.repositories.organization import OrganizationRepository, organization_repo
+from app.repositories.session import SessionRepository, session_repo
+from app.repositories.user import UserRepository, user_repo
+
+__all__ = [
+    "OAuthAccountRepository",
+    "OAuthAuthorizationCodeRepository",
+    "OAuthClientRepository",
+    "OAuthConsentRepository",
+    "OAuthProviderTokenRepository",
+    "OAuthStateRepository",
+    "OrganizationRepository",
+    "SessionRepository",
+    "UserRepository",
+    "oauth_account_repo",
+    "oauth_authorization_code_repo",
+    "oauth_client_repo",
+    "oauth_consent_repo",
+    "oauth_provider_token_repo",
+    "oauth_state_repo",
+    "organization_repo",
+    "session_repo",
+    "user_repo",
+]

backend/app/repositories/base.py

@@ -0,0 +1,420 @@
+# app/repositories/base.py
+"""
+Base repository class for async database operations using SQLAlchemy 2.0 async patterns.
+
+Provides reusable create, read, update, and delete operations for all models.
+"""
+
+import logging
+import uuid
+from datetime import UTC
+from typing import Any, TypeVar
+
+from fastapi.encoders import jsonable_encoder
+from pydantic import BaseModel
+from sqlalchemy import func, select
+from sqlalchemy.exc import DataError, IntegrityError, OperationalError
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import Load
+
+from app.core.database import Base
+from app.core.repository_exceptions import (
+    DuplicateEntryError,
+    IntegrityConstraintError,
+    InvalidInputError,
+)
+
+logger = logging.getLogger(__name__)
+
+ModelType = TypeVar("ModelType", bound=Base)
+CreateSchemaType = TypeVar("CreateSchemaType", bound=BaseModel)
+UpdateSchemaType = TypeVar("UpdateSchemaType", bound=BaseModel)
+
+
+class BaseRepository[
+    ModelType: Base,
+    CreateSchemaType: BaseModel,
+    UpdateSchemaType: BaseModel,
+]:
+    """Async repository operations for a model."""
+
+    def __init__(self, model: type[ModelType]):
+        """
+        Repository object with default async methods to Create, Read, Update, Delete.
+
+        Parameters:
+            model: A SQLAlchemy model class
+        """
+        self.model = model
+
+    async def get(
+        self, db: AsyncSession, id: str, options: list[Load] | None = None
+    ) -> ModelType | None:
+        """
+        Get a single record by ID with UUID validation and optional eager loading.
+
+        Args:
+            db: Database session
+            id: Record UUID
+            options: Optional list of SQLAlchemy load options (e.g., joinedload, selectinload)
+                    for eager loading relationships to prevent N+1 queries
+
+        Returns:
+            Model instance or None if not found
+        """
+        try:
+            if isinstance(id, uuid.UUID):
+                uuid_obj = id
+            else:
+                uuid_obj = uuid.UUID(str(id))
+        except (ValueError, AttributeError, TypeError) as e:
+            logger.warning("Invalid UUID format: %s - %s", id, e)
+            return None
+
+        try:
+            query = select(self.model).where(self.model.id == uuid_obj)
+
+            if options:
+                for option in options:
+                    query = query.options(option)
+
+            result = await db.execute(query)
+            return result.scalar_one_or_none()
+        except Exception as e:
+            logger.error(
+                "Error retrieving %s with id %s: %s", self.model.__name__, id, e
+            )
+            raise
+
+    async def get_multi(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        options: list[Load] | None = None,
+    ) -> list[ModelType]:
+        """
+        Get multiple records with pagination validation and optional eager loading.
+        """
+        if skip < 0:
+            raise InvalidInputError("skip must be non-negative")
+        if limit < 0:
+            raise InvalidInputError("limit must be non-negative")
+        if limit > 1000:
+            raise InvalidInputError("Maximum limit is 1000")
+
+        try:
+            query = select(self.model).order_by(self.model.id).offset(skip).limit(limit)
+
+            if options:
+                for option in options:
+                    query = query.options(option)
+
+            result = await db.execute(query)
+            return list(result.scalars().all())
+        except Exception as e:
+            logger.error(
+                "Error retrieving multiple %s records: %s", self.model.__name__, e
+            )
+            raise
+
+    async def create(
+        self, db: AsyncSession, *, obj_in: CreateSchemaType
+    ) -> ModelType:  # pragma: no cover
+        """Create a new record with error handling.
+
+        NOTE: This method is defensive code that's never called in practice.
+        All repository subclasses override this method with their own implementations.
+        Marked as pragma: no cover to avoid false coverage gaps.
+        """
+        try:  # pragma: no cover
+            obj_in_data = jsonable_encoder(obj_in)
+            db_obj = self.model(**obj_in_data)
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+            return db_obj
+        except IntegrityError as e:  # pragma: no cover
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            if "unique" in error_msg.lower() or "duplicate" in error_msg.lower():
+                logger.warning(
+                    "Duplicate entry attempted for %s: %s",
+                    self.model.__name__,
+                    error_msg,
+                )
+                raise DuplicateEntryError(
+                    f"A {self.model.__name__} with this data already exists"
+                )
+            logger.error(
+                "Integrity error creating %s: %s", self.model.__name__, error_msg
+            )
+            raise IntegrityConstraintError(f"Database integrity error: {error_msg}")
+        except (OperationalError, DataError) as e:  # pragma: no cover
+            await db.rollback()
+            logger.error("Database error creating %s: %s", self.model.__name__, e)
+            raise IntegrityConstraintError(f"Database operation failed: {e!s}")
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.exception("Unexpected error creating %s: %s", self.model.__name__, e)
+            raise
+
+    async def update(
+        self,
+        db: AsyncSession,
+        *,
+        db_obj: ModelType,
+        obj_in: UpdateSchemaType | dict[str, Any],
+    ) -> ModelType:
+        """Update a record with error handling."""
+        try:
+            obj_data = jsonable_encoder(db_obj)
+            if isinstance(obj_in, dict):
+                update_data = obj_in
+            else:
+                update_data = obj_in.model_dump(exclude_unset=True)
+
+            for field in obj_data:
+                if field in update_data:
+                    setattr(db_obj, field, update_data[field])
+
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+            return db_obj
+        except IntegrityError as e:
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            if "unique" in error_msg.lower() or "duplicate" in error_msg.lower():
+                logger.warning(
+                    "Duplicate entry attempted for %s: %s",
+                    self.model.__name__,
+                    error_msg,
+                )
+                raise DuplicateEntryError(
+                    f"A {self.model.__name__} with this data already exists"
+                )
+            logger.error(
+                "Integrity error updating %s: %s", self.model.__name__, error_msg
+            )
+            raise IntegrityConstraintError(f"Database integrity error: {error_msg}")
+        except (OperationalError, DataError) as e:
+            await db.rollback()
+            logger.error("Database error updating %s: %s", self.model.__name__, e)
+            raise IntegrityConstraintError(f"Database operation failed: {e!s}")
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Unexpected error updating %s: %s", self.model.__name__, e)
+            raise
+
+    async def remove(self, db: AsyncSession, *, id: str) -> ModelType | None:
+        """Delete a record with error handling and null check."""
+        try:
+            if isinstance(id, uuid.UUID):
+                uuid_obj = id
+            else:
+                uuid_obj = uuid.UUID(str(id))
+        except (ValueError, AttributeError, TypeError) as e:
+            logger.warning("Invalid UUID format for deletion: %s - %s", id, e)
+            return None
+
+        try:
+            result = await db.execute(
+                select(self.model).where(self.model.id == uuid_obj)
+            )
+            obj = result.scalar_one_or_none()
+
+            if obj is None:
+                logger.warning(
+                    "%s with id %s not found for deletion", self.model.__name__, id
+                )
+                return None
+
+            await db.delete(obj)
+            await db.commit()
+            return obj
+        except IntegrityError as e:
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            logger.error(
+                "Integrity error deleting %s: %s", self.model.__name__, error_msg
+            )
+            raise IntegrityConstraintError(
+                f"Cannot delete {self.model.__name__}: referenced by other records"
+            )
+        except Exception as e:
+            await db.rollback()
+            logger.exception(
+                "Error deleting %s with id %s: %s", self.model.__name__, id, e
+            )
+            raise
+
+    async def get_multi_with_total(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        sort_by: str | None = None,
+        sort_order: str = "asc",
+        filters: dict[str, Any] | None = None,
+    ) -> tuple[list[ModelType], int]:  # pragma: no cover
+        """
+        Get multiple records with total count, filtering, and sorting.
+
+        NOTE: This method is defensive code that's never called in practice.
+        All repository subclasses override this method with their own implementations.
+        Marked as pragma: no cover to avoid false coverage gaps.
+        """
+        if skip < 0:
+            raise InvalidInputError("skip must be non-negative")
+        if limit < 0:
+            raise InvalidInputError("limit must be non-negative")
+        if limit > 1000:
+            raise InvalidInputError("Maximum limit is 1000")
+
+        try:
+            query = select(self.model)
+
+            if hasattr(self.model, "deleted_at"):
+                query = query.where(self.model.deleted_at.is_(None))
+
+            if filters:
+                for field, value in filters.items():
+                    if hasattr(self.model, field) and value is not None:
+                        query = query.where(getattr(self.model, field) == value)
+
+            count_query = select(func.count()).select_from(query.alias())
+            count_result = await db.execute(count_query)
+            total = count_result.scalar_one()
+
+            if sort_by and hasattr(self.model, sort_by):
+                sort_column = getattr(self.model, sort_by)
+                if sort_order.lower() == "desc":
+                    query = query.order_by(sort_column.desc())
+                else:
+                    query = query.order_by(sort_column.asc())
+            else:
+                query = query.order_by(self.model.id)
+
+            query = query.offset(skip).limit(limit)
+            items_result = await db.execute(query)
+            items = list(items_result.scalars().all())
+
+            return items, total
+        except Exception as e:  # pragma: no cover
+            logger.error(
+                "Error retrieving paginated %s records: %s", self.model.__name__, e
+            )
+            raise
+
+    async def count(self, db: AsyncSession) -> int:
+        """Get total count of records."""
+        try:
+            result = await db.execute(select(func.count(self.model.id)))
+            return result.scalar_one()
+        except Exception as e:
+            logger.error("Error counting %s records: %s", self.model.__name__, e)
+            raise
+
+    async def exists(self, db: AsyncSession, id: str) -> bool:
+        """Check if a record exists by ID."""
+        obj = await self.get(db, id=id)
+        return obj is not None
+
+    async def soft_delete(self, db: AsyncSession, *, id: str) -> ModelType | None:
+        """
+        Soft delete a record by setting deleted_at timestamp.
+
+        Only works if the model has a 'deleted_at' column.
+        """
+        from datetime import datetime
+
+        try:
+            if isinstance(id, uuid.UUID):
+                uuid_obj = id
+            else:
+                uuid_obj = uuid.UUID(str(id))
+        except (ValueError, AttributeError, TypeError) as e:
+            logger.warning("Invalid UUID format for soft deletion: %s - %s", id, e)
+            return None
+
+        try:
+            result = await db.execute(
+                select(self.model).where(self.model.id == uuid_obj)
+            )
+            obj = result.scalar_one_or_none()
+
+            if obj is None:
+                logger.warning(
+                    "%s with id %s not found for soft deletion", self.model.__name__, id
+                )
+                return None
+
+            if not hasattr(self.model, "deleted_at"):
+                logger.error("%s does not support soft deletes", self.model.__name__)
+                raise InvalidInputError(
+                    f"{self.model.__name__} does not have a deleted_at column"
+                )
+
+            obj.deleted_at = datetime.now(UTC)
+            db.add(obj)
+            await db.commit()
+            await db.refresh(obj)
+            return obj
+        except Exception as e:
+            await db.rollback()
+            logger.exception(
+                "Error soft deleting %s with id %s: %s", self.model.__name__, id, e
+            )
+            raise
+
+    async def restore(self, db: AsyncSession, *, id: str) -> ModelType | None:
+        """
+        Restore a soft-deleted record by clearing the deleted_at timestamp.
+
+        Only works if the model has a 'deleted_at' column.
+        """
+        try:
+            if isinstance(id, uuid.UUID):
+                uuid_obj = id
+            else:
+                uuid_obj = uuid.UUID(str(id))
+        except (ValueError, AttributeError, TypeError) as e:
+            logger.warning("Invalid UUID format for restoration: %s - %s", id, e)
+            return None
+
+        try:
+            if hasattr(self.model, "deleted_at"):
+                result = await db.execute(
+                    select(self.model).where(
+                        self.model.id == uuid_obj, self.model.deleted_at.isnot(None)
+                    )
+                )
+                obj = result.scalar_one_or_none()
+            else:
+                logger.error("%s does not support soft deletes", self.model.__name__)
+                raise InvalidInputError(
+                    f"{self.model.__name__} does not have a deleted_at column"
+                )
+
+            if obj is None:
+                logger.warning(
+                    "Soft-deleted %s with id %s not found for restoration",
+                    self.model.__name__,
+                    id,
+                )
+                return None
+
+            obj.deleted_at = None
+            db.add(obj)
+            await db.commit()
+            await db.refresh(obj)
+            return obj
+        except Exception as e:
+            await db.rollback()
+            logger.exception(
+                "Error restoring %s with id %s: %s", self.model.__name__, id, e
+            )
+            raise

backend/app/repositories/oauth_account.py

@@ -0,0 +1,249 @@
+# app/repositories/oauth_account.py
+"""Repository for OAuthAccount model async database operations."""
+
+import logging
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel
+from sqlalchemy import and_, delete, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import joinedload
+
+from app.core.repository_exceptions import DuplicateEntryError
+from app.models.oauth_account import OAuthAccount
+from app.repositories.base import BaseRepository
+from app.schemas.oauth import OAuthAccountCreate
+
+logger = logging.getLogger(__name__)
+
+
+class EmptySchema(BaseModel):
+    """Placeholder schema for repository operations that don't need update schemas."""
+
+
+class OAuthAccountRepository(
+    BaseRepository[OAuthAccount, OAuthAccountCreate, EmptySchema]
+):
+    """Repository for OAuth account links."""
+
+    async def get_by_provider_id(
+        self,
+        db: AsyncSession,
+        *,
+        provider: str,
+        provider_user_id: str,
+    ) -> OAuthAccount | None:
+        """Get OAuth account by provider and provider user ID."""
+        try:
+            result = await db.execute(
+                select(OAuthAccount)
+                .where(
+                    and_(
+                        OAuthAccount.provider == provider,
+                        OAuthAccount.provider_user_id == provider_user_id,
+                    )
+                )
+                .options(joinedload(OAuthAccount.user))
+            )
+            return result.scalar_one_or_none()
+        except Exception as e:  # pragma: no cover
+            logger.error(
+                "Error getting OAuth account for %s:%s: %s",
+                provider,
+                provider_user_id,
+                e,
+            )
+            raise
+
+    async def get_by_provider_email(
+        self,
+        db: AsyncSession,
+        *,
+        provider: str,
+        email: str,
+    ) -> OAuthAccount | None:
+        """Get OAuth account by provider and email."""
+        try:
+            result = await db.execute(
+                select(OAuthAccount)
+                .where(
+                    and_(
+                        OAuthAccount.provider == provider,
+                        OAuthAccount.provider_email == email,
+                    )
+                )
+                .options(joinedload(OAuthAccount.user))
+            )
+            return result.scalar_one_or_none()
+        except Exception as e:  # pragma: no cover
+            logger.error(
+                "Error getting OAuth account for %s email %s: %s", provider, email, e
+            )
+            raise
+
+    async def get_user_accounts(
+        self,
+        db: AsyncSession,
+        *,
+        user_id: str | UUID,
+    ) -> list[OAuthAccount]:
+        """Get all OAuth accounts linked to a user."""
+        try:
+            user_uuid = UUID(str(user_id)) if isinstance(user_id, str) else user_id
+
+            result = await db.execute(
+                select(OAuthAccount)
+                .where(OAuthAccount.user_id == user_uuid)
+                .order_by(OAuthAccount.created_at.desc())
+            )
+            return list(result.scalars().all())
+        except Exception as e:  # pragma: no cover
+            logger.error("Error getting OAuth accounts for user %s: %s", user_id, e)
+            raise
+
+    async def get_user_account_by_provider(
+        self,
+        db: AsyncSession,
+        *,
+        user_id: str | UUID,
+        provider: str,
+    ) -> OAuthAccount | None:
+        """Get a specific OAuth account for a user and provider."""
+        try:
+            user_uuid = UUID(str(user_id)) if isinstance(user_id, str) else user_id
+
+            result = await db.execute(
+                select(OAuthAccount).where(
+                    and_(
+                        OAuthAccount.user_id == user_uuid,
+                        OAuthAccount.provider == provider,
+                    )
+                )
+            )
+            return result.scalar_one_or_none()
+        except Exception as e:  # pragma: no cover
+            logger.error(
+                "Error getting OAuth account for user %s, provider %s: %s",
+                user_id,
+                provider,
+                e,
+            )
+            raise
+
+    async def create_account(
+        self, db: AsyncSession, *, obj_in: OAuthAccountCreate
+    ) -> OAuthAccount:
+        """Create a new OAuth account link."""
+        try:
+            db_obj = OAuthAccount(
+                user_id=obj_in.user_id,
+                provider=obj_in.provider,
+                provider_user_id=obj_in.provider_user_id,
+                provider_email=obj_in.provider_email,
+                access_token=obj_in.access_token,
+                refresh_token=obj_in.refresh_token,
+                token_expires_at=obj_in.token_expires_at,
+            )
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+
+            logger.info(
+                "OAuth account created: %s linked to user %s",
+                obj_in.provider,
+                obj_in.user_id,
+            )
+            return db_obj
+        except IntegrityError as e:  # pragma: no cover
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            if "uq_oauth_provider_user" in error_msg.lower():
+                logger.warning(
+                    "OAuth account already exists: %s:%s",
+                    obj_in.provider,
+                    obj_in.provider_user_id,
+                )
+                raise DuplicateEntryError(
+                    f"This {obj_in.provider} account is already linked to another user"
+                )
+            logger.error("Integrity error creating OAuth account: %s", error_msg)
+            raise DuplicateEntryError(f"Failed to create OAuth account: {error_msg}")
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.exception("Error creating OAuth account: %s", e)
+            raise
+
+    async def delete_account(
+        self,
+        db: AsyncSession,
+        *,
+        user_id: str | UUID,
+        provider: str,
+    ) -> bool:
+        """Delete an OAuth account link."""
+        try:
+            user_uuid = UUID(str(user_id)) if isinstance(user_id, str) else user_id
+
+            result = await db.execute(
+                delete(OAuthAccount).where(
+                    and_(
+                        OAuthAccount.user_id == user_uuid,
+                        OAuthAccount.provider == provider,
+                    )
+                )
+            )
+            await db.commit()
+
+            deleted = result.rowcount > 0
+            if deleted:
+                logger.info(
+                    "OAuth account deleted: %s unlinked from user %s", provider, user_id
+                )
+            else:
+                logger.warning(
+                    "OAuth account not found for deletion: %s for user %s",
+                    provider,
+                    user_id,
+                )
+
+            return deleted
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.error(
+                "Error deleting OAuth account %s for user %s: %s", provider, user_id, e
+            )
+            raise
+
+    async def update_tokens(
+        self,
+        db: AsyncSession,
+        *,
+        account: OAuthAccount,
+        access_token: str | None = None,
+        refresh_token: str | None = None,
+        token_expires_at: datetime | None = None,
+    ) -> OAuthAccount:
+        """Update OAuth tokens for an account."""
+        try:
+            if access_token is not None:
+                account.access_token = access_token
+            if refresh_token is not None:
+                account.refresh_token = refresh_token
+            if token_expires_at is not None:
+                account.token_expires_at = token_expires_at
+
+            db.add(account)
+            await db.commit()
+            await db.refresh(account)
+
+            return account
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.error("Error updating OAuth tokens: %s", e)
+            raise
+
+
+# Singleton instance
+oauth_account_repo = OAuthAccountRepository(OAuthAccount)

backend/app/repositories/oauth_authorization_code.py

@@ -0,0 +1,108 @@
+# app/repositories/oauth_authorization_code.py
+"""Repository for OAuthAuthorizationCode model."""
+
+import logging
+from datetime import UTC, datetime
+from uuid import UUID
+
+from sqlalchemy import and_, delete, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.oauth_authorization_code import OAuthAuthorizationCode
+
+logger = logging.getLogger(__name__)
+
+
+class OAuthAuthorizationCodeRepository:
+    """Repository for OAuth 2.0 authorization codes."""
+
+    async def create_code(
+        self,
+        db: AsyncSession,
+        *,
+        code: str,
+        client_id: str,
+        user_id: UUID,
+        redirect_uri: str,
+        scope: str,
+        expires_at: datetime,
+        code_challenge: str | None = None,
+        code_challenge_method: str | None = None,
+        state: str | None = None,
+        nonce: str | None = None,
+    ) -> OAuthAuthorizationCode:
+        """Create and persist a new authorization code."""
+        auth_code = OAuthAuthorizationCode(
+            code=code,
+            client_id=client_id,
+            user_id=user_id,
+            redirect_uri=redirect_uri,
+            scope=scope,
+            code_challenge=code_challenge,
+            code_challenge_method=code_challenge_method,
+            state=state,
+            nonce=nonce,
+            expires_at=expires_at,
+            used=False,
+        )
+        db.add(auth_code)
+        await db.commit()
+        return auth_code
+
+    async def consume_code_atomically(
+        self, db: AsyncSession, *, code: str
+    ) -> UUID | None:
+        """
+        Atomically mark a code as used and return its UUID.
+
+        Returns the UUID if the code was found and not yet used, None otherwise.
+        This prevents race conditions per RFC 6749 Section 4.1.2.
+        """
+        stmt = (
+            update(OAuthAuthorizationCode)
+            .where(
+                and_(
+                    OAuthAuthorizationCode.code == code,
+                    OAuthAuthorizationCode.used == False,  # noqa: E712
+                )
+            )
+            .values(used=True)
+            .returning(OAuthAuthorizationCode.id)
+        )
+        result = await db.execute(stmt)
+        row_id = result.scalar_one_or_none()
+        if row_id is not None:
+            await db.commit()
+        return row_id
+
+    async def get_by_id(
+        self, db: AsyncSession, *, code_id: UUID
+    ) -> OAuthAuthorizationCode | None:
+        """Get authorization code by its UUID primary key."""
+        result = await db.execute(
+            select(OAuthAuthorizationCode).where(OAuthAuthorizationCode.id == code_id)
+        )
+        return result.scalar_one_or_none()
+
+    async def get_by_code(
+        self, db: AsyncSession, *, code: str
+    ) -> OAuthAuthorizationCode | None:
+        """Get authorization code by the code string value."""
+        result = await db.execute(
+            select(OAuthAuthorizationCode).where(OAuthAuthorizationCode.code == code)
+        )
+        return result.scalar_one_or_none()
+
+    async def cleanup_expired(self, db: AsyncSession) -> int:
+        """Delete all expired authorization codes. Returns count deleted."""
+        result = await db.execute(
+            delete(OAuthAuthorizationCode).where(
+                OAuthAuthorizationCode.expires_at < datetime.now(UTC)
+            )
+        )
+        await db.commit()
+        return result.rowcount  # type: ignore[attr-defined]
+
+
+# Singleton instance
+oauth_authorization_code_repo = OAuthAuthorizationCodeRepository()

backend/app/repositories/oauth_client.py

@@ -0,0 +1,201 @@
+# app/repositories/oauth_client.py
+"""Repository for OAuthClient model async database operations."""
+
+import logging
+import secrets
+from uuid import UUID
+
+from pydantic import BaseModel
+from sqlalchemy import and_, delete, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.repository_exceptions import DuplicateEntryError
+from app.models.oauth_client import OAuthClient
+from app.repositories.base import BaseRepository
+from app.schemas.oauth import OAuthClientCreate
+
+logger = logging.getLogger(__name__)
+
+
+class EmptySchema(BaseModel):
+    """Placeholder schema for repository operations that don't need update schemas."""
+
+
+class OAuthClientRepository(
+    BaseRepository[OAuthClient, OAuthClientCreate, EmptySchema]
+):
+    """Repository for OAuth clients (provider mode)."""
+
+    async def get_by_client_id(
+        self, db: AsyncSession, *, client_id: str
+    ) -> OAuthClient | None:
+        """Get OAuth client by client_id."""
+        try:
+            result = await db.execute(
+                select(OAuthClient).where(
+                    and_(
+                        OAuthClient.client_id == client_id,
+                        OAuthClient.is_active == True,  # noqa: E712
+                    )
+                )
+            )
+            return result.scalar_one_or_none()
+        except Exception as e:  # pragma: no cover
+            logger.error("Error getting OAuth client %s: %s", client_id, e)
+            raise
+
+    async def create_client(
+        self,
+        db: AsyncSession,
+        *,
+        obj_in: OAuthClientCreate,
+        owner_user_id: UUID | None = None,
+    ) -> tuple[OAuthClient, str | None]:
+        """Create a new OAuth client."""
+        try:
+            client_id = secrets.token_urlsafe(32)
+
+            client_secret = None
+            client_secret_hash = None
+            if obj_in.client_type == "confidential":
+                client_secret = secrets.token_urlsafe(48)
+                from app.core.auth import get_password_hash
+
+                client_secret_hash = get_password_hash(client_secret)
+
+            db_obj = OAuthClient(
+                client_id=client_id,
+                client_secret_hash=client_secret_hash,
+                client_name=obj_in.client_name,
+                client_description=obj_in.client_description,
+                client_type=obj_in.client_type,
+                redirect_uris=obj_in.redirect_uris,
+                allowed_scopes=obj_in.allowed_scopes,
+                owner_user_id=owner_user_id,
+                is_active=True,
+            )
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+
+            logger.info(
+                "OAuth client created: %s (%s...)", obj_in.client_name, client_id[:8]
+            )
+            return db_obj, client_secret
+        except IntegrityError as e:  # pragma: no cover
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            logger.error("Error creating OAuth client: %s", error_msg)
+            raise DuplicateEntryError(f"Failed to create OAuth client: {error_msg}")
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.exception("Error creating OAuth client: %s", e)
+            raise
+
+    async def deactivate_client(
+        self, db: AsyncSession, *, client_id: str
+    ) -> OAuthClient | None:
+        """Deactivate an OAuth client."""
+        try:
+            client = await self.get_by_client_id(db, client_id=client_id)
+            if client is None:
+                return None
+
+            client.is_active = False
+            db.add(client)
+            await db.commit()
+            await db.refresh(client)
+
+            logger.info("OAuth client deactivated: %s", client.client_name)
+            return client
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.error("Error deactivating OAuth client %s: %s", client_id, e)
+            raise
+
+    async def validate_redirect_uri(
+        self, db: AsyncSession, *, client_id: str, redirect_uri: str
+    ) -> bool:
+        """Validate that a redirect URI is allowed for a client."""
+        try:
+            client = await self.get_by_client_id(db, client_id=client_id)
+            if client is None:
+                return False
+
+            return redirect_uri in (client.redirect_uris or [])
+        except Exception as e:  # pragma: no cover
+            logger.error("Error validating redirect URI: %s", e)
+            return False
+
+    async def verify_client_secret(
+        self, db: AsyncSession, *, client_id: str, client_secret: str
+    ) -> bool:
+        """Verify client credentials."""
+        try:
+            result = await db.execute(
+                select(OAuthClient).where(
+                    and_(
+                        OAuthClient.client_id == client_id,
+                        OAuthClient.is_active == True,  # noqa: E712
+                    )
+                )
+            )
+            client = result.scalar_one_or_none()
+
+            if client is None or client.client_secret_hash is None:
+                return False
+
+            from app.core.auth import verify_password
+
+            stored_hash: str = str(client.client_secret_hash)
+
+            if stored_hash.startswith("$2"):
+                return verify_password(client_secret, stored_hash)
+            else:
+                import hashlib
+
+                secret_hash = hashlib.sha256(client_secret.encode()).hexdigest()
+                return secrets.compare_digest(stored_hash, secret_hash)
+        except Exception as e:  # pragma: no cover
+            logger.error("Error verifying client secret: %s", e)
+            return False
+
+    async def get_all_clients(
+        self, db: AsyncSession, *, include_inactive: bool = False
+    ) -> list[OAuthClient]:
+        """Get all OAuth clients."""
+        try:
+            query = select(OAuthClient).order_by(OAuthClient.created_at.desc())
+            if not include_inactive:
+                query = query.where(OAuthClient.is_active == True)  # noqa: E712
+
+            result = await db.execute(query)
+            return list(result.scalars().all())
+        except Exception as e:  # pragma: no cover
+            logger.error("Error getting all OAuth clients: %s", e)
+            raise
+
+    async def delete_client(self, db: AsyncSession, *, client_id: str) -> bool:
+        """Delete an OAuth client permanently."""
+        try:
+            result = await db.execute(
+                delete(OAuthClient).where(OAuthClient.client_id == client_id)
+            )
+            await db.commit()
+
+            deleted = result.rowcount > 0
+            if deleted:
+                logger.info("OAuth client deleted: %s", client_id)
+            else:
+                logger.warning("OAuth client not found for deletion: %s", client_id)
+
+            return deleted
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.error("Error deleting OAuth client %s: %s", client_id, e)
+            raise
+
+
+# Singleton instance
+oauth_client_repo = OAuthClientRepository(OAuthClient)

backend/app/repositories/oauth_consent.py

@@ -0,0 +1,113 @@
+# app/repositories/oauth_consent.py
+"""Repository for OAuthConsent model."""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import and_, delete, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.oauth_client import OAuthClient
+from app.models.oauth_provider_token import OAuthConsent
+
+logger = logging.getLogger(__name__)
+
+
+class OAuthConsentRepository:
+    """Repository for OAuth consent records (user grants to clients)."""
+
+    async def get_consent(
+        self, db: AsyncSession, *, user_id: UUID, client_id: str
+    ) -> OAuthConsent | None:
+        """Get the consent record for a user-client pair, or None if not found."""
+        result = await db.execute(
+            select(OAuthConsent).where(
+                and_(
+                    OAuthConsent.user_id == user_id,
+                    OAuthConsent.client_id == client_id,
+                )
+            )
+        )
+        return result.scalar_one_or_none()
+
+    async def grant_consent(
+        self,
+        db: AsyncSession,
+        *,
+        user_id: UUID,
+        client_id: str,
+        scopes: list[str],
+    ) -> OAuthConsent:
+        """
+        Create or update consent for a user-client pair.
+
+        If consent already exists, the new scopes are merged with existing ones.
+        Returns the created or updated consent record.
+        """
+        consent = await self.get_consent(db, user_id=user_id, client_id=client_id)
+
+        if consent:
+            existing = (
+                set(consent.granted_scopes.split()) if consent.granted_scopes else set()
+            )
+            merged = existing | set(scopes)
+            consent.granted_scopes = " ".join(sorted(merged))  # type: ignore[assignment]
+        else:
+            consent = OAuthConsent(
+                user_id=user_id,
+                client_id=client_id,
+                granted_scopes=" ".join(sorted(set(scopes))),
+            )
+            db.add(consent)
+
+        await db.commit()
+        await db.refresh(consent)
+        return consent
+
+    async def get_user_consents_with_clients(
+        self, db: AsyncSession, *, user_id: UUID
+    ) -> list[dict[str, Any]]:
+        """Get all consent records for a user joined with client details."""
+        result = await db.execute(
+            select(OAuthConsent, OAuthClient)
+            .join(OAuthClient, OAuthConsent.client_id == OAuthClient.client_id)
+            .where(OAuthConsent.user_id == user_id)
+        )
+        rows = result.all()
+        return [
+            {
+                "client_id": consent.client_id,
+                "client_name": client.client_name,
+                "client_description": client.client_description,
+                "granted_scopes": consent.granted_scopes.split()
+                if consent.granted_scopes
+                else [],
+                "granted_at": consent.created_at.isoformat(),
+            }
+            for consent, client in rows
+        ]
+
+    async def revoke_consent(
+        self, db: AsyncSession, *, user_id: UUID, client_id: str
+    ) -> bool:
+        """
+        Delete the consent record for a user-client pair.
+
+        Returns True if a record was found and deleted.
+        Note: Callers are responsible for also revoking associated tokens.
+        """
+        result = await db.execute(
+            delete(OAuthConsent).where(
+                and_(
+                    OAuthConsent.user_id == user_id,
+                    OAuthConsent.client_id == client_id,
+                )
+            )
+        )
+        await db.commit()
+        return result.rowcount > 0  # type: ignore[attr-defined]
+
+
+# Singleton instance
+oauth_consent_repo = OAuthConsentRepository()

backend/app/repositories/oauth_provider_token.py

@@ -0,0 +1,142 @@
+# app/repositories/oauth_provider_token.py
+"""Repository for OAuthProviderRefreshToken model."""
+
+import logging
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+from sqlalchemy import and_, delete, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.oauth_provider_token import OAuthProviderRefreshToken
+
+logger = logging.getLogger(__name__)
+
+
+class OAuthProviderTokenRepository:
+    """Repository for OAuth provider refresh tokens."""
+
+    async def create_token(
+        self,
+        db: AsyncSession,
+        *,
+        token_hash: str,
+        jti: str,
+        client_id: str,
+        user_id: UUID,
+        scope: str,
+        expires_at: datetime,
+        device_info: str | None = None,
+        ip_address: str | None = None,
+    ) -> OAuthProviderRefreshToken:
+        """Create and persist a new refresh token record."""
+        token = OAuthProviderRefreshToken(
+            token_hash=token_hash,
+            jti=jti,
+            client_id=client_id,
+            user_id=user_id,
+            scope=scope,
+            expires_at=expires_at,
+            device_info=device_info,
+            ip_address=ip_address,
+        )
+        db.add(token)
+        await db.commit()
+        return token
+
+    async def get_by_token_hash(
+        self, db: AsyncSession, *, token_hash: str
+    ) -> OAuthProviderRefreshToken | None:
+        """Get refresh token record by SHA-256 token hash."""
+        result = await db.execute(
+            select(OAuthProviderRefreshToken).where(
+                OAuthProviderRefreshToken.token_hash == token_hash
+            )
+        )
+        return result.scalar_one_or_none()
+
+    async def get_by_jti(
+        self, db: AsyncSession, *, jti: str
+    ) -> OAuthProviderRefreshToken | None:
+        """Get refresh token record by JWT ID (JTI)."""
+        result = await db.execute(
+            select(OAuthProviderRefreshToken).where(
+                OAuthProviderRefreshToken.jti == jti
+            )
+        )
+        return result.scalar_one_or_none()
+
+    async def revoke(
+        self, db: AsyncSession, *, token: OAuthProviderRefreshToken
+    ) -> None:
+        """Mark a specific token record as revoked."""
+        token.revoked = True  # type: ignore[assignment]
+        token.last_used_at = datetime.now(UTC)  # type: ignore[assignment]
+        await db.commit()
+
+    async def revoke_all_for_user_client(
+        self, db: AsyncSession, *, user_id: UUID, client_id: str
+    ) -> int:
+        """
+        Revoke all active tokens for a specific user-client pair.
+
+        Used when security incidents are detected (e.g., authorization code reuse).
+        Returns the number of tokens revoked.
+        """
+        result = await db.execute(
+            update(OAuthProviderRefreshToken)
+            .where(
+                and_(
+                    OAuthProviderRefreshToken.user_id == user_id,
+                    OAuthProviderRefreshToken.client_id == client_id,
+                    OAuthProviderRefreshToken.revoked == False,  # noqa: E712
+                )
+            )
+            .values(revoked=True)
+        )
+        count = result.rowcount  # type: ignore[attr-defined]
+        if count > 0:
+            await db.commit()
+        return count
+
+    async def revoke_all_for_user(self, db: AsyncSession, *, user_id: UUID) -> int:
+        """
+        Revoke all active tokens for a user across all clients.
+
+        Used when user changes password or logs out everywhere.
+        Returns the number of tokens revoked.
+        """
+        result = await db.execute(
+            update(OAuthProviderRefreshToken)
+            .where(
+                and_(
+                    OAuthProviderRefreshToken.user_id == user_id,
+                    OAuthProviderRefreshToken.revoked == False,  # noqa: E712
+                )
+            )
+            .values(revoked=True)
+        )
+        count = result.rowcount  # type: ignore[attr-defined]
+        if count > 0:
+            await db.commit()
+        return count
+
+    async def cleanup_expired(self, db: AsyncSession, *, cutoff_days: int = 7) -> int:
+        """
+        Delete expired refresh tokens older than cutoff_days.
+
+        Should be called periodically (e.g., daily).
+        Returns the number of tokens deleted.
+        """
+        cutoff = datetime.now(UTC) - timedelta(days=cutoff_days)
+        result = await db.execute(
+            delete(OAuthProviderRefreshToken).where(
+                OAuthProviderRefreshToken.expires_at < cutoff
+            )
+        )
+        await db.commit()
+        return result.rowcount  # type: ignore[attr-defined]
+
+
+# Singleton instance
+oauth_provider_token_repo = OAuthProviderTokenRepository()

backend/app/repositories/oauth_state.py

@@ -0,0 +1,113 @@
+# app/repositories/oauth_state.py
+"""Repository for OAuthState model async database operations."""
+
+import logging
+from datetime import UTC, datetime
+
+from pydantic import BaseModel
+from sqlalchemy import delete, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.repository_exceptions import DuplicateEntryError
+from app.models.oauth_state import OAuthState
+from app.repositories.base import BaseRepository
+from app.schemas.oauth import OAuthStateCreate
+
+logger = logging.getLogger(__name__)
+
+
+class EmptySchema(BaseModel):
+    """Placeholder schema for repository operations that don't need update schemas."""
+
+
+class OAuthStateRepository(BaseRepository[OAuthState, OAuthStateCreate, EmptySchema]):
+    """Repository for OAuth state (CSRF protection)."""
+
+    async def create_state(
+        self, db: AsyncSession, *, obj_in: OAuthStateCreate
+    ) -> OAuthState:
+        """Create a new OAuth state for CSRF protection."""
+        try:
+            db_obj = OAuthState(
+                state=obj_in.state,
+                code_verifier=obj_in.code_verifier,
+                nonce=obj_in.nonce,
+                provider=obj_in.provider,
+                redirect_uri=obj_in.redirect_uri,
+                user_id=obj_in.user_id,
+                expires_at=obj_in.expires_at,
+            )
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+
+            logger.debug("OAuth state created for %s", obj_in.provider)
+            return db_obj
+        except IntegrityError as e:  # pragma: no cover
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            logger.error("OAuth state collision: %s", error_msg)
+            raise DuplicateEntryError("Failed to create OAuth state, please retry")
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.exception("Error creating OAuth state: %s", e)
+            raise
+
+    async def get_and_consume_state(
+        self, db: AsyncSession, *, state: str
+    ) -> OAuthState | None:
+        """Get and delete OAuth state (consume it)."""
+        try:
+            result = await db.execute(
+                select(OAuthState).where(OAuthState.state == state)
+            )
+            db_obj = result.scalar_one_or_none()
+
+            if db_obj is None:
+                logger.warning("OAuth state not found: %s...", state[:8])
+                return None
+
+            now = datetime.now(UTC)
+            expires_at = db_obj.expires_at
+            if expires_at.tzinfo is None:
+                expires_at = expires_at.replace(tzinfo=UTC)
+
+            if expires_at < now:
+                logger.warning("OAuth state expired: %s...", state[:8])
+                await db.delete(db_obj)
+                await db.commit()
+                return None
+
+            await db.delete(db_obj)
+            await db.commit()
+
+            logger.debug("OAuth state consumed: %s...", state[:8])
+            return db_obj
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.error("Error consuming OAuth state: %s", e)
+            raise
+
+    async def cleanup_expired(self, db: AsyncSession) -> int:
+        """Clean up expired OAuth states."""
+        try:
+            now = datetime.now(UTC)
+
+            stmt = delete(OAuthState).where(OAuthState.expires_at < now)
+            result = await db.execute(stmt)
+            await db.commit()
+
+            count = result.rowcount
+            if count > 0:
+                logger.info("Cleaned up %s expired OAuth states", count)
+
+            return count
+        except Exception as e:  # pragma: no cover
+            await db.rollback()
+            logger.error("Error cleaning up expired OAuth states: %s", e)
+            raise
+
+
+# Singleton instance
+oauth_state_repo = OAuthStateRepository(OAuthState)

backend/app/repositories/organization.py

@@ -0,0 +1,499 @@
+# app/repositories/organization.py
+"""Repository for Organization model async database operations using SQLAlchemy 2.0 patterns."""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import and_, case, func, or_, select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.repository_exceptions import DuplicateEntryError, IntegrityConstraintError
+from app.models.organization import Organization
+from app.models.user import User
+from app.models.user_organization import OrganizationRole, UserOrganization
+from app.repositories.base import BaseRepository
+from app.schemas.organizations import (
+    OrganizationCreate,
+    OrganizationUpdate,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class OrganizationRepository(
+    BaseRepository[Organization, OrganizationCreate, OrganizationUpdate]
+):
+    """Repository for Organization model."""
+
+    async def get_by_slug(self, db: AsyncSession, *, slug: str) -> Organization | None:
+        """Get organization by slug."""
+        try:
+            result = await db.execute(
+                select(Organization).where(Organization.slug == slug)
+            )
+            return result.scalar_one_or_none()
+        except Exception as e:
+            logger.error("Error getting organization by slug %s: %s", slug, e)
+            raise
+
+    async def create(
+        self, db: AsyncSession, *, obj_in: OrganizationCreate
+    ) -> Organization:
+        """Create a new organization with error handling."""
+        try:
+            db_obj = Organization(
+                name=obj_in.name,
+                slug=obj_in.slug,
+                description=obj_in.description,
+                is_active=obj_in.is_active,
+                settings=obj_in.settings or {},
+            )
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+            return db_obj
+        except IntegrityError as e:
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            if (
+                "slug" in error_msg.lower()
+                or "unique" in error_msg.lower()
+                or "duplicate" in error_msg.lower()
+            ):
+                logger.warning("Duplicate slug attempted: %s", obj_in.slug)
+                raise DuplicateEntryError(
+                    f"Organization with slug '{obj_in.slug}' already exists"
+                )
+            logger.error("Integrity error creating organization: %s", error_msg)
+            raise IntegrityConstraintError(f"Database integrity error: {error_msg}")
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Unexpected error creating organization: %s", e)
+            raise
+
+    async def get_multi_with_filters(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        is_active: bool | None = None,
+        search: str | None = None,
+        sort_by: str = "created_at",
+        sort_order: str = "desc",
+    ) -> tuple[list[Organization], int]:
+        """Get multiple organizations with filtering, searching, and sorting."""
+        try:
+            query = select(Organization)
+
+            if is_active is not None:
+                query = query.where(Organization.is_active == is_active)
+
+            if search:
+                search_filter = or_(
+                    Organization.name.ilike(f"%{search}%"),
+                    Organization.slug.ilike(f"%{search}%"),
+                    Organization.description.ilike(f"%{search}%"),
+                )
+                query = query.where(search_filter)
+
+            count_query = select(func.count()).select_from(query.alias())
+            count_result = await db.execute(count_query)
+            total = count_result.scalar_one()
+
+            sort_column = getattr(Organization, sort_by, Organization.created_at)
+            if sort_order == "desc":
+                query = query.order_by(sort_column.desc())
+            else:
+                query = query.order_by(sort_column.asc())
+
+            query = query.offset(skip).limit(limit)
+            result = await db.execute(query)
+            organizations = list(result.scalars().all())
+
+            return organizations, total
+        except Exception as e:
+            logger.error("Error getting organizations with filters: %s", e)
+            raise
+
+    async def get_member_count(self, db: AsyncSession, *, organization_id: UUID) -> int:
+        """Get the count of active members in an organization."""
+        try:
+            result = await db.execute(
+                select(func.count(UserOrganization.user_id)).where(
+                    and_(
+                        UserOrganization.organization_id == organization_id,
+                        UserOrganization.is_active,
+                    )
+                )
+            )
+            return result.scalar_one() or 0
+        except Exception as e:
+            logger.error(
+                "Error getting member count for organization %s: %s", organization_id, e
+            )
+            raise
+
+    async def get_multi_with_member_counts(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        is_active: bool | None = None,
+        search: str | None = None,
+    ) -> tuple[list[dict[str, Any]], int]:
+        """Get organizations with member counts in a SINGLE QUERY using JOIN and GROUP BY."""
+        try:
+            query = (
+                select(
+                    Organization,
+                    func.count(
+                        func.distinct(
+                            case(
+                                (
+                                    UserOrganization.is_active,
+                                    UserOrganization.user_id,
+                                ),
+                                else_=None,
+                            )
+                        )
+                    ).label("member_count"),
+                )
+                .outerjoin(
+                    UserOrganization,
+                    Organization.id == UserOrganization.organization_id,
+                )
+                .group_by(Organization.id)
+            )
+
+            if is_active is not None:
+                query = query.where(Organization.is_active == is_active)
+
+            search_filter = None
+            if search:
+                search_filter = or_(
+                    Organization.name.ilike(f"%{search}%"),
+                    Organization.slug.ilike(f"%{search}%"),
+                    Organization.description.ilike(f"%{search}%"),
+                )
+                query = query.where(search_filter)
+
+            count_query = select(func.count(Organization.id))
+            if is_active is not None:
+                count_query = count_query.where(Organization.is_active == is_active)
+            if search_filter is not None:
+                count_query = count_query.where(search_filter)
+
+            count_result = await db.execute(count_query)
+            total = count_result.scalar_one()
+
+            query = (
+                query.order_by(Organization.created_at.desc()).offset(skip).limit(limit)
+            )
+
+            result = await db.execute(query)
+            rows = result.all()
+
+            orgs_with_counts = [
+                {"organization": org, "member_count": member_count}
+                for org, member_count in rows
+            ]
+
+            return orgs_with_counts, total
+
+        except Exception as e:
+            logger.exception("Error getting organizations with member counts: %s", e)
+            raise
+
+    async def add_user(
+        self,
+        db: AsyncSession,
+        *,
+        organization_id: UUID,
+        user_id: UUID,
+        role: OrganizationRole = OrganizationRole.MEMBER,
+        custom_permissions: str | None = None,
+    ) -> UserOrganization:
+        """Add a user to an organization with a specific role."""
+        try:
+            result = await db.execute(
+                select(UserOrganization).where(
+                    and_(
+                        UserOrganization.user_id == user_id,
+                        UserOrganization.organization_id == organization_id,
+                    )
+                )
+            )
+            existing = result.scalar_one_or_none()
+
+            if existing:
+                if not existing.is_active:
+                    existing.is_active = True
+                    existing.role = role
+                    existing.custom_permissions = custom_permissions
+                    await db.commit()
+                    await db.refresh(existing)
+                    return existing
+                else:
+                    raise DuplicateEntryError(
+                        "User is already a member of this organization"
+                    )
+
+            user_org = UserOrganization(
+                user_id=user_id,
+                organization_id=organization_id,
+                role=role,
+                is_active=True,
+                custom_permissions=custom_permissions,
+            )
+            db.add(user_org)
+            await db.commit()
+            await db.refresh(user_org)
+            return user_org
+        except IntegrityError as e:
+            await db.rollback()
+            logger.error("Integrity error adding user to organization: %s", e)
+            raise IntegrityConstraintError("Failed to add user to organization")
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Error adding user to organization: %s", e)
+            raise
+
+    async def remove_user(
+        self, db: AsyncSession, *, organization_id: UUID, user_id: UUID
+    ) -> bool:
+        """Remove a user from an organization (soft delete)."""
+        try:
+            result = await db.execute(
+                select(UserOrganization).where(
+                    and_(
+                        UserOrganization.user_id == user_id,
+                        UserOrganization.organization_id == organization_id,
+                    )
+                )
+            )
+            user_org = result.scalar_one_or_none()
+
+            if not user_org:
+                return False
+
+            user_org.is_active = False
+            await db.commit()
+            return True
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Error removing user from organization: %s", e)
+            raise
+
+    async def update_user_role(
+        self,
+        db: AsyncSession,
+        *,
+        organization_id: UUID,
+        user_id: UUID,
+        role: OrganizationRole,
+        custom_permissions: str | None = None,
+    ) -> UserOrganization | None:
+        """Update a user's role in an organization."""
+        try:
+            result = await db.execute(
+                select(UserOrganization).where(
+                    and_(
+                        UserOrganization.user_id == user_id,
+                        UserOrganization.organization_id == organization_id,
+                    )
+                )
+            )
+            user_org = result.scalar_one_or_none()
+
+            if not user_org:
+                return None
+
+            user_org.role = role
+            if custom_permissions is not None:
+                user_org.custom_permissions = custom_permissions
+            await db.commit()
+            await db.refresh(user_org)
+            return user_org
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Error updating user role: %s", e)
+            raise
+
+    async def get_organization_members(
+        self,
+        db: AsyncSession,
+        *,
+        organization_id: UUID,
+        skip: int = 0,
+        limit: int = 100,
+        is_active: bool | None = True,
+    ) -> tuple[list[dict[str, Any]], int]:
+        """Get members of an organization with user details."""
+        try:
+            query = (
+                select(UserOrganization, User)
+                .join(User, UserOrganization.user_id == User.id)
+                .where(UserOrganization.organization_id == organization_id)
+            )
+
+            if is_active is not None:
+                query = query.where(UserOrganization.is_active == is_active)
+
+            count_query = select(func.count()).select_from(
+                select(UserOrganization)
+                .where(UserOrganization.organization_id == organization_id)
+                .where(
+                    UserOrganization.is_active == is_active
+                    if is_active is not None
+                    else True
+                )
+                .alias()
+            )
+            count_result = await db.execute(count_query)
+            total = count_result.scalar_one()
+
+            query = (
+                query.order_by(UserOrganization.created_at.desc())
+                .offset(skip)
+                .limit(limit)
+            )
+            result = await db.execute(query)
+            results = result.all()
+
+            members = []
+            for user_org, user in results:
+                members.append(
+                    {
+                        "user_id": user.id,
+                        "email": user.email,
+                        "first_name": user.first_name,
+                        "last_name": user.last_name,
+                        "role": user_org.role,
+                        "is_active": user_org.is_active,
+                        "joined_at": user_org.created_at,
+                    }
+                )
+
+            return members, total
+        except Exception as e:
+            logger.error("Error getting organization members: %s", e)
+            raise
+
+    async def get_user_organizations(
+        self, db: AsyncSession, *, user_id: UUID, is_active: bool | None = True
+    ) -> list[Organization]:
+        """Get all organizations a user belongs to."""
+        try:
+            query = (
+                select(Organization)
+                .join(
+                    UserOrganization,
+                    Organization.id == UserOrganization.organization_id,
+                )
+                .where(UserOrganization.user_id == user_id)
+            )
+
+            if is_active is not None:
+                query = query.where(UserOrganization.is_active == is_active)
+
+            result = await db.execute(query)
+            return list(result.scalars().all())
+        except Exception as e:
+            logger.error("Error getting user organizations: %s", e)
+            raise
+
+    async def get_user_organizations_with_details(
+        self, db: AsyncSession, *, user_id: UUID, is_active: bool | None = True
+    ) -> list[dict[str, Any]]:
+        """Get user's organizations with role and member count in SINGLE QUERY."""
+        try:
+            member_count_subq = (
+                select(
+                    UserOrganization.organization_id,
+                    func.count(UserOrganization.user_id).label("member_count"),
+                )
+                .where(UserOrganization.is_active)
+                .group_by(UserOrganization.organization_id)
+                .subquery()
+            )
+
+            query = (
+                select(
+                    Organization,
+                    UserOrganization.role,
+                    func.coalesce(member_count_subq.c.member_count, 0).label(
+                        "member_count"
+                    ),
+                )
+                .join(
+                    UserOrganization,
+                    Organization.id == UserOrganization.organization_id,
+                )
+                .outerjoin(
+                    member_count_subq,
+                    Organization.id == member_count_subq.c.organization_id,
+                )
+                .where(UserOrganization.user_id == user_id)
+            )
+
+            if is_active is not None:
+                query = query.where(UserOrganization.is_active == is_active)
+
+            result = await db.execute(query)
+            rows = result.all()
+
+            return [
+                {"organization": org, "role": role, "member_count": member_count}
+                for org, role, member_count in rows
+            ]
+
+        except Exception as e:
+            logger.exception("Error getting user organizations with details: %s", e)
+            raise
+
+    async def get_user_role_in_org(
+        self, db: AsyncSession, *, user_id: UUID, organization_id: UUID
+    ) -> OrganizationRole | None:
+        """Get a user's role in a specific organization."""
+        try:
+            result = await db.execute(
+                select(UserOrganization).where(
+                    and_(
+                        UserOrganization.user_id == user_id,
+                        UserOrganization.organization_id == organization_id,
+                        UserOrganization.is_active,
+                    )
+                )
+            )
+            user_org = result.scalar_one_or_none()
+
+            return user_org.role if user_org else None  # pyright: ignore[reportReturnType]
+        except Exception as e:
+            logger.error("Error getting user role in org: %s", e)
+            raise
+
+    async def is_user_org_owner(
+        self, db: AsyncSession, *, user_id: UUID, organization_id: UUID
+    ) -> bool:
+        """Check if a user is an owner of an organization."""
+        role = await self.get_user_role_in_org(
+            db, user_id=user_id, organization_id=organization_id
+        )
+        return role == OrganizationRole.OWNER
+
+    async def is_user_org_admin(
+        self, db: AsyncSession, *, user_id: UUID, organization_id: UUID
+    ) -> bool:
+        """Check if a user is an owner or admin of an organization."""
+        role = await self.get_user_role_in_org(
+            db, user_id=user_id, organization_id=organization_id
+        )
+        return role in [OrganizationRole.OWNER, OrganizationRole.ADMIN]
+
+
+# Singleton instance
+organization_repo = OrganizationRepository(Organization)

backend/app/repositories/session.py

@@ -0,0 +1,333 @@
+# app/repositories/session.py
+"""Repository for UserSession model async database operations using SQLAlchemy 2.0 patterns."""
+
+import logging
+import uuid
+from datetime import UTC, datetime, timedelta
+from uuid import UUID
+
+from sqlalchemy import and_, delete, func, select, update
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy.orm import joinedload
+
+from app.core.repository_exceptions import IntegrityConstraintError, InvalidInputError
+from app.models.user_session import UserSession
+from app.repositories.base import BaseRepository
+from app.schemas.sessions import SessionCreate, SessionUpdate
+
+logger = logging.getLogger(__name__)
+
+
+class SessionRepository(BaseRepository[UserSession, SessionCreate, SessionUpdate]):
+    """Repository for UserSession model."""
+
+    async def get_by_jti(self, db: AsyncSession, *, jti: str) -> UserSession | None:
+        """Get session by refresh token JTI."""
+        try:
+            result = await db.execute(
+                select(UserSession).where(UserSession.refresh_token_jti == jti)
+            )
+            return result.scalar_one_or_none()
+        except Exception as e:
+            logger.error("Error getting session by JTI %s: %s", jti, e)
+            raise
+
+    async def get_active_by_jti(
+        self, db: AsyncSession, *, jti: str
+    ) -> UserSession | None:
+        """Get active session by refresh token JTI."""
+        try:
+            result = await db.execute(
+                select(UserSession).where(
+                    and_(
+                        UserSession.refresh_token_jti == jti,
+                        UserSession.is_active,
+                    )
+                )
+            )
+            return result.scalar_one_or_none()
+        except Exception as e:
+            logger.error("Error getting active session by JTI %s: %s", jti, e)
+            raise
+
+    async def get_user_sessions(
+        self,
+        db: AsyncSession,
+        *,
+        user_id: str,
+        active_only: bool = True,
+        with_user: bool = False,
+    ) -> list[UserSession]:
+        """Get all sessions for a user with optional eager loading."""
+        try:
+            user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+
+            query = select(UserSession).where(UserSession.user_id == user_uuid)
+
+            if with_user:
+                query = query.options(joinedload(UserSession.user))
+
+            if active_only:
+                query = query.where(UserSession.is_active)
+
+            query = query.order_by(UserSession.last_used_at.desc())
+            result = await db.execute(query)
+            return list(result.scalars().all())
+        except Exception as e:
+            logger.error("Error getting sessions for user %s: %s", user_id, e)
+            raise
+
+    async def create_session(
+        self, db: AsyncSession, *, obj_in: SessionCreate
+    ) -> UserSession:
+        """Create a new user session."""
+        try:
+            db_obj = UserSession(
+                user_id=obj_in.user_id,
+                refresh_token_jti=obj_in.refresh_token_jti,
+                device_name=obj_in.device_name,
+                device_id=obj_in.device_id,
+                ip_address=obj_in.ip_address,
+                user_agent=obj_in.user_agent,
+                last_used_at=obj_in.last_used_at,
+                expires_at=obj_in.expires_at,
+                is_active=True,
+                location_city=obj_in.location_city,
+                location_country=obj_in.location_country,
+            )
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+
+            logger.info(
+                "Session created for user %s from %s (IP: %s)",
+                obj_in.user_id,
+                obj_in.device_name,
+                obj_in.ip_address,
+            )
+
+            return db_obj
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Error creating session: %s", e)
+            raise IntegrityConstraintError(f"Failed to create session: {e!s}")
+
+    async def deactivate(
+        self, db: AsyncSession, *, session_id: str
+    ) -> UserSession | None:
+        """Deactivate a session (logout from device)."""
+        try:
+            session = await self.get(db, id=session_id)
+            if not session:
+                logger.warning("Session %s not found for deactivation", session_id)
+                return None
+
+            session.is_active = False
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+
+            logger.info(
+                "Session %s deactivated for user %s (%s)",
+                session_id,
+                session.user_id,
+                session.device_name,
+            )
+
+            return session
+        except Exception as e:
+            await db.rollback()
+            logger.error("Error deactivating session %s: %s", session_id, e)
+            raise
+
+    async def deactivate_all_user_sessions(
+        self, db: AsyncSession, *, user_id: str
+    ) -> int:
+        """Deactivate all active sessions for a user (logout from all devices)."""
+        try:
+            user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+
+            stmt = (
+                update(UserSession)
+                .where(and_(UserSession.user_id == user_uuid, UserSession.is_active))
+                .values(is_active=False)
+            )
+
+            result = await db.execute(stmt)
+            await db.commit()
+
+            count = result.rowcount
+
+            logger.info("Deactivated %s sessions for user %s", count, user_id)
+
+            return count
+        except Exception as e:
+            await db.rollback()
+            logger.error("Error deactivating all sessions for user %s: %s", user_id, e)
+            raise
+
+    async def update_last_used(
+        self, db: AsyncSession, *, session: UserSession
+    ) -> UserSession:
+        """Update the last_used_at timestamp for a session."""
+        try:
+            session.last_used_at = datetime.now(UTC)
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+            return session
+        except Exception as e:
+            await db.rollback()
+            logger.error("Error updating last_used for session %s: %s", session.id, e)
+            raise
+
+    async def update_refresh_token(
+        self,
+        db: AsyncSession,
+        *,
+        session: UserSession,
+        new_jti: str,
+        new_expires_at: datetime,
+    ) -> UserSession:
+        """Update session with new refresh token JTI and expiration."""
+        try:
+            session.refresh_token_jti = new_jti
+            session.expires_at = new_expires_at
+            session.last_used_at = datetime.now(UTC)
+            db.add(session)
+            await db.commit()
+            await db.refresh(session)
+            return session
+        except Exception as e:
+            await db.rollback()
+            logger.error(
+                "Error updating refresh token for session %s: %s", session.id, e
+            )
+            raise
+
+    async def cleanup_expired(self, db: AsyncSession, *, keep_days: int = 30) -> int:
+        """Clean up expired sessions using optimized bulk DELETE."""
+        try:
+            cutoff_date = datetime.now(UTC) - timedelta(days=keep_days)
+            now = datetime.now(UTC)
+
+            stmt = delete(UserSession).where(
+                and_(
+                    UserSession.is_active == False,  # noqa: E712
+                    UserSession.expires_at < now,
+                    UserSession.created_at < cutoff_date,
+                )
+            )
+
+            result = await db.execute(stmt)
+            await db.commit()
+
+            count = result.rowcount
+
+            if count > 0:
+                logger.info("Cleaned up %s expired sessions using bulk DELETE", count)
+
+            return count
+        except Exception as e:
+            await db.rollback()
+            logger.error("Error cleaning up expired sessions: %s", e)
+            raise
+
+    async def cleanup_expired_for_user(self, db: AsyncSession, *, user_id: str) -> int:
+        """Clean up expired and inactive sessions for a specific user."""
+        try:
+            try:
+                uuid_obj = uuid.UUID(user_id)
+            except (ValueError, AttributeError):
+                logger.error("Invalid UUID format: %s", user_id)
+                raise InvalidInputError(f"Invalid user ID format: {user_id}")
+
+            now = datetime.now(UTC)
+
+            stmt = delete(UserSession).where(
+                and_(
+                    UserSession.user_id == uuid_obj,
+                    UserSession.is_active == False,  # noqa: E712
+                    UserSession.expires_at < now,
+                )
+            )
+
+            result = await db.execute(stmt)
+            await db.commit()
+
+            count = result.rowcount
+
+            if count > 0:
+                logger.info(
+                    "Cleaned up %s expired sessions for user %s using bulk DELETE",
+                    count,
+                    user_id,
+                )
+
+            return count
+        except Exception as e:
+            await db.rollback()
+            logger.error(
+                "Error cleaning up expired sessions for user %s: %s", user_id, e
+            )
+            raise
+
+    async def get_user_session_count(self, db: AsyncSession, *, user_id: str) -> int:
+        """Get count of active sessions for a user."""
+        try:
+            user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
+
+            result = await db.execute(
+                select(func.count(UserSession.id)).where(
+                    and_(UserSession.user_id == user_uuid, UserSession.is_active)
+                )
+            )
+            return result.scalar_one()
+        except Exception as e:
+            logger.error("Error counting sessions for user %s: %s", user_id, e)
+            raise
+
+    async def get_all_sessions(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        active_only: bool = True,
+        with_user: bool = True,
+    ) -> tuple[list[UserSession], int]:
+        """Get all sessions across all users with pagination (admin only)."""
+        try:
+            query = select(UserSession)
+
+            if with_user:
+                query = query.options(joinedload(UserSession.user))
+
+            if active_only:
+                query = query.where(UserSession.is_active)
+
+            count_query = select(func.count(UserSession.id))
+            if active_only:
+                count_query = count_query.where(UserSession.is_active)
+
+            count_result = await db.execute(count_query)
+            total = count_result.scalar_one()
+
+            query = (
+                query.order_by(UserSession.last_used_at.desc())
+                .offset(skip)
+                .limit(limit)
+            )
+
+            result = await db.execute(query)
+            sessions = list(result.scalars().all())
+
+            return sessions, total
+
+        except Exception as e:
+            logger.exception("Error getting all sessions: %s", e)
+            raise
+
+
+# Singleton instance
+session_repo = SessionRepository(UserSession)

backend/app/repositories/user.py

@@ -0,0 +1,269 @@
+# app/repositories/user.py
+"""Repository for User model async database operations using SQLAlchemy 2.0 patterns."""
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy import or_, select, update
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.auth import get_password_hash_async
+from app.core.repository_exceptions import DuplicateEntryError, InvalidInputError
+from app.models.user import User
+from app.repositories.base import BaseRepository
+from app.schemas.users import UserCreate, UserUpdate
+
+logger = logging.getLogger(__name__)
+
+
+class UserRepository(BaseRepository[User, UserCreate, UserUpdate]):
+    """Repository for User model."""
+
+    async def get_by_email(self, db: AsyncSession, *, email: str) -> User | None:
+        """Get user by email address."""
+        try:
+            result = await db.execute(select(User).where(User.email == email))
+            return result.scalar_one_or_none()
+        except Exception as e:
+            logger.error("Error getting user by email %s: %s", email, e)
+            raise
+
+    async def create(self, db: AsyncSession, *, obj_in: UserCreate) -> User:
+        """Create a new user with async password hashing and error handling."""
+        try:
+            password_hash = await get_password_hash_async(obj_in.password)
+
+            db_obj = User(
+                email=obj_in.email,
+                password_hash=password_hash,
+                first_name=obj_in.first_name,
+                last_name=obj_in.last_name,
+                phone_number=obj_in.phone_number
+                if hasattr(obj_in, "phone_number")
+                else None,
+                is_superuser=obj_in.is_superuser
+                if hasattr(obj_in, "is_superuser")
+                else False,
+                preferences={},
+            )
+            db.add(db_obj)
+            await db.commit()
+            await db.refresh(db_obj)
+            return db_obj
+        except IntegrityError as e:
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            if "email" in error_msg.lower():
+                logger.warning("Duplicate email attempted: %s", obj_in.email)
+                raise DuplicateEntryError(
+                    f"User with email {obj_in.email} already exists"
+                )
+            logger.error("Integrity error creating user: %s", error_msg)
+            raise DuplicateEntryError(f"Database integrity error: {error_msg}")
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Unexpected error creating user: %s", e)
+            raise
+
+    async def create_oauth_user(
+        self,
+        db: AsyncSession,
+        *,
+        email: str,
+        first_name: str = "User",
+        last_name: str | None = None,
+    ) -> User:
+        """Create a new passwordless user for OAuth sign-in."""
+        try:
+            db_obj = User(
+                email=email,
+                password_hash=None,  # OAuth-only user
+                first_name=first_name,
+                last_name=last_name,
+                is_active=True,
+                is_superuser=False,
+            )
+            db.add(db_obj)
+            await db.flush()  # Get user.id without committing
+            return db_obj
+        except IntegrityError as e:
+            await db.rollback()
+            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
+            if "email" in error_msg.lower():
+                logger.warning("Duplicate email attempted: %s", email)
+                raise DuplicateEntryError(f"User with email {email} already exists")
+            logger.error("Integrity error creating OAuth user: %s", error_msg)
+            raise DuplicateEntryError(f"Database integrity error: {error_msg}")
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Unexpected error creating OAuth user: %s", e)
+            raise
+
+    async def update(
+        self, db: AsyncSession, *, db_obj: User, obj_in: UserUpdate | dict[str, Any]
+    ) -> User:
+        """Update user with async password hashing if password is updated."""
+        if isinstance(obj_in, dict):
+            update_data = obj_in
+        else:
+            update_data = obj_in.model_dump(exclude_unset=True)
+
+        if "password" in update_data:
+            update_data["password_hash"] = await get_password_hash_async(
+                update_data["password"]
+            )
+            del update_data["password"]
+
+        return await super().update(db, db_obj=db_obj, obj_in=update_data)
+
+    async def update_password(
+        self, db: AsyncSession, *, user: User, password_hash: str
+    ) -> User:
+        """Set a new password hash on a user and commit."""
+        user.password_hash = password_hash
+        await db.commit()
+        await db.refresh(user)
+        return user
+
+    async def get_multi_with_total(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        sort_by: str | None = None,
+        sort_order: str = "asc",
+        filters: dict[str, Any] | None = None,
+        search: str | None = None,
+    ) -> tuple[list[User], int]:
+        """Get multiple users with total count, filtering, sorting, and search."""
+        if skip < 0:
+            raise InvalidInputError("skip must be non-negative")
+        if limit < 0:
+            raise InvalidInputError("limit must be non-negative")
+        if limit > 1000:
+            raise InvalidInputError("Maximum limit is 1000")
+
+        try:
+            query = select(User)
+            query = query.where(User.deleted_at.is_(None))
+
+            if filters:
+                for field, value in filters.items():
+                    if hasattr(User, field) and value is not None:
+                        query = query.where(getattr(User, field) == value)
+
+            if search:
+                search_filter = or_(
+                    User.email.ilike(f"%{search}%"),
+                    User.first_name.ilike(f"%{search}%"),
+                    User.last_name.ilike(f"%{search}%"),
+                )
+                query = query.where(search_filter)
+
+            from sqlalchemy import func
+
+            count_query = select(func.count()).select_from(query.alias())
+            count_result = await db.execute(count_query)
+            total = count_result.scalar_one()
+
+            if sort_by and hasattr(User, sort_by):
+                sort_column = getattr(User, sort_by)
+                if sort_order.lower() == "desc":
+                    query = query.order_by(sort_column.desc())
+                else:
+                    query = query.order_by(sort_column.asc())
+
+            query = query.offset(skip).limit(limit)
+            result = await db.execute(query)
+            users = list(result.scalars().all())
+
+            return users, total
+
+        except Exception as e:
+            logger.error("Error retrieving paginated users: %s", e)
+            raise
+
+    async def bulk_update_status(
+        self, db: AsyncSession, *, user_ids: list[UUID], is_active: bool
+    ) -> int:
+        """Bulk update is_active status for multiple users."""
+        try:
+            if not user_ids:
+                return 0
+
+            stmt = (
+                update(User)
+                .where(User.id.in_(user_ids))
+                .where(User.deleted_at.is_(None))
+                .values(is_active=is_active, updated_at=datetime.now(UTC))
+            )
+
+            result = await db.execute(stmt)
+            await db.commit()
+
+            updated_count = result.rowcount
+            logger.info(
+                "Bulk updated %s users to is_active=%s", updated_count, is_active
+            )
+            return updated_count
+
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Error bulk updating user status: %s", e)
+            raise
+
+    async def bulk_soft_delete(
+        self,
+        db: AsyncSession,
+        *,
+        user_ids: list[UUID],
+        exclude_user_id: UUID | None = None,
+    ) -> int:
+        """Bulk soft delete multiple users."""
+        try:
+            if not user_ids:
+                return 0
+
+            filtered_ids = [uid for uid in user_ids if uid != exclude_user_id]
+
+            if not filtered_ids:
+                return 0
+
+            stmt = (
+                update(User)
+                .where(User.id.in_(filtered_ids))
+                .where(User.deleted_at.is_(None))
+                .values(
+                    deleted_at=datetime.now(UTC),
+                    is_active=False,
+                    updated_at=datetime.now(UTC),
+                )
+            )
+
+            result = await db.execute(stmt)
+            await db.commit()
+
+            deleted_count = result.rowcount
+            logger.info("Bulk soft deleted %s users", deleted_count)
+            return deleted_count
+
+        except Exception as e:
+            await db.rollback()
+            logger.exception("Error bulk deleting users: %s", e)
+            raise
+
+    def is_active(self, user: User) -> bool:
+        """Check if user is active."""
+        return bool(user.is_active)
+
+    def is_superuser(self, user: User) -> bool:
+        """Check if user is a superuser."""
+        return bool(user.is_superuser)
+
+
+# Singleton instance
+user_repo = UserRepository(User)

backend/app/schemas/common.py

@@ -0,0 +1,184 @@
+"""
+Common schemas used across the API for pagination, responses, filtering, and sorting.
+"""
+
+from enum import Enum
+from math import ceil
+from typing import TypeVar
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+
+class SortOrder(str, Enum):
+    """Sort order options."""
+
+    ASC = "asc"
+    DESC = "desc"
+
+
+class PaginationParams(BaseModel):
+    """Parameters for pagination."""
+
+    page: int = Field(default=1, ge=1, description="Page number (1-indexed)")
+    limit: int = Field(
+        default=20, ge=1, le=100, description="Number of items per page (max 100)"
+    )
+
+    @property
+    def offset(self) -> int:
+        """Calculate the offset for database queries."""
+        return (self.page - 1) * self.limit
+
+    @property
+    def skip(self) -> int:
+        """Alias for offset (compatibility with existing code)."""
+        return self.offset
+
+    model_config = {"json_schema_extra": {"example": {"page": 1, "limit": 20}}}
+
+
+class SortParams(BaseModel):
+    """Parameters for sorting."""
+
+    sort_by: str | None = Field(default=None, description="Field name to sort by")
+    sort_order: SortOrder = Field(
+        default=SortOrder.ASC, description="Sort order (asc or desc)"
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {"sort_by": "created_at", "sort_order": "desc"}
+        }
+    }
+
+
+class PaginationMeta(BaseModel):
+    """Metadata for paginated responses."""
+
+    total: int = Field(..., description="Total number of items")
+    page: int = Field(..., description="Current page number")
+    page_size: int = Field(..., description="Number of items in current page")
+    total_pages: int = Field(..., description="Total number of pages")
+    has_next: bool = Field(..., description="Whether there is a next page")
+    has_prev: bool = Field(..., description="Whether there is a previous page")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "total": 150,
+                "page": 1,
+                "page_size": 20,
+                "total_pages": 8,
+                "has_next": True,
+                "has_prev": False,
+            }
+        }
+    }
+
+
+class PaginatedResponse[T](BaseModel):
+    """Generic paginated response wrapper."""
+
+    data: list[T] = Field(..., description="List of items")
+    pagination: PaginationMeta = Field(..., description="Pagination metadata")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "data": [{"id": "123", "name": "Example Item"}],
+                "pagination": {
+                    "total": 150,
+                    "page": 1,
+                    "page_size": 20,
+                    "total_pages": 8,
+                    "has_next": True,
+                    "has_prev": False,
+                },
+            }
+        }
+    }
+
+
+class MessageResponse(BaseModel):
+    """Simple message response."""
+
+    success: bool = Field(default=True, description="Operation success status")
+    message: str = Field(..., description="Human-readable message")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {"success": True, "message": "Operation completed successfully"}
+        }
+    }
+
+
+class BulkActionRequest(BaseModel):
+    """Request schema for bulk operations on multiple items."""
+
+    ids: list[UUID] = Field(
+        ...,
+        min_length=1,
+        max_length=100,
+        description="List of item IDs to perform action on (max 100)",
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "ids": [
+                    "550e8400-e29b-41d4-a716-446655440000",
+                    "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
+                ]
+            }
+        }
+    }
+
+
+class BulkActionResponse(BaseModel):
+    """Response schema for bulk operations."""
+
+    success: bool = Field(default=True, description="Operation success status")
+    message: str = Field(..., description="Human-readable message")
+    affected_count: int = Field(
+        ..., description="Number of items affected by the operation"
+    )
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "success": True,
+                "message": "Successfully deactivated 5 users",
+                "affected_count": 5,
+            }
+        }
+    }
+
+
+def create_pagination_meta(
+    total: int, page: int, limit: int, items_count: int
+) -> PaginationMeta:
+    """
+    Helper function to create pagination metadata.
+
+    Args:
+        total: Total number of items
+        page: Current page number
+        limit: Items per page
+        items_count: Number of items in current page
+
+    Returns:
+        PaginationMeta object with calculated values
+    """
+    total_pages = ceil(total / limit) if limit > 0 else 0
+
+    return PaginationMeta(
+        total=total,
+        page=page,
+        page_size=items_count,
+        total_pages=total_pages,
+        has_next=page < total_pages,
+        has_prev=page > 1,
+    )

backend/app/schemas/errors.py

@@ -0,0 +1,88 @@
+"""
+Error schemas for standardized API error responses.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class ErrorCode(str, Enum):
+    """Standard error codes for the API."""
+
+    # Authentication errors (AUTH_xxx)
+    INVALID_CREDENTIALS = "AUTH_001"
+    TOKEN_EXPIRED = "AUTH_002"
+    TOKEN_INVALID = "AUTH_003"
+    INSUFFICIENT_PERMISSIONS = "AUTH_004"
+    USER_INACTIVE = "AUTH_005"
+    AUTHENTICATION_REQUIRED = "AUTH_006"
+    OPERATION_FORBIDDEN = "AUTH_007"  # Operation not allowed for this user/role
+
+    # User errors (USER_xxx)
+    USER_NOT_FOUND = "USER_001"
+    USER_ALREADY_EXISTS = "USER_002"
+    USER_CREATION_FAILED = "USER_003"
+    USER_UPDATE_FAILED = "USER_004"
+    USER_DELETION_FAILED = "USER_005"
+
+    # Validation errors (VAL_xxx)
+    VALIDATION_ERROR = "VAL_001"
+    INVALID_PASSWORD = "VAL_002"
+    INVALID_EMAIL = "VAL_003"
+    INVALID_PHONE_NUMBER = "VAL_004"
+    INVALID_UUID = "VAL_005"
+    INVALID_INPUT = "VAL_006"
+
+    # Database errors (DB_xxx)
+    DATABASE_ERROR = "DB_001"
+    DUPLICATE_ENTRY = "DB_002"
+    FOREIGN_KEY_VIOLATION = "DB_003"
+    RECORD_NOT_FOUND = "DB_004"
+
+    # Generic errors (SYS_xxx)
+    INTERNAL_ERROR = "SYS_001"
+    NOT_FOUND = "SYS_002"
+    METHOD_NOT_ALLOWED = "SYS_003"
+    RATE_LIMIT_EXCEEDED = "SYS_004"
+    ALREADY_EXISTS = "SYS_005"  # Generic resource already exists error
+
+
+class ErrorDetail(BaseModel):
+    """Detailed information about a single error."""
+
+    code: ErrorCode = Field(..., description="Machine-readable error code")
+    message: str = Field(..., description="Human-readable error message")
+    field: str | None = Field(None, description="Field name if error is field-specific")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "code": "VAL_002",
+                "message": "Password must be at least 8 characters long",
+                "field": "password",
+            }
+        }
+    }
+
+
+class ErrorResponse(BaseModel):
+    """Standardized error response format."""
+
+    success: bool = Field(default=False, description="Always false for error responses")
+    errors: list[ErrorDetail] = Field(..., description="List of errors that occurred")
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "success": False,
+                "errors": [
+                    {
+                        "code": "AUTH_001",
+                        "message": "Invalid email or password",
+                        "field": None,
+                    }
+                ],
+            }
+        }
+    }

backend/app/schemas/oauth.py

@@ -0,0 +1,395 @@
+"""
+Pydantic schemas for OAuth authentication.
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+# ============================================================================
+# OAuth Provider Info (for frontend to display available providers)
+# ============================================================================
+
+
+class OAuthProviderInfo(BaseModel):
+    """Information about an available OAuth provider."""
+
+    provider: str = Field(..., description="Provider identifier (google, github)")
+    name: str = Field(..., description="Human-readable provider name")
+    icon: str | None = Field(None, description="Icon identifier for frontend")
+
+
+class OAuthProvidersResponse(BaseModel):
+    """Response containing list of enabled OAuth providers."""
+
+    enabled: bool = Field(..., description="Whether OAuth is globally enabled")
+    providers: list[OAuthProviderInfo] = Field(
+        default_factory=list, description="List of enabled providers"
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "enabled": True,
+                "providers": [
+                    {"provider": "google", "name": "Google", "icon": "google"},
+                    {"provider": "github", "name": "GitHub", "icon": "github"},
+                ],
+            }
+        }
+    )
+
+
+# ============================================================================
+# OAuth Account (linked provider accounts)
+# ============================================================================
+
+
+class OAuthAccountBase(BaseModel):
+    """Base schema for OAuth accounts."""
+
+    provider: str = Field(..., max_length=50, description="OAuth provider name")
+    provider_email: str | None = Field(
+        None, max_length=255, description="Email from OAuth provider"
+    )
+
+
+class OAuthAccountCreate(OAuthAccountBase):
+    """Schema for creating an OAuth account link (internal use)."""
+
+    user_id: UUID
+    provider_user_id: str = Field(..., max_length=255)
+    access_token: str | None = None
+    refresh_token: str | None = None
+    token_expires_at: datetime | None = None
+
+
+class OAuthAccountResponse(OAuthAccountBase):
+    """Schema for OAuth account response to clients."""
+
+    id: UUID
+    created_at: datetime
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        json_schema_extra={
+            "example": {
+                "id": "123e4567-e89b-12d3-a456-426614174000",
+                "provider": "google",
+                "provider_email": "user@gmail.com",
+                "created_at": "2025-11-24T12:00:00Z",
+            }
+        },
+    )
+
+
+class OAuthAccountsListResponse(BaseModel):
+    """Response containing list of linked OAuth accounts."""
+
+    accounts: list[OAuthAccountResponse]
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "accounts": [
+                    {
+                        "id": "123e4567-e89b-12d3-a456-426614174000",
+                        "provider": "google",
+                        "provider_email": "user@gmail.com",
+                        "created_at": "2025-11-24T12:00:00Z",
+                    }
+                ]
+            }
+        }
+    )
+
+
+# ============================================================================
+# OAuth Flow (authorization, callback, etc.)
+# ============================================================================
+
+
+class OAuthAuthorizeRequest(BaseModel):
+    """Request parameters for OAuth authorization."""
+
+    provider: str = Field(..., description="OAuth provider (google, github)")
+    redirect_uri: str | None = Field(
+        None, description="Frontend callback URL after OAuth"
+    )
+    mode: str = Field(
+        default="login",
+        description="OAuth mode: login, register, or link",
+        pattern="^(login|register|link)$",
+    )
+
+
+class OAuthCallbackRequest(BaseModel):
+    """Request parameters for OAuth callback."""
+
+    code: str = Field(..., description="Authorization code from provider")
+    state: str = Field(..., description="State parameter for CSRF protection")
+
+
+class OAuthCallbackResponse(BaseModel):
+    """Response after successful OAuth authentication."""
+
+    access_token: str = Field(..., description="JWT access token")
+    refresh_token: str = Field(..., description="JWT refresh token")
+    token_type: str = Field(default="bearer")
+    expires_in: int = Field(..., description="Token expiration in seconds")
+    is_new_user: bool = Field(
+        default=False, description="Whether a new user was created"
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+                "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+                "token_type": "bearer",
+                "expires_in": 900,
+                "is_new_user": False,
+            }
+        }
+    )
+
+
+class OAuthUnlinkResponse(BaseModel):
+    """Response after unlinking an OAuth account."""
+
+    success: bool = Field(..., description="Whether the unlink was successful")
+    message: str = Field(..., description="Status message")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {"success": True, "message": "Google account unlinked"}
+        }
+    )
+
+
+# ============================================================================
+# OAuth State (CSRF protection - internal use)
+# ============================================================================
+
+
+class OAuthStateCreate(BaseModel):
+    """Schema for creating OAuth state (internal use)."""
+
+    state: str = Field(..., max_length=255)
+    code_verifier: str | None = Field(None, max_length=128)
+    nonce: str | None = Field(None, max_length=255)
+    provider: str = Field(..., max_length=50)
+    redirect_uri: str | None = Field(None, max_length=500)
+    user_id: UUID | None = None
+    expires_at: datetime
+
+
+# ============================================================================
+# OAuth Client (Provider Mode - MCP clients)
+# ============================================================================
+
+
+class OAuthClientBase(BaseModel):
+    """Base schema for OAuth clients."""
+
+    client_name: str = Field(..., max_length=255, description="Client application name")
+    client_description: str | None = Field(
+        None, max_length=1000, description="Client description"
+    )
+    redirect_uris: list[str] = Field(
+        default_factory=list, description="Allowed redirect URIs"
+    )
+    allowed_scopes: list[str] = Field(
+        default_factory=list, description="Allowed OAuth scopes"
+    )
+
+
+class OAuthClientCreate(OAuthClientBase):
+    """Schema for creating an OAuth client."""
+
+    client_type: str = Field(
+        default="public",
+        description="Client type: public or confidential",
+        pattern="^(public|confidential)$",
+    )
+
+
+class OAuthClientResponse(OAuthClientBase):
+    """Schema for OAuth client response."""
+
+    id: UUID
+    client_id: str = Field(..., description="OAuth client ID")
+    client_type: str
+    is_active: bool
+    created_at: datetime
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        json_schema_extra={
+            "example": {
+                "id": "123e4567-e89b-12d3-a456-426614174000",
+                "client_id": "abc123def456",
+                "client_name": "My MCP App",
+                "client_description": "My application that uses MCP",
+                "client_type": "public",
+                "redirect_uris": ["http://localhost:3000/callback"],
+                "allowed_scopes": ["read:users", "write:users"],
+                "is_active": True,
+                "created_at": "2025-11-24T12:00:00Z",
+            }
+        },
+    )
+
+
+class OAuthClientWithSecret(OAuthClientResponse):
+    """Schema for OAuth client response including secret (only shown once)."""
+
+    client_secret: str | None = Field(
+        None, description="Client secret (only shown once for confidential clients)"
+    )
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        json_schema_extra={
+            "example": {
+                "id": "123e4567-e89b-12d3-a456-426614174000",
+                "client_id": "abc123def456",
+                "client_secret": "secret_xyz789",
+                "client_name": "My MCP App",
+                "client_type": "confidential",
+                "redirect_uris": ["http://localhost:3000/callback"],
+                "allowed_scopes": ["read:users"],
+                "is_active": True,
+                "created_at": "2025-11-24T12:00:00Z",
+            }
+        },
+    )
+
+
+# ============================================================================
+# OAuth Provider Discovery (RFC 8414 - skeleton)
+# ============================================================================
+
+
+class OAuthServerMetadata(BaseModel):
+    """OAuth 2.0 Authorization Server Metadata (RFC 8414)."""
+
+    issuer: str = Field(..., description="Authorization server issuer URL")
+    authorization_endpoint: str = Field(..., description="Authorization endpoint URL")
+    token_endpoint: str = Field(..., description="Token endpoint URL")
+    registration_endpoint: str | None = Field(
+        None, description="Dynamic client registration endpoint"
+    )
+    revocation_endpoint: str | None = Field(
+        None, description="Token revocation endpoint"
+    )
+    introspection_endpoint: str | None = Field(
+        None, description="Token introspection endpoint (RFC 7662)"
+    )
+    scopes_supported: list[str] = Field(
+        default_factory=list, description="Supported scopes"
+    )
+    response_types_supported: list[str] = Field(
+        default_factory=lambda: ["code"], description="Supported response types"
+    )
+    grant_types_supported: list[str] = Field(
+        default_factory=lambda: ["authorization_code", "refresh_token"],
+        description="Supported grant types",
+    )
+    code_challenge_methods_supported: list[str] = Field(
+        default_factory=lambda: ["S256"], description="Supported PKCE methods"
+    )
+    token_endpoint_auth_methods_supported: list[str] = Field(
+        default_factory=lambda: ["client_secret_basic", "client_secret_post", "none"],
+        description="Supported client authentication methods",
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "issuer": "https://api.example.com",
+                "authorization_endpoint": "https://api.example.com/oauth/authorize",
+                "token_endpoint": "https://api.example.com/oauth/token",
+                "revocation_endpoint": "https://api.example.com/oauth/revoke",
+                "introspection_endpoint": "https://api.example.com/oauth/introspect",
+                "scopes_supported": ["openid", "profile", "email", "read:users"],
+                "response_types_supported": ["code"],
+                "grant_types_supported": ["authorization_code", "refresh_token"],
+                "code_challenge_methods_supported": ["S256"],
+                "token_endpoint_auth_methods_supported": [
+                    "client_secret_basic",
+                    "client_secret_post",
+                    "none",
+                ],
+            }
+        }
+    )
+
+
+# ============================================================================
+# OAuth Token Responses (RFC 6749)
+# ============================================================================
+
+
+class OAuthTokenResponse(BaseModel):
+    """OAuth 2.0 Token Response (RFC 6749 Section 5.1)."""
+
+    access_token: str = Field(..., description="The access token issued by the server")
+    token_type: str = Field(
+        default="Bearer", description="The type of token (typically 'Bearer')"
+    )
+    expires_in: int | None = Field(None, description="Token lifetime in seconds")
+    refresh_token: str | None = Field(
+        None, description="Refresh token for obtaining new access tokens"
+    )
+    scope: str | None = Field(
+        None, description="Space-separated list of granted scopes"
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+                "token_type": "Bearer",
+                "expires_in": 3600,
+                "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
+                "scope": "openid profile email",
+            }
+        }
+    )
+
+
+class OAuthTokenIntrospectionResponse(BaseModel):
+    """OAuth 2.0 Token Introspection Response (RFC 7662)."""
+
+    active: bool = Field(..., description="Whether the token is currently active")
+    scope: str | None = Field(None, description="Space-separated list of scopes")
+    client_id: str | None = Field(None, description="Client identifier for the token")
+    username: str | None = Field(
+        None, description="Human-readable identifier for the resource owner"
+    )
+    token_type: str | None = Field(
+        None, description="Type of the token (e.g., 'Bearer')"
+    )
+    exp: int | None = Field(None, description="Token expiration time (Unix timestamp)")
+    iat: int | None = Field(None, description="Token issue time (Unix timestamp)")
+    nbf: int | None = Field(None, description="Token not-before time (Unix timestamp)")
+    sub: str | None = Field(None, description="Subject of the token (user ID)")
+    aud: str | None = Field(None, description="Intended audience of the token")
+    iss: str | None = Field(None, description="Issuer of the token")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "active": True,
+                "scope": "openid profile",
+                "client_id": "client123",
+                "username": "user@example.com",
+                "token_type": "Bearer",
+                "exp": 1735689600,
+                "iat": 1735686000,
+                "sub": "user-uuid-here",
+            }
+        }
+    )

backend/app/schemas/organizations.py

@@ -0,0 +1,169 @@
+# app/schemas/organizations.py
+import re
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from app.models.user_organization import OrganizationRole
+
+
+# Organization Schemas
+class OrganizationBase(BaseModel):
+    """Base organization schema with common fields."""
+
+    name: str = Field(..., min_length=1, max_length=255)
+    slug: str | None = Field(None, min_length=1, max_length=255)
+    description: str | None = None
+    is_active: bool = True
+    settings: dict[str, Any] | None = {}
+
+    @field_validator("slug")
+    @classmethod
+    def validate_slug(cls, v: str | None) -> str | None:
+        """Validate slug format: lowercase, alphanumeric, hyphens only."""
+        if v is None:
+            return v
+        if not re.match(r"^[a-z0-9-]+$", v):
+            raise ValueError(
+                "Slug must contain only lowercase letters, numbers, and hyphens"
+            )
+        if v.startswith("-") or v.endswith("-"):
+            raise ValueError("Slug cannot start or end with a hyphen")
+        if "--" in v:
+            raise ValueError("Slug cannot contain consecutive hyphens")
+        return v
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str) -> str:
+        """Validate organization name."""
+        if not v or v.strip() == "":
+            raise ValueError("Organization name cannot be empty")
+        return v.strip()
+
+
+class OrganizationCreate(OrganizationBase):
+    """Schema for creating a new organization."""
+
+    name: str = Field(..., min_length=1, max_length=255)
+    slug: str = Field(..., min_length=1, max_length=255)  # pyright: ignore[reportIncompatibleVariableOverride]
+
+
+class OrganizationUpdate(BaseModel):
+    """Schema for updating an organization."""
+
+    name: str | None = Field(None, min_length=1, max_length=255)
+    slug: str | None = Field(None, min_length=1, max_length=255)
+    description: str | None = None
+    is_active: bool | None = None
+    settings: dict[str, Any] | None = None
+
+    @field_validator("slug")
+    @classmethod
+    def validate_slug(cls, v: str | None) -> str | None:
+        """Validate slug format."""
+        if v is None:
+            return v
+        if not re.match(r"^[a-z0-9-]+$", v):
+            raise ValueError(
+                "Slug must contain only lowercase letters, numbers, and hyphens"
+            )
+        if v.startswith("-") or v.endswith("-"):
+            raise ValueError("Slug cannot start or end with a hyphen")
+        if "--" in v:
+            raise ValueError("Slug cannot contain consecutive hyphens")
+        return v
+
+    @field_validator("name")
+    @classmethod
+    def validate_name(cls, v: str | None) -> str | None:
+        """Validate organization name."""
+        if v is not None and (not v or v.strip() == ""):
+            raise ValueError("Organization name cannot be empty")
+        return v.strip() if v else v
+
+
+class OrganizationResponse(OrganizationBase):
+    """Schema for organization API responses."""
+
+    id: UUID
+    created_at: datetime
+    updated_at: datetime | None = None
+    member_count: int | None = 0
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class OrganizationListResponse(BaseModel):
+    """Schema for paginated organization list responses."""
+
+    organizations: list[OrganizationResponse]
+    total: int
+    page: int
+    page_size: int
+    pages: int
+
+
+# User-Organization Relationship Schemas
+class UserOrganizationBase(BaseModel):
+    """Base schema for user-organization relationship."""
+
+    role: OrganizationRole = OrganizationRole.MEMBER
+    is_active: bool = True
+    custom_permissions: str | None = None
+
+
+class UserOrganizationCreate(BaseModel):
+    """Schema for adding a user to an organization."""
+
+    user_id: UUID
+    role: OrganizationRole = OrganizationRole.MEMBER
+    custom_permissions: str | None = None
+
+
+class UserOrganizationUpdate(BaseModel):
+    """Schema for updating user's role in an organization."""
+
+    role: OrganizationRole | None = None
+    is_active: bool | None = None
+    custom_permissions: str | None = None
+
+
+class UserOrganizationResponse(BaseModel):
+    """Schema for user-organization relationship responses."""
+
+    user_id: UUID
+    organization_id: UUID
+    role: OrganizationRole
+    is_active: bool
+    custom_permissions: str | None = None
+    created_at: datetime
+    updated_at: datetime | None = None
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class OrganizationMemberResponse(BaseModel):
+    """Schema for organization member information."""
+
+    user_id: UUID
+    email: str
+    first_name: str
+    last_name: str | None = None
+    role: OrganizationRole
+    is_active: bool
+    joined_at: datetime
+
+    model_config = ConfigDict(from_attributes=True)
+
+
+class OrganizationMemberListResponse(BaseModel):
+    """Schema for paginated organization member list."""
+
+    members: list[OrganizationMemberResponse]
+    total: int
+    page: int
+    page_size: int
+    pages: int

backend/app/schemas/sessions.py

@@ -0,0 +1,183 @@
+"""
+Pydantic schemas for user session management.
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SessionBase(BaseModel):
+    """Base schema for user sessions."""
+
+    device_name: str | None = Field(
+        None, max_length=255, description="Friendly device name"
+    )
+    device_id: str | None = Field(
+        None, max_length=255, description="Persistent device identifier"
+    )
+
+
+class SessionCreate(SessionBase):
+    """Schema for creating a new session (internal use)."""
+
+    user_id: UUID
+    refresh_token_jti: str = Field(..., max_length=255)
+    ip_address: str | None = Field(None, max_length=45)
+    user_agent: str | None = Field(None, max_length=500)
+    last_used_at: datetime
+    expires_at: datetime
+    location_city: str | None = Field(None, max_length=100)
+    location_country: str | None = Field(None, max_length=100)
+
+
+class SessionUpdate(BaseModel):
+    """Schema for updating a session (internal use)."""
+
+    last_used_at: datetime | None = None
+    is_active: bool | None = None
+    refresh_token_jti: str | None = None
+    expires_at: datetime | None = None
+
+
+class SessionResponse(SessionBase):
+    """
+    Schema for session responses to clients.
+
+    This is what users see when they list their active sessions.
+    """
+
+    id: UUID
+    ip_address: str | None = None
+    location_city: str | None = None
+    location_country: str | None = None
+    last_used_at: datetime
+    created_at: datetime
+    expires_at: datetime
+    is_current: bool = Field(
+        default=False, description="Whether this is the current session"
+    )
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        json_schema_extra={
+            "example": {
+                "id": "123e4567-e89b-12d3-a456-426614174000",
+                "device_name": "iPhone 14",
+                "device_id": "device-abc-123",
+                "ip_address": "192.168.1.100",
+                "location_city": "San Francisco",
+                "location_country": "United States",
+                "last_used_at": "2025-10-31T12:00:00Z",
+                "created_at": "2025-10-30T09:00:00Z",
+                "expires_at": "2025-11-06T09:00:00Z",
+                "is_current": True,
+            }
+        },
+    )
+
+
+class SessionListResponse(BaseModel):
+    """Response containing list of sessions."""
+
+    sessions: list[SessionResponse]
+    total: int = Field(..., description="Total number of active sessions")
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "sessions": [
+                    {
+                        "id": "123e4567-e89b-12d3-a456-426614174000",
+                        "device_name": "iPhone 14",
+                        "ip_address": "192.168.1.100",
+                        "last_used_at": "2025-10-31T12:00:00Z",
+                        "created_at": "2025-10-30T09:00:00Z",
+                        "expires_at": "2025-11-06T09:00:00Z",
+                        "is_current": True,
+                    }
+                ],
+                "total": 1,
+            }
+        }
+    )
+
+
+class LogoutRequest(BaseModel):
+    """Request schema for logout endpoint."""
+
+    refresh_token: str = Field(
+        ..., description="Refresh token for the session to logout from", min_length=10
+    )
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {"refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}
+        }
+    )
+
+
+class AdminSessionResponse(SessionBase):
+    """
+    Schema for session responses in admin panel.
+
+    Includes user information for admin to see who owns each session.
+    """
+
+    id: UUID
+    user_id: UUID
+    user_email: str = Field(..., description="Email of the user who owns this session")
+    user_full_name: str | None = Field(None, description="Full name of the user")
+    ip_address: str | None = None
+    location_city: str | None = None
+    location_country: str | None = None
+    last_used_at: datetime
+    created_at: datetime
+    expires_at: datetime
+    is_active: bool
+
+    model_config = ConfigDict(
+        from_attributes=True,
+        json_schema_extra={
+            "example": {
+                "id": "123e4567-e89b-12d3-a456-426614174000",
+                "user_id": "456e7890-e89b-12d3-a456-426614174001",
+                "user_email": "user@example.com",
+                "user_full_name": "John Doe",
+                "device_name": "iPhone 14",
+                "device_id": "device-abc-123",
+                "ip_address": "192.168.1.100",
+                "location_city": "San Francisco",
+                "location_country": "United States",
+                "last_used_at": "2025-10-31T12:00:00Z",
+                "created_at": "2025-10-30T09:00:00Z",
+                "expires_at": "2025-11-06T09:00:00Z",
+                "is_active": True,
+            }
+        },
+    )
+
+
+class DeviceInfo(BaseModel):
+    """Device information extracted from request."""
+
+    device_name: str | None = None
+    device_id: str | None = None
+    ip_address: str | None = None
+    user_agent: str | None = None
+    location_city: str | None = None
+    location_country: str | None = None
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "device_name": "Chrome on MacBook",
+                "device_id": "device-xyz-789",
+                "ip_address": "192.168.1.50",
+                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
+                "location_city": "San Francisco",
+                "location_country": "United States",
+            }
+        }
+    )

backend/app/schemas/users.py

@@ -1,84 +1,93 @@
 # app/schemas/users.py
-import re
 from datetime import datetime
-from typing import Optional, Dict, Any
+from typing import Any
 from uuid import UUID
 
-from pydantic import BaseModel, EmailStr, field_validator, ConfigDict
+from pydantic import BaseModel, ConfigDict, EmailStr, Field, field_validator
+
+from app.schemas.validators import validate_password_strength, validate_phone_number
 
 
 class UserBase(BaseModel):
     email: EmailStr
     first_name: str
-    last_name: Optional[str] = None
+    last_name: str | None = None
-    phone_number: Optional[str] = None
+    phone_number: str | None = None
 
-    @field_validator('phone_number')
+    @field_validator("phone_number")
     @classmethod
-    def validate_phone_number(cls, v: Optional[str]) -> Optional[str]:
+    def validate_phone(cls, v: str | None) -> str | None:
-        if v is None:
+        return validate_phone_number(v)
-            return v
-        # Simple regex for phone validation
-        if not re.match(r'^\+?[0-9\s\-\(\)]{8,20}$', v):
-            raise ValueError('Invalid phone number format')
-        return v
 
 
 class UserCreate(UserBase):
     password: str
     is_superuser: bool = False
+    is_active: bool = True
 
-    @field_validator('password')
+    @field_validator("password")
     @classmethod
     def password_strength(cls, v: str) -> str:
-        """Basic password strength validation"""
+        """Enterprise-grade password strength validation"""
-        if len(v) < 8:
+        return validate_password_strength(v)
-            raise ValueError('Password must be at least 8 characters')
-        if not any(char.isdigit() for char in v):
-            raise ValueError('Password must contain at least one digit')
-        if not any(char.isupper() for char in v):
-            raise ValueError('Password must contain at least one uppercase letter')
-        return v
 
 
 class UserUpdate(BaseModel):
-    first_name: Optional[str] = None
+    first_name: str | None = None
-    last_name: Optional[str] = None
+    last_name: str | None = None
-    phone_number: Optional[str] = None
+    phone_number: str | None = None
-    preferences: Optional[Dict[str, Any]] = None
+    password: str | None = None
-    is_active: Optional[bool] = True
+    preferences: dict[str, Any] | None = None
-    @field_validator('phone_number')
+    locale: str | None = Field(
-    def validate_phone_number(cls, v: Optional[str]) -> Optional[str]:
+        None,
+        max_length=10,
+        pattern=r"^[a-z]{2}(-[A-Z]{2})?$",
+        description="User's preferred locale (BCP 47 format: en, it, en-US, it-IT)",
+        examples=["en", "it", "en-US", "it-IT"],
+    )
+    is_active: bool | None = (
+        None  # Changed default from True to None to avoid unintended updates
+    )
+    is_superuser: bool | None = None  # Explicitly reject privilege escalation attempts
+
+    @field_validator("phone_number")
+    @classmethod
+    def validate_phone(cls, v: str | None) -> str | None:
+        return validate_phone_number(v)
+
+    @field_validator("password")
+    @classmethod
+    def password_strength(cls, v: str | None) -> str | None:
+        """Enterprise-grade password strength validation"""
         if v is None:
             return v
+        return validate_password_strength(v)
 
-        # Return early for empty strings or whitespace-only strings
+    @field_validator("locale")
-        if not v or v.strip() == "":
+    @classmethod
-            raise ValueError('Phone number cannot be empty')
+    def validate_locale(cls, v: str | None) -> str | None:
+        """Validate locale against supported locales."""
+        if v is None:
+            return v
+        # Only support English and Italian for template showcase
+        # Note: Locales stored in lowercase for case-insensitive matching
+        supported_locales = {"en", "it", "en-us", "en-gb", "it-it"}
+        # Normalize to lowercase for comparison and storage
+        v_lower = v.lower()
+        if v_lower not in supported_locales:
+            raise ValueError(
+                f"Unsupported locale '{v}'. Supported locales: {sorted(supported_locales)}"
+            )
+        # Return normalized lowercase version for consistency
+        return v_lower
 
-        # Remove all spaces and formatting characters
+    @field_validator("is_superuser")
-        cleaned = re.sub(r'[\s\-\(\)]', '', v)
+    @classmethod
-
+    def prevent_superuser_modification(cls, v: bool | None) -> bool | None:
-        # Basic pattern:
+        """Prevent users from modifying their superuser status via this schema."""
-        # Must start with + or 0
+        if v is not None:
-        # After + must have at least 8 digits
+            raise ValueError("Cannot modify superuser status through user update")
-        # After 0 must have at least 8 digits
+        return v
-        # Maximum total length of 15 digits (international standard)
-        # Only allowed characters are + at start and digits
-        pattern = r'^(?:\+[0-9]{8,14}|0[0-9]{8,14})$'
-
-        if not re.match(pattern, cleaned):
-            raise ValueError('Phone number must start with + or 0 followed by 8-14 digits')
-
-        # Additional validation to catch specific invalid cases
-        if cleaned.count('+') > 1:
-            raise ValueError('Phone number can only contain one + symbol at the start')
-
-        # Check for any non-digit characters (except the leading +)
-        if not all(c.isdigit() for c in cleaned[1:]):
-            raise ValueError('Phone number can only contain digits after the prefix')
-
-        return cleaned
 
 
 class UserInDB(UserBase):
@@ -86,7 +95,8 @@ class UserInDB(UserBase):
     is_active: bool
     is_superuser: bool
     created_at: datetime
-    updated_at: Optional[datetime] = None
+    updated_at: datetime | None = None
+    locale: str | None = None
 
     model_config = ConfigDict(from_attributes=True)
 
@@ -96,26 +106,29 @@ class UserResponse(UserBase):
     is_active: bool
     is_superuser: bool
     created_at: datetime
-    updated_at: Optional[datetime] = None
+    updated_at: datetime | None = None
+    locale: str | None = None
 
     model_config = ConfigDict(from_attributes=True)
 
 
 class Token(BaseModel):
     access_token: str
-    refresh_token: Optional[str] = None
+    refresh_token: str | None = None
     token_type: str = "bearer"
+    user: "UserResponse"  # Forward reference since UserResponse is defined above
+    expires_in: int | None = None  # Token expiration in seconds
 
 
 class TokenPayload(BaseModel):
     sub: str  # User ID
     exp: int  # Expiration time
-    iat: Optional[int] = None  # Issued at
+    iat: int | None = None  # Issued at
-    jti: Optional[str] = None  # JWT ID
+    jti: str | None = None  # JWT ID
-    is_superuser: Optional[bool] = False
+    is_superuser: bool | None = False
-    first_name: Optional[str] = None
+    first_name: str | None = None
-    email: Optional[str] = None
+    email: str | None = None
-    type: Optional[str] = None  # Token type (access/refresh)
+    type: str | None = None  # Token type (access/refresh)
 
 
 class TokenData(BaseModel):
@@ -123,21 +136,30 @@ class TokenData(BaseModel):
     is_superuser: bool = False
 
 
+class PasswordChange(BaseModel):
+    """Schema for changing password (requires current password)."""
+
+    current_password: str
+    new_password: str
+
+    @field_validator("new_password")
+    @classmethod
+    def password_strength(cls, v: str) -> str:
+        """Enterprise-grade password strength validation"""
+        return validate_password_strength(v)
+
+
 class PasswordReset(BaseModel):
+    """Schema for resetting password (via email token)."""
+
     token: str
     new_password: str
 
-    @field_validator('new_password')
+    @field_validator("new_password")
     @classmethod
     def password_strength(cls, v: str) -> str:
-        """Basic password strength validation"""
+        """Enterprise-grade password strength validation"""
-        if len(v) < 8:
+        return validate_password_strength(v)
-            raise ValueError('Password must be at least 8 characters')
-        if not any(char.isdigit() for char in v):
-            raise ValueError('Password must contain at least one digit')
-        if not any(char.isupper() for char in v):
-            raise ValueError('Password must contain at least one uppercase letter')
-        return v
 
 
 class LoginRequest(BaseModel):
@@ -147,3 +169,33 @@ class LoginRequest(BaseModel):
 
 class RefreshTokenRequest(BaseModel):
     refresh_token: str
+
+
+class PasswordResetRequest(BaseModel):
+    """Schema for requesting a password reset."""
+
+    email: EmailStr = Field(..., description="Email address of the account")
+
+    model_config = {"json_schema_extra": {"example": {"email": "user@example.com"}}}
+
+
+class PasswordResetConfirm(BaseModel):
+    """Schema for confirming a password reset with token."""
+
+    token: str = Field(..., description="Password reset token from email")
+    new_password: str = Field(..., min_length=8, description="New password")
+
+    @field_validator("new_password")
+    @classmethod
+    def password_strength(cls, v: str) -> str:
+        """Enterprise-grade password strength validation"""
+        return validate_password_strength(v)
+
+    model_config = {
+        "json_schema_extra": {
+            "example": {
+                "token": "eyJwYXlsb2FkIjp7ImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImV4cCI6MTcxMjM0NTY3OH19",
+                "new_password": "NewSecurePassword123",
+            }
+        }
+    }

backend/app/schemas/validators.py

@@ -0,0 +1,211 @@
+"""
+Shared validators for Pydantic schemas.
+
+This module provides reusable validation functions to ensure consistency
+across all schemas and avoid code duplication.
+"""
+
+import re
+
+# Common weak passwords that should be rejected
+COMMON_PASSWORDS: set[str] = {
+    "password",
+    "password1",
+    "password123",
+    "password1234",
+    "admin",
+    "admin123",
+    "admin1234",
+    "welcome",
+    "welcome1",
+    "welcome123",
+    "qwerty",
+    "qwerty123",
+    "12345678",
+    "123456789",
+    "1234567890",
+    "letmein",
+    "letmein1",
+    "letmein123",
+    "monkey123",
+    "dragon123",
+    "passw0rd",
+    "p@ssw0rd",
+    "p@ssword",
+}
+
+
+def validate_password_strength(password: str) -> str:
+    """
+    Validate password strength with enterprise-grade requirements.
+
+    Requirements:
+    - Minimum 12 characters (increased from 8 for better security)
+    - At least one lowercase letter
+    - At least one uppercase letter
+    - At least one digit
+    - At least one special character
+    - Not in common password list
+
+    Args:
+        password: The password to validate
+
+    Returns:
+        The validated password
+
+    Raises:
+        ValueError: If password doesn't meet requirements
+
+    Examples:
+        >>> validate_password_strength("MySecureP@ss123")  # Valid
+        >>> validate_password_strength("password1")  # Invalid - too weak
+    """
+    # Check if we are in demo mode
+    from app.core.config import settings
+
+    if settings.DEMO_MODE:
+        # In demo mode, allow specific weak passwords for demo accounts
+        demo_passwords = {"Demo123!", "Admin123!"}
+        if password in demo_passwords:
+            return password
+
+    # Check minimum length
+    if len(password) < 12:
+        raise ValueError("Password must be at least 12 characters long")
+
+    # Check against common passwords (case-insensitive)
+    if password.lower() in COMMON_PASSWORDS:
+        raise ValueError("Password is too common. Please choose a stronger password")
+
+    # Check for required character types
+    checks = [
+        (any(c.islower() for c in password), "at least one lowercase letter"),
+        (any(c.isupper() for c in password), "at least one uppercase letter"),
+        (any(c.isdigit() for c in password), "at least one digit"),
+        (
+            any(c in "!@#$%^&*()_+-=[]{}|;:,.<>?~`" for c in password),
+            "at least one special character (!@#$%^&*()_+-=[]{}|;:,.<>?~`)",
+        ),
+    ]
+
+    failed = [msg for check, msg in checks if not check]
+    if failed:
+        raise ValueError(f"Password must contain {', '.join(failed)}")
+
+    return password
+
+
+def validate_phone_number(phone: str | None) -> str | None:
+    """
+    Validate phone number format.
+
+    Accepts international format with + prefix or local format with 0 prefix.
+    Removes formatting characters (spaces, hyphens, parentheses).
+
+    Args:
+        phone: Phone number to validate (can be None)
+
+    Returns:
+        Cleaned phone number or None
+
+    Raises:
+        ValueError: If phone number format is invalid
+
+    Examples:
+        >>> validate_phone_number("+1 (555) 123-4567")  # Valid
+        >>> validate_phone_number("0412 345 678")  # Valid
+        >>> validate_phone_number("invalid")  # Invalid
+    """
+    if phone is None:
+        return None
+
+    # Check for empty strings
+    if not phone or phone.strip() == "":
+        raise ValueError("Phone number cannot be empty")
+
+    # Remove all spaces and formatting characters
+    cleaned = re.sub(r"[\s\-\(\)]", "", phone)
+
+    # Basic pattern:
+    # Must start with + or 0
+    # After + must have at least 8 digits
+    # After 0 must have at least 8 digits
+    # Maximum total length of 15 digits (international standard)
+    # Only allowed characters are + at start and digits
+    pattern = r"^(?:\+[0-9]{8,14}|0[0-9]{8,14})$"
+
+    if not re.match(pattern, cleaned):
+        raise ValueError("Phone number must start with + or 0 followed by 8-14 digits")
+
+    # Additional validation to catch specific invalid cases
+    # NOTE: These checks are defensive code - the regex pattern above already catches these cases
+    if cleaned.count("+") > 1:  # pragma: no cover
+        raise ValueError("Phone number can only contain one + symbol at the start")
+
+    # Check for any non-digit characters (except the leading +)
+    if not all(c.isdigit() for c in cleaned[1:]):  # pragma: no cover
+        raise ValueError("Phone number can only contain digits after the prefix")
+
+    return cleaned
+
+
+def validate_email_format(email: str) -> str:
+    """
+    Additional email validation beyond Pydantic's EmailStr.
+
+    This can be extended for custom email validation rules.
+
+    Args:
+        email: Email address to validate
+
+    Returns:
+        Validated email address
+
+    Raises:
+        ValueError: If email format is invalid
+    """
+    # Pydantic's EmailStr already does comprehensive validation
+    # This function is here for custom rules if needed
+
+    # Example: Reject disposable email domains (optional)
+    # disposable_domains = {'tempmail.com', '10minutemail.com', 'guerrillamail.com'}
+    # domain = email.split('@')[1].lower()
+    # if domain in disposable_domains:
+    #     raise ValueError('Disposable email addresses are not allowed')
+
+    return email.lower()  # Normalize to lowercase
+
+
+def validate_slug(slug: str) -> str:
+    """
+    Validate URL slug format.
+
+    Slugs must:
+    - Be 2-50 characters long
+    - Contain only lowercase letters, numbers, and hyphens
+    - Not start or end with a hyphen
+    - Not contain consecutive hyphens
+
+    Args:
+        slug: URL slug to validate
+
+    Returns:
+        Validated slug
+
+    Raises:
+        ValueError: If slug format is invalid
+    """
+    if not slug or len(slug) < 2:
+        raise ValueError("Slug must be at least 2 characters long")
+
+    if len(slug) > 50:
+        raise ValueError("Slug must be at most 50 characters long")
+
+    # Check format
+    if not re.match(r"^[a-z0-9]+(?:-[a-z0-9]+)*$", slug):
+        raise ValueError(
+            "Slug can only contain lowercase letters, numbers, and hyphens. "
+            "It cannot start or end with a hyphen, and cannot contain consecutive hyphens"
+        )
+
+    return slug

backend/app/services/__init__.py

@@ -0,0 +1,19 @@
+# app/services/__init__.py
+from . import oauth_provider_service
+from .auth_service import AuthService
+from .oauth_service import OAuthService
+from .organization_service import OrganizationService, organization_service
+from .session_service import SessionService, session_service
+from .user_service import UserService, user_service
+
+__all__ = [
+    "AuthService",
+    "OAuthService",
+    "OrganizationService",
+    "SessionService",
+    "UserService",
+    "oauth_provider_service",
+    "organization_service",
+    "session_service",
+    "user_service",
+]

backend/app/services/auth_service.py

@@ -1,36 +1,40 @@
 # app/services/auth_service.py
 import logging
-from typing import Optional
 from uuid import UUID
 
-from sqlalchemy.orm import Session
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.auth import (
-    verify_password,
+    TokenExpiredError,
-    get_password_hash,
+    TokenInvalidError,
     create_access_token,
     create_refresh_token,
-    TokenExpiredError,
+    get_password_hash_async,
-    TokenInvalidError
+    verify_password_async,
 )
+from app.core.config import settings
+from app.core.exceptions import AuthenticationError, DuplicateError
+from app.core.repository_exceptions import DuplicateEntryError
 from app.models.user import User
-from app.schemas.users import Token, UserCreate
+from app.repositories.user import user_repo
+from app.schemas.users import Token, UserCreate, UserResponse
 
 logger = logging.getLogger(__name__)
 
-
+# Pre-computed bcrypt hash used for constant-time comparison when user is not found,
-class AuthenticationError(Exception):
+# preventing timing attacks that could enumerate valid email addresses.
-    """Exception raised for authentication errors"""
+_DUMMY_HASH = "$2b$12$EixZaYVK1fsbw1ZfbX3OXePaWxn96p36zLFbnJHfxPSEFBzXKiHia"
-    pass
 
 
 class AuthService:
     """Service for handling authentication operations"""
 
     @staticmethod
-    def authenticate_user(db: Session, email: str, password: str) -> Optional[User]:
+    async def authenticate_user(
+        db: AsyncSession, email: str, password: str
+    ) -> User | None:
         """
-        Authenticate a user with email and password.
+        Authenticate a user with email and password using async password verification.
 
         Args:
             db: Database session
@@ -40,12 +44,16 @@ class AuthService:
         Returns:
             User if authenticated, None otherwise
         """
-        user = db.query(User).filter(User.email == email).first()
+        user = await user_repo.get_by_email(db, email=email)
 
         if not user:
+            # Perform a dummy verification to match timing of a real bcrypt check,
+            # preventing email enumeration via response-time differences.
+            await verify_password_async(password, _DUMMY_HASH)
             return None
 
-        if not verify_password(password, user.password_hash):
+        # Verify password asynchronously to avoid blocking event loop
+        if not await verify_password_async(password, user.password_hash):
             return None
 
         if not user.is_active:
@@ -54,7 +62,7 @@ class AuthService:
         return user
 
     @staticmethod
-    def create_user(db: Session, user_data: UserCreate) -> User:
+    async def create_user(db: AsyncSession, user_data: UserCreate) -> User:
         """
         Create a new user.
 
@@ -64,31 +72,30 @@ class AuthService:
 
         Returns:
             Created user
+
+        Raises:
+            AuthenticationError: If user already exists or creation fails
         """
-        # Check if user already exists
+        try:
-        existing_user = db.query(User).filter(User.email == user_data.email).first()
+            # Check if user already exists
-        if existing_user:
+            existing_user = await user_repo.get_by_email(db, email=user_data.email)
-            raise AuthenticationError("User with this email already exists")
+            if existing_user:
+                raise DuplicateError("User with this email already exists")
 
-        # Create new user
+            # Delegate creation (hashing + commit) to the repository
-        hashed_password = get_password_hash(user_data.password)
+            user = await user_repo.create(db, obj_in=user_data)
 
-        # Create user object from model
+            logger.info("User created successfully: %s", user.email)
-        user = User(
+            return user
-            email=user_data.email,
-            password_hash=hashed_password,
-            first_name=user_data.first_name,
-            last_name=user_data.last_name,
-            phone_number=user_data.phone_number,
-            is_active=True,
-            is_superuser=False
-        )
 
-        db.add(user)
+        except (AuthenticationError, DuplicateError):
-        db.commit()
+            # Re-raise API exceptions without rollback
-        db.refresh(user)
+            raise
-
+        except DuplicateEntryError as e:
-        return user
+            raise DuplicateError(str(e))
+        except Exception as e:
+            logger.exception("Error creating user: %s", e)
+            raise AuthenticationError(f"Failed to create user: {e!s}")
 
     @staticmethod
     def create_tokens(user: User) -> Token:
@@ -99,32 +106,33 @@ class AuthService:
             user: User to create tokens for
 
         Returns:
-            Token object with access and refresh tokens
+            Token object with access and refresh tokens and user info
         """
         # Generate claims
         claims = {
             "is_superuser": user.is_superuser,
             "email": user.email,
-            "first_name": user.first_name
+            "first_name": user.first_name,
         }
 
         # Create tokens
-        access_token = create_access_token(
+        access_token = create_access_token(subject=str(user.id), claims=claims)
-            subject=str(user.id),
-            claims=claims
-        )
 
-        refresh_token = create_refresh_token(
+        refresh_token = create_refresh_token(subject=str(user.id))
-            subject=str(user.id)
+
-        )
+        # Convert User model to UserResponse schema
+        user_response = UserResponse.model_validate(user)
 
         return Token(
             access_token=access_token,
-            refresh_token=refresh_token
+            refresh_token=refresh_token,
+            user=user_response,
+            expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES
+            * 60,  # Convert minutes to seconds
         )
 
     @staticmethod
-    def refresh_tokens(db: Session, refresh_token: str) -> Token:
+    async def refresh_tokens(db: AsyncSession, refresh_token: str) -> Token:
         """
         Generate new tokens using a refresh token.
 
@@ -150,7 +158,7 @@ class AuthService:
             user_id = token_data.user_id
 
             # Get user from database
-            user = db.query(User).filter(User.id == user_id).first()
+            user = await user_repo.get(db, id=str(user_id))
             if not user or not user.is_active:
                 raise TokenInvalidError("Invalid user or inactive account")
 
@@ -158,11 +166,13 @@ class AuthService:
             return AuthService.create_tokens(user)
 
         except (TokenExpiredError, TokenInvalidError) as e:
-            logger.warning(f"Token refresh failed: {str(e)}")
+            logger.warning("Token refresh failed: %s", e)
             raise
 
     @staticmethod
-    def change_password(db: Session, user_id: UUID, current_password: str, new_password: str) -> bool:
+    async def change_password(
+        db: AsyncSession, user_id: UUID, current_password: str, new_password: str
+    ) -> bool:
         """
         Change a user's password.
 
@@ -176,18 +186,58 @@ class AuthService:
             True if password was changed successfully
 
         Raises:
-            AuthenticationError: If current password is incorrect
+            AuthenticationError: If current password is incorrect or update fails
         """
-        user = db.query(User).filter(User.id == user_id).first()
+        try:
+            user = await user_repo.get(db, id=str(user_id))
+            if not user:
+                raise AuthenticationError("User not found")
+
+            # Verify current password asynchronously
+            if not await verify_password_async(current_password, user.password_hash):
+                raise AuthenticationError("Current password is incorrect")
+
+            # Hash new password asynchronously to avoid blocking event loop
+            new_hash = await get_password_hash_async(new_password)
+            await user_repo.update_password(db, user=user, password_hash=new_hash)
+
+            logger.info("Password changed successfully for user %s", user_id)
+            return True
+
+        except AuthenticationError:
+            # Re-raise authentication errors without rollback
+            raise
+        except Exception as e:
+            # Rollback on any database errors
+            await db.rollback()
+            logger.exception("Error changing password for user %s: %s", user_id, e)
+            raise AuthenticationError(f"Failed to change password: {e!s}")
+
+    @staticmethod
+    async def reset_password(
+        db: AsyncSession, *, email: str, new_password: str
+    ) -> User:
+        """
+        Reset a user's password without requiring the current password.
+
+        Args:
+            db: Database session
+            email: User email address
+            new_password: New password to set
+
+        Returns:
+            Updated user
+
+        Raises:
+            AuthenticationError: If user not found or inactive
+        """
+        user = await user_repo.get_by_email(db, email=email)
         if not user:
             raise AuthenticationError("User not found")
+        if not user.is_active:
+            raise AuthenticationError("User account is inactive")
 
-        # Verify current password
+        new_hash = await get_password_hash_async(new_password)
-        if not verify_password(current_password, user.password_hash):
+        user = await user_repo.update_password(db, user=user, password_hash=new_hash)
-            raise AuthenticationError("Current password is incorrect")
+        logger.info("Password reset successfully for %s", email)
-
+        return user
-        # Update password
-        user.password_hash = get_password_hash(new_password)
-        db.commit()
-
-        return True

backend/app/services/email_service.py

@@ -0,0 +1,295 @@
+# app/services/email_service.py
+"""
+Email service with placeholder implementation.
+
+This service provides email sending functionality with a simple console/log-based
+placeholder that can be easily replaced with a real email provider (SendGrid, SES, etc.)
+"""
+
+import logging
+from abc import ABC, abstractmethod
+
+from app.core.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+class EmailBackend(ABC):
+    """Abstract base class for email backends."""
+
+    @abstractmethod
+    async def send_email(
+        self,
+        to: list[str],
+        subject: str,
+        html_content: str,
+        text_content: str | None = None,
+    ) -> bool:
+        """Send an email."""
+
+
+class ConsoleEmailBackend(EmailBackend):
+    """
+    Console/log-based email backend for development and testing.
+
+    This backend logs email content instead of actually sending emails.
+    Replace this with a real backend (SMTP, SendGrid, SES) for production.
+    """
+
+    async def send_email(
+        self,
+        to: list[str],
+        subject: str,
+        html_content: str,
+        text_content: str | None = None,
+    ) -> bool:
+        """
+        Log email content to console/logs.
+
+        Args:
+            to: List of recipient email addresses
+            subject: Email subject
+            html_content: HTML version of the email
+            text_content: Plain text version of the email
+
+        Returns:
+            True if "sent" successfully
+        """
+        logger.info("=" * 80)
+        logger.info("EMAIL SENT (Console Backend)")
+        logger.info("=" * 80)
+        logger.info("To: %s", ", ".join(to))
+        logger.info("Subject: %s", subject)
+        logger.info("-" * 80)
+        if text_content:
+            logger.info("Plain Text Content:")
+            logger.info(text_content)
+            logger.info("-" * 80)
+        logger.info("HTML Content:")
+        logger.info(html_content)
+        logger.info("=" * 80)
+        return True
+
+
+class SMTPEmailBackend(EmailBackend):
+    """
+    SMTP email backend for production use.
+
+    TODO: Implement SMTP sending with proper error handling.
+    This is a placeholder for future implementation.
+    """
+
+    def __init__(self, host: str, port: int, username: str, password: str):
+        self.host = host
+        self.port = port
+        self.username = username
+        self.password = password
+
+    async def send_email(
+        self,
+        to: list[str],
+        subject: str,
+        html_content: str,
+        text_content: str | None = None,
+    ) -> bool:
+        """Send email via SMTP."""
+        # TODO: Implement SMTP sending
+        logger.warning("SMTP backend not yet implemented, falling back to console")
+        console_backend = ConsoleEmailBackend()
+        return await console_backend.send_email(to, subject, html_content, text_content)
+
+
+class EmailService:
+    """
+    High-level email service that uses different backends.
+
+    This service provides a clean interface for sending various types of emails
+    and can be configured to use different backends (console, SMTP, SendGrid, etc.)
+    """
+
+    def __init__(self, backend: EmailBackend | None = None):
+        """
+        Initialize email service with a backend.
+
+        Args:
+            backend: Email backend to use. Defaults to ConsoleEmailBackend.
+        """
+        self.backend = backend or ConsoleEmailBackend()
+
+    async def send_password_reset_email(
+        self, to_email: str, reset_token: str, user_name: str | None = None
+    ) -> bool:
+        """
+        Send password reset email.
+
+        Args:
+            to_email: Recipient email address
+            reset_token: Password reset token
+            user_name: User's name for personalization
+
+        Returns:
+            True if email sent successfully
+        """
+        # Generate reset URL
+        reset_url = f"{settings.FRONTEND_URL}/reset-password?token={reset_token}"
+
+        # Prepare email content
+        subject = "Password Reset Request"
+
+        # Plain text version
+        text_content = f"""
+Hello{" " + user_name if user_name else ""},
+
+You requested a password reset for your account. Click the link below to reset your password:
+
+{reset_url}
+
+This link will expire in 1 hour.
+
+If you didn't request this, please ignore this email.
+
+Best regards,
+The {settings.PROJECT_NAME} Team
+"""
+
+        # HTML version
+        html_content = f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        body {{ font-family: Arial, sans-serif; line-height: 1.6; color: #333; }}
+        .container {{ max-width: 600px; margin: 0 auto; padding: 20px; }}
+        .header {{ background-color: #4CAF50; color: white; padding: 20px; text-align: center; }}
+        .content {{ padding: 20px; background-color: #f9f9f9; }}
+        .button {{ display: inline-block; padding: 12px 24px; background-color: #4CAF50;
+                   color: white; text-decoration: none; border-radius: 4px; margin: 20px 0; }}
+        .footer {{ padding: 20px; text-align: center; color: #777; font-size: 12px; }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>Password Reset</h1>
+        </div>
+        <div class="content">
+            <p>Hello{" " + user_name if user_name else ""},</p>
+            <p>You requested a password reset for your account. Click the button below to reset your password:</p>
+            <p style="text-align: center;">
+                <a href="{reset_url}" class="button">Reset Password</a>
+            </p>
+            <p>Or copy and paste this link into your browser:</p>
+            <p style="word-break: break-all; color: #4CAF50;">{reset_url}</p>
+            <p><strong>This link will expire in 1 hour.</strong></p>
+            <p>If you didn't request this, please ignore this email.</p>
+        </div>
+        <div class="footer">
+            <p>Best regards,<br>The {settings.PROJECT_NAME} Team</p>
+        </div>
+    </div>
+</body>
+</html>
+"""
+
+        try:
+            return await self.backend.send_email(
+                to=[to_email],
+                subject=subject,
+                html_content=html_content,
+                text_content=text_content,
+            )
+        except Exception as e:
+            logger.error("Failed to send password reset email to %s: %s", to_email, e)
+            return False
+
+    async def send_email_verification(
+        self, to_email: str, verification_token: str, user_name: str | None = None
+    ) -> bool:
+        """
+        Send email verification email.
+
+        Args:
+            to_email: Recipient email address
+            verification_token: Email verification token
+            user_name: User's name for personalization
+
+        Returns:
+            True if email sent successfully
+        """
+        # Generate verification URL
+        verification_url = (
+            f"{settings.FRONTEND_URL}/verify-email?token={verification_token}"
+        )
+
+        # Prepare email content
+        subject = "Verify Your Email Address"
+
+        # Plain text version
+        text_content = f"""
+Hello{" " + user_name if user_name else ""},
+
+Thank you for signing up! Please verify your email address by clicking the link below:
+
+{verification_url}
+
+This link will expire in 24 hours.
+
+If you didn't create an account, please ignore this email.
+
+Best regards,
+The {settings.PROJECT_NAME} Team
+"""
+
+        # HTML version
+        html_content = f"""
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        body {{ font-family: Arial, sans-serif; line-height: 1.6; color: #333; }}
+        .container {{ max-width: 600px; margin: 0 auto; padding: 20px; }}
+        .header {{ background-color: #2196F3; color: white; padding: 20px; text-align: center; }}
+        .content {{ padding: 20px; background-color: #f9f9f9; }}
+        .button {{ display: inline-block; padding: 12px 24px; background-color: #2196F3;
+                   color: white; text-decoration: none; border-radius: 4px; margin: 20px 0; }}
+        .footer {{ padding: 20px; text-align: center; color: #777; font-size: 12px; }}
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div class="header">
+            <h1>Verify Your Email</h1>
+        </div>
+        <div class="content">
+            <p>Hello{" " + user_name if user_name else ""},</p>
+            <p>Thank you for signing up! Please verify your email address by clicking the button below:</p>
+            <p style="text-align: center;">
+                <a href="{verification_url}" class="button">Verify Email</a>
+            </p>
+            <p>Or copy and paste this link into your browser:</p>
+            <p style="word-break: break-all; color: #2196F3;">{verification_url}</p>
+            <p><strong>This link will expire in 24 hours.</strong></p>
+            <p>If you didn't create an account, please ignore this email.</p>
+        </div>
+        <div class="footer">
+            <p>Best regards,<br>The {settings.PROJECT_NAME} Team</p>
+        </div>
+    </div>
+</body>
+</html>
+"""
+
+        try:
+            return await self.backend.send_email(
+                to=[to_email],
+                subject=subject,
+                html_content=html_content,
+                text_content=text_content,
+            )
+        except Exception as e:
+            logger.error("Failed to send verification email to %s: %s", to_email, e)
+            return False
+
+
+# Global email service instance
+email_service = EmailService()

backend/app/services/oauth_provider_service.py

@@ -0,0 +1,970 @@
+"""
+OAuth Provider Service for MCP integration.
+
+Implements OAuth 2.0 Authorization Server functionality:
+- Authorization code flow with PKCE
+- Token issuance (JWT access tokens, opaque refresh tokens)
+- Token refresh
+- Token revocation
+- Consent management
+
+Security features:
+- PKCE required for public clients (S256)
+- Short-lived authorization codes (10 minutes)
+- JWT access tokens (self-contained, no DB lookup)
+- Secure refresh token storage (hashed)
+- Token rotation on refresh
+- Comprehensive validation
+"""
+
+import base64
+import hashlib
+import logging
+import secrets
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from uuid import UUID
+
+import jwt
+from jwt.exceptions import ExpiredSignatureError, InvalidTokenError
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.config import settings
+from app.models.oauth_client import OAuthClient
+from app.models.user import User
+from app.repositories.oauth_authorization_code import oauth_authorization_code_repo
+from app.repositories.oauth_client import oauth_client_repo
+from app.repositories.oauth_consent import oauth_consent_repo
+from app.repositories.oauth_provider_token import oauth_provider_token_repo
+from app.repositories.user import user_repo
+from app.schemas.oauth import OAuthClientCreate
+
+logger = logging.getLogger(__name__)
+
+# Constants
+AUTHORIZATION_CODE_EXPIRY_MINUTES = 10
+ACCESS_TOKEN_EXPIRY_MINUTES = 60  # 1 hour for MCP clients
+REFRESH_TOKEN_EXPIRY_DAYS = 30
+
+
+class OAuthProviderError(Exception):
+    """Base exception for OAuth provider errors."""
+
+    def __init__(
+        self,
+        error: str,
+        error_description: str | None = None,
+        error_uri: str | None = None,
+    ):
+        self.error = error
+        self.error_description = error_description
+        self.error_uri = error_uri
+        super().__init__(error_description or error)
+
+
+class InvalidClientError(OAuthProviderError):
+    """Client authentication failed."""
+
+    def __init__(self, description: str = "Invalid client credentials"):
+        super().__init__("invalid_client", description)
+
+
+class InvalidGrantError(OAuthProviderError):
+    """Invalid authorization grant."""
+
+    def __init__(self, description: str = "Invalid grant"):
+        super().__init__("invalid_grant", description)
+
+
+class InvalidRequestError(OAuthProviderError):
+    """Invalid request parameters."""
+
+    def __init__(self, description: str = "Invalid request"):
+        super().__init__("invalid_request", description)
+
+
+class InvalidScopeError(OAuthProviderError):
+    """Invalid scope requested."""
+
+    def __init__(self, description: str = "Invalid scope"):
+        super().__init__("invalid_scope", description)
+
+
+class UnauthorizedClientError(OAuthProviderError):
+    """Client not authorized for this grant type."""
+
+    def __init__(self, description: str = "Unauthorized client"):
+        super().__init__("unauthorized_client", description)
+
+
+class AccessDeniedError(OAuthProviderError):
+    """User denied authorization."""
+
+    def __init__(self, description: str = "Access denied"):
+        super().__init__("access_denied", description)
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def generate_code() -> str:
+    """Generate a cryptographically secure authorization code."""
+    return secrets.token_urlsafe(64)
+
+
+def generate_token() -> str:
+    """Generate a cryptographically secure token."""
+    return secrets.token_urlsafe(48)
+
+
+def generate_jti() -> str:
+    """Generate a unique JWT ID."""
+    return secrets.token_urlsafe(32)
+
+
+def hash_token(token: str) -> str:
+    """Hash a token using SHA-256."""
+    return hashlib.sha256(token.encode()).hexdigest()
+
+
+def verify_pkce(code_verifier: str, code_challenge: str, method: str) -> bool:
+    """
+    Verify PKCE code_verifier against stored code_challenge.
+
+    SECURITY: Only S256 method is supported. The 'plain' method provides
+    no security benefit and is explicitly rejected per RFC 7636 Section 4.3.
+    """
+    if method != "S256":
+        # SECURITY: Reject any method other than S256
+        # 'plain' method provides no security against code interception attacks
+        logger.warning("PKCE verification rejected for unsupported method: %s", method)
+        return False
+
+    # SHA-256 hash, then base64url encode (RFC 7636 Section 4.2)
+    digest = hashlib.sha256(code_verifier.encode()).digest()
+    computed = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    return secrets.compare_digest(computed, code_challenge)
+
+
+def parse_scope(scope: str) -> list[str]:
+    """Parse space-separated scope string into list."""
+    return [s.strip() for s in scope.split() if s.strip()]
+
+
+def join_scope(scopes: list[str]) -> str:
+    """Join scope list into space-separated string."""
+    return " ".join(sorted(set(scopes)))
+
+
+# ============================================================================
+# Client Validation
+# ============================================================================
+
+
+async def get_client(db: AsyncSession, client_id: str) -> OAuthClient | None:
+    """Get OAuth client by client_id."""
+    return await oauth_client_repo.get_by_client_id(db, client_id=client_id)
+
+
+async def validate_client(
+    db: AsyncSession,
+    client_id: str,
+    client_secret: str | None = None,
+    require_secret: bool = False,
+) -> OAuthClient:
+    """
+    Validate OAuth client credentials.
+
+    Args:
+        db: Database session
+        client_id: Client identifier
+        client_secret: Client secret (required for confidential clients)
+        require_secret: Whether to require secret validation
+
+    Returns:
+        Validated OAuthClient
+
+    Raises:
+        InvalidClientError: If client validation fails
+    """
+    client = await get_client(db, client_id)
+    if not client:
+        raise InvalidClientError("Unknown client_id")
+
+    # Confidential clients must provide valid secret
+    if client.client_type == "confidential" or require_secret:
+        if not client_secret:
+            raise InvalidClientError("Client secret required")
+        if not client.client_secret_hash:
+            raise InvalidClientError("Client not configured with secret")
+
+        # SECURITY: Verify secret using bcrypt
+        from app.core.auth import verify_password
+
+        stored_hash = str(client.client_secret_hash)
+
+        if not stored_hash.startswith("$2"):
+            raise InvalidClientError(
+                "Client secret uses deprecated hash format. "
+                "Please regenerate your client credentials."
+            )
+
+        if not verify_password(client_secret, stored_hash):
+            raise InvalidClientError("Invalid client secret")
+
+    return client
+
+
+def validate_redirect_uri(client: OAuthClient, redirect_uri: str) -> None:
+    """
+    Validate redirect_uri against client's registered URIs.
+
+    Raises:
+        InvalidRequestError: If redirect_uri is not registered
+    """
+    if not client.redirect_uris:
+        raise InvalidRequestError("Client has no registered redirect URIs")
+
+    if redirect_uri not in client.redirect_uris:
+        raise InvalidRequestError("Invalid redirect_uri")
+
+
+def validate_scopes(client: OAuthClient, requested_scopes: list[str]) -> list[str]:
+    """
+    Validate requested scopes against client's allowed scopes.
+
+    Returns:
+        List of valid scopes (intersection of requested and allowed)
+
+    Raises:
+        InvalidScopeError: If no valid scopes
+    """
+    allowed = set(client.allowed_scopes or [])
+    requested = set(requested_scopes)
+
+    # If no scopes requested, use all allowed scopes
+    if not requested:
+        return list(allowed)
+
+    valid = requested & allowed
+    if not valid:
+        raise InvalidScopeError(
+            "None of the requested scopes are allowed for this client"
+        )
+
+    # Warn if some scopes were filtered out
+    invalid = requested - allowed
+    if invalid:
+        logger.warning(
+            "Client %s requested invalid scopes: %s", client.client_id, invalid
+        )
+
+    return list(valid)
+
+
+# ============================================================================
+# Authorization Code Flow
+# ============================================================================
+
+
+async def create_authorization_code(
+    db: AsyncSession,
+    client: OAuthClient,
+    user: User,
+    redirect_uri: str,
+    scope: str,
+    code_challenge: str | None = None,
+    code_challenge_method: str | None = None,
+    state: str | None = None,
+    nonce: str | None = None,
+) -> str:
+    """
+    Create an authorization code for the authorization code flow.
+
+    Args:
+        db: Database session
+        client: Validated OAuth client
+        user: Authenticated user
+        redirect_uri: Validated redirect URI
+        scope: Granted scopes (space-separated)
+        code_challenge: PKCE code challenge
+        code_challenge_method: PKCE method (S256)
+        state: CSRF state parameter
+        nonce: OpenID Connect nonce
+
+    Returns:
+        Authorization code string
+    """
+    # Public clients MUST use PKCE
+    if client.client_type == "public":
+        if not code_challenge or code_challenge_method != "S256":
+            raise InvalidRequestError("PKCE with S256 is required for public clients")
+
+    code = generate_code()
+    expires_at = datetime.now(UTC) + timedelta(
+        minutes=AUTHORIZATION_CODE_EXPIRY_MINUTES
+    )
+
+    await oauth_authorization_code_repo.create_code(
+        db,
+        code=code,
+        client_id=client.client_id,
+        user_id=user.id,
+        redirect_uri=redirect_uri,
+        scope=scope,
+        expires_at=expires_at,
+        code_challenge=code_challenge,
+        code_challenge_method=code_challenge_method,
+        state=state,
+        nonce=nonce,
+    )
+
+    logger.info(
+        "Created authorization code for user %s and client %s",
+        user.id,
+        client.client_id,
+    )
+    return code
+
+
+async def exchange_authorization_code(
+    db: AsyncSession,
+    code: str,
+    client_id: str,
+    redirect_uri: str,
+    code_verifier: str | None = None,
+    client_secret: str | None = None,
+    device_info: str | None = None,
+    ip_address: str | None = None,
+) -> dict[str, Any]:
+    """
+    Exchange authorization code for tokens.
+
+    Args:
+        db: Database session
+        code: Authorization code
+        client_id: Client identifier
+        redirect_uri: Must match the original redirect_uri
+        code_verifier: PKCE code verifier
+        client_secret: Client secret (for confidential clients)
+        device_info: Optional device information
+        ip_address: Optional IP address
+
+    Returns:
+        Token response dict with access_token, refresh_token, etc.
+
+    Raises:
+        InvalidGrantError: If code is invalid, expired, or already used
+        InvalidClientError: If client validation fails
+    """
+    # Atomically mark code as used and fetch it (prevents race condition)
+    # RFC 6749 Section 4.1.2: Authorization codes MUST be single-use
+    updated_id = await oauth_authorization_code_repo.consume_code_atomically(
+        db, code=code
+    )
+
+    if not updated_id:
+        # Either code doesn't exist or was already used
+        # Check if it exists to provide appropriate error
+        existing_code = await oauth_authorization_code_repo.get_by_code(db, code=code)
+
+        if existing_code and existing_code.used:
+            # Code reuse is a security incident - revoke all tokens for this grant
+            logger.warning(
+                "Authorization code reuse detected for client %s",
+                existing_code.client_id,
+            )
+            await revoke_tokens_for_user_client(
+                db, UUID(str(existing_code.user_id)), str(existing_code.client_id)
+            )
+            raise InvalidGrantError("Authorization code has already been used")
+        else:
+            raise InvalidGrantError("Invalid authorization code")
+
+    # Now fetch the full auth code record
+    auth_code = await oauth_authorization_code_repo.get_by_id(db, code_id=updated_id)
+    if auth_code is None:
+        raise InvalidGrantError("Authorization code not found after consumption")
+
+    if auth_code.is_expired:
+        raise InvalidGrantError("Authorization code has expired")
+
+    if auth_code.client_id != client_id:
+        raise InvalidGrantError("Authorization code was not issued to this client")
+
+    if auth_code.redirect_uri != redirect_uri:
+        raise InvalidGrantError("redirect_uri mismatch")
+
+    # Validate client - ALWAYS require secret for confidential clients
+    client = await get_client(db, client_id)
+    if not client:
+        raise InvalidClientError("Unknown client_id")
+
+    # Confidential clients MUST authenticate (RFC 6749 Section 3.2.1)
+    if client.client_type == "confidential":
+        if not client_secret:
+            raise InvalidClientError("Client secret required for confidential clients")
+        client = await validate_client(
+            db, client_id, client_secret, require_secret=True
+        )
+    elif client_secret:
+        # Public client provided secret - validate it if given
+        client = await validate_client(
+            db, client_id, client_secret, require_secret=True
+        )
+
+    # Verify PKCE
+    if auth_code.code_challenge:
+        if not code_verifier:
+            raise InvalidGrantError("code_verifier required")
+        if not verify_pkce(
+            code_verifier,
+            str(auth_code.code_challenge),
+            str(auth_code.code_challenge_method or "S256"),
+        ):
+            raise InvalidGrantError("Invalid code_verifier")
+    elif client.client_type == "public":
+        # Public clients without PKCE - this shouldn't happen if we validated on authorize
+        raise InvalidGrantError("PKCE required for public clients")
+
+    # Get user
+    user = await user_repo.get(db, id=str(auth_code.user_id))
+    if not user or not user.is_active:
+        raise InvalidGrantError("User not found or inactive")
+
+    # Generate tokens
+    return await create_tokens(
+        db=db,
+        client=client,
+        user=user,
+        scope=str(auth_code.scope),
+        nonce=str(auth_code.nonce) if auth_code.nonce else None,
+        device_info=device_info,
+        ip_address=ip_address,
+    )
+
+
+# ============================================================================
+# Token Generation
+# ============================================================================
+
+
+async def create_tokens(
+    db: AsyncSession,
+    client: OAuthClient,
+    user: User,
+    scope: str,
+    nonce: str | None = None,
+    device_info: str | None = None,
+    ip_address: str | None = None,
+) -> dict[str, Any]:
+    """
+    Create access and refresh tokens.
+
+    Args:
+        db: Database session
+        client: OAuth client
+        user: User
+        scope: Granted scopes
+        nonce: OpenID Connect nonce (included in ID token)
+        device_info: Optional device information
+        ip_address: Optional IP address
+
+    Returns:
+        Token response dict
+    """
+    now = datetime.now(UTC)
+    jti = generate_jti()
+
+    # Access token expiry
+    access_token_lifetime = int(client.access_token_lifetime or "3600")
+    access_expires = now + timedelta(seconds=access_token_lifetime)
+
+    # Refresh token expiry
+    refresh_token_lifetime = int(
+        client.refresh_token_lifetime or str(REFRESH_TOKEN_EXPIRY_DAYS * 86400)
+    )
+    refresh_expires = now + timedelta(seconds=refresh_token_lifetime)
+
+    # Create JWT access token
+    # SECURITY: Include all standard JWT claims per RFC 7519
+    access_token_payload = {
+        "iss": settings.OAUTH_ISSUER,
+        "sub": str(user.id),
+        "aud": client.client_id,
+        "exp": int(access_expires.timestamp()),
+        "iat": int(now.timestamp()),
+        "nbf": int(now.timestamp()),  # Not Before - token is valid immediately
+        "jti": jti,
+        "scope": scope,
+        "client_id": client.client_id,
+        # User info (basic claims)
+        "email": user.email,
+        "name": f"{user.first_name or ''} {user.last_name or ''}".strip() or user.email,
+    }
+
+    # Add nonce for OpenID Connect
+    if nonce:
+        access_token_payload["nonce"] = nonce
+
+    access_token = jwt.encode(
+        access_token_payload,
+        settings.SECRET_KEY,
+        algorithm=settings.ALGORITHM,
+    )
+
+    # Create opaque refresh token
+    refresh_token = generate_token()
+    refresh_token_hash = hash_token(refresh_token)
+
+    # Store refresh token in database
+    await oauth_provider_token_repo.create_token(
+        db,
+        token_hash=refresh_token_hash,
+        jti=jti,
+        client_id=client.client_id,
+        user_id=user.id,
+        scope=scope,
+        expires_at=refresh_expires,
+        device_info=device_info,
+        ip_address=ip_address,
+    )
+
+    logger.info("Issued tokens for user %s to client %s", user.id, client.client_id)
+
+    return {
+        "access_token": access_token,
+        "token_type": "Bearer",
+        "expires_in": access_token_lifetime,
+        "refresh_token": refresh_token,
+        "scope": scope,
+    }
+
+
+async def refresh_tokens(
+    db: AsyncSession,
+    refresh_token: str,
+    client_id: str,
+    client_secret: str | None = None,
+    scope: str | None = None,
+    device_info: str | None = None,
+    ip_address: str | None = None,
+) -> dict[str, Any]:
+    """
+    Refresh access token using refresh token.
+
+    Implements token rotation - old refresh token is invalidated,
+    new refresh token is issued.
+
+    Args:
+        db: Database session
+        refresh_token: Refresh token
+        client_id: Client identifier
+        client_secret: Client secret (for confidential clients)
+        scope: Optional reduced scope
+        device_info: Optional device information
+        ip_address: Optional IP address
+
+    Returns:
+        New token response dict
+
+    Raises:
+        InvalidGrantError: If refresh token is invalid
+    """
+    # Find refresh token
+    token_hash = hash_token(refresh_token)
+    token_record = await oauth_provider_token_repo.get_by_token_hash(
+        db, token_hash=token_hash
+    )
+
+    if not token_record:
+        raise InvalidGrantError("Invalid refresh token")
+
+    if token_record.revoked:
+        # Token reuse after revocation - security incident
+        logger.warning(
+            "Revoked refresh token reuse detected for client %s", token_record.client_id
+        )
+        raise InvalidGrantError("Refresh token has been revoked")
+
+    if token_record.is_expired:
+        raise InvalidGrantError("Refresh token has expired")
+
+    if token_record.client_id != client_id:
+        raise InvalidGrantError("Refresh token was not issued to this client")
+
+    # Validate client
+    client = await validate_client(
+        db,
+        client_id,
+        client_secret,
+        require_secret=(client_secret is not None),
+    )
+
+    # Get user
+    user = await user_repo.get(db, id=str(token_record.user_id))
+    if not user or not user.is_active:
+        raise InvalidGrantError("User not found or inactive")
+
+    # Validate scope (can only reduce, not expand)
+    token_scope = str(token_record.scope) if token_record.scope else ""
+    original_scopes = set(parse_scope(token_scope))
+    if scope:
+        requested_scopes = set(parse_scope(scope))
+        if not requested_scopes.issubset(original_scopes):
+            raise InvalidScopeError("Cannot expand scope on refresh")
+        final_scope = join_scope(list(requested_scopes))
+    else:
+        final_scope = token_scope
+
+    # Revoke old refresh token (token rotation)
+    await oauth_provider_token_repo.revoke(db, token=token_record)
+
+    # Issue new tokens
+    device = str(token_record.device_info) if token_record.device_info else None
+    ip_addr = str(token_record.ip_address) if token_record.ip_address else None
+    return await create_tokens(
+        db=db,
+        client=client,
+        user=user,
+        scope=final_scope,
+        device_info=device_info or device,
+        ip_address=ip_address or ip_addr,
+    )
+
+
+# ============================================================================
+# Token Revocation
+# ============================================================================
+
+
+async def revoke_token(
+    db: AsyncSession,
+    token: str,
+    token_type_hint: str | None = None,
+    client_id: str | None = None,
+    client_secret: str | None = None,
+) -> bool:
+    """
+    Revoke a token (access or refresh).
+
+    For refresh tokens: marks as revoked in database
+    For access tokens: we can't truly revoke JWTs, but we can revoke
+    the associated refresh token to prevent further refreshes
+
+    Args:
+        db: Database session
+        token: Token to revoke
+        token_type_hint: "access_token" or "refresh_token"
+        client_id: Client identifier (for validation)
+        client_secret: Client secret (for confidential clients)
+
+    Returns:
+        True if token was revoked, False if not found
+    """
+    # Try as refresh token first (more likely)
+    if token_type_hint != "access_token":
+        token_hash = hash_token(token)
+        refresh_record = await oauth_provider_token_repo.get_by_token_hash(
+            db, token_hash=token_hash
+        )
+
+        if refresh_record:
+            # Validate client if provided
+            if client_id and refresh_record.client_id != client_id:
+                raise InvalidClientError("Token was not issued to this client")
+
+            await oauth_provider_token_repo.revoke(db, token=refresh_record)
+            logger.info("Revoked refresh token %s...", refresh_record.jti[:8])
+            return True
+
+    # Try as access token (JWT)
+    if token_type_hint != "refresh_token":
+        try:
+            payload = jwt.decode(
+                token,
+                settings.SECRET_KEY,
+                algorithms=[settings.ALGORITHM],
+                options={
+                    "verify_exp": False,
+                    "verify_aud": False,
+                },  # Allow expired tokens
+            )
+            jti = payload.get("jti")
+            if jti:
+                # Find and revoke the associated refresh token
+                refresh_record = await oauth_provider_token_repo.get_by_jti(db, jti=jti)
+                if refresh_record:
+                    if client_id and refresh_record.client_id != client_id:
+                        raise InvalidClientError("Token was not issued to this client")
+                    await oauth_provider_token_repo.revoke(db, token=refresh_record)
+                    logger.info(
+                        "Revoked refresh token via access token JTI %s...", jti[:8]
+                    )
+                    return True
+        except InvalidTokenError:
+            pass
+        except Exception:  # noqa: S110 - Intentional: invalid JWT not an error
+            pass
+
+    return False
+
+
+async def revoke_tokens_for_user_client(
+    db: AsyncSession,
+    user_id: UUID,
+    client_id: str,
+) -> int:
+    """
+    Revoke all tokens for a specific user-client pair.
+
+    Used when security incidents are detected (e.g., code reuse).
+
+    Args:
+        db: Database session
+        user_id: User identifier
+        client_id: Client identifier
+
+    Returns:
+        Number of tokens revoked
+    """
+    count = await oauth_provider_token_repo.revoke_all_for_user_client(
+        db, user_id=user_id, client_id=client_id
+    )
+
+    if count > 0:
+        logger.warning(
+            "Revoked %s tokens for user %s and client %s", count, user_id, client_id
+        )
+
+    return count
+
+
+async def revoke_all_user_tokens(db: AsyncSession, user_id: UUID) -> int:
+    """
+    Revoke all OAuth provider tokens for a user.
+
+    Used when user changes password or explicitly logs out everywhere.
+
+    Args:
+        db: Database session
+        user_id: User identifier
+
+    Returns:
+        Number of tokens revoked
+    """
+    count = await oauth_provider_token_repo.revoke_all_for_user(db, user_id=user_id)
+
+    if count > 0:
+        logger.info("Revoked %s OAuth provider tokens for user %s", count, user_id)
+
+    return count
+
+
+# ============================================================================
+# Token Introspection (RFC 7662)
+# ============================================================================
+
+
+async def introspect_token(
+    db: AsyncSession,
+    token: str,
+    token_type_hint: str | None = None,
+    client_id: str | None = None,
+    client_secret: str | None = None,
+) -> dict[str, Any]:
+    """
+    Introspect a token to determine its validity and metadata.
+
+    Implements RFC 7662 Token Introspection.
+
+    Args:
+        db: Database session
+        token: Token to introspect
+        token_type_hint: "access_token" or "refresh_token"
+        client_id: Client requesting introspection
+        client_secret: Client secret
+
+    Returns:
+        Introspection response dict
+    """
+    # Validate client if credentials provided
+    if client_id:
+        await validate_client(db, client_id, client_secret)
+
+    # Try as access token (JWT) first
+    if token_type_hint != "refresh_token":
+        try:
+            payload = jwt.decode(
+                token,
+                settings.SECRET_KEY,
+                algorithms=[settings.ALGORITHM],
+                options={
+                    "verify_aud": False
+                },  # Don't require audience match for introspection
+            )
+
+            # Check if associated refresh token is revoked
+            jti = payload.get("jti")
+            if jti:
+                refresh_record = await oauth_provider_token_repo.get_by_jti(db, jti=jti)
+                if refresh_record and refresh_record.revoked:
+                    return {"active": False}
+
+            return {
+                "active": True,
+                "scope": payload.get("scope", ""),
+                "client_id": payload.get("client_id"),
+                "username": payload.get("email"),
+                "token_type": "Bearer",
+                "exp": payload.get("exp"),
+                "iat": payload.get("iat"),
+                "sub": payload.get("sub"),
+                "aud": payload.get("aud"),
+                "iss": payload.get("iss"),
+            }
+        except ExpiredSignatureError:
+            return {"active": False}
+        except InvalidTokenError:
+            pass
+        except Exception:  # noqa: S110 - Intentional: invalid JWT falls through to refresh token check
+            pass
+
+    # Try as refresh token
+    if token_type_hint != "access_token":
+        token_hash = hash_token(token)
+        refresh_record = await oauth_provider_token_repo.get_by_token_hash(
+            db, token_hash=token_hash
+        )
+
+        if refresh_record and refresh_record.is_valid:
+            return {
+                "active": True,
+                "scope": refresh_record.scope,
+                "client_id": refresh_record.client_id,
+                "token_type": "refresh_token",
+                "exp": int(refresh_record.expires_at.timestamp()),
+                "iat": int(refresh_record.created_at.timestamp()),
+                "sub": str(refresh_record.user_id),
+            }
+
+    return {"active": False}
+
+
+# ============================================================================
+# Consent Management
+# ============================================================================
+
+
+async def get_consent(
+    db: AsyncSession,
+    user_id: UUID,
+    client_id: str,
+):
+    """Get existing consent record for user-client pair."""
+    return await oauth_consent_repo.get_consent(
+        db, user_id=user_id, client_id=client_id
+    )
+
+
+async def check_consent(
+    db: AsyncSession,
+    user_id: UUID,
+    client_id: str,
+    requested_scopes: list[str],
+) -> bool:
+    """
+    Check if user has already consented to the requested scopes.
+
+    Returns True if all requested scopes are already granted.
+    """
+    consent = await get_consent(db, user_id, client_id)
+    if not consent:
+        return False
+    return consent.has_scopes(requested_scopes)
+
+
+async def grant_consent(
+    db: AsyncSession,
+    user_id: UUID,
+    client_id: str,
+    scopes: list[str],
+):
+    """
+    Grant or update consent for a user-client pair.
+
+    If consent already exists, updates the granted scopes.
+    """
+    return await oauth_consent_repo.grant_consent(
+        db, user_id=user_id, client_id=client_id, scopes=scopes
+    )
+
+
+async def revoke_consent(
+    db: AsyncSession,
+    user_id: UUID,
+    client_id: str,
+) -> bool:
+    """
+    Revoke consent and all tokens for a user-client pair.
+
+    Returns True if consent was found and revoked.
+    """
+    # Revoke all tokens first
+    await revoke_tokens_for_user_client(db, user_id, client_id)
+
+    # Delete consent record
+    return await oauth_consent_repo.revoke_consent(
+        db, user_id=user_id, client_id=client_id
+    )
+
+
+# ============================================================================
+# Cleanup
+# ============================================================================
+
+
+async def register_client(db: AsyncSession, client_data: OAuthClientCreate) -> tuple:
+    """Create a new OAuth client. Returns (client, secret)."""
+    return await oauth_client_repo.create_client(db, obj_in=client_data)
+
+
+async def list_clients(db: AsyncSession) -> list:
+    """List all registered OAuth clients."""
+    return await oauth_client_repo.get_all_clients(db)
+
+
+async def delete_client_by_id(db: AsyncSession, client_id: str) -> None:
+    """Delete an OAuth client by client_id."""
+    await oauth_client_repo.delete_client(db, client_id=client_id)
+
+
+async def list_user_consents(db: AsyncSession, user_id: UUID) -> list[dict]:
+    """Get all OAuth consents for a user with client details."""
+    return await oauth_consent_repo.get_user_consents_with_clients(db, user_id=user_id)
+
+
+async def cleanup_expired_codes(db: AsyncSession) -> int:
+    """
+    Delete expired authorization codes.
+
+    Should be called periodically (e.g., every hour).
+
+    Returns:
+        Number of codes deleted
+    """
+    return await oauth_authorization_code_repo.cleanup_expired(db)
+
+
+async def cleanup_expired_tokens(db: AsyncSession) -> int:
+    """
+    Delete expired and revoked refresh tokens.
+
+    Should be called periodically (e.g., daily).
+
+    Returns:
+        Number of tokens deleted
+    """
+    return await oauth_provider_token_repo.cleanup_expired(db, cutoff_days=7)

backend/app/services/oauth_service.py

@@ -0,0 +1,744 @@
+"""
+OAuth Service for handling social authentication flows.
+
+Supports:
+- Google OAuth (OpenID Connect)
+- GitHub OAuth
+
+Features:
+- PKCE support for public clients
+- State parameter for CSRF protection
+- Auto-linking by email (configurable)
+- Account linking for existing users
+"""
+
+import logging
+import secrets
+from datetime import UTC, datetime, timedelta
+from typing import TypedDict, cast
+from uuid import UUID
+
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.auth import create_access_token, create_refresh_token
+from app.core.config import settings
+from app.core.exceptions import AuthenticationError
+from app.models.user import User
+from app.repositories.oauth_account import oauth_account_repo as oauth_account
+from app.repositories.oauth_state import oauth_state_repo as oauth_state
+from app.repositories.user import user_repo
+from app.schemas.oauth import (
+    OAuthAccountCreate,
+    OAuthCallbackResponse,
+    OAuthProviderInfo,
+    OAuthProvidersResponse,
+    OAuthStateCreate,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class _OAuthProviderConfigRequired(TypedDict):
+    name: str
+    icon: str
+    authorize_url: str
+    token_url: str
+    userinfo_url: str
+    scopes: list[str]
+    supports_pkce: bool
+
+
+class OAuthProviderConfig(_OAuthProviderConfigRequired, total=False):
+    """Type definition for OAuth provider configuration."""
+
+    email_url: str  # Optional, GitHub-only
+
+
+# Provider configurations
+OAUTH_PROVIDERS: dict[str, OAuthProviderConfig] = {
+    "google": {
+        "name": "Google",
+        "icon": "google",
+        "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth",
+        "token_url": "https://oauth2.googleapis.com/token",
+        "userinfo_url": "https://www.googleapis.com/oauth2/v3/userinfo",
+        "scopes": ["openid", "email", "profile"],
+        "supports_pkce": True,
+    },
+    "github": {
+        "name": "GitHub",
+        "icon": "github",
+        "authorize_url": "https://github.com/login/oauth/authorize",
+        "token_url": "https://github.com/login/oauth/access_token",
+        "userinfo_url": "https://api.github.com/user",
+        "email_url": "https://api.github.com/user/emails",
+        "scopes": ["read:user", "user:email"],
+        "supports_pkce": False,  # GitHub doesn't support PKCE
+    },
+}
+
+
+class OAuthService:
+    """Service for handling OAuth authentication flows."""
+
+    @staticmethod
+    def get_enabled_providers() -> OAuthProvidersResponse:
+        """
+        Get list of enabled OAuth providers.
+
+        Returns:
+            OAuthProvidersResponse with enabled providers
+        """
+        providers = []
+
+        for provider_id in settings.enabled_oauth_providers:
+            if provider_id in OAUTH_PROVIDERS:
+                config = OAUTH_PROVIDERS[provider_id]
+                providers.append(
+                    OAuthProviderInfo(
+                        provider=provider_id,
+                        name=config["name"],
+                        icon=config["icon"],
+                    )
+                )
+
+        return OAuthProvidersResponse(
+            enabled=settings.OAUTH_ENABLED and len(providers) > 0,
+            providers=providers,
+        )
+
+    @staticmethod
+    def _get_provider_credentials(provider: str) -> tuple[str, str]:
+        """Get client ID and secret for a provider."""
+        if provider == "google":
+            client_id = settings.OAUTH_GOOGLE_CLIENT_ID
+            client_secret = settings.OAUTH_GOOGLE_CLIENT_SECRET
+        elif provider == "github":
+            client_id = settings.OAUTH_GITHUB_CLIENT_ID
+            client_secret = settings.OAUTH_GITHUB_CLIENT_SECRET
+        else:
+            raise AuthenticationError(f"Unknown OAuth provider: {provider}")
+
+        if not client_id or not client_secret:
+            raise AuthenticationError(f"OAuth provider {provider} is not configured")
+
+        return client_id, client_secret
+
+    @staticmethod
+    async def create_authorization_url(
+        db: AsyncSession,
+        *,
+        provider: str,
+        redirect_uri: str,
+        user_id: str | None = None,
+    ) -> tuple[str, str]:
+        """
+        Create OAuth authorization URL with state and optional PKCE.
+
+        Args:
+            db: Database session
+            provider: OAuth provider (google, github)
+            redirect_uri: Callback URL after OAuth
+            user_id: User ID if linking account (user is logged in)
+
+        Returns:
+            Tuple of (authorization_url, state)
+
+        Raises:
+            AuthenticationError: If provider is not configured
+        """
+        if not settings.OAUTH_ENABLED:
+            raise AuthenticationError("OAuth is not enabled")
+
+        if provider not in OAUTH_PROVIDERS:
+            raise AuthenticationError(f"Unknown OAuth provider: {provider}")
+
+        if provider not in settings.enabled_oauth_providers:
+            raise AuthenticationError(f"OAuth provider {provider} is not enabled")
+
+        config = OAUTH_PROVIDERS[provider]
+        client_id, client_secret = OAuthService._get_provider_credentials(provider)
+
+        # Generate state for CSRF protection
+        state = secrets.token_urlsafe(32)
+
+        # Generate PKCE code verifier and challenge if supported
+        code_verifier = None
+        code_challenge = None
+        if config.get("supports_pkce"):
+            code_verifier = secrets.token_urlsafe(64)
+            # Create code_challenge using S256 method
+            import base64
+            import hashlib
+
+            code_challenge_bytes = hashlib.sha256(code_verifier.encode()).digest()
+            code_challenge = (
+                base64.urlsafe_b64encode(code_challenge_bytes).decode().rstrip("=")
+            )
+
+        # Generate nonce for OIDC (Google)
+        nonce = secrets.token_urlsafe(32) if provider == "google" else None
+
+        # Store state in database
+        from uuid import UUID
+
+        state_data = OAuthStateCreate(
+            state=state,
+            code_verifier=code_verifier,
+            nonce=nonce,
+            provider=provider,
+            redirect_uri=redirect_uri,
+            user_id=UUID(user_id) if user_id else None,
+            expires_at=datetime.now(UTC)
+            + timedelta(minutes=settings.OAUTH_STATE_EXPIRE_MINUTES),
+        )
+        await oauth_state.create_state(db, obj_in=state_data)
+
+        # Build authorization URL
+        async with AsyncOAuth2Client(
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_uri=redirect_uri,
+        ) as client:
+            # Prepare authorization params
+            auth_params = {
+                "state": state,
+                "scope": " ".join(config["scopes"]),
+            }
+
+            if code_challenge:
+                auth_params["code_challenge"] = code_challenge
+                auth_params["code_challenge_method"] = "S256"
+
+            if nonce:
+                auth_params["nonce"] = nonce
+
+            url, _ = client.create_authorization_url(
+                config["authorize_url"],
+                **auth_params,
+            )
+
+        logger.info("OAuth authorization URL created for %s", provider)
+        return url, state
+
+    @staticmethod
+    async def handle_callback(
+        db: AsyncSession,
+        *,
+        code: str,
+        state: str,
+        redirect_uri: str,
+    ) -> OAuthCallbackResponse:
+        """
+        Handle OAuth callback and authenticate/create user.
+
+        Args:
+            db: Database session
+            code: Authorization code from provider
+            state: State parameter for CSRF verification
+            redirect_uri: Callback URL (must match authorization request)
+
+        Returns:
+            OAuthCallbackResponse with tokens
+
+        Raises:
+            AuthenticationError: If authentication fails
+        """
+        # Validate and consume state
+        state_record = await oauth_state.get_and_consume_state(db, state=state)
+        if not state_record:
+            raise AuthenticationError("Invalid or expired OAuth state")
+
+        # SECURITY: Validate redirect_uri matches the one from authorization request
+        # This prevents authorization code injection attacks (RFC 6749 Section 10.6)
+        if state_record.redirect_uri != redirect_uri:
+            logger.warning(
+                "OAuth redirect_uri mismatch: expected %s, got %s",
+                state_record.redirect_uri,
+                redirect_uri,
+            )
+            raise AuthenticationError("Redirect URI mismatch")
+
+        # Extract provider from state record (str for type safety)
+        provider: str = str(state_record.provider)
+
+        if provider not in OAUTH_PROVIDERS:
+            raise AuthenticationError(f"Unknown OAuth provider: {provider}")
+
+        config = OAUTH_PROVIDERS[provider]
+        client_id, client_secret = OAuthService._get_provider_credentials(provider)
+
+        # Exchange code for tokens
+        async with AsyncOAuth2Client(
+            client_id=client_id,
+            client_secret=client_secret,
+            redirect_uri=redirect_uri,
+        ) as client:
+            try:
+                # Prepare token request params
+                token_params: dict[str, str] = {"code": code}
+
+                if state_record.code_verifier:
+                    token_params["code_verifier"] = str(state_record.code_verifier)
+
+                token = await client.fetch_token(
+                    config["token_url"],
+                    **token_params,
+                )
+
+                # SECURITY: Validate ID token signature and nonce for OpenID Connect
+                # This prevents token forgery and replay attacks (OIDC Core 3.1.3.7)
+                if provider == "google" and state_record.nonce:
+                    id_token = token.get("id_token")
+                    if id_token:
+                        await OAuthService._verify_google_id_token(
+                            id_token=str(id_token),
+                            expected_nonce=str(state_record.nonce),
+                            client_id=client_id,
+                        )
+            except AuthenticationError:
+                raise
+            except Exception as e:
+                logger.error("OAuth token exchange failed: %s", e)
+                raise AuthenticationError("Failed to exchange authorization code")
+
+            # Get user info from provider
+            try:
+                access_token = token.get("access_token")
+                if not access_token:
+                    raise AuthenticationError("No access token received")
+
+                user_info = await OAuthService._get_user_info(
+                    client, provider, config, access_token
+                )
+            except Exception as e:
+                logger.error("Failed to get user info: %s", e)
+                raise AuthenticationError(
+                    "Failed to get user information from provider"
+                )
+
+        # Process user info and create/link account
+        provider_user_id = str(user_info.get("id") or user_info.get("sub"))
+        # Email can be None if user didn't grant email permission
+        # SECURITY: Normalize email (lowercase, strip) to prevent case-based account duplication
+        email_raw = user_info.get("email")
+        provider_email: str | None = (
+            str(email_raw).lower().strip() if email_raw else None
+        )
+
+        if not provider_user_id:
+            raise AuthenticationError("Provider did not return user ID")
+
+        # Check if this OAuth account already exists
+        existing_oauth = await oauth_account.get_by_provider_id(
+            db, provider=provider, provider_user_id=provider_user_id
+        )
+
+        is_new_user = False
+
+        if existing_oauth:
+            # Existing OAuth account - login
+            user = existing_oauth.user
+            if not user.is_active:
+                raise AuthenticationError("User account is inactive")
+
+            # Update tokens if stored
+            if token.get("access_token"):
+                await oauth_account.update_tokens(
+                    db,
+                    account=existing_oauth,
+                    access_token=token.get("access_token"),
+                    refresh_token=token.get("refresh_token"),
+                    token_expires_at=datetime.now(UTC)
+                    + timedelta(seconds=token.get("expires_in", 3600)),
+                )
+
+            logger.info("OAuth login successful for %s via %s", user.email, provider)
+
+        elif state_record.user_id:
+            # Account linking flow (user is already logged in)
+            user = await user_repo.get(db, id=str(state_record.user_id))
+
+            if not user:
+                raise AuthenticationError("User not found for account linking")
+
+            # Check if user already has this provider linked
+            user_id = cast(UUID, user.id)
+            existing_provider = await oauth_account.get_user_account_by_provider(
+                db, user_id=user_id, provider=provider
+            )
+            if existing_provider:
+                raise AuthenticationError(
+                    f"You already have a {provider} account linked"
+                )
+
+            # Create OAuth account link
+            oauth_create = OAuthAccountCreate(
+                user_id=user_id,
+                provider=provider,
+                provider_user_id=provider_user_id,
+                provider_email=provider_email,
+                access_token=token.get("access_token"),
+                refresh_token=token.get("refresh_token"),
+                token_expires_at=datetime.now(UTC)
+                + timedelta(seconds=token.get("expires_in", 3600))
+                if token.get("expires_in")
+                else None,
+            )
+            await oauth_account.create_account(db, obj_in=oauth_create)
+
+            logger.info("OAuth account linked: %s -> %s", provider, user.email)
+
+        else:
+            # New OAuth login - check for existing user by email
+            user = None
+
+            if provider_email and settings.OAUTH_AUTO_LINK_BY_EMAIL:
+                user = await user_repo.get_by_email(db, email=provider_email)
+
+            if user:
+                # Auto-link to existing user
+                if not user.is_active:
+                    raise AuthenticationError("User account is inactive")
+
+                # Check if user already has this provider linked
+                user_id = cast(UUID, user.id)
+                existing_provider = await oauth_account.get_user_account_by_provider(
+                    db, user_id=user_id, provider=provider
+                )
+                if existing_provider:
+                    # This shouldn't happen if we got here, but safety check
+                    logger.warning(
+                        "OAuth account already linked (race condition?): %s -> %s",
+                        provider,
+                        user.email,
+                    )
+                else:
+                    # Create OAuth account link
+                    oauth_create = OAuthAccountCreate(
+                        user_id=user_id,
+                        provider=provider,
+                        provider_user_id=provider_user_id,
+                        provider_email=provider_email,
+                        access_token=token.get("access_token"),
+                        refresh_token=token.get("refresh_token"),
+                        token_expires_at=datetime.now(UTC)
+                        + timedelta(seconds=token.get("expires_in", 3600))
+                        if token.get("expires_in")
+                        else None,
+                    )
+                    await oauth_account.create_account(db, obj_in=oauth_create)
+
+                logger.info(
+                    "OAuth auto-linked by email: %s -> %s", provider, user.email
+                )
+
+            else:
+                # Create new user
+                if not provider_email:
+                    raise AuthenticationError(
+                        f"Email is required for registration. "
+                        f"Please grant email permission to {provider}."
+                    )
+
+                user = await OAuthService._create_oauth_user(
+                    db,
+                    email=provider_email,
+                    provider=provider,
+                    provider_user_id=provider_user_id,
+                    user_info=user_info,
+                    token=token,
+                )
+                is_new_user = True
+
+                logger.info("New user created via OAuth: %s (%s)", user.email, provider)
+
+        # Generate JWT tokens
+        claims = {
+            "is_superuser": user.is_superuser,
+            "email": user.email,
+            "first_name": user.first_name,
+        }
+
+        access_token_jwt = create_access_token(subject=str(user.id), claims=claims)
+        refresh_token_jwt = create_refresh_token(subject=str(user.id))
+
+        return OAuthCallbackResponse(
+            access_token=access_token_jwt,
+            refresh_token=refresh_token_jwt,
+            token_type="bearer",
+            expires_in=settings.ACCESS_TOKEN_EXPIRE_MINUTES * 60,
+            is_new_user=is_new_user,
+        )
+
+    @staticmethod
+    async def _get_user_info(
+        client: AsyncOAuth2Client,
+        provider: str,
+        config: OAuthProviderConfig,
+        access_token: str,
+    ) -> dict[str, object]:
+        """Get user info from OAuth provider."""
+        headers = {"Authorization": f"Bearer {access_token}"}
+
+        if provider == "github":
+            # GitHub returns JSON with Accept header
+            headers["Accept"] = "application/vnd.github+json"
+
+        resp = await client.get(config["userinfo_url"], headers=headers)
+        resp.raise_for_status()
+        user_info = resp.json()
+
+        # GitHub requires separate request for email
+        if provider == "github" and not user_info.get("email"):
+            email_resp = await client.get(
+                config["email_url"],  # pyright: ignore[reportTypedDictNotRequiredAccess]
+                headers=headers,
+            )
+            email_resp.raise_for_status()
+            emails = email_resp.json()
+
+            # Find primary verified email
+            for email_data in emails:
+                if email_data.get("primary") and email_data.get("verified"):
+                    user_info["email"] = email_data["email"]
+                    break
+
+        return user_info
+
+    # Google's OIDC configuration endpoints
+    GOOGLE_JWKS_URL = "https://www.googleapis.com/oauth2/v3/certs"
+    GOOGLE_ISSUERS = ("https://accounts.google.com", "accounts.google.com")
+
+    @staticmethod
+    async def _verify_google_id_token(
+        id_token: str,
+        expected_nonce: str,
+        client_id: str,
+    ) -> dict[str, object]:
+        """
+        Verify Google ID token signature and claims.
+
+        SECURITY: This properly verifies the ID token by:
+        1. Fetching Google's public keys (JWKS)
+        2. Verifying the JWT signature against the public key
+        3. Validating issuer, audience, expiry, and nonce claims
+
+        Args:
+            id_token: The ID token JWT string
+            expected_nonce: The nonce we sent in the authorization request
+            client_id: Our OAuth client ID (expected audience)
+
+        Returns:
+            Decoded ID token payload
+
+        Raises:
+            AuthenticationError: If verification fails
+        """
+        import httpx
+        import jwt as pyjwt
+        from jwt.algorithms import RSAAlgorithm
+        from jwt.exceptions import InvalidTokenError
+
+        try:
+            # Fetch Google's public keys (JWKS)
+            # In production, consider caching this with TTL matching Cache-Control header
+            async with httpx.AsyncClient() as client:
+                jwks_response = await client.get(
+                    OAuthService.GOOGLE_JWKS_URL,
+                    timeout=10.0,
+                )
+                jwks_response.raise_for_status()
+                jwks = jwks_response.json()
+
+            # Get the key ID from the token header
+            unverified_header = pyjwt.get_unverified_header(id_token)
+            kid = unverified_header.get("kid")
+            if not kid:
+                raise AuthenticationError("ID token missing key ID (kid)")
+
+            # Find the matching public key
+            jwk_data = None
+            for key in jwks.get("keys", []):
+                if key.get("kid") == kid:
+                    jwk_data = key
+                    break
+
+            if not jwk_data:
+                raise AuthenticationError("ID token signed with unknown key")
+
+            # Convert JWK to a public key object for PyJWT
+            public_key = RSAAlgorithm.from_jwk(jwk_data)
+
+            # Verify the token signature and decode claims
+            # PyJWT will verify signature against the RSA public key
+            payload = pyjwt.decode(
+                id_token,
+                public_key,
+                algorithms=["RS256"],  # Google uses RS256
+                audience=client_id,
+                issuer=OAuthService.GOOGLE_ISSUERS,
+                options={
+                    "verify_signature": True,
+                    "verify_aud": True,
+                    "verify_iss": True,
+                    "verify_exp": True,
+                    "verify_iat": True,
+                },
+            )
+
+            # Verify nonce (OIDC replay attack protection)
+            token_nonce = payload.get("nonce")
+            if token_nonce != expected_nonce:
+                logger.warning(
+                    "OAuth ID token nonce mismatch: expected %s, got %s",
+                    expected_nonce,
+                    token_nonce,
+                )
+                raise AuthenticationError("Invalid ID token nonce")
+
+            logger.debug("Google ID token verified successfully")
+            return payload
+
+        except InvalidTokenError as e:
+            logger.warning("Google ID token verification failed: %s", e)
+            raise AuthenticationError("Invalid ID token signature")
+        except httpx.HTTPError as e:
+            logger.error("Failed to fetch Google JWKS: %s", e)
+            # If we can't verify the ID token, fail closed for security
+            raise AuthenticationError("Failed to verify ID token")
+        except Exception as e:
+            logger.error("Unexpected error verifying Google ID token: %s", e)
+            raise AuthenticationError("ID token verification error")
+
+    @staticmethod
+    async def _create_oauth_user(
+        db: AsyncSession,
+        *,
+        email: str,
+        provider: str,
+        provider_user_id: str,
+        user_info: dict,
+        token: dict,
+    ) -> User:
+        """Create a new user from OAuth provider data."""
+        # Extract name from user_info
+        first_name = "User"
+        last_name = None
+
+        if provider == "google":
+            first_name = user_info.get("given_name") or user_info.get("name", "User")
+            last_name = user_info.get("family_name")
+        elif provider == "github":
+            # GitHub has full name, try to split
+            name = user_info.get("name") or user_info.get("login", "User")
+            parts = name.split(" ", 1)
+            first_name = parts[0]
+            last_name = parts[1] if len(parts) > 1 else None
+
+        # Create user (no password for OAuth-only users)
+        user = User(
+            email=email,
+            password_hash=None,  # OAuth-only user
+            first_name=first_name,
+            last_name=last_name,
+            is_active=True,
+            is_superuser=False,
+        )
+        db.add(user)
+        await db.flush()  # Get user.id
+
+        # Create OAuth account link
+        user_id = cast(UUID, user.id)
+        oauth_create = OAuthAccountCreate(
+            user_id=user_id,
+            provider=provider,
+            provider_user_id=provider_user_id,
+            provider_email=email,
+            access_token=token.get("access_token"),
+            refresh_token=token.get("refresh_token"),
+            token_expires_at=datetime.now(UTC)
+            + timedelta(seconds=token.get("expires_in", 3600))
+            if token.get("expires_in")
+            else None,
+        )
+        await oauth_account.create_account(db, obj_in=oauth_create)
+
+        await db.refresh(user)
+
+        return user
+
+    @staticmethod
+    async def unlink_provider(
+        db: AsyncSession,
+        *,
+        user: User,
+        provider: str,
+    ) -> bool:
+        """
+        Unlink an OAuth provider from a user account.
+
+        Args:
+            db: Database session
+            user: User to unlink from
+            provider: Provider to unlink
+
+        Returns:
+            True if unlinked successfully
+
+        Raises:
+            AuthenticationError: If unlinking would leave user without login method
+        """
+        # Check if user can safely remove this OAuth account
+        # Note: We query directly instead of using user.can_remove_oauth property
+        # because the property uses lazy loading which doesn't work in async context
+        user_id = cast(UUID, user.id)
+        has_password = user.password_hash is not None
+        oauth_accounts = await oauth_account.get_user_accounts(db, user_id=user_id)
+        can_remove = has_password or len(oauth_accounts) > 1
+
+        if not can_remove:
+            raise AuthenticationError(
+                "Cannot unlink OAuth account. You must have either a password set "
+                "or at least one other OAuth provider linked."
+            )
+
+        deleted = await oauth_account.delete_account(
+            db, user_id=user_id, provider=provider
+        )
+
+        if not deleted:
+            raise AuthenticationError(f"No {provider} account found to unlink")
+
+        logger.info("OAuth provider unlinked: %s from %s", provider, user.email)
+        return True
+
+    @staticmethod
+    async def get_user_accounts(db: AsyncSession, *, user_id: UUID) -> list:
+        """Get all OAuth accounts linked to a user."""
+        return await oauth_account.get_user_accounts(db, user_id=user_id)
+
+    @staticmethod
+    async def get_user_account_by_provider(
+        db: AsyncSession, *, user_id: UUID, provider: str
+    ):
+        """Get a specific OAuth account for a user and provider."""
+        return await oauth_account.get_user_account_by_provider(
+            db, user_id=user_id, provider=provider
+        )
+
+    @staticmethod
+    async def cleanup_expired_states(db: AsyncSession) -> int:
+        """
+        Clean up expired OAuth states.
+
+        Should be called periodically (e.g., by a background task).
+
+        Args:
+            db: Database session
+
+        Returns:
+            Number of states cleaned up
+        """
+        return await oauth_state.cleanup_expired(db)

backend/app/services/organization_service.py

@@ -0,0 +1,155 @@
+# app/services/organization_service.py
+"""Service layer for organization operations — delegates to OrganizationRepository."""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.exceptions import NotFoundError
+from app.models.organization import Organization
+from app.models.user_organization import OrganizationRole, UserOrganization
+from app.repositories.organization import OrganizationRepository, organization_repo
+from app.schemas.organizations import OrganizationCreate, OrganizationUpdate
+
+logger = logging.getLogger(__name__)
+
+
+class OrganizationService:
+    """Service for organization management operations."""
+
+    def __init__(
+        self, organization_repository: OrganizationRepository | None = None
+    ) -> None:
+        self._repo = organization_repository or organization_repo
+
+    async def get_organization(self, db: AsyncSession, org_id: str) -> Organization:
+        """Get organization by ID, raising NotFoundError if not found."""
+        org = await self._repo.get(db, id=org_id)
+        if not org:
+            raise NotFoundError(f"Organization {org_id} not found")
+        return org
+
+    async def create_organization(
+        self, db: AsyncSession, *, obj_in: OrganizationCreate
+    ) -> Organization:
+        """Create a new organization."""
+        return await self._repo.create(db, obj_in=obj_in)
+
+    async def update_organization(
+        self,
+        db: AsyncSession,
+        *,
+        org: Organization,
+        obj_in: OrganizationUpdate | dict[str, Any],
+    ) -> Organization:
+        """Update an existing organization."""
+        return await self._repo.update(db, db_obj=org, obj_in=obj_in)
+
+    async def remove_organization(self, db: AsyncSession, org_id: str) -> None:
+        """Permanently delete an organization by ID."""
+        await self._repo.remove(db, id=org_id)
+
+    async def get_member_count(self, db: AsyncSession, *, organization_id: UUID) -> int:
+        """Get number of active members in an organization."""
+        return await self._repo.get_member_count(db, organization_id=organization_id)
+
+    async def get_multi_with_member_counts(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        is_active: bool | None = None,
+        search: str | None = None,
+    ) -> tuple[list[dict[str, Any]], int]:
+        """List organizations with member counts and pagination."""
+        return await self._repo.get_multi_with_member_counts(
+            db, skip=skip, limit=limit, is_active=is_active, search=search
+        )
+
+    async def get_user_organizations_with_details(
+        self,
+        db: AsyncSession,
+        *,
+        user_id: UUID,
+        is_active: bool | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get all organizations a user belongs to, with membership details."""
+        return await self._repo.get_user_organizations_with_details(
+            db, user_id=user_id, is_active=is_active
+        )
+
+    async def get_organization_members(
+        self,
+        db: AsyncSession,
+        *,
+        organization_id: UUID,
+        skip: int = 0,
+        limit: int = 100,
+        is_active: bool | None = True,
+    ) -> tuple[list[dict[str, Any]], int]:
+        """Get members of an organization with pagination."""
+        return await self._repo.get_organization_members(
+            db,
+            organization_id=organization_id,
+            skip=skip,
+            limit=limit,
+            is_active=is_active,
+        )
+
+    async def add_member(
+        self,
+        db: AsyncSession,
+        *,
+        organization_id: UUID,
+        user_id: UUID,
+        role: OrganizationRole = OrganizationRole.MEMBER,
+    ) -> UserOrganization:
+        """Add a user to an organization."""
+        return await self._repo.add_user(
+            db, organization_id=organization_id, user_id=user_id, role=role
+        )
+
+    async def remove_member(
+        self,
+        db: AsyncSession,
+        *,
+        organization_id: UUID,
+        user_id: UUID,
+    ) -> bool:
+        """Remove a user from an organization. Returns True if found and removed."""
+        return await self._repo.remove_user(
+            db, organization_id=organization_id, user_id=user_id
+        )
+
+    async def get_user_role_in_org(
+        self, db: AsyncSession, *, user_id: UUID, organization_id: UUID
+    ) -> OrganizationRole | None:
+        """Get the role of a user in an organization."""
+        return await self._repo.get_user_role_in_org(
+            db, user_id=user_id, organization_id=organization_id
+        )
+
+    async def get_org_distribution(
+        self, db: AsyncSession, *, limit: int = 6
+    ) -> list[dict[str, Any]]:
+        """Return top organizations by member count for admin dashboard."""
+        from sqlalchemy import func, select
+
+        result = await db.execute(
+            select(
+                Organization.name,
+                func.count(UserOrganization.user_id).label("count"),
+            )
+            .join(UserOrganization, Organization.id == UserOrganization.organization_id)
+            .group_by(Organization.name)
+            .order_by(func.count(UserOrganization.user_id).desc())
+            .limit(limit)
+        )
+        return [{"name": row.name, "value": row.count} for row in result.all()]
+
+
+# Default singleton
+organization_service = OrganizationService()

backend/app/services/session_cleanup.py

@@ -0,0 +1,88 @@
+"""
+Background job for cleaning up expired sessions.
+
+This service runs periodically to remove old session records from the database.
+"""
+
+import logging
+from datetime import UTC, datetime
+
+from app.core.database import SessionLocal
+from app.repositories.session import session_repo as session_repo
+
+logger = logging.getLogger(__name__)
+
+
+async def cleanup_expired_sessions(keep_days: int = 30) -> int:
+    """
+    Clean up expired and inactive sessions.
+
+    This removes sessions that are:
+    - Inactive (is_active=False) AND
+    - Expired (expires_at < now) AND
+    - Older than keep_days
+
+    Args:
+        keep_days: Keep inactive sessions for this many days for audit purposes
+
+    Returns:
+        Number of sessions deleted
+    """
+    logger.info("Starting session cleanup job...")
+
+    async with SessionLocal() as db:
+        try:
+            # Use repository method to cleanup
+            count = await session_repo.cleanup_expired(db, keep_days=keep_days)
+
+            logger.info("Session cleanup complete: %s sessions deleted", count)
+
+            return count
+
+        except Exception as e:
+            logger.exception("Error during session cleanup: %s", e)
+            return 0
+
+
+async def get_session_statistics() -> dict:
+    """
+    Get statistics about current sessions.
+
+    Returns:
+        Dictionary with session stats
+    """
+    async with SessionLocal() as db:
+        try:
+            from sqlalchemy import func, select
+
+            from app.models.user_session import UserSession
+
+            total_result = await db.execute(select(func.count(UserSession.id)))
+            total_sessions = total_result.scalar_one()
+
+            active_result = await db.execute(
+                select(func.count(UserSession.id)).where(UserSession.is_active)
+            )
+            active_sessions = active_result.scalar_one()
+
+            expired_result = await db.execute(
+                select(func.count(UserSession.id)).where(
+                    UserSession.expires_at < datetime.now(UTC)
+                )
+            )
+            expired_sessions = expired_result.scalar_one()
+
+            stats = {
+                "total": total_sessions,
+                "active": active_sessions,
+                "inactive": total_sessions - active_sessions,
+                "expired": expired_sessions,
+            }
+
+            logger.info("Session statistics: %s", stats)
+
+            return stats
+
+        except Exception as e:
+            logger.exception("Error getting session statistics: %s", e)
+            return {}

backend/app/services/session_service.py

@@ -0,0 +1,97 @@
+# app/services/session_service.py
+"""Service layer for session operations — delegates to SessionRepository."""
+
+import logging
+from datetime import datetime
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models.user_session import UserSession
+from app.repositories.session import SessionRepository, session_repo
+from app.schemas.sessions import SessionCreate
+
+logger = logging.getLogger(__name__)
+
+
+class SessionService:
+    """Service for user session management operations."""
+
+    def __init__(self, session_repository: SessionRepository | None = None) -> None:
+        self._repo = session_repository or session_repo
+
+    async def create_session(
+        self, db: AsyncSession, *, obj_in: SessionCreate
+    ) -> UserSession:
+        """Create a new session record."""
+        return await self._repo.create_session(db, obj_in=obj_in)
+
+    async def get_session(
+        self, db: AsyncSession, session_id: str
+    ) -> UserSession | None:
+        """Get session by ID."""
+        return await self._repo.get(db, id=session_id)
+
+    async def get_user_sessions(
+        self, db: AsyncSession, *, user_id: str, active_only: bool = True
+    ) -> list[UserSession]:
+        """Get all sessions for a user."""
+        return await self._repo.get_user_sessions(
+            db, user_id=user_id, active_only=active_only
+        )
+
+    async def get_active_by_jti(
+        self, db: AsyncSession, *, jti: str
+    ) -> UserSession | None:
+        """Get active session by refresh token JTI."""
+        return await self._repo.get_active_by_jti(db, jti=jti)
+
+    async def get_by_jti(self, db: AsyncSession, *, jti: str) -> UserSession | None:
+        """Get session by refresh token JTI (active or inactive)."""
+        return await self._repo.get_by_jti(db, jti=jti)
+
+    async def deactivate(
+        self, db: AsyncSession, *, session_id: str
+    ) -> UserSession | None:
+        """Deactivate a session (logout from device)."""
+        return await self._repo.deactivate(db, session_id=session_id)
+
+    async def deactivate_all_user_sessions(
+        self, db: AsyncSession, *, user_id: str
+    ) -> int:
+        """Deactivate all sessions for a user. Returns count deactivated."""
+        return await self._repo.deactivate_all_user_sessions(db, user_id=user_id)
+
+    async def update_refresh_token(
+        self,
+        db: AsyncSession,
+        *,
+        session: UserSession,
+        new_jti: str,
+        new_expires_at: datetime,
+    ) -> UserSession:
+        """Update session with a rotated refresh token."""
+        return await self._repo.update_refresh_token(
+            db, session=session, new_jti=new_jti, new_expires_at=new_expires_at
+        )
+
+    async def cleanup_expired_for_user(self, db: AsyncSession, *, user_id: str) -> int:
+        """Remove expired sessions for a user. Returns count removed."""
+        return await self._repo.cleanup_expired_for_user(db, user_id=user_id)
+
+    async def get_all_sessions(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        active_only: bool = True,
+        with_user: bool = True,
+    ) -> tuple[list[UserSession], int]:
+        """Get all sessions with pagination (admin only)."""
+        return await self._repo.get_all_sessions(
+            db, skip=skip, limit=limit, active_only=active_only, with_user=with_user
+        )
+
+
+# Default singleton
+session_service = SessionService()

backend/app/services/user_service.py

@@ -0,0 +1,120 @@
+# app/services/user_service.py
+"""Service layer for user operations — delegates to UserRepository."""
+
+import logging
+from typing import Any
+from uuid import UUID
+
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.core.exceptions import NotFoundError
+from app.models.user import User
+from app.repositories.user import UserRepository, user_repo
+from app.schemas.users import UserCreate, UserUpdate
+
+logger = logging.getLogger(__name__)
+
+
+class UserService:
+    """Service for user management operations."""
+
+    def __init__(self, user_repository: UserRepository | None = None) -> None:
+        self._repo = user_repository or user_repo
+
+    async def get_user(self, db: AsyncSession, user_id: str) -> User:
+        """Get user by ID, raising NotFoundError if not found."""
+        user = await self._repo.get(db, id=user_id)
+        if not user:
+            raise NotFoundError(f"User {user_id} not found")
+        return user
+
+    async def get_by_email(self, db: AsyncSession, email: str) -> User | None:
+        """Get user by email address."""
+        return await self._repo.get_by_email(db, email=email)
+
+    async def create_user(self, db: AsyncSession, user_data: UserCreate) -> User:
+        """Create a new user."""
+        return await self._repo.create(db, obj_in=user_data)
+
+    async def update_user(
+        self, db: AsyncSession, *, user: User, obj_in: UserUpdate | dict[str, Any]
+    ) -> User:
+        """Update an existing user."""
+        return await self._repo.update(db, db_obj=user, obj_in=obj_in)
+
+    async def soft_delete_user(self, db: AsyncSession, user_id: str) -> None:
+        """Soft-delete a user by ID."""
+        await self._repo.soft_delete(db, id=user_id)
+
+    async def list_users(
+        self,
+        db: AsyncSession,
+        *,
+        skip: int = 0,
+        limit: int = 100,
+        sort_by: str | None = None,
+        sort_order: str = "asc",
+        filters: dict[str, Any] | None = None,
+        search: str | None = None,
+    ) -> tuple[list[User], int]:
+        """List users with pagination, sorting, filtering, and search."""
+        return await self._repo.get_multi_with_total(
+            db,
+            skip=skip,
+            limit=limit,
+            sort_by=sort_by,
+            sort_order=sort_order,
+            filters=filters,
+            search=search,
+        )
+
+    async def bulk_update_status(
+        self, db: AsyncSession, *, user_ids: list[UUID], is_active: bool
+    ) -> int:
+        """Bulk update active status for multiple users. Returns count updated."""
+        return await self._repo.bulk_update_status(
+            db, user_ids=user_ids, is_active=is_active
+        )
+
+    async def bulk_soft_delete(
+        self,
+        db: AsyncSession,
+        *,
+        user_ids: list[UUID],
+        exclude_user_id: UUID | None = None,
+    ) -> int:
+        """Bulk soft-delete multiple users. Returns count deleted."""
+        return await self._repo.bulk_soft_delete(
+            db, user_ids=user_ids, exclude_user_id=exclude_user_id
+        )
+
+    async def get_stats(self, db: AsyncSession) -> dict[str, Any]:
+        """Return user stats needed for the admin dashboard."""
+        from sqlalchemy import func, select
+
+        total_users = (
+            await db.execute(select(func.count()).select_from(User))
+        ).scalar() or 0
+        active_count = (
+            await db.execute(
+                select(func.count()).select_from(User).where(User.is_active)
+            )
+        ).scalar() or 0
+        inactive_count = (
+            await db.execute(
+                select(func.count()).select_from(User).where(User.is_active.is_(False))
+            )
+        ).scalar() or 0
+        all_users = list(
+            (await db.execute(select(User).order_by(User.created_at))).scalars().all()
+        )
+        return {
+            "total_users": total_users,
+            "active_count": active_count,
+            "inactive_count": inactive_count,
+            "all_users": all_users,
+        }
+
+
+# Default singleton
+user_service = UserService()

backend/app/utils/auth_test_utils.py

@@ -0,0 +1,124 @@
+"""
+Authentication utilities for testing.
+This module provides tools to bypass FastAPI's authentication in tests.
+"""
+
+from collections.abc import Callable
+
+from fastapi import FastAPI
+from fastapi.security import OAuth2PasswordBearer
+from starlette.testclient import TestClient
+
+from app.api.dependencies.auth import get_current_user, get_optional_current_user
+from app.models.user import User
+
+
+def create_test_auth_client(
+    app: FastAPI,
+    test_user: User,
+    extra_overrides: dict[Callable, Callable] | None = None,
+) -> TestClient:
+    """
+    Create a test client with authentication pre-configured.
+
+    This bypasses the OAuth2 token validation and directly returns the test user.
+
+    Args:
+        app: The FastAPI app to test
+        test_user: The user object to use for authentication
+        extra_overrides: Additional dependency overrides to apply
+
+    Returns:
+        TestClient with authentication configured
+    """
+    # First override the oauth2_scheme dependency to return a dummy token
+    # This prevents FastAPI from trying to extract a real bearer token from the request
+    oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
+    app.dependency_overrides[oauth2_scheme] = lambda: "dummy_token_for_testing"
+
+    # Then override the get_current_user dependency to return our test user
+    app.dependency_overrides[get_current_user] = lambda: test_user
+
+    # Apply any extra overrides
+    if extra_overrides:
+        for dep, override in extra_overrides.items():
+            app.dependency_overrides[dep] = override
+
+    # Create and return the client
+    return TestClient(app)
+
+
+def create_test_optional_auth_client(app: FastAPI, test_user: User) -> TestClient:
+    """
+    Create a test client with optional authentication pre-configured.
+
+    This is useful for testing endpoints that use get_optional_current_user.
+
+    Args:
+        app: The FastAPI app to test
+        test_user: The user object to use for authentication
+
+    Returns:
+        TestClient with optional authentication configured
+    """
+    # Override the get_optional_current_user dependency
+    app.dependency_overrides[get_optional_current_user] = lambda: test_user
+
+    # Create and return the client
+    return TestClient(app)
+
+
+def create_test_superuser_client(app: FastAPI, test_user: User) -> TestClient:
+    """
+    Create a test client with superuser authentication pre-configured.
+
+    Args:
+        app: The FastAPI app to test
+        test_user: The user object to use as superuser
+
+    Returns:
+        TestClient with superuser authentication
+    """
+    # Make sure user is a superuser
+    test_user.is_superuser = True
+
+    # Use the auth client creation with superuser
+    return create_test_auth_client(app, test_user)
+
+
+def create_test_unauthenticated_client(app: FastAPI) -> TestClient:
+    """
+    Create a test client that will fail authentication checks.
+
+    This is useful for testing the unauthorized case of protected endpoints.
+
+    Args:
+        app: The FastAPI app to test
+
+    Returns:
+        TestClient without authentication
+    """
+    # Any authentication attempts will fail
+    return TestClient(app)
+
+
+def cleanup_test_client_auth(app: FastAPI) -> None:
+    """
+    Clean up authentication overrides from the FastAPI app.
+
+    Call this after your tests to restore normal authentication behavior.
+
+    Args:
+        app: The FastAPI app to clean up
+    """
+    # Get all auth dependencies
+    auth_deps = [
+        get_current_user,
+        get_optional_current_user,
+        OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login"),
+    ]
+
+    # Remove overrides
+    for dep in auth_deps:
+        if dep in app.dependency_overrides:
+            del app.dependency_overrides[dep]

backend/app/utils/device.py

@@ -0,0 +1,242 @@
+"""
+Utility functions for extracting and parsing device information from HTTP requests.
+"""
+
+import re
+
+from fastapi import Request
+
+from app.schemas.sessions import DeviceInfo
+
+
+def extract_device_info(request: Request) -> DeviceInfo:
+    """
+    Extract device information from the HTTP request.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        DeviceInfo object with parsed device information
+    """
+    user_agent = request.headers.get("user-agent", "")
+
+    device_info = DeviceInfo(
+        device_name=parse_device_name(user_agent),
+        device_id=request.headers.get("x-device-id"),  # Client must send this header
+        ip_address=get_client_ip(request),
+        user_agent=user_agent[:500] if user_agent else None,  # Truncate to max length
+        location_city=None,  # Can be populated via IP geolocation service
+        location_country=None,  # Can be populated via IP geolocation service
+    )
+
+    return device_info
+
+
+def parse_device_name(user_agent: str) -> str | None:
+    """
+    Parse user agent string to extract a friendly device name.
+
+    Args:
+        user_agent: User-Agent header string
+
+    Returns:
+        Friendly device name string or None
+
+    Examples:
+        "Mozilla/5.0 (iPhone; CPU iPhone OS 15_0 like Mac OS X)" -> "iPhone"
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" -> "Mac"
+        "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" -> "Windows PC"
+    """
+    if not user_agent:
+        return "Unknown device"
+
+    user_agent_lower = user_agent.lower()
+
+    # Mobile devices (check first, as they can contain desktop patterns too)
+    if "iphone" in user_agent_lower:
+        return "iPhone"
+    elif "ipad" in user_agent_lower:
+        return "iPad"
+    elif "android" in user_agent_lower:
+        # Try to extract device model
+        android_match = re.search(r"android.*;\s*([^)]+)\s*build", user_agent_lower)
+        if android_match:
+            device_model = android_match.group(1).strip()
+            return f"Android ({device_model.title()})"
+        return "Android device"
+    elif "windows phone" in user_agent_lower:
+        return "Windows Phone"
+
+    # Tablets (check before desktop, as some tablets contain "android")
+    elif "tablet" in user_agent_lower:
+        return "Tablet"
+
+    # Smart TVs (check before desktop OS patterns)
+    elif any(tv in user_agent_lower for tv in ["smart-tv", "smarttv"]):
+        return "Smart TV"
+
+    # Game consoles (check before desktop OS patterns, as Xbox contains "Windows")
+    elif "playstation" in user_agent_lower:
+        return "PlayStation"
+    elif "xbox" in user_agent_lower:
+        return "Xbox"
+    elif "nintendo" in user_agent_lower:
+        return "Nintendo"
+
+    # Desktop operating systems
+    elif "macintosh" in user_agent_lower or "mac os x" in user_agent_lower:
+        # Try to extract browser
+        browser = extract_browser(user_agent)
+        return f"{browser} on Mac" if browser else "Mac"
+    elif "windows" in user_agent_lower:
+        browser = extract_browser(user_agent)
+        return f"{browser} on Windows" if browser else "Windows PC"
+    elif "linux" in user_agent_lower and "android" not in user_agent_lower:
+        browser = extract_browser(user_agent)
+        return f"{browser} on Linux" if browser else "Linux"
+    elif "cros" in user_agent_lower:
+        return "Chromebook"
+
+    # Fallback: just return browser name if detected
+    browser = extract_browser(user_agent)
+    if browser:
+        return browser
+
+    return "Unknown device"
+
+
+def extract_browser(user_agent: str) -> str | None:
+    """
+    Extract browser name from user agent string.
+
+    Args:
+        user_agent: User-Agent header string
+
+    Returns:
+        Browser name or None
+
+    Examples:
+        "Mozilla/5.0 ... Chrome/96.0" -> "Chrome"
+        "Mozilla/5.0 ... Firefox/94.0" -> "Firefox"
+    """
+    if not user_agent:
+        return None
+
+    user_agent_lower = user_agent.lower()
+
+    # Check specific browsers (order matters - check Edge before Chrome!)
+    if "edg/" in user_agent_lower or "edge/" in user_agent_lower:
+        return "Edge"
+    elif "opr/" in user_agent_lower or "opera" in user_agent_lower:
+        return "Opera"
+    elif "chrome/" in user_agent_lower:
+        return "Chrome"
+    elif "safari/" in user_agent_lower:
+        # Make sure it's actually Safari, not Chrome (which also contains "Safari")
+        if "chrome" not in user_agent_lower:
+            return "Safari"
+        return None
+    elif "firefox/" in user_agent_lower:
+        return "Firefox"
+    elif "msie" in user_agent_lower or "trident/" in user_agent_lower:
+        return "Internet Explorer"
+
+    return None
+
+
+def get_client_ip(request: Request) -> str | None:
+    """
+    Extract client IP address from request, considering proxy headers.
+
+    Checks X-Forwarded-For and X-Real-IP headers for proxy scenarios.
+
+    Args:
+        request: FastAPI Request object
+
+    Returns:
+        Client IP address string or None
+
+    Notes:
+        - In production behind a proxy/load balancer, X-Forwarded-For is often set
+        - The first IP in X-Forwarded-For is typically the real client IP
+        - request.client.host is fallback for direct connections
+    """
+    # Check X-Forwarded-For (common in proxied environments)
+    x_forwarded_for = request.headers.get("x-forwarded-for")
+    if x_forwarded_for:
+        # Get the first IP (original client)
+        client_ip = x_forwarded_for.split(",")[0].strip()
+        return client_ip
+
+    # Check X-Real-IP (used by some proxies like nginx)
+    x_real_ip = request.headers.get("x-real-ip")
+    if x_real_ip:
+        return x_real_ip.strip()
+
+    # Fallback to direct connection IP
+    if request.client and request.client.host:
+        return request.client.host
+
+    return None
+
+
+def is_mobile_device(user_agent: str) -> bool:
+    """
+    Check if the device is a mobile device based on user agent.
+
+    Args:
+        user_agent: User-Agent header string
+
+    Returns:
+        True if mobile device, False otherwise
+    """
+    if not user_agent:
+        return False
+
+    mobile_patterns = [
+        "mobile",
+        "android",
+        "iphone",
+        "ipad",
+        "ipod",
+        "blackberry",
+        "windows phone",
+        "webos",
+        "opera mini",
+        "iemobile",
+        "mobile safari",
+    ]
+
+    user_agent_lower = user_agent.lower()
+    return any(pattern in user_agent_lower for pattern in mobile_patterns)
+
+
+def get_device_type(user_agent: str) -> str:
+    """
+    Determine the general device type.
+
+    Args:
+        user_agent: User-Agent header string
+
+    Returns:
+        Device type: "mobile", "tablet", "desktop", or "other"
+    """
+    if not user_agent:
+        return "other"
+
+    user_agent_lower = user_agent.lower()
+
+    # Check for tablets first (they can contain "mobile" too)
+    if "ipad" in user_agent_lower or "tablet" in user_agent_lower:
+        return "tablet"
+
+    # Check for mobile
+    if is_mobile_device(user_agent):
+        return "mobile"
+
+    # Check for desktop OS patterns
+    if any(os in user_agent_lower for os in ["windows", "macintosh", "linux", "cros"]):
+        return "desktop"
+
+    return "other"

backend/app/utils/security.py

@@ -0,0 +1,294 @@
+"""
+Security utilities for token-based operations.
+
+This module provides utilities for creating and verifying signed tokens,
+useful for operations like file uploads, password resets, or any other
+time-limited, single-use operations.
+"""
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+from typing import Any
+
+from app.core.config import settings
+
+
+def create_upload_token(
+    file_path: str, content_type: str, expires_in: int = 300
+) -> str:
+    """
+    Create a signed token for secure file uploads.
+
+    This generates a time-limited, single-use token that can be verified
+    to ensure the upload is authorized.
+
+    Args:
+        file_path: The destination path for the file
+        content_type: The expected content type (e.g., "image/jpeg")
+        expires_in: Expiration time in seconds (default: 300 = 5 minutes)
+
+    Returns:
+        A base64 encoded token string
+
+    Example:
+        >>> token = create_upload_token("/uploads/avatar.jpg", "image/jpeg")
+        >>> # Send token to client, client includes it in upload request
+    """
+    # Create the payload
+    payload = {
+        "path": file_path,
+        "content_type": content_type,
+        "exp": int(time.time()) + expires_in,
+        "nonce": secrets.token_hex(8),  # Add randomness to prevent token reuse
+    }
+
+    # Convert to JSON and encode
+    payload_bytes = json.dumps(payload).encode("utf-8")
+
+    # Create a signature using HMAC-SHA256 for security
+    # This prevents length extension attacks that plain SHA-256 is vulnerable to
+    signature = hmac.new(
+        settings.SECRET_KEY.encode("utf-8"), payload_bytes, hashlib.sha256
+    ).hexdigest()
+
+    # Combine payload and signature
+    token_data = {"payload": payload, "signature": signature}
+
+    # Encode the final token
+    token_json = json.dumps(token_data)
+    token = base64.urlsafe_b64encode(token_json.encode("utf-8")).decode("utf-8")
+
+    return token
+
+
+def verify_upload_token(token: str) -> dict[str, Any] | None:
+    """
+    Verify an upload token and return the payload if valid.
+
+    Args:
+        token: The token string to verify
+
+    Returns:
+        The payload dictionary if valid, None if invalid or expired
+
+    Example:
+        >>> payload = verify_upload_token(token_from_client)
+        >>> if payload:
+        ...     file_path = payload["path"]
+        ...     content_type = payload["content_type"]
+        ...     # Proceed with upload
+        ... else:
+        ...     # Token invalid or expired
+    """
+    try:
+        # Decode the token
+        token_json = base64.urlsafe_b64decode(token.encode("utf-8")).decode("utf-8")
+        token_data = json.loads(token_json)
+
+        # Extract payload and signature
+        payload = token_data["payload"]
+        signature = token_data["signature"]
+
+        # Verify signature using HMAC and constant-time comparison
+        payload_bytes = json.dumps(payload).encode("utf-8")
+        expected_signature = hmac.new(
+            settings.SECRET_KEY.encode("utf-8"), payload_bytes, hashlib.sha256
+        ).hexdigest()
+
+        if not hmac.compare_digest(signature, expected_signature):
+            return None
+
+        # Check expiration
+        if payload["exp"] < int(time.time()):
+            return None
+
+        return payload
+
+    except (ValueError, KeyError, json.JSONDecodeError):
+        return None
+
+
+def create_password_reset_token(email: str, expires_in: int = 3600) -> str:
+    """
+    Create a signed token for password reset.
+
+    Args:
+        email: User's email address
+        expires_in: Expiration time in seconds (default: 3600 = 1 hour)
+
+    Returns:
+        A base64 encoded token string
+
+    Example:
+        >>> token = create_password_reset_token("user@example.com")
+        >>> # Send token to user via email
+    """
+    # Create the payload
+    payload = {
+        "email": email,
+        "exp": int(time.time()) + expires_in,
+        "nonce": secrets.token_hex(16),  # Extra randomness
+        "purpose": "password_reset",
+    }
+
+    # Convert to JSON and encode
+    payload_bytes = json.dumps(payload).encode("utf-8")
+
+    # Create a signature using HMAC-SHA256 for security
+    # This prevents length extension attacks that plain SHA-256 is vulnerable to
+    signature = hmac.new(
+        settings.SECRET_KEY.encode("utf-8"), payload_bytes, hashlib.sha256
+    ).hexdigest()
+
+    # Combine payload and signature
+    token_data = {"payload": payload, "signature": signature}
+
+    # Encode the final token
+    token_json = json.dumps(token_data)
+    token = base64.urlsafe_b64encode(token_json.encode("utf-8")).decode("utf-8")
+
+    return token
+
+
+def verify_password_reset_token(token: str) -> str | None:
+    """
+    Verify a password reset token and return the email if valid.
+
+    Args:
+        token: The token string to verify
+
+    Returns:
+        The email address if valid, None if invalid or expired
+
+    Example:
+        >>> email = verify_password_reset_token(token_from_user)
+        >>> if email:
+        ...     # Proceed with password reset
+        ... else:
+        ...     # Token invalid or expired
+    """
+    try:
+        # Decode the token
+        token_json = base64.urlsafe_b64decode(token.encode("utf-8")).decode("utf-8")
+        token_data = json.loads(token_json)
+
+        # Extract payload and signature
+        payload = token_data["payload"]
+        signature = token_data["signature"]
+
+        # Verify it's a password reset token
+        if payload.get("purpose") != "password_reset":
+            return None
+
+        # Verify signature using HMAC and constant-time comparison
+        payload_bytes = json.dumps(payload).encode("utf-8")
+        expected_signature = hmac.new(
+            settings.SECRET_KEY.encode("utf-8"), payload_bytes, hashlib.sha256
+        ).hexdigest()
+
+        if not hmac.compare_digest(signature, expected_signature):
+            return None
+
+        # Check expiration
+        if payload["exp"] < int(time.time()):
+            return None
+
+        return payload["email"]
+
+    except (ValueError, KeyError, json.JSONDecodeError):
+        return None
+
+
+def create_email_verification_token(email: str, expires_in: int = 86400) -> str:
+    """
+    Create a signed token for email verification.
+
+    Args:
+        email: User's email address
+        expires_in: Expiration time in seconds (default: 86400 = 24 hours)
+
+    Returns:
+        A base64 encoded token string
+
+    Example:
+        >>> token = create_email_verification_token("user@example.com")
+        >>> # Send token to user via email
+    """
+    # Create the payload
+    payload = {
+        "email": email,
+        "exp": int(time.time()) + expires_in,
+        "nonce": secrets.token_hex(16),
+        "purpose": "email_verification",
+    }
+
+    # Convert to JSON and encode
+    payload_bytes = json.dumps(payload).encode("utf-8")
+
+    # Create a signature using HMAC-SHA256 for security
+    # This prevents length extension attacks that plain SHA-256 is vulnerable to
+    signature = hmac.new(
+        settings.SECRET_KEY.encode("utf-8"), payload_bytes, hashlib.sha256
+    ).hexdigest()
+
+    # Combine payload and signature
+    token_data = {"payload": payload, "signature": signature}
+
+    # Encode the final token
+    token_json = json.dumps(token_data)
+    token = base64.urlsafe_b64encode(token_json.encode("utf-8")).decode("utf-8")
+
+    return token
+
+
+def verify_email_verification_token(token: str) -> str | None:
+    """
+    Verify an email verification token and return the email if valid.
+
+    Args:
+        token: The token string to verify
+
+    Returns:
+        The email address if valid, None if invalid or expired
+
+    Example:
+        >>> email = verify_email_verification_token(token_from_user)
+        >>> if email:
+        ...     # Mark email as verified
+        ... else:
+        ...     # Token invalid or expired
+    """
+    try:
+        # Decode the token
+        token_json = base64.urlsafe_b64decode(token.encode("utf-8")).decode("utf-8")
+        token_data = json.loads(token_json)
+
+        # Extract payload and signature
+        payload = token_data["payload"]
+        signature = token_data["signature"]
+
+        # Verify it's an email verification token
+        if payload.get("purpose") != "email_verification":
+            return None
+
+        # Verify signature using HMAC and constant-time comparison
+        payload_bytes = json.dumps(payload).encode("utf-8")
+        expected_signature = hmac.new(
+            settings.SECRET_KEY.encode("utf-8"), payload_bytes, hashlib.sha256
+        ).hexdigest()
+
+        if not hmac.compare_digest(signature, expected_signature):
+            return None
+
+        # Check expiration
+        if payload["exp"] < int(time.time()):
+            return None
+
+        return payload["email"]
+
+    except (ValueError, KeyError, json.JSONDecodeError):
+        return None

backend/app/utils/test_utils.py

@@ -1,24 +1,27 @@
 import logging
-from sqlalchemy import create_engine, event
+
+from sqlalchemy import create_engine
 from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
-from sqlalchemy.orm import sessionmaker, clear_mappers
+from sqlalchemy.orm import sessionmaker
 from sqlalchemy.pool import StaticPool
 
 from app.core.database import Base
 
 logger = logging.getLogger(__name__)
 
+
 def get_test_engine():
     """Create an SQLite in-memory engine specifically for testing"""
     test_engine = create_engine(
         "sqlite:///:memory:",
         connect_args={"check_same_thread": False},
         poolclass=StaticPool,  # Use static pool for in-memory testing
-        echo=False
+        echo=False,
     )
 
     return test_engine
 
+
 def setup_test_db():
     """Create a test database and session factory"""
     # Create a new engine for this test run
@@ -29,14 +32,12 @@ def setup_test_db():
 
     # Create session factory
     TestingSessionLocal = sessionmaker(
-        autocommit=False,
+        autocommit=False, autoflush=False, bind=test_engine, expire_on_commit=False
-        autoflush=False,
-        bind=test_engine,
-        expire_on_commit=False
     )
 
     return test_engine, TestingSessionLocal
 
+
 def teardown_test_db(engine):
     """Clean up after tests"""
     # Drop all tables
@@ -45,13 +46,14 @@ def teardown_test_db(engine):
     # Dispose of engine
     engine.dispose()
 
+
 async def get_async_test_engine():
     """Create an async SQLite in-memory engine specifically for testing"""
     test_engine = create_async_engine(
         "sqlite+aiosqlite:///:memory:",
         connect_args={"check_same_thread": False},
         poolclass=StaticPool,  # Use static pool for in-memory testing
-        echo=False
+        echo=False,
     )
     return test_engine
 
@@ -63,12 +65,12 @@ async def setup_async_test_db():
     async with test_engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
 
-    AsyncTestingSessionLocal = sessionmaker(
+    AsyncTestingSessionLocal = sessionmaker(  # pyright: ignore[reportCallIssue]
         autocommit=False,
         autoflush=False,
-        bind=test_engine,
+        bind=test_engine,  # pyright: ignore[reportArgumentType]
         expire_on_commit=False,
-        class_=AsyncSession
+        class_=AsyncSession,
     )
 
     return test_engine, AsyncTestingSessionLocal

backend/docs/BENCHMARKS.md

@@ -0,0 +1,311 @@
+# Performance Benchmarks Guide
+
+Automated performance benchmarking infrastructure using **pytest-benchmark** to detect latency regressions in critical API endpoints.
+
+## Table of Contents
+
+- [Why Benchmark?](#why-benchmark)
+- [Quick Start](#quick-start)
+- [How It Works](#how-it-works)
+- [Understanding Results](#understanding-results)
+- [Test Organization](#test-organization)
+- [Writing Benchmark Tests](#writing-benchmark-tests)
+- [Baseline Management](#baseline-management)
+- [CI/CD Integration](#cicd-integration)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Why Benchmark?
+
+Performance regressions are silent bugs — they don't break tests or cause errors, but they degrade the user experience over time. Common causes include:
+
+- **Unintended N+1 queries** after adding a relationship
+- **Heavier serialization** after adding new fields to a response model
+- **Middleware overhead** from new security headers or logging
+- **Dependency upgrades** that introduce slower code paths
+
+Without automated benchmarks, these regressions go unnoticed until users complain. Performance benchmarks serve as an **early warning system** — they measure endpoint latency on every run and flag significant deviations from an established baseline.
+
+### What benchmarks give you
+
+| Benefit | Description |
+|---------|-------------|
+| **Regression detection** | Automatically flags when an endpoint becomes significantly slower |
+| **Baseline tracking** | Stores known-good performance numbers for comparison |
+| **Confidence in refactors** | Verify that code changes don't degrade response times |
+| **Visibility** | Makes performance a first-class, measurable quality attribute |
+
+---
+
+## Quick Start
+
+```bash
+# Run benchmarks (no comparison, just see current numbers)
+make benchmark
+
+# Save current results as the baseline
+make benchmark-save
+
+# Run benchmarks and compare against the saved baseline
+make benchmark-check
+```
+
+---
+
+## How It Works
+
+The benchmarking system has three layers:
+
+### 1. pytest-benchmark integration
+
+[pytest-benchmark](https://pytest-benchmark.readthedocs.io/) is a pytest plugin that provides a `benchmark` fixture. It handles:
+
+- **Calibration**: Automatically determines how many iterations to run for statistical significance
+- **Timing**: Uses `time.perf_counter` for high-resolution measurements
+- **Statistics**: Computes min, max, mean, median, standard deviation, IQR, and outlier detection
+- **Comparison**: Compares current results against saved baselines and flags regressions
+
+### 2. Benchmark types
+
+The test suite includes two categories of performance tests:
+
+| Type | How it works | Examples |
+|------|-------------|----------|
+| **pytest-benchmark tests** | Uses the `benchmark` fixture for precise, multi-round timing | `test_health_endpoint_performance`, `test_openapi_schema_performance`, `test_password_hashing_performance`, `test_password_verification_performance`, `test_access_token_creation_performance`, `test_refresh_token_creation_performance`, `test_token_decode_performance` |
+| **Manual latency tests** | Uses `time.perf_counter` with explicit thresholds (for async endpoints that pytest-benchmark doesn't support natively) | `test_login_latency`, `test_get_current_user_latency`, `test_register_latency`, `test_token_refresh_latency`, `test_sessions_list_latency`, `test_user_profile_update_latency` |
+
+### 3. Regression detection
+
+When running `make benchmark-check`, the system:
+
+1. Runs all benchmark tests
+2. Compares results against the saved baseline (`.benchmarks/` directory)
+3. **Fails the build** if any test's mean time exceeds **200%** of the baseline (i.e., 3× slower)
+
+The `200%` threshold in `--benchmark-compare-fail=mean:200%` means "fail if the mean increased by more than 200% relative to the baseline." This is deliberately generous to avoid false positives from normal run-to-run variance while still catching real regressions.
+
+---
+
+## Understanding Results
+
+A typical benchmark output looks like this:
+
+```
+--------------------------------------------------------------------------------------- benchmark: 2 tests --------------------------------------------------------------------------------------
+Name (time in ms)                       Min               Max              Mean            StdDev            Median               IQR            Outliers       OPS            Rounds  Iterations
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+test_health_endpoint_performance     0.9841 (1.0)      1.5513 (1.0)      1.1390 (1.0)      0.1098 (1.0)      1.1151 (1.0)      0.1672 (1.0)          39;2  877.9666 (1.0)         133           1
+test_openapi_schema_performance      1.6523 (1.68)     2.0892 (1.35)     1.7843 (1.57)     0.1553 (1.41)     1.7200 (1.54)     0.1727 (1.03)          2;0  560.4471 (0.64)         10           1
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+```
+
+### Column reference
+
+| Column | Meaning |
+|--------|---------|
+| **Min** | Fastest single execution |
+| **Max** | Slowest single execution |
+| **Mean** | Average across all rounds — the primary metric for regression detection |
+| **StdDev** | How much results vary between rounds (lower = more stable) |
+| **Median** | Middle value, less sensitive to outliers than mean |
+| **IQR** | Interquartile range — spread of the middle 50% of results |
+| **Outliers** | Format `A;B` — A = within 1 StdDev, B = within 1.5 IQR from quartiles |
+| **OPS** | Operations per second (`1 / Mean`) |
+| **Rounds** | How many times the test was executed (auto-calibrated) |
+| **Iterations** | Iterations per round (usually 1 for ms-scale tests) |
+
+### The ratio numbers `(1.0)`, `(1.68)`, etc.
+
+These show how each test compares **to the best result in that column**. The fastest test is always `(1.0)`, and others show their relative factor. For example, `(1.68)` means "1.68× slower than the fastest."
+
+### Color coding
+
+- **Green**: The fastest (best) value in each column
+- **Red**: The slowest (worst) value in each column
+
+This is a **relative ranking within the current run** — red does NOT mean the test failed or that performance is bad. It simply highlights which endpoint is the slower one in the group.
+
+### What's "normal"?
+
+For this project's current endpoints:
+
+| Test | Expected range | Why |
+|------|---------------|-----|
+| `GET /health` | ~1–1.5ms | Minimal logic, mocked DB check |
+| `GET /api/v1/openapi.json` | ~1.5–2.5ms | Serializes entire API schema |
+| `get_password_hash` | ~200ms | CPU-bound bcrypt hashing |
+| `verify_password` | ~200ms | CPU-bound bcrypt verification |
+| `create_access_token` | ~17–20µs | JWT encoding with HMAC-SHA256 |
+| `create_refresh_token` | ~17–20µs | JWT encoding with HMAC-SHA256 |
+| `decode_token` | ~20–25µs | JWT decoding and claim validation |
+| `POST /api/v1/auth/login` | < 500ms threshold | Includes bcrypt password verification |
+| `POST /api/v1/auth/register` | < 500ms threshold | Includes bcrypt password hashing |
+| `POST /api/v1/auth/refresh` | < 200ms threshold | Token rotation + DB session update |
+| `GET /api/v1/users/me` | < 200ms threshold | DB lookup + token validation |
+| `GET /api/v1/sessions/me` | < 200ms threshold | Session list query + token validation |
+| `PATCH /api/v1/users/me` | < 200ms threshold | DB update + token validation |
+
+---
+
+## Test Organization
+
+```
+backend/tests/
+├── benchmarks/
+│   └── test_endpoint_performance.py   # All performance benchmark tests
+│
+backend/.benchmarks/                    # Saved baselines (auto-generated)
+└── Linux-CPython-3.12-64bit/
+    └── 0001_baseline.json             # Platform-specific baseline file
+```
+
+### Test markers
+
+All benchmark tests use the `@pytest.mark.benchmark` marker. The `--benchmark-only` flag ensures that only tests using the `benchmark` fixture are executed during benchmark runs, while manual latency tests (async) are skipped.
+
+---
+
+## Writing Benchmark Tests
+
+### Stateless endpoint (using pytest-benchmark fixture)
+
+```python
+import pytest
+from fastapi.testclient import TestClient
+
+def test_my_endpoint_performance(sync_client, benchmark):
+    """Benchmark: GET /my-endpoint should respond within acceptable latency."""
+    result = benchmark(sync_client.get, "/my-endpoint")
+    assert result.status_code == 200
+```
+
+The `benchmark` fixture handles all timing, calibration, and statistics automatically. Just pass it the callable and arguments.
+
+### Async / DB-dependent endpoint (manual timing)
+
+For async endpoints that require database access, use manual timing with an explicit threshold:
+
+```python
+import time
+import pytest
+
+MAX_RESPONSE_MS = 300
+
+@pytest.mark.asyncio
+async def test_my_async_endpoint_latency(client, setup_fixture):
+    """Performance: endpoint must respond under threshold."""
+    iterations = 5
+    total_ms = 0.0
+
+    for _ in range(iterations):
+        start = time.perf_counter()
+        response = await client.get("/api/v1/my-endpoint")
+        elapsed_ms = (time.perf_counter() - start) * 1000
+        total_ms += elapsed_ms
+        assert response.status_code == 200
+
+    mean_ms = total_ms / iterations
+    assert mean_ms < MAX_RESPONSE_MS, (
+        f"Latency regression: {mean_ms:.1f}ms exceeds {MAX_RESPONSE_MS}ms threshold"
+    )
+```
+
+### Guidelines for new benchmarks
+
+1. **Benchmark critical paths** — endpoints users hit frequently or where latency matters most
+2. **Mock external dependencies** for stateless tests to isolate endpoint overhead
+3. **Set generous thresholds** for manual tests — account for CI variability
+4. **Keep benchmarks fast** — they run on every check, so avoid heavy setup
+
+---
+
+## Baseline Management
+
+### Saving a baseline
+
+```bash
+make benchmark-save
+```
+
+This runs all benchmarks and saves results to `.benchmarks/<platform>/0001_baseline.json`. The baseline captures:
+- Mean, min, max, median, stddev for each test
+- Machine info (CPU, OS, Python version)
+- Timestamp
+
+### Comparing against baseline
+
+```bash
+make benchmark-check
+```
+
+If no baseline exists, this command automatically creates one and prints a warning. On subsequent runs, it compares current results against the saved baseline.
+
+### When to update the baseline
+
+- **After intentional performance changes** (e.g., you optimized an endpoint — save the new, faster baseline)
+- **After infrastructure changes** (e.g., new CI runner, different hardware)
+- **After adding new benchmark tests** (the new tests need a baseline entry)
+
+```bash
+# Update the baseline after intentional changes
+make benchmark-save
+```
+
+### Version control
+
+The `.benchmarks/` directory can be committed to version control so that CI pipelines can compare against a known-good baseline. However, since benchmark results are machine-specific, you may prefer to generate baselines in CI rather than committing local results.
+
+---
+
+## CI/CD Integration
+
+Add benchmark checking to your CI pipeline to catch regressions on every PR:
+
+```yaml
+# Example GitHub Actions step
+- name: Performance regression check
+  run: |
+    cd backend
+    make benchmark-save   # Create baseline from main branch
+    # ... apply PR changes ...
+    make benchmark-check  # Compare PR against baseline
+```
+
+A more robust approach:
+1. Save the baseline on the `main` branch after each merge
+2. On PR branches, run `make benchmark-check` against the `main` baseline
+3. The pipeline fails if any endpoint regresses beyond the 200% threshold
+
+---
+
+## Troubleshooting
+
+### "No benchmark baseline found" warning
+
+```
+⚠️  No benchmark baseline found. Run 'make benchmark-save' first to create one.
+```
+
+This means no baseline file exists yet. The command will auto-create one. Future runs of `make benchmark-check` will compare against it.
+
+### Machine info mismatch warning
+
+```
+WARNING: benchmark machine_info is different
+```
+
+This is expected when comparing baselines generated on a different machine or OS. The comparison still works, but absolute numbers may differ. Re-save the baseline on the current machine if needed.
+
+### High variance (large StdDev)
+
+If StdDev is high relative to the Mean, results may be unreliable. Common causes:
+- System under load during benchmark run
+- Garbage collection interference
+- Thermal throttling
+
+Try running benchmarks on an idle system or increasing `min_rounds` in `pyproject.toml`.
+
+### Only 7 of 13 tests run
+
+The async tests (`test_login_latency`, `test_get_current_user_latency`, `test_register_latency`, `test_token_refresh_latency`, `test_sessions_list_latency`, `test_user_profile_update_latency`) are skipped during `--benchmark-only` runs because they don't use the `benchmark` fixture. They run as part of the normal test suite (`make test`) with manual threshold assertions.

backend/docs/COMMON_PITFALLS.md

@@ -0,0 +1,736 @@
+# Common Pitfalls & How to Avoid Them
+
+> **Purpose**: This document catalogs common mistakes encountered during implementation and provides explicit rules to prevent them. **Read this before writing any code.**
+
+## Table of Contents
+
+- [SQLAlchemy & Database](#sqlalchemy--database)
+- [Pydantic & Validation](#pydantic--validation)
+- [FastAPI & API Design](#fastapi--api-design)
+- [Security & Authentication](#security--authentication)
+- [Python Language Gotchas](#python-language-gotchas)
+
+---
+
+## SQLAlchemy & Database
+
+### ❌ PITFALL #1: Using Mutable Defaults in Columns
+
+**Issue**: Using `default={}` or `default=[]` creates shared state across all instances.
+
+```python
+# ❌ WRONG - All instances share the same dict!
+class User(Base):
+    metadata = Column(JSON, default={})  # DANGER: Mutable default!
+    tags = Column(JSON, default=[])     # DANGER: Shared list!
+```
+
+```python
+# ✅ CORRECT - Use callable factory
+class User(Base):
+    metadata = Column(JSON, default=dict)  # New dict per instance
+    tags = Column(JSON, default=list)      # New list per instance
+```
+
+**Rule**: Always use `default=dict` or `default=list` (without parentheses), never `default={}` or `default=[]`.
+
+---
+
+### ❌ PITFALL #2: Forgetting to Index Foreign Keys
+
+**Issue**: Foreign key columns without indexes cause slow JOIN operations.
+
+```python
+# ❌ WRONG - No index on foreign key
+class UserSession(Base):
+    user_id = Column(UUID, ForeignKey('users.id'), nullable=False)
+```
+
+```python
+# ✅ CORRECT - Always index foreign keys
+class UserSession(Base):
+    user_id = Column(UUID, ForeignKey('users.id'), nullable=False, index=True)
+```
+
+**Rule**: ALWAYS add `index=True` to foreign key columns. SQLAlchemy doesn't do this automatically.
+
+---
+
+### ❌ PITFALL #3: Missing Composite Indexes
+
+**Issue**: Queries filtering by multiple columns cannot use single-column indexes efficiently.
+
+```python
+# ❌ MISSING - Slow query on (user_id, is_active)
+class UserSession(Base):
+    user_id = Column(UUID, ForeignKey('users.id'), index=True)
+    is_active = Column(Boolean, default=True, index=True)
+    # Query: WHERE user_id=X AND is_active=TRUE uses only one index!
+```
+
+```python
+# ✅ CORRECT - Composite index for common query pattern
+class UserSession(Base):
+    user_id = Column(UUID, ForeignKey('users.id'), index=True)
+    is_active = Column(Boolean, default=True, index=True)
+
+    __table_args__ = (
+        Index('ix_user_sessions_user_active', 'user_id', 'is_active'),
+    )
+```
+
+**Rule**: Add composite indexes for commonly used multi-column filters. Review query patterns and create indexes accordingly.
+
+**Performance Impact**: Can reduce query time from seconds to milliseconds for large tables.
+
+---
+
+### ❌ PITFALL #4: Not Using Soft Deletes
+
+**Issue**: Hard deletes destroy data and audit trails permanently.
+
+```python
+# ❌ RISKY - Permanent data loss
+def delete_user(user_id: UUID):
+    user = db.query(User).filter(User.id == user_id).first()
+    db.delete(user)  # Data gone forever!
+    db.commit()
+```
+
+```python
+# ✅ CORRECT - Soft delete with audit trail
+class User(Base):
+    deleted_at = Column(DateTime(timezone=True), nullable=True)
+
+def soft_delete_user(user_id: UUID):
+    user = db.query(User).filter(User.id == user_id).first()
+    user.deleted_at = datetime.now(timezone.utc)
+    db.commit()
+```
+
+**Rule**: For user data, ALWAYS use soft deletes. Add `deleted_at` column and filter queries with `.filter(deleted_at.is_(None))`.
+
+---
+
+### ❌ PITFALL #5: Missing Query Ordering
+
+**Issue**: Queries without `ORDER BY` return unpredictable results, breaking pagination.
+
+```python
+# ❌ WRONG - Random order, pagination broken
+def get_users(skip: int, limit: int):
+    return db.query(User).offset(skip).limit(limit).all()
+```
+
+```python
+# ✅ CORRECT - Stable ordering for consistent pagination
+def get_users(skip: int, limit: int):
+    return (
+        db.query(User)
+        .filter(User.deleted_at.is_(None))
+        .order_by(User.created_at.desc())  # Consistent order
+        .offset(skip)
+        .limit(limit)
+        .all()
+    )
+```
+
+**Rule**: ALWAYS add `.order_by()` to paginated queries. Default to `created_at.desc()` for newest-first.
+
+---
+
+## Pydantic & Validation
+
+### ❌ PITFALL #6: Missing Size Validation on JSON Fields
+
+**Issue**: Unbounded JSON fields enable DoS attacks through deeply nested objects.
+
+```python
+# ❌ WRONG - No size limit (JSON bomb vulnerability)
+class UserCreate(BaseModel):
+    metadata: dict[str, Any]  # No limit!
+```
+
+```python
+# ✅ CORRECT - Validate serialized size
+import json
+from pydantic import field_validator
+
+class UserCreate(BaseModel):
+    metadata: dict[str, Any]
+
+    @field_validator("metadata")
+    @classmethod
+    def validate_metadata_size(cls, v: dict[str, Any]) -> dict[str, Any]:
+        metadata_json = json.dumps(v, separators=(",", ":"))
+        max_size = 10_000  # 10KB limit
+
+        if len(metadata_json) > max_size:
+            raise ValueError(f"Metadata exceeds {max_size} bytes")
+
+        return v
+```
+
+**Rule**: ALWAYS validate the serialized size of dict/JSON fields. Typical limits:
+- User metadata: 10KB
+- Configuration: 100KB
+- Never exceed 1MB
+
+**Security Impact**: Prevents DoS attacks via deeply nested JSON objects.
+
+---
+
+### ❌ PITFALL #7: Missing max_length on String Fields
+
+**Issue**: Unbounded text fields enable memory exhaustion attacks and database errors.
+
+```python
+# ❌ WRONG - No length limit
+class UserCreate(BaseModel):
+    email: str
+    name: str
+    bio: str | None = None
+```
+
+```python
+# ✅ CORRECT - Explicit length limits matching database
+class UserCreate(BaseModel):
+    email: str = Field(..., max_length=255)
+    name: str = Field(..., min_length=1, max_length=100)
+    bio: str | None = Field(None, max_length=500)
+```
+
+**Rule**: Add `max_length` to ALL string fields. Limits should match database column definitions:
+- Emails: 255 characters
+- Names/titles: 100-255 characters
+- Descriptions/bios: 500-1000 characters
+- Error messages: 5000 characters
+
+---
+
+### ❌ PITFALL #8: Inconsistent Validation Between Create and Update
+
+**Issue**: Adding validators to Create schema but not Update schema.
+
+```python
+# ❌ INCOMPLETE - Only validates on create
+class UserCreate(BaseModel):
+    email: str = Field(..., max_length=255)
+
+    @field_validator("email")
+    @classmethod
+    def validate_email_format(cls, v: str) -> str:
+        if "@" not in v:
+            raise ValueError("Invalid email format")
+        return v.lower()
+
+class UserUpdate(BaseModel):
+    email: str | None = None  # No validator!
+```
+
+```python
+# ✅ CORRECT - Same validation on both schemas
+class UserCreate(BaseModel):
+    email: str = Field(..., max_length=255)
+
+    @field_validator("email")
+    @classmethod
+    def validate_email_format(cls, v: str) -> str:
+        if "@" not in v:
+            raise ValueError("Invalid email format")
+        return v.lower()
+
+class UserUpdate(BaseModel):
+    email: str | None = Field(None, max_length=255)
+
+    @field_validator("email")
+    @classmethod
+    def validate_email_format(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if "@" not in v:
+            raise ValueError("Invalid email format")
+        return v.lower()
+```
+
+**Rule**: Apply the SAME validators to both Create and Update schemas. Handle `None` values in Update validators.
+
+---
+
+### ❌ PITFALL #9: Not Using Field Descriptions
+
+**Issue**: Missing descriptions make API documentation unclear.
+
+```python
+# ❌ WRONG - No descriptions
+class UserCreate(BaseModel):
+    email: str
+    password: str
+    is_superuser: bool = False
+```
+
+```python
+# ✅ CORRECT - Clear descriptions
+class UserCreate(BaseModel):
+    email: str = Field(
+        ...,
+        description="User's email address (must be unique)",
+        examples=["user@example.com"]
+    )
+    password: str = Field(
+        ...,
+        min_length=8,
+        description="Password (minimum 8 characters)",
+        examples=["SecurePass123!"]
+    )
+    is_superuser: bool = Field(
+        default=False,
+        description="Whether user has superuser privileges"
+    )
+```
+
+**Rule**: Add `description` and `examples` to all fields for automatic OpenAPI documentation.
+
+---
+
+## FastAPI & API Design
+
+### ❌ PITFALL #10: Missing Rate Limiting
+
+**Issue**: No rate limiting allows abuse and DoS attacks.
+
+```python
+# ❌ WRONG - No rate limits
+@router.post("/auth/login")
+def login(credentials: OAuth2PasswordRequestForm):
+    # Anyone can try unlimited passwords!
+    ...
+```
+
+```python
+# ✅ CORRECT - Rate limit sensitive endpoints
+from slowapi import Limiter
+
+limiter = Limiter(key_func=lambda request: request.client.host)
+
+@router.post("/auth/login")
+@limiter.limit("5/minute")  # Only 5 attempts per minute
+def login(request: Request, credentials: OAuth2PasswordRequestForm):
+    ...
+```
+
+**Rule**: Apply rate limits to ALL endpoints:
+- Authentication: 5/minute
+- Write operations: 10-20/minute
+- Read operations: 30-60/minute
+
+---
+
+### ❌ PITFALL #11: Returning Sensitive Data in Responses
+
+**Issue**: Exposing internal fields like passwords, tokens, or internal IDs.
+
+```python
+# ❌ WRONG - Returns password hash!
+@router.get("/users/{user_id}")
+def get_user(user_id: UUID, db: Session = Depends(get_db)) -> User:
+    return user_repo.get(db, id=user_id)  # Returns ORM model with ALL fields!
+```
+
+```python
+# ✅ CORRECT - Use response schema
+@router.get("/users/{user_id}", response_model=UserResponse)
+def get_user(user_id: UUID, db: Session = Depends(get_db)):
+    user = user_repo.get(db, id=user_id)
+    if not user:
+        raise HTTPException(status_code=404, detail="User not found")
+    return user  # Pydantic filters to only UserResponse fields
+
+class UserResponse(BaseModel):
+    """Public user data - NO sensitive fields."""
+    id: UUID
+    email: str
+    is_active: bool
+    created_at: datetime
+    # NO: password, hashed_password, tokens, etc.
+
+    model_config = ConfigDict(from_attributes=True)
+```
+
+**Rule**: ALWAYS use dedicated response schemas. Never return ORM models directly.
+
+---
+
+### ❌ PITFALL #12: Missing Error Response Standardization
+
+**Issue**: Inconsistent error formats confuse API consumers.
+
+```python
+# ❌ WRONG - Different error formats
+@router.get("/users/{user_id}")
+def get_user(user_id: UUID):
+    if not user:
+        raise HTTPException(404, "Not found")  # Format 1
+
+    if not user.is_active:
+        return {"error": "User inactive"}  # Format 2
+
+    try:
+        ...
+    except Exception as e:
+        return {"message": str(e)}  # Format 3
+```
+
+```python
+# ✅ CORRECT - Consistent error format
+class ErrorResponse(BaseModel):
+    success: bool = False
+    errors: list[ErrorDetail]
+
+class ErrorDetail(BaseModel):
+    code: str
+    message: str
+    field: str | None = None
+
+@router.get("/users/{user_id}")
+def get_user(user_id: UUID):
+    if not user:
+        raise NotFoundError(
+            message="User not found",
+            error_code="USER_001"
+        )
+
+# Global exception handler ensures consistent format
+@app.exception_handler(APIException)
+async def api_exception_handler(request: Request, exc: APIException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={
+            "success": False,
+            "errors": [
+                {
+                    "code": exc.error_code,
+                    "message": exc.message,
+                    "field": exc.field
+                }
+            ]
+        }
+    )
+```
+
+**Rule**: Use custom exceptions and global handlers for consistent error responses across all endpoints.
+
+---
+
+## Security & Authentication
+
+### ❌ PITFALL #13: Logging Sensitive Information
+
+**Issue**: Passwords, tokens, and secrets in logs create security vulnerabilities.
+
+```python
+# ❌ WRONG - Logs credentials
+logger.info(f"User {email} logged in with password: {password}")  # NEVER!
+logger.debug(f"JWT token: {access_token}")  # NEVER!
+logger.info(f"Database URL: {settings.database_url}")  # Contains password!
+```
+
+```python
+# ✅ CORRECT - Never log sensitive data
+logger.info(f"User {email} logged in successfully")
+logger.debug("Access token generated")
+logger.info(f"Database connected: {settings.database_url.split('@')[1]}")  # Only host
+```
+
+**Rule**: NEVER log:
+- Passwords (plain or hashed)
+- Tokens (access, refresh, API keys)
+- Full database URLs
+- Credit card numbers
+- Personal data (SSN, passport, etc.)
+
+**Use Pydantic's `SecretStr`** for sensitive config values.
+
+---
+
+### ❌ PITFALL #14: Weak Password Requirements
+
+**Issue**: No password strength requirements allow weak passwords.
+
+```python
+# ❌ WRONG - No validation
+class UserCreate(BaseModel):
+    password: str
+```
+
+```python
+# ✅ CORRECT - Enforce minimum standards
+class UserCreate(BaseModel):
+    password: str = Field(..., min_length=8)
+
+    @field_validator("password")
+    @classmethod
+    def validate_password_strength(cls, v: str) -> str:
+        if len(v) < 8:
+            raise ValueError("Password must be at least 8 characters")
+
+        # For admin/superuser, enforce stronger requirements
+        has_upper = any(c.isupper() for c in v)
+        has_lower = any(c.islower() for c in v)
+        has_digit = any(c.isdigit() for c in v)
+
+        if not (has_upper and has_lower and has_digit):
+            raise ValueError(
+                "Password must contain uppercase, lowercase, and number"
+            )
+
+        return v
+```
+
+**Rule**: Enforce password requirements:
+- Minimum 8 characters
+- Mix of upper/lower case and numbers for sensitive accounts
+- Use bcrypt with appropriate cost factor (12+)
+
+---
+
+### ❌ PITFALL #15: Not Validating Token Ownership
+
+**Issue**: Users can access other users' resources using valid tokens.
+
+```python
+# ❌ WRONG - No ownership check
+@router.delete("/sessions/{session_id}")
+def revoke_session(
+    session_id: UUID,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    session = session_repo.get(db, id=session_id)
+    session_repo.deactivate(db, session_id=session_id)
+    # BUG: User can revoke ANYONE'S session!
+    return {"message": "Session revoked"}
+```
+
+```python
+# ✅ CORRECT - Verify ownership
+@router.delete("/sessions/{session_id}")
+def revoke_session(
+    session_id: UUID,
+    current_user: User = Depends(get_current_user),
+    db: Session = Depends(get_db)
+):
+    session = session_repo.get(db, id=session_id)
+
+    if not session:
+        raise NotFoundError("Session not found")
+
+    # CRITICAL: Check ownership
+    if session.user_id != current_user.id:
+        raise AuthorizationError("You can only revoke your own sessions")
+
+    session_repo.deactivate(db, session_id=session_id)
+    return {"message": "Session revoked"}
+```
+
+**Rule**: ALWAYS verify resource ownership before allowing operations. Check `resource.user_id == current_user.id`.
+
+---
+
+## Python Language Gotchas
+
+### ❌ PITFALL #16: Using is for Value Comparison
+
+**Issue**: `is` checks identity, not equality.
+
+```python
+# ❌ WRONG - Compares object identity
+if user.role is "admin":  # May fail due to string interning
+    grant_access()
+
+if count is 0:  # Never works for integers outside -5 to 256
+    return empty_response
+```
+
+```python
+# ✅ CORRECT - Use == for value comparison
+if user.role == "admin":
+    grant_access()
+
+if count == 0:
+    return empty_response
+```
+
+**Rule**: Use `==` for value comparison. Only use `is` for:
+- `is None` (checking for None)
+- `is True` / `is False` (checking for exact boolean objects)
+
+---
+
+### ❌ PITFALL #17: Mutable Default Arguments
+
+**Issue**: Default mutable arguments are shared across all function calls.
+
+```python
+# ❌ WRONG - list is shared!
+def add_tag(user: User, tags: list = []):
+    tags.append("default")
+    user.tags.extend(tags)
+    # Second call will have ["default", "default"]!
+```
+
+```python
+# ✅ CORRECT - Use None and create new list
+def add_tag(user: User, tags: list | None = None):
+    if tags is None:
+        tags = []
+    tags.append("default")
+    user.tags.extend(tags)
+```
+
+**Rule**: Never use mutable defaults (`[]`, `{}`). Use `None` and create inside function.
+
+---
+
+### ❌ PITFALL #18: Not Using Type Hints
+
+**Issue**: Missing type hints prevent catching bugs at development time.
+
+```python
+# ❌ WRONG - No type hints
+def create_user(email, password, is_active=True):
+    user = User(email=email, password=password, is_active=is_active)
+    db.add(user)
+    return user
+```
+
+```python
+# ✅ CORRECT - Full type hints
+def create_user(
+    email: str,
+    password: str,
+    is_active: bool = True
+) -> User:
+    user = User(email=email, password=password, is_active=is_active)
+    db.add(user)
+    return user
+```
+
+**Rule**: Add type hints to ALL functions. Use `pyright` to enforce type checking (`make type-check`).
+
+---
+
+---
+
+### ❌ PITFALL #19: Importing Repositories Directly in Routes
+
+**Issue**: Routes should never call repositories directly. The layered architecture requires all business operations to go through the service layer.
+
+```python
+# ❌ WRONG - Route bypasses service layer
+from app.repositories.session import session_repo
+
+@router.get("/sessions/me")
+async def list_sessions(
+    current_user: User = Depends(get_current_active_user),
+    db: AsyncSession = Depends(get_db),
+):
+    return await session_repo.get_user_sessions(db, user_id=current_user.id)
+```
+
+```python
+# ✅ CORRECT - Route calls service injected via dependency
+from app.api.dependencies.services import get_session_service
+from app.services.session_service import SessionService
+
+@router.get("/sessions/me")
+async def list_sessions(
+    current_user: User = Depends(get_current_active_user),
+    session_service: SessionService = Depends(get_session_service),
+    db: AsyncSession = Depends(get_db),
+):
+    return await session_service.get_user_sessions(db, user_id=current_user.id)
+```
+
+**Rule**: Routes import from `app.api.dependencies.services`, never from `app.repositories.*`. Services are the only callers of repositories.
+
+---
+
+## Checklist Before Committing
+
+Use this checklist to catch issues before code review:
+
+### Database
+- [ ] No mutable defaults (`default=dict`, not `default={}`)
+- [ ] All foreign keys have `index=True`
+- [ ] Composite indexes for multi-column queries
+- [ ] Soft deletes with `deleted_at` column
+- [ ] All queries have `.order_by()` for pagination
+
+### Validation
+- [ ] All dict/JSON fields have size validators
+- [ ] All string fields have `max_length`
+- [ ] Validators applied to BOTH Create and Update schemas
+- [ ] All fields have descriptions
+
+### API Design
+- [ ] Rate limits on all endpoints
+- [ ] Response schemas (never return ORM models)
+- [ ] Consistent error format with global handlers
+- [ ] OpenAPI docs are clear and complete
+
+### Security
+- [ ] No passwords, tokens, or secrets in logs
+- [ ] Password strength validation
+- [ ] Resource ownership verification
+- [ ] CORS configured (no wildcards in production)
+
+### Architecture
+- [ ] Routes never import repositories directly (only services)
+- [ ] Services call repositories; repositories call database only
+- [ ] New service registered in `app/api/dependencies/services.py`
+
+### Python
+- [ ] Use `==` not `is` for value comparison
+- [ ] No mutable default arguments
+- [ ] Type hints on all functions
+- [ ] No unused imports or variables
+
+---
+
+## Prevention Tools
+
+### Pre-commit Checks
+
+Add these to your development workflow (or use `make validate`):
+
+```bash
+# Format + lint (Ruff replaces Black, isort, flake8)
+uv run ruff format app tests
+uv run ruff check app tests
+
+# Type checking
+uv run pyright app
+
+# Run tests
+IS_TEST=True uv run pytest --cov=app --cov-report=term-missing
+
+# Check coverage (should be 80%+)
+coverage report --fail-under=80
+```
+
+---
+
+## When to Update This Document
+
+Add new entries when:
+1. A bug makes it to production
+2. Multiple review cycles catch the same issue
+3. An issue takes >30 minutes to debug
+4. Security vulnerability discovered
+
+---
+
+**Last Updated**: 2026-02-28
+**Issues Cataloged**: 19 common pitfalls
+**Remember**: This document exists because these issues HAVE occurred. Don't skip it.

backend/docs/E2E_TESTING.md

@@ -0,0 +1,348 @@
+# Backend E2E Testing Guide
+
+End-to-end testing infrastructure using **Testcontainers** (real PostgreSQL) and **Schemathesis** (OpenAPI contract testing).
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Requirements](#requirements)
+- [How It Works](#how-it-works)
+- [Test Organization](#test-organization)
+- [Writing E2E Tests](#writing-e2e-tests)
+- [Running Tests](#running-tests)
+- [Troubleshooting](#troubleshooting)
+- [CI/CD Integration](#cicd-integration)
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install E2E dependencies
+make install-e2e
+
+# 2. Ensure Docker is running
+make check-docker
+
+# 3. Run E2E tests
+make test-e2e
+```
+
+---
+
+## Requirements
+
+### Docker
+
+E2E tests use Testcontainers to spin up real PostgreSQL containers. Docker must be running:
+
+- **macOS/Windows**: Docker Desktop
+- **Linux**: Docker Engine (`sudo systemctl start docker`)
+
+### Dependencies
+
+E2E tests require additional packages beyond the standard dev dependencies:
+
+```bash
+# Install E2E dependencies
+make install-e2e
+
+# Or manually:
+uv sync --extra dev --extra e2e
+```
+
+This installs:
+- `testcontainers[postgres]>=4.0.0` - Docker container management
+- `schemathesis>=3.30.0` - OpenAPI contract testing
+
+---
+
+## How It Works
+
+### Testcontainers
+
+Testcontainers automatically manages Docker containers for tests:
+
+1. **Session-scoped container**: A single PostgreSQL 17 container starts once per test session
+2. **Function-scoped isolation**: Each test gets fresh tables (drop + recreate)
+3. **Automatic cleanup**: Container is destroyed when tests complete
+
+This approach catches bugs that SQLite-based tests miss:
+- PostgreSQL-specific SQL behavior
+- Real constraint violations
+- Actual transaction semantics
+- JSONB column behavior
+
+### Schemathesis
+
+Schemathesis generates test cases from your OpenAPI schema:
+
+1. **Schema loading**: Reads `/api/v1/openapi.json` from your FastAPI app
+2. **Test generation**: Creates test cases for each endpoint
+3. **Response validation**: Verifies responses match documented schema
+
+This catches:
+- Undocumented response codes
+- Schema mismatches (wrong types, missing fields)
+- Edge cases in input validation
+
+---
+
+## Test Organization
+
+```
+backend/tests/
+├── e2e/                          # E2E tests (PostgreSQL, Docker required)
+│   ├── __init__.py
+│   ├── conftest.py               # Testcontainers fixtures
+│   ├── test_api_contracts.py     # Schemathesis schema tests
+│   └── test_database_workflows.py # PostgreSQL workflow tests
+│
+├── api/                          # Integration tests (SQLite, fast)
+├── repositories/                 # Repository unit tests
+└── conftest.py                   # Standard fixtures
+```
+
+### Test Markers
+
+Tests use pytest markers for filtering:
+
+| Marker | Description |
+|--------|-------------|
+| `@pytest.mark.e2e` | End-to-end test requiring Docker |
+| `@pytest.mark.postgres` | PostgreSQL-specific test |
+| `@pytest.mark.schemathesis` | Schemathesis schema test |
+
+---
+
+## Writing E2E Tests
+
+### Basic E2E Test
+
+```python
+import pytest
+from uuid import uuid4
+
+@pytest.mark.e2e
+@pytest.mark.postgres
+@pytest.mark.asyncio
+async def test_user_workflow(e2e_client):
+    """Test user registration with real PostgreSQL."""
+    email = f"test-{uuid4().hex[:8]}@example.com"
+
+    response = await e2e_client.post(
+        "/api/v1/auth/register",
+        json={
+            "email": email,
+            "password": "SecurePassword123!",
+            "first_name": "Test",
+            "last_name": "User",
+        },
+    )
+
+    assert response.status_code in [200, 201]
+    assert response.json()["email"] == email
+```
+
+### Available Fixtures
+
+| Fixture | Scope | Description |
+|---------|-------|-------------|
+| `postgres_container` | session | Raw Testcontainers PostgreSQL container |
+| `async_postgres_url` | session | Asyncpg-compatible connection URL |
+| `e2e_db_session` | function | SQLAlchemy AsyncSession with fresh tables |
+| `e2e_client` | function | httpx AsyncClient connected to real DB |
+
+### Schemathesis Test
+
+```python
+import pytest
+import schemathesis
+from hypothesis import settings, Phase
+
+from app.main import app
+
+schema = schemathesis.from_asgi("/api/v1/openapi.json", app=app)
+
+@pytest.mark.e2e
+@pytest.mark.schemathesis
+@schema.parametrize(endpoint="/api/v1/auth/register")
+@settings(max_examples=20)
+def test_registration_schema(case):
+    """Test registration endpoint conforms to schema."""
+    response = case.call_asgi()
+    case.validate_response(response)
+```
+
+---
+
+## Running Tests
+
+### Commands
+
+```bash
+# Run all E2E tests
+make test-e2e
+
+# Run only Schemathesis schema tests
+make test-e2e-schema
+
+# Run all tests (unit + integration + E2E)
+make test-all
+
+# Check Docker availability
+make check-docker
+```
+
+### Direct pytest
+
+```bash
+# All E2E tests
+IS_TEST=True PYTHONPATH=. uv run pytest tests/e2e/ -v
+
+# Only PostgreSQL tests
+IS_TEST=True PYTHONPATH=. uv run pytest tests/e2e/ -v -m postgres
+
+# Only Schemathesis tests
+IS_TEST=True PYTHONPATH=. uv run pytest tests/e2e/ -v -m schemathesis
+```
+
+---
+
+## Troubleshooting
+
+### Docker Not Running
+
+**Error:**
+```
+Docker is not running!
+E2E tests require Docker to be running.
+```
+
+**Solution:**
+```bash
+# macOS/Windows
+# Open Docker Desktop
+
+# Linux
+sudo systemctl start docker
+```
+
+### Testcontainers Not Installed
+
+**Error:**
+```
+SKIPPED: testcontainers not installed - run: make install-e2e
+```
+
+**Solution:**
+```bash
+make install-e2e
+# Or: uv sync --extra dev --extra e2e
+```
+
+### Container Startup Timeout
+
+**Error:**
+```
+testcontainers.core.waiting_utils.UnexpectedResponse
+```
+
+**Solutions:**
+1. Increase Docker resources (memory, CPU)
+2. Pull the image manually: `docker pull postgres:17-alpine`
+3. Check Docker daemon logs: `docker logs`
+
+### Port Conflicts
+
+**Error:**
+```
+Error starting container: port is already allocated
+```
+
+**Solution:**
+Testcontainers uses random ports, so conflicts are rare. If occurring:
+1. Stop other PostgreSQL containers: `docker stop $(docker ps -q)`
+2. Check for orphaned containers: `docker container prune`
+
+### Ryuk/Reaper Port 8080 Issues
+
+**Error:**
+```
+ConnectionError: Port mapping for container ... and port 8080 is not available
+```
+
+**Solution:**
+This is related to the Testcontainers Reaper (Ryuk) which handles automatic cleanup.
+The `conftest.py` automatically disables Ryuk to avoid this issue. If you still encounter
+this error, ensure you're using the latest conftest.py or set the environment variable:
+
+```bash
+export TESTCONTAINERS_RYUK_DISABLED=true
+```
+
+### Parallel Test Execution Issues
+
+**Error:**
+```
+ScopeMismatch: ... cannot use a higher-scoped fixture 'postgres_container'
+```
+
+**Solution:**
+E2E tests must run sequentially (not in parallel) because they share a session-scoped
+PostgreSQL container. The Makefile commands use `-n 0` to disable parallel execution.
+If running pytest directly, add `-n 0`:
+
+```bash
+IS_TEST=True PYTHONPATH=. uv run pytest tests/e2e/ -v -n 0
+```
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+A workflow template is provided at `.github/workflows/backend-e2e-tests.yml.template`.
+
+To enable:
+1. Rename to `backend-e2e-tests.yml`
+2. Push to repository
+
+The workflow:
+- Runs on pushes to `main`/`develop` affecting `backend/`
+- Uses `continue-on-error: true` (E2E failures don't block merge)
+- Caches uv dependencies for speed
+
+### Local CI Simulation
+
+```bash
+# Run what CI runs
+make test-all
+```
+
+---
+
+## Best Practices
+
+### DO
+
+- Use unique emails per test: `f"test-{uuid4().hex[:8]}@example.com"`
+- Mark tests with appropriate markers: `@pytest.mark.e2e`
+- Keep E2E tests focused on critical workflows
+- Use `e2e_client` fixture for most tests
+
+### DON'T
+
+- Share state between tests (each test gets fresh tables)
+- Test every endpoint in E2E (use unit tests for edge cases)
+- Skip the `IS_TEST=True` environment variable
+- Run E2E tests without Docker
+
+---
+
+## Further Reading
+
+- [Testcontainers Documentation](https://testcontainers.com/guides/getting-started-with-testcontainers-for-python/)
+- [Schemathesis Documentation](https://schemathesis.readthedocs.io/)
+- [pytest-asyncio Documentation](https://pytest-asyncio.readthedocs.io/)

backend/entrypoint.sh

@@ -1,8 +1,22 @@
-#!/bin/bash
+#!/bin/sh
 set -e
 echo "Starting Backend"
 
+# Ensure the project's virtualenv binaries are on PATH so commands like
+# 'uvicorn' work even when not prefixed by 'uv run'. This matches how uv
+# installs the env into /app/.venv in our containers.
+if [ -d "/app/.venv/bin" ]; then
+  export PATH="/app/.venv/bin:$PATH"
+fi
+
 # Apply database migrations
-alembic upgrade head
+# Avoid installing the project in editable mode (which tries to write egg-info)
+# when running inside a bind-mounted volume with restricted permissions.
+# See: https://github.com/astral-sh/uv (use --no-project to skip project build)
+uv run --no-project alembic upgrade head
+
+# Initialize database (creates first superuser if needed)
+uv run --no-project python app/init_db.py
+
 # Execute the command passed to docker run
 exec "$@"