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.template

@@ -1,22 +1,15 @@
 # Common settings
-PROJECT_NAME=Syndarix
+PROJECT_NAME=App
 VERSION=1.0.0
 
 # Database settings
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=postgres
-POSTGRES_DB=syndarix
+POSTGRES_DB=app
 POSTGRES_HOST=db
 POSTGRES_PORT=5432
 DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
 
-# Redis settings (cache, pub/sub, Celery broker)
-REDIS_URL=redis://redis:6379/0
-
-# Celery settings (optional - defaults to REDIS_URL if not set)
-# CELERY_BROKER_URL=redis://redis:6379/0
-# CELERY_RESULT_BACKEND=redis://redis:6379/0
-
 # Backend settings
 BACKEND_PORT=8000
 # CRITICAL: Generate a secure SECRET_KEY for production!

.gitea/workflows/ci.yaml

@@ -1,460 +0,0 @@
-# Syndarix CI/CD Pipeline
-# Gitea Actions workflow for continuous integration and deployment
-#
-# Pipeline Structure:
-# - lint: Fast feedback (linting and type checking)
-# - test: Run test suites (depends on lint)
-# - build: Build Docker images (depends on test)
-# - deploy: Deploy to production (depends on build, only on main)
-
-name: CI/CD Pipeline
-
-on:
-  push:
-    branches:
-      - main
-      - dev
-      - 'feature/**'
-  pull_request:
-    branches:
-      - main
-      - dev
-
-env:
-  PYTHON_VERSION: "3.12"
-  NODE_VERSION: "20"
-  UV_VERSION: "0.4.x"
-
-jobs:
-  # ===========================================================================
-  # LINT JOB - Fast feedback first
-  # ===========================================================================
-  lint:
-    name: Lint & Type Check
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        component: [backend, frontend]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      # ----- Backend Linting -----
-      - name: Set up Python
-        if: matrix.component == 'backend'
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install uv
-        if: matrix.component == 'backend'
-        uses: astral-sh/setup-uv@v4
-        with:
-          version: ${{ env.UV_VERSION }}
-
-      - name: Cache uv dependencies
-        if: matrix.component == 'backend'
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache/uv
-            backend/.venv
-          key: uv-${{ runner.os }}-${{ hashFiles('backend/uv.lock') }}
-          restore-keys: |
-            uv-${{ runner.os }}-
-
-      - name: Install backend dependencies
-        if: matrix.component == 'backend'
-        working-directory: backend
-        run: uv sync --extra dev --frozen
-
-      - name: Run ruff linting
-        if: matrix.component == 'backend'
-        working-directory: backend
-        run: uv run ruff check app
-
-      - name: Run ruff format check
-        if: matrix.component == 'backend'
-        working-directory: backend
-        run: uv run ruff format --check app
-
-      - name: Run mypy type checking
-        if: matrix.component == 'backend'
-        working-directory: backend
-        run: uv run mypy app
-
-      # ----- Frontend Linting -----
-      - name: Set up Node.js
-        if: matrix.component == 'frontend'
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-
-      - name: Cache npm dependencies
-        if: matrix.component == 'frontend'
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.npm
-            frontend/node_modules
-          key: npm-${{ runner.os }}-${{ hashFiles('frontend/package-lock.json') }}
-          restore-keys: |
-            npm-${{ runner.os }}-
-
-      - name: Install frontend dependencies
-        if: matrix.component == 'frontend'
-        working-directory: frontend
-        run: npm ci
-
-      - name: Run ESLint
-        if: matrix.component == 'frontend'
-        working-directory: frontend
-        run: npm run lint
-
-      - name: Run TypeScript type check
-        if: matrix.component == 'frontend'
-        working-directory: frontend
-        run: npm run type-check
-
-      - name: Run Prettier format check
-        if: matrix.component == 'frontend'
-        working-directory: frontend
-        run: npm run format:check
-
-  # ===========================================================================
-  # TEST JOB - Run test suites
-  # ===========================================================================
-  test:
-    name: Test
-    runs-on: ubuntu-latest
-    needs: lint
-    strategy:
-      matrix:
-        component: [backend, frontend]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      # ----- Backend Tests -----
-      - name: Set up Python
-        if: matrix.component == 'backend'
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install uv
-        if: matrix.component == 'backend'
-        uses: astral-sh/setup-uv@v4
-        with:
-          version: ${{ env.UV_VERSION }}
-
-      - name: Cache uv dependencies
-        if: matrix.component == 'backend'
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.cache/uv
-            backend/.venv
-          key: uv-${{ runner.os }}-${{ hashFiles('backend/uv.lock') }}
-          restore-keys: |
-            uv-${{ runner.os }}-
-
-      - name: Install backend dependencies
-        if: matrix.component == 'backend'
-        working-directory: backend
-        run: uv sync --extra dev --frozen
-
-      - name: Run pytest with coverage
-        if: matrix.component == 'backend'
-        working-directory: backend
-        env:
-          IS_TEST: "True"
-        run: |
-          uv run pytest --cov=app --cov-report=xml --cov-report=term-missing --cov-fail-under=90
-
-      - name: Upload backend coverage report
-        if: matrix.component == 'backend'
-        uses: actions/upload-artifact@v4
-        with:
-          name: backend-coverage
-          path: backend/coverage.xml
-          retention-days: 7
-
-      # ----- Frontend Tests -----
-      - name: Set up Node.js
-        if: matrix.component == 'frontend'
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-
-      - name: Cache npm dependencies
-        if: matrix.component == 'frontend'
-        uses: actions/cache@v4
-        with:
-          path: |
-            ~/.npm
-            frontend/node_modules
-          key: npm-${{ runner.os }}-${{ hashFiles('frontend/package-lock.json') }}
-          restore-keys: |
-            npm-${{ runner.os }}-
-
-      - name: Install frontend dependencies
-        if: matrix.component == 'frontend'
-        working-directory: frontend
-        run: npm ci
-
-      - name: Run Jest unit tests
-        if: matrix.component == 'frontend'
-        working-directory: frontend
-        run: npm test -- --coverage --passWithNoTests
-
-      - name: Upload frontend coverage report
-        if: matrix.component == 'frontend'
-        uses: actions/upload-artifact@v4
-        with:
-          name: frontend-coverage
-          path: frontend/coverage/
-          retention-days: 7
-
-  # ===========================================================================
-  # BUILD JOB - Build Docker images
-  # ===========================================================================
-  build:
-    name: Build
-    runs-on: ubuntu-latest
-    needs: test
-    strategy:
-      matrix:
-        component: [backend, frontend]
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Cache Docker layers
-        uses: actions/cache@v4
-        with:
-          path: /tmp/.buildx-cache
-          key: docker-${{ matrix.component }}-${{ github.sha }}
-          restore-keys: |
-            docker-${{ matrix.component }}-
-
-      - name: Build backend Docker image
-        if: matrix.component == 'backend'
-        uses: docker/build-push-action@v5
-        with:
-          context: ./backend
-          file: ./backend/Dockerfile
-          target: production
-          push: false
-          tags: syndarix-backend:${{ github.sha }}
-          cache-from: type=local,src=/tmp/.buildx-cache
-          cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
-
-      - name: Build frontend Docker image
-        if: matrix.component == 'frontend'
-        uses: docker/build-push-action@v5
-        with:
-          context: ./frontend
-          file: ./frontend/Dockerfile
-          target: runner
-          push: false
-          tags: syndarix-frontend:${{ github.sha }}
-          build-args: |
-            NEXT_PUBLIC_API_URL=http://localhost:8000
-          cache-from: type=local,src=/tmp/.buildx-cache
-          cache-to: type=local,dest=/tmp/.buildx-cache-new,mode=max
-
-      # Prevent cache from growing indefinitely
-      - name: Move cache
-        run: |
-          rm -rf /tmp/.buildx-cache
-          mv /tmp/.buildx-cache-new /tmp/.buildx-cache
-
-  # ===========================================================================
-  # DEPLOY JOB - Deploy to production (only on main branch)
-  # ===========================================================================
-  deploy:
-    name: Deploy
-    runs-on: ubuntu-latest
-    needs: build
-    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
-    environment: production
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Deploy notification
-        run: |
-          echo "Deployment to production would happen here"
-          echo "Branch: ${{ github.ref }}"
-          echo "Commit: ${{ github.sha }}"
-          echo "Actor: ${{ github.actor }}"
-
-      # TODO: Add actual deployment steps when infrastructure is ready
-      # Options:
-      # - SSH to production server and run docker-compose pull && docker-compose up -d
-      # - Use Kubernetes deployment
-      # - Use cloud provider deployment (AWS ECS, GCP Cloud Run, etc.)
-      # - Trigger webhook to deployment orchestrator
-
-  # ===========================================================================
-  # SECURITY SCAN JOB - Run on main and dev branches
-  # ===========================================================================
-  security:
-    name: Security Scan
-    runs-on: ubuntu-latest
-    needs: lint
-    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev'
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          version: ${{ env.UV_VERSION }}
-
-      - name: Install backend dependencies
-        working-directory: backend
-        run: uv sync --extra dev --frozen
-
-      - name: Run Bandit security scan (via ruff)
-        working-directory: backend
-        run: |
-          # Ruff includes flake8-bandit (S rules) for security scanning
-          # Run with explicit security rules only
-          uv run ruff check app --select=S --ignore=S101,S104,S105,S106,S603,S607
-
-      - name: Run pip-audit for dependency vulnerabilities
-        working-directory: backend
-        run: |
-          # pip-audit checks for known vulnerabilities in Python dependencies
-          uv run pip-audit --require-hashes --disable-pip -r <(uv pip compile pyproject.toml) || true
-          # Note: Using || true temporarily while setting up proper remediation
-
-      - name: Check for secrets in code
-        run: |
-          # Basic check for common secret patterns
-          # In production, use tools like gitleaks or trufflehog
-          echo "Checking for potential hardcoded secrets..."
-          ! grep -rn --include="*.py" --include="*.ts" --include="*.tsx" --include="*.js" \
-            -E "(api_key|apikey|secret_key|secretkey|password|passwd|token)\s*=\s*['\"][^'\"]{8,}['\"]" \
-            backend/app frontend/src || echo "No obvious secrets found"
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-
-      - name: Install frontend dependencies
-        working-directory: frontend
-        run: npm ci
-
-      - name: Run npm audit
-        working-directory: frontend
-        run: |
-          npm audit --audit-level=high || true
-          # Note: Using || true to not fail on moderate vulnerabilities
-          # In production, consider stricter settings
-
-  # ===========================================================================
-  # E2E TEST JOB - Run end-to-end tests with Playwright
-  # ===========================================================================
-  e2e-tests:
-    name: E2E Tests
-    runs-on: ubuntu-latest
-    needs: [lint, test]
-    if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev' || github.event_name == 'pull_request'
-    services:
-      postgres:
-        image: pgvector/pgvector:pg17
-        env:
-          POSTGRES_USER: postgres
-          POSTGRES_PASSWORD: postgres
-          POSTGRES_DB: syndarix_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd "pg_isready -U postgres"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis:7-alpine
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v4
-        with:
-          version: ${{ env.UV_VERSION }}
-
-      - name: Install backend dependencies
-        working-directory: backend
-        run: uv sync --extra dev --frozen
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-
-      - 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: Start backend server
-        working-directory: backend
-        env:
-          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/syndarix_test
-          REDIS_URL: redis://localhost:6379/0
-          SECRET_KEY: test-secret-key-for-e2e-tests-only
-          ENVIRONMENT: test
-          IS_TEST: "True"
-        run: |
-          # Run migrations
-          uv run python -c "from app.database import create_tables; import asyncio; asyncio.run(create_tables())" || true
-          # Start backend in background
-          uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 &
-          # Wait for backend to be ready
-          sleep 10
-
-      - name: Run Playwright E2E tests
-        working-directory: frontend
-        env:
-          NEXT_PUBLIC_API_URL: http://localhost:8000
-        run: |
-          npm run build
-          npm run test:e2e -- --project=chromium
-
-      - name: Upload Playwright report
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: playwright-report
-          path: frontend/playwright-report/
-          retention-days: 7

.githooks/pre-commit

@@ -1,61 +0,0 @@
-#!/bin/bash
-# Pre-commit hook to enforce validation before commits on protected branches
-# Install: git config core.hooksPath .githooks
-
-set -e
-
-# Get the current branch name
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-# Protected branches that require validation
-PROTECTED_BRANCHES="main dev"
-
-# Check if we're on a protected branch
-is_protected() {
-    for branch in $PROTECTED_BRANCHES; do
-        if [ "$BRANCH" = "$branch" ]; then
-            return 0
-        fi
-    done
-    return 1
-}
-
-if is_protected; then
-    echo "🔒 Committing to protected branch '$BRANCH' - running validation..."
-
-    # Check if we have backend changes
-    if git diff --cached --name-only | grep -q "^backend/"; then
-        echo "📦 Backend changes detected - running make validate..."
-        cd backend
-        if ! make validate; then
-            echo ""
-            echo "❌ Backend validation failed!"
-            echo "   Please fix the issues and try again."
-            echo "   Run 'cd backend && make validate' to see errors."
-            exit 1
-        fi
-        cd ..
-        echo "✅ Backend validation passed!"
-    fi
-
-    # Check if we have frontend changes
-    if git diff --cached --name-only | grep -q "^frontend/"; then
-        echo "🎨 Frontend changes detected - running npm run validate..."
-        cd frontend
-        if ! npm run validate 2>/dev/null; then
-            echo ""
-            echo "❌ Frontend validation failed!"
-            echo "   Please fix the issues and try again."
-            echo "   Run 'cd frontend && npm run validate' to see errors."
-            exit 1
-        fi
-        cd ..
-        echo "✅ Frontend validation passed!"
-    fi
-
-    echo "🎉 All validations passed! Proceeding with commit..."
-else
-    echo "📝 Committing to feature branch '$BRANCH' - skipping validation (run manually if needed)"
-fi
-
-exit 0

.github/workflows/README.md

@@ -41,7 +41,7 @@ To enable CI/CD workflows:
 - Runs on: Push to main/develop, PRs affecting frontend code
 - Tests: Frontend unit tests (Jest)
 - Coverage: Uploads to Codecov
-- Fast: Uses npm cache
+- Fast: Uses bun cache
 
 ### `e2e-tests.yml`
 - Runs on: All pushes and PRs

.gitignore

@@ -187,7 +187,7 @@ coverage.xml
 .hypothesis/
 .pytest_cache/
 cover/
-
+backend/.benchmarks
 # Translations
 *.mo
 *.pot

AGENTS.md

@@ -13,10 +13,10 @@ uv run uvicorn app.main:app --reload  # Start dev server
 
 # Frontend (Node.js)
 cd frontend
-npm install                   # Install dependencies
-npm run dev                   # Start dev server
-npm run generate:api          # Generate API client from OpenAPI
-npm run test:e2e              # Run E2E tests
+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:**
@@ -37,7 +37,7 @@ Default superuser (change in production):
 │   ├── app/
 │   │   ├── api/            # API routes (auth, users, organizations, admin)
 │   │   ├── core/           # Core functionality (auth, config, database)
-│   │   ├── crud/           # Database CRUD operations
+│   │   ├── repositories/   # Repository pattern (database operations)
 │   │   ├── models/         # SQLAlchemy ORM models
 │   │   ├── schemas/        # Pydantic request/response schemas
 │   │   ├── services/       # Business logic layer
@@ -113,7 +113,7 @@ OAUTH_ISSUER=https://api.yourdomain.com      # JWT issuer URL (must be HTTPS in
 ### Database Pattern
 - **Async SQLAlchemy 2.0** with PostgreSQL
 - **Connection pooling**: 20 base connections, 50 max overflow
-- **CRUD base class**: `crud/base.py` with common operations
+- **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
@@ -121,7 +121,7 @@ OAUTH_ISSUER=https://api.yourdomain.com      # JWT issuer URL (must be HTTPS in
 ### Frontend State Management
 - **Zustand stores**: Lightweight state management
 - **TanStack Query**: API data fetching/caching
-- **Auto-generated client**: From OpenAPI spec via `npm run generate:api`
+- **Auto-generated client**: From OpenAPI spec via `bun run generate:api`
 - **Dependency Injection**: ALWAYS use `useAuth()` from `AuthContext`, NEVER import `useAuthStore` directly
 
 ### Internationalization (i18n)
@@ -165,21 +165,25 @@ Permission dependencies in `api/dependencies/permissions.py`:
 **Frontend Unit Tests (Jest):**
 - 97% coverage
 - Component, hook, and utility testing
-- Run: `npm test`
-- Coverage: `npm run test:coverage`
+- 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: `npm run test:e2e`
-- UI mode: `npm run test:e2e:ui`
+- 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)
-- **mypy**: Type checking with Pydantic plugin
+- **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:**
@@ -218,11 +222,11 @@ NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
 ### Adding a New API Endpoint
 
 1. **Define schema** in `backend/app/schemas/`
-2. **Create CRUD operations** in `backend/app/crud/`
+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**: `npm run generate:api`
+6. **Generate frontend client**: `bun run generate:api`
 
 ### Database Migrations
 
@@ -239,7 +243,7 @@ python migrate.py auto "description"      # Generate + apply
 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**: `npm run type-check`
+5. **Run type check**: `bun run type-check`
 
 ## Security Features
 
@@ -249,6 +253,10 @@ python migrate.py auto "description"      # Generate + apply
 - **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
 
@@ -281,7 +289,7 @@ docker-compose exec backend python -c "from app.init_db import init_db; import a
 - 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 (CRUD, password change)
+- 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

CLAUDE.md

@@ -1,204 +1,253 @@
 # CLAUDE.md
 
-Claude Code context for **Syndarix** - AI-Powered Software Consulting Agency.
+Claude Code context for FastAPI + Next.js Full-Stack Template.
 
-**Built on PragmaStack.** See [AGENTS.md](./AGENTS.md) for base template context.
-
----
-
-## Syndarix Project Context
-
-### Vision
-
-Syndarix is an autonomous platform that orchestrates specialized AI agents to deliver complete software solutions with minimal human intervention. It acts as a virtual consulting agency with AI agents playing roles like Product Owner, Architect, Engineers, QA, etc.
-
-### Repository
-
-- **URL:** https://gitea.pragmazest.com/cardosofelipe/syndarix
-- **Issue Tracker:** Gitea Issues (primary)
-- **CI/CD:** Gitea Actions
-
-### Core Concepts
-
-**Agent Types & Instances:**
-- Agent Type = Template (base model, failover, expertise, personality)
-- Agent Instance = Spawned from type, assigned to project
-- Multiple instances of same type can work together
-
-**Project Workflow:**
-1. Requirements discovery with Product Owner agent
-2. Architecture spike (PO + BA + Architect brainstorm)
-3. Implementation planning and backlog creation
-4. Autonomous sprint execution with checkpoints
-5. Demo and client feedback
-
-**Autonomy Levels:**
-- `FULL_CONTROL`: Approve every action
-- `MILESTONE`: Approve sprint boundaries
-- `AUTONOMOUS`: Only major decisions
-
-**MCP-First Architecture:**
-All integrations via Model Context Protocol servers with explicit scoping:
-```python
-# All tools take project_id for scoping
-search_knowledge(project_id="proj-123", query="auth flow")
-create_issue(project_id="proj-123", title="Add login")
-```
-
-### Directory Structure
-
-```
-docs/
-├── development/    # Workflow and coding standards
-├── requirements/   # Requirements documents
-├── architecture/   # Architecture documentation
-├── adrs/          # Architecture Decision Records
-└── spikes/        # Spike research documents
-```
-
-### Current Phase
-
-**Backlog Population** - Creating detailed issues for Phase 0-1 implementation.
-
----
-
-## Development Standards
-
-**CRITICAL: These rules are mandatory. See linked docs for full details.**
-
-### Quick Reference
-
-| Topic | Documentation |
-|-------|---------------|
-| **Workflow & Branching** | [docs/development/WORKFLOW.md](./docs/development/WORKFLOW.md) |
-| **Coding Standards** | [docs/development/CODING_STANDARDS.md](./docs/development/CODING_STANDARDS.md) |
-| **Design System** | [frontend/docs/design-system/](./frontend/docs/design-system/) |
-| **Backend E2E Testing** | [backend/docs/E2E_TESTING.md](./backend/docs/E2E_TESTING.md) |
-| **Demo Mode** | [frontend/docs/DEMO_MODE.md](./frontend/docs/DEMO_MODE.md) |
-
-### Essential Rules Summary
-
-1. **Issue-Driven Development**: Every piece of work MUST have an issue first
-2. **Branch per Feature**: `feature/<issue-number>-<description>`, single branch for design+implementation
-3. **Testing Required**: All code must be tested, aim for >90% coverage
-4. **Code Review**: Must pass multi-agent review before merge
-5. **No Direct Commits**: Never commit directly to `main` or `dev`
-6. **Stack Verification**: ALWAYS run the full stack before considering work done (see below)
-
-### CRITICAL: Stack Verification Before Merge
-
-**This is NON-NEGOTIABLE. A feature with 100% test coverage that crashes on startup is WORTHLESS.**
-
-Before considering ANY issue complete:
-
-```bash
-# 1. Start the dev stack
-make dev
-
-# 2. Wait for backend to be healthy, check logs
-docker compose -f docker-compose.dev.yml logs backend --tail=100
-
-# 3. Start frontend
-cd frontend && npm run dev
-
-# 4. Verify both are running without errors
-```
-
-**The issue is NOT done if:**
-- Backend crashes on startup (import errors, missing dependencies)
-- Frontend fails to compile or render
-- Health checks fail
-- Any error appears in logs
-
-**Why this matters:**
-- Tests run in isolation and may pass despite broken imports
-- Docker builds cache layers and may hide dependency issues
-- A single `ModuleNotFoundError` renders all test coverage meaningless
-
-### Common Commands
-
-```bash
-# Backend
-IS_TEST=True uv run pytest          # Run tests
-uv run ruff check src/              # Lint
-uv run mypy src/                    # Type check
-python migrate.py auto "message"    # Database migration
-
-# Frontend
-npm test                            # Unit tests
-npm run lint                        # Lint
-npm run type-check                  # Type check
-npm run generate:api                # Regenerate API client
-```
-
----
+**See [AGENTS.md](./AGENTS.md) for project context, architecture, and development commands.**
 
 ## Claude Code-Specific Guidance
 
 ### Critical User Preferences
 
-**File Operations:**
-- ALWAYS use Read/Write/Edit tools instead of `cat >> file << EOF`
-- Never use heredoc - it triggers manual approval dialogs
+#### File Operations - NEVER Use Heredoc/Cat Append
+**ALWAYS use Read/Write/Edit tools instead of `cat >> file << EOF` commands.**
 
-**Work Style:**
+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
 
-### Critical Pattern: Auth Store DI
+### 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
+// ❌ WRONG - Bypasses dependency injection
 import { useAuthStore } from '@/lib/stores/authStore';
+const { user, isAuthenticated } = useAuthStore();
 
-// ✅ CORRECT
+// ✅ CORRECT - Uses dependency injection
 import { useAuth } from '@/lib/auth/AuthContext';
+const { user, isAuthenticated } = useAuth();
 ```
 
-See [CODING_STANDARDS.md](./docs/development/CODING_STANDARDS.md#auth-store-dependency-injection) for details.
+**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`
 
-**Parallel tool calls for:**
-- Independent git commands
+**When to use parallel tool calls:**
+- Independent git commands: `git status`, `git diff`, `git log`
 - Reading multiple unrelated files
-- Running multiple test suites
+- Running multiple test suites simultaneously
 - Independent validation steps
 
----
+## Custom Skills
 
-## Key Extensions (from PragmaStack base)
+No Claude Code Skills installed yet. To create one, invoke the built-in "skill-creator" skill.
 
-- Celery + Redis for agent job queue
-- WebSocket/SSE for real-time updates
-- pgvector for RAG knowledge base
-- MCP server integration layer
-
----
+**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
 
-**Documentation:**
+**Comprehensive Documentation:**
 - [AGENTS.md](./AGENTS.md) - Framework-agnostic AI assistant context
 - [README.md](./README.md) - User-facing project overview
-- [docs/development/](./docs/development/) - Development workflow and standards
-- [backend/docs/](./backend/docs/) - Backend architecture and guides
-- [frontend/docs/design-system/](./frontend/docs/design-system/) - Complete design system
+- `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

@@ -91,7 +91,10 @@ Ready to write some code? Awesome!
 cd backend
 
 # Install dependencies (uv manages virtual environment automatically)
-uv sync
+make install-dev
+
+# Setup pre-commit hooks
+uv run pre-commit install
 
 # Setup environment
 cp .env.example .env
@@ -100,8 +103,14 @@ cp .env.example .env
 # Run migrations
 python migrate.py apply
 
+# Run quality + security checks
+make validate-all
+
 # Run tests
-IS_TEST=True uv run pytest
+make test
+
+# Run full pipeline (quality + security + tests)
+make check
 
 # Start dev server
 uvicorn app.main:app --reload
@@ -113,20 +122,20 @@ uvicorn app.main:app --reload
 cd frontend
 
 # Install dependencies
-npm install
+bun install
 
 # Setup environment
 cp .env.local.example .env.local
 
 # Generate API client
-npm run generate:api
+bun run generate:api
 
 # Run tests
-npm test
-npm run test:e2e:ui
+bun run test
+bun run test:e2e:ui
 
 # Start dev server
-npm run dev
+bun run dev
 ```
 
 ---
@@ -195,7 +204,7 @@ export function UserProfile({ userId }: UserProfileProps) {
 
 ### Key Patterns
 
-- **Backend**: Use CRUD pattern, keep routes thin, business logic in services
+- **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
 
@@ -316,7 +325,7 @@ Fixed stuff
 ### Before Submitting
 
 - [ ] Code follows project style guidelines
-- [ ] All tests pass locally
+- [ ] `make check` passes (quality + security + tests) in backend
 - [ ] New tests added for new features
 - [ ] Documentation updated if needed
 - [ ] No merge conflicts with `main`

Makefile

@@ -1,34 +1,18 @@
-.PHONY: help dev dev-full prod down logs logs-dev clean clean-slate drop-db reset-db push-images deploy
-.PHONY: test test-backend test-mcp test-frontend test-all test-cov test-integration validate validate-all format-all
+.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 ?= ghcr.io/cardosofelipe/pragma-stack
 
 # Default target
 help:
-	@echo "Syndarix - AI-Powered Software Consulting Agency"
+	@echo "FastAPI + Next.js Full-Stack Template"
 	@echo ""
 	@echo "Development:"
-	@echo "  make dev           - Start backend + db + MCP servers (frontend runs separately)"
+	@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 "Testing:"
-	@echo "  make test          - Run all tests (backend + MCP servers)"
-	@echo "  make test-backend  - Run backend tests only"
-	@echo "  make test-mcp      - Run MCP server tests only"
-	@echo "  make test-frontend - Run frontend tests only"
-	@echo "  make test-cov      - Run all tests with coverage reports"
-	@echo "  make test-integration - Run MCP integration tests (requires running stack)"
-	@echo ""
-	@echo "Formatting:"
-	@echo "  make format-all    - Format code in backend + MCP servers + frontend"
-	@echo ""
-	@echo "Validation:"
-	@echo "  make validate      - Validate backend + MCP servers (lint, type-check, test)"
-	@echo "  make validate-all  - Validate everything including frontend"
-	@echo ""
 	@echo "Database:"
 	@echo "  make drop-db       - Drop and recreate empty database"
 	@echo "  make reset-db      - Drop database and apply all migrations"
@@ -37,6 +21,7 @@ help:
 	@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:"
@@ -44,11 +29,8 @@ help:
 	@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 mcp-servers/llm-gateway && make   - LLM Gateway commands"
-	@echo "  cd mcp-servers/knowledge-base && make - Knowledge Base commands"
-	@echo "  cd mcp-servers/git-ops && make       - Git Operations commands"
-	@echo "  cd frontend && npm run               - Frontend-specific commands"
+	@echo "  cd backend && make help   - Backend-specific commands"
+	@echo "  cd frontend && npm run    - Frontend-specific commands"
 
 # ============================================================================
 # Development
@@ -108,6 +90,28 @@ push-images:
 	docker push $(REGISTRY)/backend:$(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
 # ============================================================================
@@ -118,103 +122,3 @@ clean:
 # 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
-
-# ============================================================================
-# Testing
-# ============================================================================
-
-test: test-backend test-mcp
-	@echo ""
-	@echo "All tests passed!"
-
-test-backend:
-	@echo "Running backend tests..."
-	@cd backend && IS_TEST=True uv run pytest tests/ -v
-
-test-mcp:
-	@echo "Running MCP server tests..."
-	@echo ""
-	@echo "=== LLM Gateway ==="
-	@cd mcp-servers/llm-gateway && uv run pytest tests/ -v
-	@echo ""
-	@echo "=== Knowledge Base ==="
-	@cd mcp-servers/knowledge-base && uv run pytest tests/ -v
-	@echo ""
-	@echo "=== Git Operations ==="
-	@cd mcp-servers/git-ops && IS_TEST=True uv run pytest tests/ -v
-
-test-frontend:
-	@echo "Running frontend tests..."
-	@cd frontend && npm test
-
-test-all: test test-frontend
-	@echo ""
-	@echo "All tests (backend + MCP + frontend) passed!"
-
-test-cov:
-	@echo "Running all tests with coverage..."
-	@echo ""
-	@echo "=== Backend Coverage ==="
-	@cd backend && IS_TEST=True uv run pytest tests/ -v --cov=app --cov-report=term-missing
-	@echo ""
-	@echo "=== LLM Gateway Coverage ==="
-	@cd mcp-servers/llm-gateway && uv run pytest tests/ -v --cov=. --cov-report=term-missing
-	@echo ""
-	@echo "=== Knowledge Base Coverage ==="
-	@cd mcp-servers/knowledge-base && uv run pytest tests/ -v --cov=. --cov-report=term-missing
-	@echo ""
-	@echo "=== Git Operations Coverage ==="
-	@cd mcp-servers/git-ops && IS_TEST=True uv run pytest tests/ -v --cov=. --cov-report=term-missing
-
-test-integration:
-	@echo "Running MCP integration tests..."
-	@echo "Note: Requires running stack (make dev first)"
-	@cd backend && RUN_INTEGRATION_TESTS=true IS_TEST=True uv run pytest tests/integration/ -v
-
-# ============================================================================
-# Formatting
-# ============================================================================
-
-format-all:
-	@echo "Formatting backend..."
-	@cd backend && make format
-	@echo ""
-	@echo "Formatting LLM Gateway..."
-	@cd mcp-servers/llm-gateway && make format
-	@echo ""
-	@echo "Formatting Knowledge Base..."
-	@cd mcp-servers/knowledge-base && make format
-	@echo ""
-	@echo "Formatting Git Operations..."
-	@cd mcp-servers/git-ops && make format
-	@echo ""
-	@echo "Formatting frontend..."
-	@cd frontend && npm run format
-	@echo ""
-	@echo "All code formatted!"
-
-# ============================================================================
-# Validation (lint + type-check + test)
-# ============================================================================
-
-validate:
-	@echo "Validating backend..."
-	@cd backend && make validate
-	@echo ""
-	@echo "Validating LLM Gateway..."
-	@cd mcp-servers/llm-gateway && make validate
-	@echo ""
-	@echo "Validating Knowledge Base..."
-	@cd mcp-servers/knowledge-base && make validate
-	@echo ""
-	@echo "Validating Git Operations..."
-	@cd mcp-servers/git-ops && make validate
-	@echo ""
-	@echo "All validations passed!"
-
-validate-all: validate
-	@echo ""
-	@echo "Validating frontend..."
-	@cd frontend && npm run validate
-	@echo ""
-	@echo "Full validation passed!"

README.md

@@ -1,175 +1,659 @@
-# Syndarix
+# <img src="frontend/public/logo.svg" alt="PragmaStack" width="32" height="32" style="vertical-align: middle" /> PragmaStack
 
-> **Your AI-Powered Software Consulting Agency**
->
-> An autonomous platform that orchestrates specialized AI agents to deliver complete software solutions with minimal human intervention.
+> **The Pragmatic Full-Stack Template. Production-ready, security-first, and opinionated.**
 
-[![Built on PragmaStack](https://img.shields.io/badge/Built_on-PragmaStack-blue)](https://gitea.pragmazest.com/cardosofelipe/fast-next-template)
+[![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)
+
+![Landing Page](docs/images/landing.png)
 
 ---
 
-## Vision
+## Why PragmaStack?
 
-Syndarix transforms the software development lifecycle by providing a **virtual consulting team** of AI agents that collaboratively plan, design, implement, test, and deliver complete software solutions.
+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.
 
-**The Problem:** Even with AI coding assistants, developers spend as much time managing AI as doing the work themselves. Context switching, babysitting, and knowledge fragmentation limit productivity.
+**PragmaStack cuts through the noise.**
 
-**The Solution:** A structured, autonomous agency where specialized AI agents handle different roles (Product Owner, Architect, Engineers, QA, etc.) with proper workflows, reviews, and quality gates.
+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.
 
 ---
 
-## Key Features
+## ✨ Features
 
-### Multi-Agent Orchestration
-- Configurable agent **types** with base model, failover, expertise, and personality
-- Spawn multiple **instances** from the same type (e.g., Dave, Ellis, Kate as Software Developers)
-- Agent-to-agent communication and collaboration
-- Per-instance customization with domain-specific knowledge
+### 🔐 **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)
 
-### Complete SDLC Support
-- **Requirements Discovery** → **Architecture Spike** → **Implementation Planning**
-- **Sprint Management** with automated ceremonies
-- **Issue Tracking** with Epic/Story/Task hierarchy
-- **Git Integration** with proper branch/PR workflows
-- **CI/CD Pipelines** with automated testing
+### 🔌 **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`
 
-### Configurable Autonomy
-- From `FULL_CONTROL` (approve everything) to `AUTONOMOUS` (only major milestones)
-- Client can intervene at any point
-- Transparent progress visibility
+### 👥 **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
 
-### MCP-First Architecture
-- All integrations via **Model Context Protocol (MCP)** servers
-- Unified Knowledge Base with project/agent scoping
-- Git providers (Gitea, GitHub, GitLab) via MCP
-- Extensible through custom MCP tools
+### 🛠️ **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
 
-### Project Complexity Wizard
-- **Script** → Minimal process, no repo needed
-- **Simple** → Single sprint, basic backlog
-- **Medium/Complex** → Full AGILE workflow with multiple sprints
+### 🎨 **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
 
 ---
 
-## Technology Stack
+## 📸 Screenshots
 
-Built on [PragmaStack](https://gitea.pragmazest.com/cardosofelipe/fast-next-template):
+<details>
+<summary>Click to view screenshots</summary>
 
-| Component | Technology |
-|-----------|------------|
-| Backend | FastAPI 0.115+ (Python 3.11+) |
-| Frontend | Next.js 16 (React 19) |
-| Database | PostgreSQL 15+ with pgvector |
-| ORM | SQLAlchemy 2.0 |
-| State Management | Zustand + TanStack Query |
-| UI | shadcn/ui + Tailwind 4 |
-| Auth | JWT dual-token + OAuth 2.0 |
-| Testing | pytest + Jest + Playwright |
+### Landing Page
+![Landing Page](docs/images/landing.png)
 
-### Syndarix Extensions
-| Component | Technology |
-|-----------|------------|
-| Task Queue | Celery + Redis |
-| Real-time | FastAPI WebSocket / SSE |
-| Vector DB | pgvector (PostgreSQL extension) |
-| MCP SDK | Anthropic MCP SDK |
+
+
+### 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>
 
 ---
 
-## Project Status
+## 🎭 Demo Mode
 
-**Phase:** Architecture & Planning
-
-See [docs/requirements/](./docs/requirements/) for the comprehensive requirements document.
-
-### Current Milestones
-- [x] Fork PragmaStack as foundation
-- [x] Create requirements document
-- [ ] Execute architecture spikes
-- [ ] Create ADRs for key decisions
-- [ ] Begin MVP implementation
-
----
-
-## Documentation
-
-- [Requirements Document](./docs/requirements/SYNDARIX_REQUIREMENTS.md)
-- [Architecture Decisions](./docs/adrs/) (coming soon)
-- [Spike Research](./docs/spikes/) (coming soon)
-- [Architecture Overview](./docs/architecture/) (coming soon)
-
----
-
-## Getting Started
-
-### Prerequisites
-- Docker & Docker Compose
-- Node.js 20+
-- Python 3.11+
-- PostgreSQL 15+ (or use Docker)
+**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
+
+```bash
+cd frontend
+echo "NEXT_PUBLIC_DEMO_MODE=true" > .env.local
+bun run dev
+```
+
+**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://gitea.pragmazest.com/cardosofelipe/syndarix.git
-cd syndarix
+git clone https://github.com/cardosofelipe/pragma-stack.git
+cd fast-next-template
 
-# Copy environment template
+# Copy environment file
 cp .env.template .env
 
-# Start development environment
-docker-compose -f docker-compose.dev.yml up -d
+# Start all services (backend, frontend, database)
+docker-compose up
 
-# Run database migrations
-make migrate
+# In another terminal, run database migrations
+docker-compose exec backend alembic upgrade head
 
-# Start the development servers
-make dev
+# Create first superuser (optional)
+docker-compose exec backend python -c "from app.init_db import init_db; import asyncio; asyncio.run(init_db())"
+```
+
+**That's it! 🎉**
+
+- Frontend: http://localhost:3000
+- Backend API: http://localhost:8000
+- API Docs: http://localhost:8000/docs
+
+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!
 ```
 
 ---
 
-## Architecture Overview
+## 🧪 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
 ```
-+====================================================================+
-|                         SYNDARIX CORE                               |
-+====================================================================+
-|  +------------------+  +------------------+  +------------------+   |
-|  | Agent Orchestrator|  | Project Manager |  | Workflow Engine  |   |
-|  +------------------+  +------------------+  +------------------+   |
-+====================================================================+
-                              |
-                              v
-+====================================================================+
-|                    MCP ORCHESTRATION LAYER                          |
-|  All integrations via unified MCP servers with project scoping      |
-+====================================================================+
-                              |
-     +------------------------+------------------------+
-     |                        |                        |
-+----v----+  +----v----+  +----v----+  +----v----+  +----v----+
-|   LLM   |  |   Git   |  |Knowledge|  |  File   |  |  Code   |
-| Providers|  |   MCP   |  |Base MCP |  |Sys. MCP |  |Analysis |
-+---------+  +---------+  +---------+  +---------+  +---------+
+
+**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
 ```
 
 ---
 
-## Contributing
+## 📖 Documentation
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+### 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
 
 ---
 
-## License
+## 🚢 Deployment
 
-MIT License - see [LICENSE](./LICENSE) for details.
+### 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
 
 ---
 
-## Acknowledgments
+## 🛣️ Roadmap & Status
 
-- Built on [PragmaStack](https://gitea.pragmazest.com/cardosofelipe/fast-next-template)
-- Powered by Claude and the Anthropic API
+### ✅ 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

@@ -11,7 +11,7 @@ omit =
     app/utils/auth_test_utils.py
 
     # Async implementations not yet in use
-    app/crud/base_async.py
+    app/repositories/base_async.py
     app/core/database_async.py
 
     # CLI scripts - run manually, not tested
@@ -23,7 +23,7 @@ omit =
     app/api/routes/__init__.py
     app/api/dependencies/__init__.py
     app/core/__init__.py
-    app/crud/__init__.py
+    app/repositories/__init__.py
     app/models/__init__.py
     app/schemas/__init__.py
     app/services/__init__.py

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/Dockerfile

@@ -7,10 +7,7 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONPATH=/app \
     UV_COMPILE_BYTECODE=1 \
     UV_LINK_MODE=copy \
-    UV_NO_CACHE=1 \
-    UV_PROJECT_ENVIRONMENT=/opt/venv \
-    VIRTUAL_ENV=/opt/venv \
-    PATH="/opt/venv/bin:$PATH"
+    UV_NO_CACHE=1
 
 # Install system dependencies and uv
 RUN apt-get update && \
@@ -23,7 +20,7 @@ RUN apt-get update && \
 # Copy dependency files
 COPY pyproject.toml uv.lock ./
 
-# Install dependencies using uv into /opt/venv (outside /app to survive bind mounts)
+# Install dependencies using uv (development mode with dev dependencies)
 RUN uv sync --extra dev --frozen
 
 # Copy application code
@@ -36,11 +33,11 @@ RUN chmod +x /usr/local/bin/entrypoint.sh
 
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
 
-# Production stage
-FROM python:3.12-slim AS production
+# Production stage — Alpine eliminates glibc CVEs (e.g. CVE-2026-0861)
+FROM python:3.12-alpine AS production
 
 # Create non-root user
-RUN groupadd -r appuser && useradd -r -g appuser appuser
+RUN addgroup -S appuser && adduser -S -G appuser appuser
 
 WORKDIR /app
 ENV PYTHONDONTWRITEBYTECODE=1 \
@@ -48,24 +45,21 @@ ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONPATH=/app \
     UV_COMPILE_BYTECODE=1 \
     UV_LINK_MODE=copy \
-    UV_NO_CACHE=1 \
-    UV_PROJECT_ENVIRONMENT=/opt/venv \
-    VIRTUAL_ENV=/opt/venv \
-    PATH="/opt/venv/bin:$PATH"
+    UV_NO_CACHE=1
 
 # Install system dependencies and uv
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends postgresql-client curl ca-certificates && \
+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/ && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
+    mv /root/.local/bin/uv* /usr/local/bin/
 
 # Copy dependency files
 COPY pyproject.toml uv.lock ./
 
-# Install only production dependencies using uv into /opt/venv
-RUN uv sync --frozen --no-dev
+# 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 . .
@@ -73,7 +67,7 @@ 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 /opt/venv
+RUN chown -R appuser:appuser /app
 
 # Switch to non-root user
 USER appuser
@@ -83,4 +77,4 @@ 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

@@ -1,4 +1,7 @@
-.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 test-integration
+.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:
@@ -14,17 +17,30 @@ help:
 	@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 mypy type checking"
-	@echo "  make validate      - Run all checks (lint + format + types)"
+	@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-integration - Run MCP integration tests (requires running stack)"
 	@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"
@@ -64,12 +80,52 @@ format-check:
 	@uv run ruff format --check app/ tests/
 
 type-check:
-	@echo "🔎 Running mypy type checking..."
-	@uv run mypy app/
+	@echo "🔎 Running pyright type checking..."
+	@uv run pyright app/
 
-validate: lint format-check type-check
+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
 # ============================================================================
@@ -80,18 +136,9 @@ test:
 
 test-cov:
 	@echo "🧪 Running tests with coverage..."
-	@IS_TEST=True PYTHONPATH=. uv run pytest --cov=app --cov-report=term-missing --cov-report=html -n 20
+	@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"
 
-# ============================================================================
-# Integration Testing (requires running stack: make dev)
-# ============================================================================
-
-test-integration:
-	@echo "🧪 Running MCP integration tests..."
-	@echo "Note: Requires running stack (make dev from project root)"
-	@RUN_INTEGRATION_TESTS=true IS_TEST=True PYTHONPATH=. uv run pytest tests/integration/ -v
-
 # ============================================================================
 # E2E Testing (requires Docker)
 # ============================================================================
@@ -124,6 +171,31 @@ 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
@@ -137,7 +209,7 @@ 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 ".mypy_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

backend/README.md

@@ -1,6 +1,6 @@
-# Syndarix Backend API
+# PragmaStack Backend API
 
-> The pragmatic, production-ready FastAPI backend for Syndarix.
+> The pragmatic, production-ready FastAPI backend for PragmaStack.
 
 ## Overview
 
@@ -14,7 +14,9 @@ Features:
 - **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, mypy for type checking
+- **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
 
@@ -149,7 +151,7 @@ uv pip list --outdated
 # Run any Python command via uv (no activation needed)
 uv run python script.py
 uv run pytest
-uv run mypy app/
+uv run pyright app/
 
 # Or activate the virtual environment
 source .venv/bin/activate
@@ -171,12 +173,22 @@ 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 mypy type checking
+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
@@ -252,7 +264,7 @@ app/
 │   ├── database.py   # Database engine setup
 │   ├── auth.py       # JWT token handling
 │   └── exceptions.py # Custom exceptions
-├── crud/             # Database operations
+├── repositories/     # Repository pattern (database operations)
 ├── models/           # SQLAlchemy ORM models
 ├── schemas/          # Pydantic request/response schemas
 ├── services/         # Business logic layer
@@ -352,18 +364,29 @@ open htmlcov/index.html
 # Using Makefile (recommended)
 make lint          # Ruff linting
 make format        # Ruff formatting
-make type-check    # mypy type checking
+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 mypy app/
+uv run pyright app/
 ```
 
 **Tools:**
 - **Ruff**: All-in-one linting, formatting, and import sorting (replaces Black, Flake8, isort)
-- **mypy**: Static type checking with Pydantic plugin
+- **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`.
 
@@ -439,7 +462,7 @@ 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 CRUD operations in `app/crud/`
+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/`
@@ -589,13 +612,42 @@ Configured in `app/core/config.py`:
 - **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)
+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`)
+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
 
 ---
 
@@ -645,7 +697,11 @@ logging.basicConfig(level=logging.INFO)
 **Built with modern Python tooling:**
 - 🚀 **uv** - 10-100x faster dependency management
 - ⚡ **Ruff** - 10-100x faster linting & formatting
-- 🔍 **mypy** - Static type checking
+- 🔍 **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/app/alembic/versions/0003_enable_pgvector_extension.py

@@ -1,66 +0,0 @@
-"""Enable pgvector extension
-
-Revision ID: 0003
-Revises: 0002
-Create Date: 2025-12-30
-
-This migration enables the pgvector extension for PostgreSQL, which provides
-vector similarity search capabilities required for the RAG (Retrieval-Augmented
-Generation) knowledge base system.
-
-Vector Dimension Reference (per ADR-008 and SPIKE-006):
----------------------------------------------------------
-The dimension size depends on the embedding model used:
-
-| Model                      | Dimensions | Use Case                    |
-|----------------------------|------------|------------------------------|
-| text-embedding-3-small     | 1536       | General docs, conversations  |
-| text-embedding-3-large     | 256-3072   | High accuracy (configurable) |
-| voyage-code-3              | 1024       | Code files (Python, JS, etc) |
-| voyage-3-large             | 1024       | High quality general purpose |
-| nomic-embed-text (Ollama)  | 768        | Local/fallback embedding     |
-
-Recommended defaults for Syndarix:
-- Documentation/conversations: 1536 (text-embedding-3-small)
-- Code files: 1024 (voyage-code-3)
-
-Prerequisites:
---------------
-This migration requires PostgreSQL with the pgvector extension installed.
-The Docker Compose configuration uses `pgvector/pgvector:pg17` which includes
-the extension pre-installed.
-
-References:
------------
-- ADR-008: Knowledge Base and RAG Architecture
-- SPIKE-006: Knowledge Base with pgvector for RAG System
-- https://github.com/pgvector/pgvector
-"""
-
-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:
-    """Enable the pgvector extension.
-
-    The CREATE EXTENSION IF NOT EXISTS statement is idempotent - it will
-    succeed whether the extension already exists or not.
-    """
-    op.execute("CREATE EXTENSION IF NOT EXISTS vector")
-
-
-def downgrade() -> None:
-    """Drop the pgvector extension.
-
-    Note: This will fail if any tables with vector columns exist.
-    Future migrations that create vector columns should be downgraded first.
-    """
-    op.execute("DROP EXTENSION IF EXISTS vector")

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/0004_add_syndarix_models.py

@@ -1,507 +0,0 @@
-"""Add Syndarix models
-
-Revision ID: 0004
-Revises: 0003
-Create Date: 2025-12-31
-
-This migration creates the core Syndarix domain tables:
-- projects: Client engagement projects
-- agent_types: Agent template configurations
-- agent_instances: Spawned agent instances assigned to projects
-- sprints: Sprint containers for issues
-- issues: Work items (epics, stories, tasks, bugs)
-"""
-
-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 = "0004"
-down_revision: str | None = "0003"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def upgrade() -> None:
-    """Create Syndarix domain tables."""
-
-    # =========================================================================
-    # Create projects table
-    # Note: ENUM types are created automatically by sa.Enum() during table creation
-    # =========================================================================
-    op.create_table(
-        "projects",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("name", sa.String(255), nullable=False),
-        sa.Column("slug", sa.String(255), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        sa.Column(
-            "autonomy_level",
-            sa.Enum(
-                "full_control",
-                "milestone",
-                "autonomous",
-                name="autonomy_level",
-            ),
-            nullable=False,
-            server_default="milestone",
-        ),
-        sa.Column(
-            "status",
-            sa.Enum(
-                "active",
-                "paused",
-                "completed",
-                "archived",
-                name="project_status",
-            ),
-            nullable=False,
-            server_default="active",
-        ),
-        sa.Column(
-            "complexity",
-            sa.Enum(
-                "script",
-                "simple",
-                "medium",
-                "complex",
-                name="project_complexity",
-            ),
-            nullable=False,
-            server_default="medium",
-        ),
-        sa.Column(
-            "client_mode",
-            sa.Enum("technical", "auto", name="client_mode"),
-            nullable=False,
-            server_default="auto",
-        ),
-        sa.Column(
-            "settings",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="{}",
-        ),
-        sa.Column("owner_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(["owner_id"], ["users.id"], ondelete="SET NULL"),
-        sa.UniqueConstraint("slug"),
-    )
-    # Single column indexes
-    op.create_index("ix_projects_name", "projects", ["name"])
-    op.create_index("ix_projects_slug", "projects", ["slug"])
-    op.create_index("ix_projects_status", "projects", ["status"])
-    op.create_index("ix_projects_autonomy_level", "projects", ["autonomy_level"])
-    op.create_index("ix_projects_complexity", "projects", ["complexity"])
-    op.create_index("ix_projects_client_mode", "projects", ["client_mode"])
-    op.create_index("ix_projects_owner_id", "projects", ["owner_id"])
-    # Composite indexes
-    op.create_index("ix_projects_slug_status", "projects", ["slug", "status"])
-    op.create_index("ix_projects_owner_status", "projects", ["owner_id", "status"])
-    op.create_index(
-        "ix_projects_autonomy_status", "projects", ["autonomy_level", "status"]
-    )
-    op.create_index(
-        "ix_projects_complexity_status", "projects", ["complexity", "status"]
-    )
-
-    # =========================================================================
-    # Create agent_types table
-    # =========================================================================
-    op.create_table(
-        "agent_types",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("name", sa.String(255), nullable=False),
-        sa.Column("slug", sa.String(255), nullable=False),
-        sa.Column("description", sa.Text(), nullable=True),
-        # Areas of expertise (e.g., ["python", "fastapi", "databases"])
-        sa.Column(
-            "expertise",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        # System prompt defining personality and behavior (required)
-        sa.Column("personality_prompt", sa.Text(), nullable=False),
-        # LLM model configuration
-        sa.Column("primary_model", sa.String(100), nullable=False),
-        sa.Column(
-            "fallback_models",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        # Model parameters (temperature, max_tokens, etc.)
-        sa.Column(
-            "model_params",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="{}",
-        ),
-        # MCP servers this agent can connect to
-        sa.Column(
-            "mcp_servers",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        # Tool permissions configuration
-        sa.Column(
-            "tool_permissions",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="{}",
-        ),
-        sa.Column("is_active", sa.Boolean(), nullable=False, server_default="true"),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint("slug"),
-    )
-    # Single column indexes
-    op.create_index("ix_agent_types_name", "agent_types", ["name"])
-    op.create_index("ix_agent_types_slug", "agent_types", ["slug"])
-    op.create_index("ix_agent_types_is_active", "agent_types", ["is_active"])
-    # Composite indexes
-    op.create_index("ix_agent_types_slug_active", "agent_types", ["slug", "is_active"])
-    op.create_index("ix_agent_types_name_active", "agent_types", ["name", "is_active"])
-
-    # =========================================================================
-    # Create agent_instances table
-    # =========================================================================
-    op.create_table(
-        "agent_instances",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("agent_type_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("name", sa.String(100), nullable=False),
-        sa.Column(
-            "status",
-            sa.Enum(
-                "idle",
-                "working",
-                "waiting",
-                "paused",
-                "terminated",
-                name="agent_status",
-            ),
-            nullable=False,
-            server_default="idle",
-        ),
-        sa.Column("current_task", sa.Text(), nullable=True),
-        # Short-term memory (conversation context, recent decisions)
-        sa.Column(
-            "short_term_memory",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="{}",
-        ),
-        # Reference to long-term memory in vector store
-        sa.Column("long_term_memory_ref", sa.String(500), nullable=True),
-        # Session ID for active MCP connections
-        sa.Column("session_id", sa.String(255), nullable=True),
-        # Activity tracking
-        sa.Column("last_activity_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("terminated_at", sa.DateTime(timezone=True), nullable=True),
-        # Usage metrics
-        sa.Column("tasks_completed", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("tokens_used", sa.BigInteger(), nullable=False, server_default="0"),
-        sa.Column(
-            "cost_incurred",
-            sa.Numeric(precision=10, scale=4),
-            nullable=False,
-            server_default="0",
-        ),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(
-            ["agent_type_id"], ["agent_types.id"], ondelete="RESTRICT"
-        ),
-        sa.ForeignKeyConstraint(["project_id"], ["projects.id"], ondelete="CASCADE"),
-    )
-    # Single column indexes
-    op.create_index("ix_agent_instances_name", "agent_instances", ["name"])
-    op.create_index("ix_agent_instances_status", "agent_instances", ["status"])
-    op.create_index(
-        "ix_agent_instances_agent_type_id", "agent_instances", ["agent_type_id"]
-    )
-    op.create_index("ix_agent_instances_project_id", "agent_instances", ["project_id"])
-    op.create_index("ix_agent_instances_session_id", "agent_instances", ["session_id"])
-    op.create_index(
-        "ix_agent_instances_last_activity_at", "agent_instances", ["last_activity_at"]
-    )
-    op.create_index(
-        "ix_agent_instances_terminated_at", "agent_instances", ["terminated_at"]
-    )
-    # Composite indexes
-    op.create_index(
-        "ix_agent_instances_project_status",
-        "agent_instances",
-        ["project_id", "status"],
-    )
-    op.create_index(
-        "ix_agent_instances_type_status",
-        "agent_instances",
-        ["agent_type_id", "status"],
-    )
-    op.create_index(
-        "ix_agent_instances_project_type",
-        "agent_instances",
-        ["project_id", "agent_type_id"],
-    )
-
-    # =========================================================================
-    # Create sprints table (before issues for FK reference)
-    # =========================================================================
-    op.create_table(
-        "sprints",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("name", sa.String(255), nullable=False),
-        sa.Column("number", sa.Integer(), nullable=False),
-        sa.Column("goal", sa.Text(), nullable=True),
-        sa.Column("start_date", sa.Date(), nullable=False),
-        sa.Column("end_date", sa.Date(), nullable=False),
-        sa.Column(
-            "status",
-            sa.Enum(
-                "planned",
-                "active",
-                "in_review",
-                "completed",
-                "cancelled",
-                name="sprint_status",
-            ),
-            nullable=False,
-            server_default="planned",
-        ),
-        sa.Column("planned_points", sa.Integer(), nullable=True),
-        sa.Column("velocity", sa.Integer(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(["project_id"], ["projects.id"], ondelete="CASCADE"),
-        sa.UniqueConstraint("project_id", "number", name="uq_sprint_project_number"),
-    )
-    # Single column indexes
-    op.create_index("ix_sprints_project_id", "sprints", ["project_id"])
-    op.create_index("ix_sprints_status", "sprints", ["status"])
-    op.create_index("ix_sprints_start_date", "sprints", ["start_date"])
-    op.create_index("ix_sprints_end_date", "sprints", ["end_date"])
-    # Composite indexes
-    op.create_index("ix_sprints_project_status", "sprints", ["project_id", "status"])
-    op.create_index("ix_sprints_project_number", "sprints", ["project_id", "number"])
-    op.create_index("ix_sprints_date_range", "sprints", ["start_date", "end_date"])
-
-    # =========================================================================
-    # Create issues table
-    # =========================================================================
-    op.create_table(
-        "issues",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
-        # Parent issue for hierarchy (Epic -> Story -> Task)
-        sa.Column("parent_id", postgresql.UUID(as_uuid=True), nullable=True),
-        # Issue type (epic, story, task, bug)
-        sa.Column(
-            "type",
-            sa.Enum(
-                "epic",
-                "story",
-                "task",
-                "bug",
-                name="issue_type",
-            ),
-            nullable=False,
-            server_default="task",
-        ),
-        # Reporter (who created this issue)
-        sa.Column("reporter_id", postgresql.UUID(as_uuid=True), nullable=True),
-        # Issue content
-        sa.Column("title", sa.String(500), nullable=False),
-        sa.Column("body", sa.Text(), nullable=False, server_default=""),
-        # Status and priority
-        sa.Column(
-            "status",
-            sa.Enum(
-                "open",
-                "in_progress",
-                "in_review",
-                "blocked",
-                "closed",
-                name="issue_status",
-            ),
-            nullable=False,
-            server_default="open",
-        ),
-        sa.Column(
-            "priority",
-            sa.Enum(
-                "low",
-                "medium",
-                "high",
-                "critical",
-                name="issue_priority",
-            ),
-            nullable=False,
-            server_default="medium",
-        ),
-        # Labels for categorization
-        sa.Column(
-            "labels",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        # Assignment - agent or human (mutually exclusive)
-        sa.Column("assigned_agent_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("human_assignee", sa.String(255), nullable=True),
-        # Sprint association
-        sa.Column("sprint_id", postgresql.UUID(as_uuid=True), nullable=True),
-        # Estimation
-        sa.Column("story_points", sa.Integer(), nullable=True),
-        sa.Column("due_date", sa.Date(), nullable=True),
-        # External tracker integration (String for flexibility)
-        sa.Column("external_tracker_type", sa.String(50), nullable=True),
-        sa.Column("external_issue_id", sa.String(255), nullable=True),
-        sa.Column("remote_url", sa.String(1000), nullable=True),
-        sa.Column("external_issue_number", sa.Integer(), nullable=True),
-        # Sync status
-        sa.Column(
-            "sync_status",
-            sa.Enum(
-                "synced",
-                "pending",
-                "conflict",
-                "error",
-                name="sync_status",
-            ),
-            nullable=False,
-            server_default="synced",
-        ),
-        sa.Column("last_synced_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("external_updated_at", sa.DateTime(timezone=True), nullable=True),
-        # Lifecycle
-        sa.Column("closed_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(["project_id"], ["projects.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["parent_id"], ["issues.id"], ondelete="CASCADE"),
-        sa.ForeignKeyConstraint(["sprint_id"], ["sprints.id"], ondelete="SET NULL"),
-        sa.ForeignKeyConstraint(
-            ["assigned_agent_id"], ["agent_instances.id"], ondelete="SET NULL"
-        ),
-    )
-    # Single column indexes
-    op.create_index("ix_issues_project_id", "issues", ["project_id"])
-    op.create_index("ix_issues_parent_id", "issues", ["parent_id"])
-    op.create_index("ix_issues_type", "issues", ["type"])
-    op.create_index("ix_issues_reporter_id", "issues", ["reporter_id"])
-    op.create_index("ix_issues_status", "issues", ["status"])
-    op.create_index("ix_issues_priority", "issues", ["priority"])
-    op.create_index("ix_issues_assigned_agent_id", "issues", ["assigned_agent_id"])
-    op.create_index("ix_issues_human_assignee", "issues", ["human_assignee"])
-    op.create_index("ix_issues_sprint_id", "issues", ["sprint_id"])
-    op.create_index("ix_issues_due_date", "issues", ["due_date"])
-    op.create_index(
-        "ix_issues_external_tracker_type", "issues", ["external_tracker_type"]
-    )
-    op.create_index("ix_issues_sync_status", "issues", ["sync_status"])
-    op.create_index("ix_issues_closed_at", "issues", ["closed_at"])
-    # Composite indexes
-    op.create_index("ix_issues_project_status", "issues", ["project_id", "status"])
-    op.create_index("ix_issues_project_priority", "issues", ["project_id", "priority"])
-    op.create_index("ix_issues_project_sprint", "issues", ["project_id", "sprint_id"])
-    op.create_index("ix_issues_project_type", "issues", ["project_id", "type"])
-    op.create_index(
-        "ix_issues_project_agent", "issues", ["project_id", "assigned_agent_id"]
-    )
-    op.create_index(
-        "ix_issues_project_status_priority",
-        "issues",
-        ["project_id", "status", "priority"],
-    )
-    op.create_index(
-        "ix_issues_external_tracker_id",
-        "issues",
-        ["external_tracker_type", "external_issue_id"],
-    )
-
-
-def downgrade() -> None:
-    """Drop Syndarix domain tables."""
-    # Drop tables in reverse order (respecting FK constraints)
-    op.drop_table("issues")
-    op.drop_table("sprints")
-    op.drop_table("agent_instances")
-    op.drop_table("agent_types")
-    op.drop_table("projects")
-
-    # Drop ENUM types
-    op.execute("DROP TYPE IF EXISTS sprint_status")
-    op.execute("DROP TYPE IF EXISTS sync_status")
-    op.execute("DROP TYPE IF EXISTS issue_priority")
-    op.execute("DROP TYPE IF EXISTS issue_status")
-    op.execute("DROP TYPE IF EXISTS issue_type")
-    op.execute("DROP TYPE IF EXISTS agent_status")
-    op.execute("DROP TYPE IF EXISTS client_mode")
-    op.execute("DROP TYPE IF EXISTS project_complexity")
-    op.execute("DROP TYPE IF EXISTS project_status")
-    op.execute("DROP TYPE IF EXISTS autonomy_level")

backend/app/alembic/versions/0005_add_memory_system_tables.py

@@ -1,512 +0,0 @@
-"""Add Agent Memory System tables
-
-Revision ID: 0005
-Revises: 0004
-Create Date: 2025-01-05
-
-This migration creates the Agent Memory System tables:
-- working_memory: Key-value storage with TTL for active sessions
-- episodes: Experiential memories from task executions
-- facts: Semantic knowledge triples with confidence scores
-- procedures: Learned skills and procedures
-- memory_consolidation_log: Tracks consolidation jobs
-
-See Issue #88: Database Schema & Storage Layer
-"""
-
-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 = "0005"
-down_revision: str | None = "0004"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def upgrade() -> None:
-    """Create Agent Memory System tables."""
-
-    # =========================================================================
-    # Create ENUM types for memory system
-    # =========================================================================
-
-    # Scope type enum
-    scope_type_enum = postgresql.ENUM(
-        "global",
-        "project",
-        "agent_type",
-        "agent_instance",
-        "session",
-        name="scope_type",
-        create_type=False,
-    )
-    scope_type_enum.create(op.get_bind(), checkfirst=True)
-
-    # Episode outcome enum
-    episode_outcome_enum = postgresql.ENUM(
-        "success",
-        "failure",
-        "partial",
-        name="episode_outcome",
-        create_type=False,
-    )
-    episode_outcome_enum.create(op.get_bind(), checkfirst=True)
-
-    # Consolidation type enum
-    consolidation_type_enum = postgresql.ENUM(
-        "working_to_episodic",
-        "episodic_to_semantic",
-        "episodic_to_procedural",
-        "pruning",
-        name="consolidation_type",
-        create_type=False,
-    )
-    consolidation_type_enum.create(op.get_bind(), checkfirst=True)
-
-    # Consolidation status enum
-    consolidation_status_enum = postgresql.ENUM(
-        "pending",
-        "running",
-        "completed",
-        "failed",
-        name="consolidation_status",
-        create_type=False,
-    )
-    consolidation_status_enum.create(op.get_bind(), checkfirst=True)
-
-    # =========================================================================
-    # Create working_memory table
-    # Key-value storage with TTL for active sessions
-    # =========================================================================
-    op.create_table(
-        "working_memory",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column(
-            "scope_type",
-            scope_type_enum,
-            nullable=False,
-        ),
-        sa.Column("scope_id", sa.String(255), nullable=False),
-        sa.Column("key", sa.String(255), nullable=False),
-        sa.Column("value", postgresql.JSONB(astext_type=sa.Text()), nullable=False),
-        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-    )
-
-    # Working memory indexes
-    op.create_index(
-        "ix_working_memory_scope_type",
-        "working_memory",
-        ["scope_type"],
-    )
-    op.create_index(
-        "ix_working_memory_scope_id",
-        "working_memory",
-        ["scope_id"],
-    )
-    op.create_index(
-        "ix_working_memory_scope_key",
-        "working_memory",
-        ["scope_type", "scope_id", "key"],
-        unique=True,
-    )
-    op.create_index(
-        "ix_working_memory_expires",
-        "working_memory",
-        ["expires_at"],
-    )
-    op.create_index(
-        "ix_working_memory_scope_list",
-        "working_memory",
-        ["scope_type", "scope_id"],
-    )
-
-    # =========================================================================
-    # Create episodes table
-    # Experiential memories from task executions
-    # =========================================================================
-    op.create_table(
-        "episodes",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("agent_instance_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("agent_type_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("session_id", sa.String(255), nullable=False),
-        sa.Column("task_type", sa.String(100), nullable=False),
-        sa.Column("task_description", sa.Text(), nullable=False),
-        sa.Column(
-            "actions",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        sa.Column("context_summary", sa.Text(), nullable=False),
-        sa.Column(
-            "outcome",
-            episode_outcome_enum,
-            nullable=False,
-        ),
-        sa.Column("outcome_details", sa.Text(), nullable=True),
-        sa.Column("duration_seconds", sa.Float(), nullable=False, server_default="0.0"),
-        sa.Column("tokens_used", sa.BigInteger(), nullable=False, server_default="0"),
-        sa.Column(
-            "lessons_learned",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        sa.Column("importance_score", sa.Float(), nullable=False, server_default="0.5"),
-        # Vector embedding - using TEXT as fallback, will be VECTOR(1536) when pgvector is available
-        sa.Column("embedding", sa.Text(), nullable=True),
-        sa.Column("occurred_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(
-            ["project_id"],
-            ["projects.id"],
-            name="fk_episodes_project",
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["agent_instance_id"],
-            ["agent_instances.id"],
-            name="fk_episodes_agent_instance",
-            ondelete="SET NULL",
-        ),
-        sa.ForeignKeyConstraint(
-            ["agent_type_id"],
-            ["agent_types.id"],
-            name="fk_episodes_agent_type",
-            ondelete="SET NULL",
-        ),
-    )
-
-    # Episode indexes
-    op.create_index("ix_episodes_project_id", "episodes", ["project_id"])
-    op.create_index("ix_episodes_agent_instance_id", "episodes", ["agent_instance_id"])
-    op.create_index("ix_episodes_agent_type_id", "episodes", ["agent_type_id"])
-    op.create_index("ix_episodes_session_id", "episodes", ["session_id"])
-    op.create_index("ix_episodes_task_type", "episodes", ["task_type"])
-    op.create_index("ix_episodes_outcome", "episodes", ["outcome"])
-    op.create_index("ix_episodes_importance_score", "episodes", ["importance_score"])
-    op.create_index("ix_episodes_occurred_at", "episodes", ["occurred_at"])
-    op.create_index("ix_episodes_project_task", "episodes", ["project_id", "task_type"])
-    op.create_index(
-        "ix_episodes_project_outcome", "episodes", ["project_id", "outcome"]
-    )
-    op.create_index(
-        "ix_episodes_agent_task", "episodes", ["agent_instance_id", "task_type"]
-    )
-    op.create_index(
-        "ix_episodes_project_time", "episodes", ["project_id", "occurred_at"]
-    )
-    op.create_index(
-        "ix_episodes_importance_time",
-        "episodes",
-        ["importance_score", "occurred_at"],
-    )
-
-    # =========================================================================
-    # Create facts table
-    # Semantic knowledge triples with confidence scores
-    # =========================================================================
-    op.create_table(
-        "facts",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column(
-            "project_id", postgresql.UUID(as_uuid=True), nullable=True
-        ),  # NULL for global facts
-        sa.Column("subject", sa.String(500), nullable=False),
-        sa.Column("predicate", sa.String(255), nullable=False),
-        sa.Column("object", sa.Text(), nullable=False),
-        sa.Column("confidence", sa.Float(), nullable=False, server_default="0.8"),
-        # Source episode IDs stored as JSON array of UUID strings for cross-db compatibility
-        sa.Column(
-            "source_episode_ids",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        sa.Column("first_learned", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("last_reinforced", sa.DateTime(timezone=True), nullable=False),
-        sa.Column(
-            "reinforcement_count", sa.Integer(), nullable=False, server_default="1"
-        ),
-        # Vector embedding
-        sa.Column("embedding", sa.Text(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(
-            ["project_id"],
-            ["projects.id"],
-            name="fk_facts_project",
-            ondelete="CASCADE",
-        ),
-    )
-
-    # Fact indexes
-    op.create_index("ix_facts_project_id", "facts", ["project_id"])
-    op.create_index("ix_facts_subject", "facts", ["subject"])
-    op.create_index("ix_facts_predicate", "facts", ["predicate"])
-    op.create_index("ix_facts_confidence", "facts", ["confidence"])
-    op.create_index("ix_facts_subject_predicate", "facts", ["subject", "predicate"])
-    op.create_index("ix_facts_project_subject", "facts", ["project_id", "subject"])
-    op.create_index(
-        "ix_facts_confidence_time", "facts", ["confidence", "last_reinforced"]
-    )
-    # Unique constraint for triples within project scope
-    op.create_index(
-        "ix_facts_unique_triple",
-        "facts",
-        ["project_id", "subject", "predicate", "object"],
-        unique=True,
-        postgresql_where=sa.text("project_id IS NOT NULL"),
-    )
-    # Unique constraint for global facts (project_id IS NULL)
-    op.create_index(
-        "ix_facts_unique_triple_global",
-        "facts",
-        ["subject", "predicate", "object"],
-        unique=True,
-        postgresql_where=sa.text("project_id IS NULL"),
-    )
-
-    # =========================================================================
-    # Create procedures table
-    # Learned skills and procedures
-    # =========================================================================
-    op.create_table(
-        "procedures",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column("project_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("agent_type_id", postgresql.UUID(as_uuid=True), nullable=True),
-        sa.Column("name", sa.String(255), nullable=False),
-        sa.Column("trigger_pattern", sa.Text(), nullable=False),
-        sa.Column(
-            "steps",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-        sa.Column("success_count", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("failure_count", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("last_used", sa.DateTime(timezone=True), nullable=True),
-        # Vector embedding
-        sa.Column("embedding", sa.Text(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.ForeignKeyConstraint(
-            ["project_id"],
-            ["projects.id"],
-            name="fk_procedures_project",
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["agent_type_id"],
-            ["agent_types.id"],
-            name="fk_procedures_agent_type",
-            ondelete="SET NULL",
-        ),
-    )
-
-    # Procedure indexes
-    op.create_index("ix_procedures_project_id", "procedures", ["project_id"])
-    op.create_index("ix_procedures_agent_type_id", "procedures", ["agent_type_id"])
-    op.create_index("ix_procedures_name", "procedures", ["name"])
-    op.create_index("ix_procedures_last_used", "procedures", ["last_used"])
-    op.create_index(
-        "ix_procedures_unique_name",
-        "procedures",
-        ["project_id", "agent_type_id", "name"],
-        unique=True,
-    )
-    op.create_index("ix_procedures_project_name", "procedures", ["project_id", "name"])
-    # Note: agent_type_id already indexed via ix_procedures_agent_type_id (line 354)
-    op.create_index(
-        "ix_procedures_success_rate",
-        "procedures",
-        ["success_count", "failure_count"],
-    )
-
-    # =========================================================================
-    # Add check constraints for data integrity
-    # =========================================================================
-
-    # Episode constraints
-    op.create_check_constraint(
-        "ck_episodes_importance_range",
-        "episodes",
-        "importance_score >= 0.0 AND importance_score <= 1.0",
-    )
-    op.create_check_constraint(
-        "ck_episodes_duration_positive",
-        "episodes",
-        "duration_seconds >= 0.0",
-    )
-    op.create_check_constraint(
-        "ck_episodes_tokens_positive",
-        "episodes",
-        "tokens_used >= 0",
-    )
-
-    # Fact constraints
-    op.create_check_constraint(
-        "ck_facts_confidence_range",
-        "facts",
-        "confidence >= 0.0 AND confidence <= 1.0",
-    )
-    op.create_check_constraint(
-        "ck_facts_reinforcement_positive",
-        "facts",
-        "reinforcement_count >= 1",
-    )
-
-    # Procedure constraints
-    op.create_check_constraint(
-        "ck_procedures_success_positive",
-        "procedures",
-        "success_count >= 0",
-    )
-    op.create_check_constraint(
-        "ck_procedures_failure_positive",
-        "procedures",
-        "failure_count >= 0",
-    )
-
-    # =========================================================================
-    # Create memory_consolidation_log table
-    # Tracks consolidation jobs
-    # =========================================================================
-    op.create_table(
-        "memory_consolidation_log",
-        sa.Column("id", postgresql.UUID(as_uuid=True), nullable=False),
-        sa.Column(
-            "consolidation_type",
-            consolidation_type_enum,
-            nullable=False,
-        ),
-        sa.Column("source_count", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("result_count", sa.Integer(), nullable=False, server_default="0"),
-        sa.Column("started_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("completed_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column(
-            "status",
-            consolidation_status_enum,
-            nullable=False,
-            server_default="pending",
-        ),
-        sa.Column("error", sa.Text(), nullable=True),
-        sa.Column(
-            "created_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.Column(
-            "updated_at",
-            sa.DateTime(timezone=True),
-            nullable=False,
-            server_default=sa.text("now()"),
-        ),
-        sa.PrimaryKeyConstraint("id"),
-    )
-
-    # Consolidation log indexes
-    op.create_index(
-        "ix_consolidation_type",
-        "memory_consolidation_log",
-        ["consolidation_type"],
-    )
-    op.create_index(
-        "ix_consolidation_status",
-        "memory_consolidation_log",
-        ["status"],
-    )
-    op.create_index(
-        "ix_consolidation_type_status",
-        "memory_consolidation_log",
-        ["consolidation_type", "status"],
-    )
-    op.create_index(
-        "ix_consolidation_started",
-        "memory_consolidation_log",
-        ["started_at"],
-    )
-
-
-def downgrade() -> None:
-    """Drop Agent Memory System tables."""
-
-    # Drop check constraints first
-    op.drop_constraint("ck_procedures_failure_positive", "procedures", type_="check")
-    op.drop_constraint("ck_procedures_success_positive", "procedures", type_="check")
-    op.drop_constraint("ck_facts_reinforcement_positive", "facts", type_="check")
-    op.drop_constraint("ck_facts_confidence_range", "facts", type_="check")
-    op.drop_constraint("ck_episodes_tokens_positive", "episodes", type_="check")
-    op.drop_constraint("ck_episodes_duration_positive", "episodes", type_="check")
-    op.drop_constraint("ck_episodes_importance_range", "episodes", type_="check")
-
-    # Drop unique indexes for global facts
-    op.drop_index("ix_facts_unique_triple_global", "facts")
-
-    # Drop tables in reverse order (dependencies first)
-    op.drop_table("memory_consolidation_log")
-    op.drop_table("procedures")
-    op.drop_table("facts")
-    op.drop_table("episodes")
-    op.drop_table("working_memory")
-
-    # Drop ENUM types
-    op.execute("DROP TYPE IF EXISTS consolidation_status")
-    op.execute("DROP TYPE IF EXISTS consolidation_type")
-    op.execute("DROP TYPE IF EXISTS episode_outcome")
-    op.execute("DROP TYPE IF EXISTS scope_type")

backend/app/alembic/versions/0006_add_abandoned_outcome.py

@@ -1,52 +0,0 @@
-"""Add ABANDONED to episode_outcome enum
-
-Revision ID: 0006
-Revises: 0005
-Create Date: 2025-01-06
-
-This migration adds the 'abandoned' value to the episode_outcome enum type.
-This allows episodes to track when a task was abandoned (not completed,
-but not necessarily a failure either - e.g., user cancelled, session timeout).
-"""
-
-from collections.abc import Sequence
-
-from alembic import op
-
-# revision identifiers, used by Alembic.
-revision: str = "0006"
-down_revision: str | None = "0005"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def upgrade() -> None:
-    """Add 'abandoned' value to episode_outcome enum."""
-    # PostgreSQL ALTER TYPE ADD VALUE is safe and non-blocking
-    op.execute("ALTER TYPE episode_outcome ADD VALUE IF NOT EXISTS 'abandoned'")
-
-
-def downgrade() -> None:
-    """Remove 'abandoned' from episode_outcome enum.
-
-    Note: PostgreSQL doesn't support removing values from enums directly.
-    This downgrade converts any 'abandoned' episodes to 'failure' and
-    recreates the enum without 'abandoned'.
-    """
-    # Convert any abandoned episodes to failure first
-    op.execute("""
-        UPDATE episodes
-        SET outcome = 'failure'
-        WHERE outcome = 'abandoned'
-    """)
-
-    # Recreate the enum without abandoned
-    # This is complex in PostgreSQL - requires creating new type, updating columns, dropping old
-    op.execute("ALTER TYPE episode_outcome RENAME TO episode_outcome_old")
-    op.execute("CREATE TYPE episode_outcome AS ENUM ('success', 'failure', 'partial')")
-    op.execute("""
-        ALTER TABLE episodes
-        ALTER COLUMN outcome TYPE episode_outcome
-        USING outcome::text::episode_outcome
-    """)
-    op.execute("DROP TYPE episode_outcome_old")

backend/app/alembic/versions/0007_add_agent_type_category_fields.py

@@ -1,90 +0,0 @@
-"""Add category and display fields to agent_types table
-
-Revision ID: 0007
-Revises: 0006
-Create Date: 2026-01-06
-
-This migration adds:
-- category: String(50) for grouping agents by role type
-- icon: String(50) for Lucide icon identifier
-- color: String(7) for hex color code
-- sort_order: Integer for display ordering within categories
-- typical_tasks: JSONB list of tasks this agent excels at
-- collaboration_hints: JSONB list of agent slugs that work well together
-"""
-
-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 = "0007"
-down_revision: str | None = "0006"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def upgrade() -> None:
-    """Add category and display fields to agent_types table."""
-    # Add new columns
-    op.add_column(
-        "agent_types",
-        sa.Column("category", sa.String(length=50), nullable=True),
-    )
-    op.add_column(
-        "agent_types",
-        sa.Column("icon", sa.String(length=50), nullable=True, server_default="bot"),
-    )
-    op.add_column(
-        "agent_types",
-        sa.Column(
-            "color", sa.String(length=7), nullable=True, server_default="#3B82F6"
-        ),
-    )
-    op.add_column(
-        "agent_types",
-        sa.Column("sort_order", sa.Integer(), nullable=False, server_default="0"),
-    )
-    op.add_column(
-        "agent_types",
-        sa.Column(
-            "typical_tasks",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-    )
-    op.add_column(
-        "agent_types",
-        sa.Column(
-            "collaboration_hints",
-            postgresql.JSONB(astext_type=sa.Text()),
-            nullable=False,
-            server_default="[]",
-        ),
-    )
-
-    # Add indexes for category and sort_order
-    op.create_index("ix_agent_types_category", "agent_types", ["category"])
-    op.create_index("ix_agent_types_sort_order", "agent_types", ["sort_order"])
-    op.create_index(
-        "ix_agent_types_category_sort", "agent_types", ["category", "sort_order"]
-    )
-
-
-def downgrade() -> None:
-    """Remove category and display fields from agent_types table."""
-    # Drop indexes
-    op.drop_index("ix_agent_types_category_sort", table_name="agent_types")
-    op.drop_index("ix_agent_types_sort_order", table_name="agent_types")
-    op.drop_index("ix_agent_types_category", table_name="agent_types")
-
-    # Drop columns
-    op.drop_column("agent_types", "collaboration_hints")
-    op.drop_column("agent_types", "typical_tasks")
-    op.drop_column("agent_types", "sort_order")
-    op.drop_column("agent_types", "color")
-    op.drop_column("agent_types", "icon")
-    op.drop_column("agent_types", "category")

backend/app/api/dependencies/auth.py

@@ -1,12 +1,12 @@
 from fastapi import Depends, Header, HTTPException, status
 from fastapi.security import OAuth2PasswordBearer
 from fastapi.security.utils import get_authorization_scheme_param
-from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 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")
@@ -32,9 +32,8 @@ async def get_current_user(
         # Decode token and get user ID
         token_data = get_token_data(token)
 
-        # Get user from database
-        result = await db.execute(select(User).where(User.id == token_data.user_id))
-        user = result.scalar_one_or_none()
+        # Get user from database via repository
+        user = await user_repo.get(db, id=str(token_data.user_id))
 
         if not user:
             raise HTTPException(
@@ -144,90 +143,9 @@ async def get_optional_current_user(
 
     try:
         token_data = get_token_data(token)
-        result = await db.execute(select(User).where(User.id == token_data.user_id))
-        user = result.scalar_one_or_none()
+        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
-
-
-async def get_current_user_sse(
-    db: AsyncSession = Depends(get_db),
-    authorization: str | None = Header(None),
-    token: str | None = None,  # Query parameter - passed directly from route
-) -> User:
-    """
-    Get the current authenticated user for SSE endpoints.
-
-    SSE (Server-Sent Events) via EventSource API doesn't support custom headers,
-    so this dependency accepts tokens from either:
-    1. Authorization header (preferred, for non-EventSource clients)
-    2. Query parameter 'token' (fallback for EventSource compatibility)
-
-    Security note: Query parameter tokens appear in server logs and browser history.
-    Consider implementing short-lived SSE-specific tokens for production if this
-    is a concern. The current approach is acceptable for internal/trusted networks.
-
-    Args:
-        db: Database session
-        authorization: Authorization header (Bearer token)
-        token: Query parameter token (fallback for EventSource)
-
-    Returns:
-        User: The authenticated user
-
-    Raises:
-        HTTPException: If authentication fails
-    """
-    # Try Authorization header first (preferred)
-    auth_token = None
-    if authorization:
-        scheme, param = get_authorization_scheme_param(authorization)
-        if scheme.lower() == "bearer" and param:
-            auth_token = param
-
-    # Fall back to query parameter if no header token
-    if not auth_token and token:
-        auth_token = token
-
-    if not auth_token:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Not authenticated",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
-
-    try:
-        # Decode token and get user ID
-        token_data = get_token_data(auth_token)
-
-        # Get user from database
-        result = await db.execute(select(User).where(User.id == token_data.user_id))
-        user = result.scalar_one_or_none()
-
-        if not user:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
-            )
-
-        if not user.is_active:
-            raise HTTPException(
-                status_code=status.HTTP_403_FORBIDDEN, detail="Inactive user"
-            )
-
-        return user
-
-    except TokenExpiredError:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Token expired",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
-    except TokenInvalidError:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Could not validate credentials",
-            headers={"WWW-Authenticate": "Bearer"},
-        )

backend/app/api/dependencies/event_bus.py

@@ -1,36 +0,0 @@
-"""
-Event bus dependency for FastAPI routes.
-
-This module provides the FastAPI dependency for injecting the EventBus
-into route handlers. The event bus is a singleton that maintains
-Redis pub/sub connections for real-time event streaming.
-"""
-
-from app.services.event_bus import (
-    EventBus,
-    get_connected_event_bus as _get_connected_event_bus,
-)
-
-
-async def get_event_bus() -> EventBus:
-    """
-    FastAPI dependency that provides a connected EventBus instance.
-
-    The EventBus is a singleton that maintains Redis pub/sub connections.
-    It's lazily initialized and connected on first access, and should be
-    closed during application shutdown via close_event_bus().
-
-    Usage:
-        @router.get("/events/stream")
-        async def stream_events(
-            event_bus: EventBus = Depends(get_event_bus)
-        ):
-            ...
-
-    Returns:
-        EventBus: The global connected event bus instance
-
-    Raises:
-        EventBusConnectionError: If connection to Redis fails
-    """
-    return await _get_connected_event_bus()

backend/app/api/dependencies/permissions.py

@@ -15,9 +15,9 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.dependencies.auth import get_current_user
 from app.core.database import get_db
-from app.crud.organization import organization as organization_crud
 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:
@@ -81,7 +81,7 @@ class OrganizationPermission:
             return current_user
 
         # Get user's role in organization
-        user_role = await organization_crud.get_user_role_in_org(
+        user_role = await organization_service.get_user_role_in_org(
             db, user_id=current_user.id, organization_id=organization_id
         )
 
@@ -123,7 +123,7 @@ async def require_org_membership(
     if current_user.is_superuser:
         return current_user
 
-    user_role = await organization_crud.get_user_role_in_org(
+    user_role = await organization_service.get_user_role_in_org(
         db, user_id=current_user.id, organization_id=organization_id
     )
 

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

@@ -2,19 +2,11 @@ from fastapi import APIRouter
 
 from app.api.routes import (
     admin,
-    agent_types,
-    agents,
     auth,
-    context,
-    events,
-    issues,
-    mcp,
     oauth,
     oauth_provider,
     organizations,
-    projects,
     sessions,
-    sprints,
     users,
 )
 
@@ -30,25 +22,3 @@ api_router.include_router(admin.router, prefix="/admin", tags=["Admin"])
 api_router.include_router(
     organizations.router, prefix="/organizations", tags=["Organizations"]
 )
-# SSE events router - no prefix, routes define full paths
-api_router.include_router(events.router, tags=["Events"])
-
-# MCP (Model Context Protocol) router
-api_router.include_router(mcp.router, prefix="/mcp", tags=["MCP"])
-
-# Context Management Engine router
-api_router.include_router(context.router, prefix="/context", tags=["Context"])
-
-# Syndarix domain routers
-api_router.include_router(projects.router, prefix="/projects", tags=["Projects"])
-api_router.include_router(
-    agent_types.router, prefix="/agent-types", tags=["Agent Types"]
-)
-# Issues router - routes include /projects/{project_id}/issues paths
-api_router.include_router(issues.router, tags=["Issues"])
-# Agents router - routes include /projects/{project_id}/agents paths
-api_router.include_router(agents.router, tags=["Agents"])
-# Sprints router - routes need prefix as they use /projects/{project_id}/sprints paths
-api_router.include_router(
-    sprints.router, prefix="/projects/{project_id}/sprints", tags=["Sprints"]
-)

backend/app/api/routes/admin.py

@@ -14,7 +14,6 @@ from uuid import UUID
 
 from fastapi import APIRouter, Depends, Query, status
 from pydantic import BaseModel, Field
-from sqlalchemy import func, select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.dependencies.permissions import require_superuser
@@ -25,12 +24,9 @@ from app.core.exceptions import (
     ErrorCode,
     NotFoundError,
 )
-from app.crud.organization import organization as organization_crud
-from app.crud.session import session as session_crud
-from app.crud.user import user as user_crud
-from app.models.organization import Organization
+from app.core.repository_exceptions import DuplicateEntryError
 from app.models.user import User
-from app.models.user_organization import OrganizationRole, UserOrganization
+from app.models.user_organization import OrganizationRole
 from app.schemas.common import (
     MessageResponse,
     PaginatedResponse,
@@ -46,6 +42,9 @@ from app.schemas.organizations import (
 )
 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__)
 
@@ -66,7 +65,7 @@ class BulkUserAction(BaseModel):
 
     action: BulkAction = Field(..., description="Action to perform on selected users")
     user_ids: list[UUID] = Field(
-        ..., min_items=1, max_items=100, description="List of user IDs (max 100)"
+        ..., min_length=1, max_length=100, description="List of user IDs (max 100)"
     )
 
 
@@ -178,38 +177,29 @@ async def admin_get_stats(
     """Get admin dashboard statistics with real data from database."""
     from app.core.config import settings
 
-    # Check if we have any data
-    total_users_query = select(func.count()).select_from(User)
-    total_users = (await db.execute(total_users_query)).scalar() or 0
+    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) - Improved calculation
-    datetime.now(UTC) - timedelta(days=30)
-
-    # Get all users with their creation dates
-    all_users_query = select(User).order_by(User.created_at)
-    result = await db.execute(all_users_query)
-    all_users = result.scalars().all()
-
-    # Build cumulative counts per day
+    # 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)
 
-        # Count all users created before end of this day
-        # Make comparison timezone-aware
         total_users_on_date = sum(
             1
             for u in all_users
             if u.created_at and u.created_at.replace(tzinfo=UTC) < date_end
         )
-        # Count active users created before end of this day
         active_users_on_date = sum(
             1
             for u in all_users
@@ -227,27 +217,16 @@ async def admin_get_stats(
         )
 
     # 2. Organization Distribution - Top 6 organizations by member count
-    org_query = (
-        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(6)
-    )
-    result = await db.execute(org_query)
-    org_dist = [
-        OrgDistributionData(name=row.name, value=row.count) for row in result.all()
-    ]
+    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) - NEW
+    # 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)
 
-        # Count users created on this specific day
-        # Make comparison timezone-aware
         day_registrations = sum(
             1
             for u in all_users
@@ -263,16 +242,8 @@ async def admin_get_stats(
         )
 
     # 4. User Status - Active vs Inactive
-    active_query = select(func.count()).select_from(User).where(User.is_active)
-    inactive_query = (
-        select(func.count()).select_from(User).where(User.is_active.is_(False))
-    )
-
-    active_count = (await db.execute(active_query)).scalar() or 0
-    inactive_count = (await db.execute(inactive_query)).scalar() or 0
-
     logger.info(
-        f"User status counts - Active: {active_count}, Inactive: {inactive_count}"
+        "User status counts - Active: %s, Inactive: %s", active_count, inactive_count
     )
 
     user_status = [
@@ -321,7 +292,7 @@ async def admin_list_users(
             filters["is_superuser"] = is_superuser
 
         # Get users with search
-        users, total = await user_crud.get_multi_with_total(
+        users, total = await user_service.list_users(
             db,
             skip=pagination.offset,
             limit=pagination.limit,
@@ -341,7 +312,7 @@ async def admin_list_users(
         return PaginatedResponse(data=users, pagination=pagination_meta)
 
     except Exception as e:
-        logger.error(f"Error listing users (admin): {e!s}", exc_info=True)
+        logger.exception("Error listing users (admin): %s", e)
         raise
 
 
@@ -364,14 +335,14 @@ async def admin_create_user(
     Allows setting is_superuser and other fields.
     """
     try:
-        user = await user_crud.create(db, obj_in=user_in)
-        logger.info(f"Admin {admin.email} created user {user.email}")
+        user = await user_service.create_user(db, user_in)
+        logger.info("Admin %s created user %s", admin.email, user.email)
         return user
-    except ValueError as e:
-        logger.warning(f"Failed to create user: {e!s}")
-        raise NotFoundError(message=str(e), error_code=ErrorCode.USER_ALREADY_EXISTS)
+    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.error(f"Error creating user (admin): {e!s}", exc_info=True)
+        logger.exception("Error creating user (admin): %s", e)
         raise
 
 
@@ -388,11 +359,7 @@ async def admin_get_user(
     db: AsyncSession = Depends(get_db),
 ) -> Any:
     """Get detailed information about a specific user."""
-    user = await user_crud.get(db, id=user_id)
-    if not user:
-        raise NotFoundError(
-            message=f"User {user_id} not found", error_code=ErrorCode.USER_NOT_FOUND
-        )
+    user = await user_service.get_user(db, str(user_id))
     return user
 
 
@@ -411,20 +378,13 @@ async def admin_update_user(
 ) -> Any:
     """Update user information with admin privileges."""
     try:
-        user = await user_crud.get(db, id=user_id)
-        if not user:
-            raise NotFoundError(
-                message=f"User {user_id} not found", error_code=ErrorCode.USER_NOT_FOUND
-            )
-
-        updated_user = await user_crud.update(db, db_obj=user, obj_in=user_in)
-        logger.info(f"Admin {admin.email} updated user {updated_user.email}")
+        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 NotFoundError:
-        raise
     except Exception as e:
-        logger.error(f"Error updating user (admin): {e!s}", exc_info=True)
+        logger.exception("Error updating user (admin): %s", e)
         raise
 
 
@@ -442,11 +402,7 @@ async def admin_delete_user(
 ) -> Any:
     """Soft delete a user (sets deleted_at timestamp)."""
     try:
-        user = await user_crud.get(db, id=user_id)
-        if not user:
-            raise NotFoundError(
-                message=f"User {user_id} not found", error_code=ErrorCode.USER_NOT_FOUND
-            )
+        user = await user_service.get_user(db, str(user_id))
 
         # Prevent deleting yourself
         if user.id == admin.id:
@@ -456,17 +412,15 @@ async def admin_delete_user(
                 error_code=ErrorCode.OPERATION_FORBIDDEN,
             )
 
-        await user_crud.soft_delete(db, id=user_id)
-        logger.info(f"Admin {admin.email} deleted user {user.email}")
+        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 NotFoundError:
-        raise
     except Exception as e:
-        logger.error(f"Error deleting user (admin): {e!s}", exc_info=True)
+        logger.exception("Error deleting user (admin): %s", e)
         raise
 
 
@@ -484,23 +438,16 @@ async def admin_activate_user(
 ) -> Any:
     """Activate a user account."""
     try:
-        user = await user_crud.get(db, id=user_id)
-        if not user:
-            raise NotFoundError(
-                message=f"User {user_id} not found", error_code=ErrorCode.USER_NOT_FOUND
-            )
-
-        await user_crud.update(db, db_obj=user, obj_in={"is_active": True})
-        logger.info(f"Admin {admin.email} activated user {user.email}")
+        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 NotFoundError:
-        raise
     except Exception as e:
-        logger.error(f"Error activating user (admin): {e!s}", exc_info=True)
+        logger.exception("Error activating user (admin): %s", e)
         raise
 
 
@@ -518,11 +465,7 @@ async def admin_deactivate_user(
 ) -> Any:
     """Deactivate a user account."""
     try:
-        user = await user_crud.get(db, id=user_id)
-        if not user:
-            raise NotFoundError(
-                message=f"User {user_id} not found", error_code=ErrorCode.USER_NOT_FOUND
-            )
+        user = await user_service.get_user(db, str(user_id))
 
         # Prevent deactivating yourself
         if user.id == admin.id:
@@ -532,17 +475,15 @@ async def admin_deactivate_user(
                 error_code=ErrorCode.OPERATION_FORBIDDEN,
             )
 
-        await user_crud.update(db, db_obj=user, obj_in={"is_active": False})
-        logger.info(f"Admin {admin.email} deactivated user {user.email}")
+        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 NotFoundError:
-        raise
     except Exception as e:
-        logger.error(f"Error deactivating user (admin): {e!s}", exc_info=True)
+        logger.exception("Error deactivating user (admin): %s", e)
         raise
 
 
@@ -567,16 +508,16 @@ async def admin_bulk_user_action(
     try:
         # Use efficient bulk operations instead of loop
         if bulk_action.action == BulkAction.ACTIVATE:
-            affected_count = await user_crud.bulk_update_status(
+            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_crud.bulk_update_status(
+            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_crud.bulk_soft_delete(
+            affected_count = await user_service.bulk_soft_delete(
                 db, user_ids=bulk_action.user_ids, exclude_user_id=admin.id
             )
         else:  # pragma: no cover
@@ -587,8 +528,11 @@ async def admin_bulk_user_action(
         failed_count = requested_count - affected_count
 
         logger.info(
-            f"Admin {admin.email} performed bulk {bulk_action.action.value} "
-            f"on {affected_count} users ({failed_count} skipped/failed)"
+            "Admin %s performed bulk %s on %s users (%s skipped/failed)",
+            admin.email,
+            bulk_action.action.value,
+            affected_count,
+            failed_count,
         )
 
         return BulkActionResult(
@@ -600,7 +544,7 @@ async def admin_bulk_user_action(
         )
 
     except Exception as e:  # pragma: no cover
-        logger.error(f"Error in bulk user action: {e!s}", exc_info=True)
+        logger.exception("Error in bulk user action: %s", e)
         raise
 
 
@@ -624,7 +568,7 @@ async def admin_list_organizations(
     """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_crud.get_multi_with_member_counts(
+        orgs_with_data, total = await organization_service.get_multi_with_member_counts(
             db,
             skip=pagination.offset,
             limit=pagination.limit,
@@ -661,7 +605,7 @@ async def admin_list_organizations(
         return PaginatedResponse(data=orgs_with_count, pagination=pagination_meta)
 
     except Exception as e:
-        logger.error(f"Error listing organizations (admin): {e!s}", exc_info=True)
+        logger.exception("Error listing organizations (admin): %s", e)
         raise
 
 
@@ -680,8 +624,8 @@ async def admin_create_organization(
 ) -> Any:
     """Create a new organization."""
     try:
-        org = await organization_crud.create(db, obj_in=org_in)
-        logger.info(f"Admin {admin.email} created organization {org.name}")
+        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 = {
@@ -697,11 +641,11 @@ async def admin_create_organization(
         }
         return OrganizationResponse(**org_dict)
 
-    except ValueError as e:
-        logger.warning(f"Failed to create organization: {e!s}")
-        raise NotFoundError(message=str(e), error_code=ErrorCode.ALREADY_EXISTS)
+    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.error(f"Error creating organization (admin): {e!s}", exc_info=True)
+        logger.exception("Error creating organization (admin): %s", e)
         raise
 
 
@@ -718,12 +662,7 @@ async def admin_get_organization(
     db: AsyncSession = Depends(get_db),
 ) -> Any:
     """Get detailed information about a specific organization."""
-    org = await organization_crud.get(db, id=org_id)
-    if not org:
-        raise NotFoundError(
-            message=f"Organization {org_id} not found", error_code=ErrorCode.NOT_FOUND
-        )
-
+    org = await organization_service.get_organization(db, str(org_id))
     org_dict = {
         "id": org.id,
         "name": org.name,
@@ -733,7 +672,7 @@ async def admin_get_organization(
         "settings": org.settings,
         "created_at": org.created_at,
         "updated_at": org.updated_at,
-        "member_count": await organization_crud.get_member_count(
+        "member_count": await organization_service.get_member_count(
             db, organization_id=org.id
         ),
     }
@@ -755,15 +694,11 @@ async def admin_update_organization(
 ) -> Any:
     """Update organization information."""
     try:
-        org = await organization_crud.get(db, id=org_id)
-        if not org:
-            raise NotFoundError(
-                message=f"Organization {org_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        updated_org = await organization_crud.update(db, db_obj=org, obj_in=org_in)
-        logger.info(f"Admin {admin.email} updated organization {updated_org.name}")
+        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,
@@ -774,16 +709,14 @@ async def admin_update_organization(
             "settings": updated_org.settings,
             "created_at": updated_org.created_at,
             "updated_at": updated_org.updated_at,
-            "member_count": await organization_crud.get_member_count(
+            "member_count": await organization_service.get_member_count(
                 db, organization_id=updated_org.id
             ),
         }
         return OrganizationResponse(**org_dict)
 
-    except NotFoundError:
-        raise
     except Exception as e:
-        logger.error(f"Error updating organization (admin): {e!s}", exc_info=True)
+        logger.exception("Error updating organization (admin): %s", e)
         raise
 
 
@@ -801,24 +734,16 @@ async def admin_delete_organization(
 ) -> Any:
     """Delete an organization and all its relationships."""
     try:
-        org = await organization_crud.get(db, id=org_id)
-        if not org:
-            raise NotFoundError(
-                message=f"Organization {org_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        await organization_crud.remove(db, id=org_id)
-        logger.info(f"Admin {admin.email} deleted organization {org.name}")
+        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 NotFoundError:
-        raise
     except Exception as e:
-        logger.error(f"Error deleting organization (admin): {e!s}", exc_info=True)
+        logger.exception("Error deleting organization (admin): %s", e)
         raise
 
 
@@ -838,14 +763,8 @@ async def admin_list_organization_members(
 ) -> Any:
     """List all members of an organization."""
     try:
-        org = await organization_crud.get(db, id=org_id)
-        if not org:
-            raise NotFoundError(
-                message=f"Organization {org_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        members, total = await organization_crud.get_organization_members(
+        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,
@@ -868,9 +787,7 @@ async def admin_list_organization_members(
     except NotFoundError:
         raise
     except Exception as e:
-        logger.error(
-            f"Error listing organization members (admin): {e!s}", exc_info=True
-        )
+        logger.exception("Error listing organization members (admin): %s", e)
         raise
 
 
@@ -898,45 +815,32 @@ async def admin_add_organization_member(
 ) -> Any:
     """Add a user to an organization."""
     try:
-        org = await organization_crud.get(db, id=org_id)
-        if not org:
-            raise NotFoundError(
-                message=f"Organization {org_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
+        org = await organization_service.get_organization(db, str(org_id))
+        user = await user_service.get_user(db, str(request.user_id))
 
-        user = await user_crud.get(db, id=request.user_id)
-        if not user:
-            raise NotFoundError(
-                message=f"User {request.user_id} not found",
-                error_code=ErrorCode.USER_NOT_FOUND,
-            )
-
-        await organization_crud.add_user(
+        await organization_service.add_member(
             db, organization_id=org_id, user_id=request.user_id, role=request.role
         )
 
         logger.info(
-            f"Admin {admin.email} added user {user.email} to organization {org.name} "
-            f"with role {request.role.value}"
+            "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 ValueError as e:
-        logger.warning(f"Failed to add user to organization: {e!s}")
-        # Use DuplicateError for "already exists" scenarios
+    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 NotFoundError:
-        raise
     except Exception as e:
-        logger.error(
-            f"Error adding member to organization (admin): {e!s}", exc_info=True
-        )
+        logger.exception("Error adding member to organization (admin): %s", e)
         raise
 
 
@@ -955,20 +859,10 @@ async def admin_remove_organization_member(
 ) -> Any:
     """Remove a user from an organization."""
     try:
-        org = await organization_crud.get(db, id=org_id)
-        if not org:
-            raise NotFoundError(
-                message=f"Organization {org_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
+        org = await organization_service.get_organization(db, str(org_id))
+        user = await user_service.get_user(db, str(user_id))
 
-        user = await user_crud.get(db, id=user_id)
-        if not user:
-            raise NotFoundError(
-                message=f"User {user_id} not found", error_code=ErrorCode.USER_NOT_FOUND
-            )
-
-        success = await organization_crud.remove_user(
+        success = await organization_service.remove_member(
             db, organization_id=org_id, user_id=user_id
         )
 
@@ -979,7 +873,10 @@ async def admin_remove_organization_member(
             )
 
         logger.info(
-            f"Admin {admin.email} removed user {user.email} from organization {org.name}"
+            "Admin %s removed user %s from organization %s",
+            admin.email,
+            user.email,
+            org.name,
         )
 
         return MessageResponse(
@@ -990,9 +887,7 @@ async def admin_remove_organization_member(
     except NotFoundError:
         raise
     except Exception as e:  # pragma: no cover
-        logger.error(
-            f"Error removing member from organization (admin): {e!s}", exc_info=True
-        )
+        logger.exception("Error removing member from organization (admin): %s", e)
         raise
 
 
@@ -1022,7 +917,7 @@ async def admin_list_sessions(
     """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_crud.get_all_sessions(
+        sessions, total = await session_service.get_all_sessions(
             db,
             skip=pagination.offset,
             limit=pagination.limit,
@@ -1061,7 +956,10 @@ async def admin_list_sessions(
             session_responses.append(session_response)
 
         logger.info(
-            f"Admin {admin.email} listed {len(session_responses)} sessions (total: {total})"
+            "Admin %s listed %s sessions (total: %s)",
+            admin.email,
+            len(session_responses),
+            total,
         )
 
         pagination_meta = create_pagination_meta(
@@ -1074,5 +972,5 @@ async def admin_list_sessions(
         return PaginatedResponse(data=session_responses, pagination=pagination_meta)
 
     except Exception as e:  # pragma: no cover
-        logger.error(f"Error listing sessions (admin): {e!s}", exc_info=True)
+        logger.exception("Error listing sessions (admin): %s", e)
         raise

backend/app/api/routes/agent_types.py

@@ -1,517 +0,0 @@
-# app/api/routes/agent_types.py
-"""
-AgentType configuration API endpoints.
-
-Provides CRUD operations for managing AI agent type templates.
-Agent types define the base configuration (model, personality, expertise)
-from which agent instances are spawned for projects.
-
-Authorization:
-- Read endpoints: Any authenticated user
-- Write endpoints (create, update, delete): Superusers only
-"""
-
-import logging
-import os
-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_user
-from app.api.dependencies.permissions import require_superuser
-from app.core.database import get_db
-from app.core.exceptions import (
-    DuplicateError,
-    ErrorCode,
-    NotFoundError,
-)
-from app.crud.syndarix.agent_type import agent_type as agent_type_crud
-from app.models.user import User
-from app.schemas.common import (
-    MessageResponse,
-    PaginatedResponse,
-    PaginationParams,
-    create_pagination_meta,
-)
-from app.schemas.syndarix import (
-    AgentTypeCreate,
-    AgentTypeResponse,
-    AgentTypeUpdate,
-)
-
-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
-
-
-def _build_agent_type_response(
-    agent_type: Any,
-    instance_count: int = 0,
-) -> AgentTypeResponse:
-    """
-    Build an AgentTypeResponse from a database model.
-
-    Args:
-        agent_type: AgentType model instance
-        instance_count: Number of agent instances for this type
-
-    Returns:
-        AgentTypeResponse schema
-    """
-    return AgentTypeResponse(
-        id=agent_type.id,
-        name=agent_type.name,
-        slug=agent_type.slug,
-        description=agent_type.description,
-        expertise=agent_type.expertise,
-        personality_prompt=agent_type.personality_prompt,
-        primary_model=agent_type.primary_model,
-        fallback_models=agent_type.fallback_models,
-        model_params=agent_type.model_params,
-        mcp_servers=agent_type.mcp_servers,
-        tool_permissions=agent_type.tool_permissions,
-        is_active=agent_type.is_active,
-        # Category and display fields
-        category=agent_type.category,
-        icon=agent_type.icon,
-        color=agent_type.color,
-        sort_order=agent_type.sort_order,
-        typical_tasks=agent_type.typical_tasks or [],
-        collaboration_hints=agent_type.collaboration_hints or [],
-        created_at=agent_type.created_at,
-        updated_at=agent_type.updated_at,
-        instance_count=instance_count,
-    )
-
-
-# ===== Write Endpoints (Admin Only) =====
-
-
-@router.post(
-    "",
-    response_model=AgentTypeResponse,
-    status_code=status.HTTP_201_CREATED,
-    summary="Create Agent Type",
-    description="Create a new agent type configuration (admin only)",
-    operation_id="create_agent_type",
-)
-@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
-async def create_agent_type(
-    request: Request,
-    agent_type_in: AgentTypeCreate,
-    admin: User = Depends(require_superuser),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Create a new agent type configuration.
-
-    Agent types define templates for AI agents including:
-    - Model configuration (primary model, fallback models, parameters)
-    - Personality and expertise areas
-    - MCP server integrations and tool permissions
-
-    Requires superuser privileges.
-
-    Args:
-        request: FastAPI request object
-        agent_type_in: Agent type creation data
-        admin: Authenticated superuser
-        db: Database session
-
-    Returns:
-        The created agent type configuration
-
-    Raises:
-        DuplicateError: If slug already exists
-    """
-    try:
-        agent_type = await agent_type_crud.create(db, obj_in=agent_type_in)
-        logger.info(
-            f"Admin {admin.email} created agent type: {agent_type.name} "
-            f"(slug: {agent_type.slug})"
-        )
-        return _build_agent_type_response(agent_type, instance_count=0)
-
-    except ValueError as e:
-        logger.warning(f"Failed to create agent type: {e!s}")
-        raise DuplicateError(
-            message=str(e),
-            error_code=ErrorCode.ALREADY_EXISTS,
-            field="slug",
-        )
-    except Exception as e:
-        logger.error(f"Error creating agent type: {e!s}", exc_info=True)
-        raise
-
-
-@router.patch(
-    "/{agent_type_id}",
-    response_model=AgentTypeResponse,
-    summary="Update Agent Type",
-    description="Update an existing agent type configuration (admin only)",
-    operation_id="update_agent_type",
-)
-@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
-async def update_agent_type(
-    request: Request,
-    agent_type_id: UUID,
-    agent_type_in: AgentTypeUpdate,
-    admin: User = Depends(require_superuser),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Update an existing agent type configuration.
-
-    Partial updates are supported - only provided fields will be updated.
-
-    Requires superuser privileges.
-
-    Args:
-        request: FastAPI request object
-        agent_type_id: UUID of the agent type to update
-        agent_type_in: Agent type update data
-        admin: Authenticated superuser
-        db: Database session
-
-    Returns:
-        The updated agent type configuration
-
-    Raises:
-        NotFoundError: If agent type not found
-        DuplicateError: If new slug already exists
-    """
-    try:
-        # Verify agent type exists
-        result = await agent_type_crud.get_with_instance_count(
-            db, agent_type_id=agent_type_id
-        )
-        if not result:
-            raise NotFoundError(
-                message=f"Agent type {agent_type_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        existing_type = result["agent_type"]
-        instance_count = result["instance_count"]
-
-        # Perform update
-        updated_type = await agent_type_crud.update(
-            db, db_obj=existing_type, obj_in=agent_type_in
-        )
-
-        logger.info(
-            f"Admin {admin.email} updated agent type: {updated_type.name} "
-            f"(id: {agent_type_id})"
-        )
-
-        return _build_agent_type_response(updated_type, instance_count=instance_count)
-
-    except NotFoundError:
-        raise
-    except ValueError as e:
-        logger.warning(f"Failed to update agent type {agent_type_id}: {e!s}")
-        raise DuplicateError(
-            message=str(e),
-            error_code=ErrorCode.ALREADY_EXISTS,
-            field="slug",
-        )
-    except Exception as e:
-        logger.error(f"Error updating agent type {agent_type_id}: {e!s}", exc_info=True)
-        raise
-
-
-@router.delete(
-    "/{agent_type_id}",
-    response_model=MessageResponse,
-    summary="Deactivate Agent Type",
-    description="Deactivate an agent type (soft delete, admin only)",
-    operation_id="deactivate_agent_type",
-)
-@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
-async def deactivate_agent_type(
-    request: Request,
-    agent_type_id: UUID,
-    admin: User = Depends(require_superuser),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Deactivate an agent type (soft delete).
-
-    This sets is_active=False rather than deleting the record,
-    preserving referential integrity with existing agent instances.
-
-    Requires superuser privileges.
-
-    Args:
-        request: FastAPI request object
-        agent_type_id: UUID of the agent type to deactivate
-        admin: Authenticated superuser
-        db: Database session
-
-    Returns:
-        Success message
-
-    Raises:
-        NotFoundError: If agent type not found
-    """
-    try:
-        deactivated = await agent_type_crud.deactivate(db, agent_type_id=agent_type_id)
-
-        if not deactivated:
-            raise NotFoundError(
-                message=f"Agent type {agent_type_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        logger.info(
-            f"Admin {admin.email} deactivated agent type: {deactivated.name} "
-            f"(id: {agent_type_id})"
-        )
-
-        return MessageResponse(
-            success=True,
-            message=f"Agent type '{deactivated.name}' has been deactivated",
-        )
-
-    except NotFoundError:
-        raise
-    except Exception as e:
-        logger.error(
-            f"Error deactivating agent type {agent_type_id}: {e!s}", exc_info=True
-        )
-        raise
-
-
-# ===== Read Endpoints (Authenticated Users) =====
-
-
-@router.get(
-    "",
-    response_model=PaginatedResponse[AgentTypeResponse],
-    summary="List Agent Types",
-    description="Get paginated list of active agent types",
-    operation_id="list_agent_types",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def list_agent_types(
-    request: Request,
-    pagination: PaginationParams = Depends(),
-    is_active: bool = Query(True, description="Filter by active status"),
-    category: str | None = Query(None, description="Filter by category"),
-    search: str | None = Query(None, description="Search by name, slug, description"),
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    List all agent types with pagination and filtering.
-
-    By default, returns only active agent types. Set is_active=false
-    to include deactivated types (useful for admin views).
-
-    Args:
-        request: FastAPI request object
-        pagination: Pagination parameters (page, limit)
-        is_active: Filter by active status (default: True)
-        category: Filter by category (e.g., "development", "design")
-        search: Optional search term for name, slug, description
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Paginated list of agent types with instance counts
-    """
-    try:
-        # Get agent types with instance counts
-        results, total = await agent_type_crud.get_multi_with_instance_counts(
-            db,
-            skip=pagination.offset,
-            limit=pagination.limit,
-            is_active=is_active,
-            category=category,
-            search=search,
-        )
-
-        # Build response objects
-        agent_types_response = [
-            _build_agent_type_response(
-                item["agent_type"],
-                instance_count=item["instance_count"],
-            )
-            for item in results
-        ]
-
-        pagination_meta = create_pagination_meta(
-            total=total,
-            page=pagination.page,
-            limit=pagination.limit,
-            items_count=len(agent_types_response),
-        )
-
-        return PaginatedResponse(data=agent_types_response, pagination=pagination_meta)
-
-    except Exception as e:
-        logger.error(f"Error listing agent types: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/grouped",
-    response_model=dict[str, list[AgentTypeResponse]],
-    summary="List Agent Types Grouped by Category",
-    description="Get all agent types organized by category",
-    operation_id="list_agent_types_grouped",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def list_agent_types_grouped(
-    request: Request,
-    is_active: bool = Query(True, description="Filter by active status"),
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get agent types grouped by category.
-
-    Returns a dictionary where keys are category names and values
-    are lists of agent types, sorted by sort_order within each category.
-
-    Args:
-        request: FastAPI request object
-        is_active: Filter by active status (default: True)
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Dictionary mapping category to list of agent types
-    """
-    try:
-        grouped = await agent_type_crud.get_grouped_by_category(db, is_active=is_active)
-
-        # Transform to response objects
-        result: dict[str, list[AgentTypeResponse]] = {}
-        for category, types in grouped.items():
-            result[category] = [
-                _build_agent_type_response(t, instance_count=0) for t in types
-            ]
-
-        return result
-    except Exception as e:
-        logger.error(f"Error getting grouped agent types: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/{agent_type_id}",
-    response_model=AgentTypeResponse,
-    summary="Get Agent Type",
-    description="Get agent type details by ID",
-    operation_id="get_agent_type",
-)
-@limiter.limit(f"{100 * RATE_MULTIPLIER}/minute")
-async def get_agent_type(
-    request: Request,
-    agent_type_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get detailed information about a specific agent type.
-
-    Args:
-        request: FastAPI request object
-        agent_type_id: UUID of the agent type
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Agent type details with instance count
-
-    Raises:
-        NotFoundError: If agent type not found
-    """
-    try:
-        result = await agent_type_crud.get_with_instance_count(
-            db, agent_type_id=agent_type_id
-        )
-
-        if not result:
-            raise NotFoundError(
-                message=f"Agent type {agent_type_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        return _build_agent_type_response(
-            result["agent_type"],
-            instance_count=result["instance_count"],
-        )
-
-    except NotFoundError:
-        raise
-    except Exception as e:
-        logger.error(f"Error getting agent type {agent_type_id}: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/slug/{slug}",
-    response_model=AgentTypeResponse,
-    summary="Get Agent Type by Slug",
-    description="Get agent type details by slug",
-    operation_id="get_agent_type_by_slug",
-)
-@limiter.limit(f"{100 * RATE_MULTIPLIER}/minute")
-async def get_agent_type_by_slug(
-    request: Request,
-    slug: str,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get detailed information about an agent type by its slug.
-
-    Slugs are human-readable identifiers like "product-owner" or "backend-engineer".
-    Useful for referencing agent types in configuration files or APIs.
-
-    Args:
-        request: FastAPI request object
-        slug: Slug identifier of the agent type
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Agent type details with instance count
-
-    Raises:
-        NotFoundError: If agent type not found
-    """
-    try:
-        agent_type = await agent_type_crud.get_by_slug(db, slug=slug)
-
-        if not agent_type:
-            raise NotFoundError(
-                message=f"Agent type with slug '{slug}' not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Get instance count separately
-        result = await agent_type_crud.get_with_instance_count(
-            db, agent_type_id=agent_type.id
-        )
-        instance_count = result["instance_count"] if result else 0
-
-        return _build_agent_type_response(agent_type, instance_count=instance_count)
-
-    except NotFoundError:
-        raise
-    except Exception as e:
-        logger.error(f"Error getting agent type by slug '{slug}': {e!s}", exc_info=True)
-        raise

backend/app/api/routes/agents.py

@@ -1,984 +0,0 @@
-# app/api/routes/agents.py
-"""
-Agent Instance management endpoints for Syndarix projects.
-
-These endpoints allow project owners and superusers to manage AI agent instances
-within their projects, including spawning, pausing, resuming, and terminating agents.
-"""
-
-import logging
-import os
-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_user
-from app.core.database import get_db
-from app.core.exceptions import (
-    AuthorizationError,
-    NotFoundError,
-    ValidationException,
-)
-from app.crud.syndarix.agent_instance import agent_instance as agent_instance_crud
-from app.crud.syndarix.agent_type import agent_type as agent_type_crud
-from app.crud.syndarix.project import project as project_crud
-from app.models.syndarix import AgentInstance, Project
-from app.models.syndarix.enums import AgentStatus
-from app.models.user import User
-from app.schemas.common import (
-    MessageResponse,
-    PaginatedResponse,
-    PaginationParams,
-    create_pagination_meta,
-)
-from app.schemas.errors import ErrorCode
-from app.schemas.syndarix.agent_instance import (
-    AgentInstanceCreate,
-    AgentInstanceMetrics,
-    AgentInstanceResponse,
-    AgentInstanceUpdate,
-)
-
-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
-
-
-# Valid status transitions for agent lifecycle management
-VALID_STATUS_TRANSITIONS: dict[AgentStatus, set[AgentStatus]] = {
-    AgentStatus.IDLE: {AgentStatus.WORKING, AgentStatus.PAUSED, AgentStatus.TERMINATED},
-    AgentStatus.WORKING: {
-        AgentStatus.IDLE,
-        AgentStatus.WAITING,
-        AgentStatus.PAUSED,
-        AgentStatus.TERMINATED,
-    },
-    AgentStatus.WAITING: {
-        AgentStatus.IDLE,
-        AgentStatus.WORKING,
-        AgentStatus.PAUSED,
-        AgentStatus.TERMINATED,
-    },
-    AgentStatus.PAUSED: {AgentStatus.IDLE, AgentStatus.TERMINATED},
-    AgentStatus.TERMINATED: set(),  # Terminal state, no transitions allowed
-}
-
-
-async def verify_project_access(
-    db: AsyncSession,
-    project_id: UUID,
-    user: User,
-) -> Project:
-    """
-    Verify user has access to a project.
-
-    Args:
-        db: Database session
-        project_id: UUID of the project to verify
-        user: Current authenticated user
-
-    Returns:
-        Project: The project if access is granted
-
-    Raises:
-        NotFoundError: If the project does not exist
-        AuthorizationError: If the user does not have access to the project
-    """
-    project = await project_crud.get(db, id=project_id)
-    if not project:
-        raise NotFoundError(
-            message=f"Project {project_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-    if not user.is_superuser and project.owner_id != user.id:
-        raise AuthorizationError(
-            message="You do not have access to this project",
-            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
-        )
-    return project
-
-
-def validate_status_transition(
-    current_status: AgentStatus,
-    target_status: AgentStatus,
-) -> None:
-    """
-    Validate that a status transition is allowed.
-
-    Args:
-        current_status: The agent's current status
-        target_status: The desired target status
-
-    Raises:
-        ValidationException: If the transition is not allowed
-    """
-    valid_targets = VALID_STATUS_TRANSITIONS.get(current_status, set())
-    if target_status not in valid_targets:
-        raise ValidationException(
-            message=f"Cannot transition from {current_status.value} to {target_status.value}",
-            error_code=ErrorCode.VALIDATION_ERROR,
-            field="status",
-        )
-
-
-def build_agent_response(
-    agent: AgentInstance,
-    agent_type_name: str | None = None,
-    agent_type_slug: str | None = None,
-    project_name: str | None = None,
-    project_slug: str | None = None,
-    assigned_issues_count: int = 0,
-) -> AgentInstanceResponse:
-    """
-    Build an AgentInstanceResponse from an AgentInstance model.
-
-    Args:
-        agent: The agent instance model
-        agent_type_name: Name of the agent type
-        agent_type_slug: Slug of the agent type
-        project_name: Name of the project
-        project_slug: Slug of the project
-        assigned_issues_count: Number of issues assigned to this agent
-
-    Returns:
-        AgentInstanceResponse: The response schema
-    """
-    return AgentInstanceResponse(
-        id=agent.id,
-        agent_type_id=agent.agent_type_id,
-        project_id=agent.project_id,
-        name=agent.name,
-        status=agent.status,
-        current_task=agent.current_task,
-        short_term_memory=agent.short_term_memory or {},
-        long_term_memory_ref=agent.long_term_memory_ref,
-        session_id=agent.session_id,
-        last_activity_at=agent.last_activity_at,
-        terminated_at=agent.terminated_at,
-        tasks_completed=agent.tasks_completed,
-        tokens_used=agent.tokens_used,
-        cost_incurred=agent.cost_incurred,
-        created_at=agent.created_at,
-        updated_at=agent.updated_at,
-        agent_type_name=agent_type_name,
-        agent_type_slug=agent_type_slug,
-        project_name=project_name,
-        project_slug=project_slug,
-        assigned_issues_count=assigned_issues_count,
-    )
-
-
-# ===== Agent Instance Management Endpoints =====
-
-
-@router.post(
-    "/projects/{project_id}/agents",
-    response_model=AgentInstanceResponse,
-    status_code=status.HTTP_201_CREATED,
-    summary="Spawn Agent Instance",
-    description="Spawn a new agent instance in a project. Requires project ownership or superuser.",
-    operation_id="spawn_agent",
-)
-@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
-async def spawn_agent(
-    request: Request,
-    project_id: UUID,
-    agent_in: AgentInstanceCreate,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Spawn a new agent instance in a project.
-
-    Creates a new agent instance from an agent type template and assigns it
-    to the specified project. The agent starts in IDLE status by default.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project to spawn the agent in
-        agent_in: Agent instance creation data
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        AgentInstanceResponse: The newly created agent instance
-
-    Raises:
-        NotFoundError: If the project is not found
-        AuthorizationError: If the user lacks access to the project
-        ValidationException: If the agent creation data is invalid
-    """
-    try:
-        # Verify project access
-        project = await verify_project_access(db, project_id, current_user)
-
-        # Ensure the agent is being created for the correct project
-        if agent_in.project_id != project_id:
-            raise ValidationException(
-                message="Agent project_id must match the URL project_id",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="project_id",
-            )
-
-        # Validate that the agent type exists and is active
-        agent_type = await agent_type_crud.get(db, id=agent_in.agent_type_id)
-        if not agent_type:
-            raise NotFoundError(
-                message=f"Agent type {agent_in.agent_type_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-        if not agent_type.is_active:
-            raise ValidationException(
-                message=f"Agent type '{agent_type.name}' is inactive and cannot be used",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="agent_type_id",
-            )
-
-        # Create the agent instance
-        agent = await agent_instance_crud.create(db, obj_in=agent_in)
-
-        logger.info(
-            f"User {current_user.email} spawned agent '{agent.name}' "
-            f"(id={agent.id}) in project {project.slug}"
-        )
-
-        # Get agent details for response
-        details = await agent_instance_crud.get_with_details(db, instance_id=agent.id)
-        if details:
-            return build_agent_response(
-                agent=details["instance"],
-                agent_type_name=details.get("agent_type_name"),
-                agent_type_slug=details.get("agent_type_slug"),
-                project_name=details.get("project_name"),
-                project_slug=details.get("project_slug"),
-                assigned_issues_count=details.get("assigned_issues_count", 0),
-            )
-
-        return build_agent_response(agent)
-
-    except (NotFoundError, AuthorizationError, ValidationException):
-        raise
-    except ValueError as e:
-        logger.warning(f"Failed to spawn agent: {e!s}")
-        raise ValidationException(
-            message=str(e),
-            error_code=ErrorCode.VALIDATION_ERROR,
-        )
-    except Exception as e:
-        logger.error(f"Error spawning agent: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/projects/{project_id}/agents",
-    response_model=PaginatedResponse[AgentInstanceResponse],
-    summary="List Project Agents",
-    description="List all agent instances in a project with optional filtering.",
-    operation_id="list_project_agents",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def list_project_agents(
-    request: Request,
-    project_id: UUID,
-    pagination: PaginationParams = Depends(),
-    status_filter: AgentStatus | None = Query(
-        None, alias="status", description="Filter by agent status"
-    ),
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    List all agent instances in a project.
-
-    Returns a paginated list of agents with optional status filtering.
-    Results are ordered by creation date (newest first).
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        pagination: Pagination parameters
-        status_filter: Optional filter by agent status
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        PaginatedResponse[AgentInstanceResponse]: Paginated list of agents
-
-    Raises:
-        NotFoundError: If the project is not found
-        AuthorizationError: If the user lacks access to the project
-    """
-    try:
-        # Verify project access
-        project = await verify_project_access(db, project_id, current_user)
-
-        # Get agents for the project
-        agents, total = await agent_instance_crud.get_by_project(
-            db,
-            project_id=project_id,
-            status=status_filter,
-            skip=pagination.offset,
-            limit=pagination.limit,
-        )
-
-        # Build response objects
-        agent_responses = []
-        for agent in agents:
-            # Get details for each agent (could be optimized with bulk query)
-            details = await agent_instance_crud.get_with_details(
-                db, instance_id=agent.id
-            )
-            if details:
-                agent_responses.append(
-                    build_agent_response(
-                        agent=details["instance"],
-                        agent_type_name=details.get("agent_type_name"),
-                        agent_type_slug=details.get("agent_type_slug"),
-                        project_name=details.get("project_name"),
-                        project_slug=details.get("project_slug"),
-                        assigned_issues_count=details.get("assigned_issues_count", 0),
-                    )
-                )
-            else:
-                agent_responses.append(build_agent_response(agent))
-
-        pagination_meta = create_pagination_meta(
-            total=total,
-            page=pagination.page,
-            limit=pagination.limit,
-            items_count=len(agent_responses),
-        )
-
-        logger.debug(
-            f"User {current_user.email} listed {len(agent_responses)} agents "
-            f"in project {project.slug}"
-        )
-
-        return PaginatedResponse(data=agent_responses, pagination=pagination_meta)
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except Exception as e:
-        logger.error(f"Error listing project agents: {e!s}", exc_info=True)
-        raise
-
-
-# ===== Project Agent Metrics Endpoint =====
-# NOTE: This endpoint MUST be defined before /{agent_id} routes
-# to prevent FastAPI from trying to parse "metrics" as a UUID
-
-
-@router.get(
-    "/projects/{project_id}/agents/metrics",
-    response_model=AgentInstanceMetrics,
-    summary="Get Project Agent Metrics",
-    description="Get aggregated usage metrics for all agents in a project.",
-    operation_id="get_project_agent_metrics",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def get_project_agent_metrics(
-    request: Request,
-    project_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get aggregated usage metrics for all agents in a project.
-
-    Returns aggregated metrics across all agents including total
-    tasks completed, tokens used, and cost incurred.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        AgentInstanceMetrics: Aggregated project agent metrics
-
-    Raises:
-        NotFoundError: If the project is not found
-        AuthorizationError: If the user lacks access to the project
-    """
-    try:
-        # Verify project access
-        project = await verify_project_access(db, project_id, current_user)
-
-        # Get aggregated metrics for the project
-        metrics = await agent_instance_crud.get_project_metrics(
-            db, project_id=project_id
-        )
-
-        logger.debug(
-            f"User {current_user.email} retrieved project metrics for {project.slug}"
-        )
-
-        return AgentInstanceMetrics(
-            total_instances=metrics["total_instances"],
-            active_instances=metrics["active_instances"],
-            idle_instances=metrics["idle_instances"],
-            total_tasks_completed=metrics["total_tasks_completed"],
-            total_tokens_used=metrics["total_tokens_used"],
-            total_cost_incurred=metrics["total_cost_incurred"],
-        )
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except Exception as e:
-        logger.error(f"Error getting project agent metrics: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/projects/{project_id}/agents/{agent_id}",
-    response_model=AgentInstanceResponse,
-    summary="Get Agent Details",
-    description="Get detailed information about a specific agent instance.",
-    operation_id="get_agent",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def get_agent(
-    request: Request,
-    project_id: UUID,
-    agent_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get detailed information about a specific agent instance.
-
-    Returns full agent details including related entity information
-    (agent type name, project name) and assigned issues count.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        agent_id: UUID of the agent instance
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        AgentInstanceResponse: The agent instance details
-
-    Raises:
-        NotFoundError: If the project or agent is not found
-        AuthorizationError: If the user lacks access to the project
-    """
-    try:
-        # Verify project access
-        await verify_project_access(db, project_id, current_user)
-
-        # Get agent with full details
-        details = await agent_instance_crud.get_with_details(db, instance_id=agent_id)
-
-        if not details:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        agent = details["instance"]
-
-        # Verify agent belongs to the specified project
-        if agent.project_id != project_id:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found in project {project_id}",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        logger.debug(
-            f"User {current_user.email} retrieved agent {agent.name} (id={agent_id})"
-        )
-
-        return build_agent_response(
-            agent=agent,
-            agent_type_name=details.get("agent_type_name"),
-            agent_type_slug=details.get("agent_type_slug"),
-            project_name=details.get("project_name"),
-            project_slug=details.get("project_slug"),
-            assigned_issues_count=details.get("assigned_issues_count", 0),
-        )
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except Exception as e:
-        logger.error(f"Error getting agent details: {e!s}", exc_info=True)
-        raise
-
-
-@router.patch(
-    "/projects/{project_id}/agents/{agent_id}",
-    response_model=AgentInstanceResponse,
-    summary="Update Agent",
-    description="Update an agent instance's configuration and state.",
-    operation_id="update_agent",
-)
-@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
-async def update_agent(
-    request: Request,
-    project_id: UUID,
-    agent_id: UUID,
-    agent_in: AgentInstanceUpdate,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Update an agent instance's configuration and state.
-
-    Allows updating agent status, current task, memory, and other
-    configurable fields. Status transitions are validated according
-    to the agent lifecycle state machine.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        agent_id: UUID of the agent instance
-        agent_in: Agent update data
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        AgentInstanceResponse: The updated agent instance
-
-    Raises:
-        NotFoundError: If the project or agent is not found
-        AuthorizationError: If the user lacks access to the project
-        ValidationException: If the status transition is invalid
-    """
-    try:
-        # Verify project access
-        await verify_project_access(db, project_id, current_user)
-
-        # Get current agent
-        agent = await agent_instance_crud.get(db, id=agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Verify agent belongs to the specified project
-        if agent.project_id != project_id:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found in project {project_id}",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Validate status transition if status is being changed
-        if agent_in.status is not None and agent_in.status != agent.status:
-            validate_status_transition(agent.status, agent_in.status)
-
-        # Update the agent
-        updated_agent = await agent_instance_crud.update(
-            db, db_obj=agent, obj_in=agent_in
-        )
-
-        logger.info(
-            f"User {current_user.email} updated agent {updated_agent.name} "
-            f"(id={agent_id})"
-        )
-
-        # Get updated details
-        details = await agent_instance_crud.get_with_details(
-            db, instance_id=updated_agent.id
-        )
-        if details:
-            return build_agent_response(
-                agent=details["instance"],
-                agent_type_name=details.get("agent_type_name"),
-                agent_type_slug=details.get("agent_type_slug"),
-                project_name=details.get("project_name"),
-                project_slug=details.get("project_slug"),
-                assigned_issues_count=details.get("assigned_issues_count", 0),
-            )
-
-        return build_agent_response(updated_agent)
-
-    except (NotFoundError, AuthorizationError, ValidationException):
-        raise
-    except Exception as e:
-        logger.error(f"Error updating agent: {e!s}", exc_info=True)
-        raise
-
-
-@router.post(
-    "/projects/{project_id}/agents/{agent_id}/pause",
-    response_model=AgentInstanceResponse,
-    summary="Pause Agent",
-    description="Pause an agent instance, temporarily stopping its work.",
-    operation_id="pause_agent",
-)
-@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
-async def pause_agent(
-    request: Request,
-    project_id: UUID,
-    agent_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Pause an agent instance.
-
-    Transitions the agent to PAUSED status, temporarily stopping
-    its work. The agent can be resumed later with the resume endpoint.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        agent_id: UUID of the agent instance
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        AgentInstanceResponse: The paused agent instance
-
-    Raises:
-        NotFoundError: If the project or agent is not found
-        AuthorizationError: If the user lacks access to the project
-        ValidationException: If the agent cannot be paused from its current state
-    """
-    try:
-        # Verify project access
-        await verify_project_access(db, project_id, current_user)
-
-        # Get current agent
-        agent = await agent_instance_crud.get(db, id=agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Verify agent belongs to the specified project
-        if agent.project_id != project_id:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found in project {project_id}",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Validate the transition to PAUSED
-        validate_status_transition(agent.status, AgentStatus.PAUSED)
-
-        # Update status to PAUSED
-        paused_agent = await agent_instance_crud.update_status(
-            db,
-            instance_id=agent_id,
-            status=AgentStatus.PAUSED,
-        )
-
-        if not paused_agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        logger.info(
-            f"User {current_user.email} paused agent {paused_agent.name} "
-            f"(id={agent_id})"
-        )
-
-        # Get updated details
-        details = await agent_instance_crud.get_with_details(
-            db, instance_id=paused_agent.id
-        )
-        if details:
-            return build_agent_response(
-                agent=details["instance"],
-                agent_type_name=details.get("agent_type_name"),
-                agent_type_slug=details.get("agent_type_slug"),
-                project_name=details.get("project_name"),
-                project_slug=details.get("project_slug"),
-                assigned_issues_count=details.get("assigned_issues_count", 0),
-            )
-
-        return build_agent_response(paused_agent)
-
-    except (NotFoundError, AuthorizationError, ValidationException):
-        raise
-    except Exception as e:
-        logger.error(f"Error pausing agent: {e!s}", exc_info=True)
-        raise
-
-
-@router.post(
-    "/projects/{project_id}/agents/{agent_id}/resume",
-    response_model=AgentInstanceResponse,
-    summary="Resume Agent",
-    description="Resume a paused agent instance.",
-    operation_id="resume_agent",
-)
-@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
-async def resume_agent(
-    request: Request,
-    project_id: UUID,
-    agent_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Resume a paused agent instance.
-
-    Transitions the agent from PAUSED back to IDLE status,
-    allowing it to accept new work.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        agent_id: UUID of the agent instance
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        AgentInstanceResponse: The resumed agent instance
-
-    Raises:
-        NotFoundError: If the project or agent is not found
-        AuthorizationError: If the user lacks access to the project
-        ValidationException: If the agent cannot be resumed from its current state
-    """
-    try:
-        # Verify project access
-        await verify_project_access(db, project_id, current_user)
-
-        # Get current agent
-        agent = await agent_instance_crud.get(db, id=agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Verify agent belongs to the specified project
-        if agent.project_id != project_id:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found in project {project_id}",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Validate the transition to IDLE (resume)
-        validate_status_transition(agent.status, AgentStatus.IDLE)
-
-        # Update status to IDLE
-        resumed_agent = await agent_instance_crud.update_status(
-            db,
-            instance_id=agent_id,
-            status=AgentStatus.IDLE,
-        )
-
-        if not resumed_agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        logger.info(
-            f"User {current_user.email} resumed agent {resumed_agent.name} "
-            f"(id={agent_id})"
-        )
-
-        # Get updated details
-        details = await agent_instance_crud.get_with_details(
-            db, instance_id=resumed_agent.id
-        )
-        if details:
-            return build_agent_response(
-                agent=details["instance"],
-                agent_type_name=details.get("agent_type_name"),
-                agent_type_slug=details.get("agent_type_slug"),
-                project_name=details.get("project_name"),
-                project_slug=details.get("project_slug"),
-                assigned_issues_count=details.get("assigned_issues_count", 0),
-            )
-
-        return build_agent_response(resumed_agent)
-
-    except (NotFoundError, AuthorizationError, ValidationException):
-        raise
-    except Exception as e:
-        logger.error(f"Error resuming agent: {e!s}", exc_info=True)
-        raise
-
-
-@router.delete(
-    "/projects/{project_id}/agents/{agent_id}",
-    response_model=MessageResponse,
-    summary="Terminate Agent",
-    description="Terminate an agent instance, permanently stopping it.",
-    operation_id="terminate_agent",
-)
-@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
-async def terminate_agent(
-    request: Request,
-    project_id: UUID,
-    agent_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Terminate an agent instance.
-
-    Permanently terminates the agent, setting its status to TERMINATED.
-    This action cannot be undone - a new agent must be spawned if needed.
-    The agent's session and current task are cleared.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        agent_id: UUID of the agent instance
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        MessageResponse: Confirmation message
-
-    Raises:
-        NotFoundError: If the project or agent is not found
-        AuthorizationError: If the user lacks access to the project
-        ValidationException: If the agent is already terminated
-    """
-    try:
-        # Verify project access
-        await verify_project_access(db, project_id, current_user)
-
-        # Get current agent
-        agent = await agent_instance_crud.get(db, id=agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Verify agent belongs to the specified project
-        if agent.project_id != project_id:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found in project {project_id}",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Check if already terminated
-        if agent.status == AgentStatus.TERMINATED:
-            raise ValidationException(
-                message="Agent is already terminated",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="status",
-            )
-
-        # Validate the transition to TERMINATED
-        validate_status_transition(agent.status, AgentStatus.TERMINATED)
-
-        agent_name = agent.name
-
-        # Terminate the agent
-        terminated_agent = await agent_instance_crud.terminate(db, instance_id=agent_id)
-
-        if not terminated_agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        logger.info(
-            f"User {current_user.email} terminated agent {agent_name} (id={agent_id})"
-        )
-
-        return MessageResponse(
-            success=True,
-            message=f"Agent '{agent_name}' has been terminated",
-        )
-
-    except (NotFoundError, AuthorizationError, ValidationException):
-        raise
-    except Exception as e:
-        logger.error(f"Error terminating agent: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/projects/{project_id}/agents/{agent_id}/metrics",
-    response_model=AgentInstanceMetrics,
-    summary="Get Agent Metrics",
-    description="Get usage metrics for a specific agent instance.",
-    operation_id="get_agent_metrics",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def get_agent_metrics(
-    request: Request,
-    project_id: UUID,
-    agent_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get usage metrics for a specific agent instance.
-
-    Returns metrics including tasks completed, tokens used,
-    and cost incurred for the specified agent.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project
-        agent_id: UUID of the agent instance
-        current_user: Current authenticated user
-        db: Database session
-
-    Returns:
-        AgentInstanceMetrics: Agent usage metrics
-
-    Raises:
-        NotFoundError: If the project or agent is not found
-        AuthorizationError: If the user lacks access to the project
-    """
-    try:
-        # Verify project access
-        await verify_project_access(db, project_id, current_user)
-
-        # Get agent
-        agent = await agent_instance_crud.get(db, id=agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Verify agent belongs to the specified project
-        if agent.project_id != project_id:
-            raise NotFoundError(
-                message=f"Agent {agent_id} not found in project {project_id}",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        # Calculate metrics for this single agent
-        # For a single agent, we report its individual metrics
-        is_active = agent.status == AgentStatus.WORKING
-        is_idle = agent.status == AgentStatus.IDLE
-
-        logger.debug(
-            f"User {current_user.email} retrieved metrics for agent {agent.name} "
-            f"(id={agent_id})"
-        )
-
-        return AgentInstanceMetrics(
-            total_instances=1,
-            active_instances=1 if is_active else 0,
-            idle_instances=1 if is_idle else 0,
-            total_tasks_completed=agent.tasks_completed,
-            total_tokens_used=agent.tokens_used,
-            total_cost_incurred=agent.cost_incurred,
-        )
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except Exception as e:
-        logger.error(f"Error getting agent metrics: {e!s}", exc_info=True)
-        raise

backend/app/api/routes/auth.py

@@ -15,16 +15,14 @@ from app.core.auth import (
     TokenExpiredError,
     TokenInvalidError,
     decode_token,
-    get_password_hash,
 )
 from app.core.database import get_db
 from app.core.exceptions import (
     AuthenticationError as AuthError,
     DatabaseError,
+    DuplicateError,
     ErrorCode,
 )
-from app.crud.session import session as session_crud
-from app.crud.user import user as user_crud
 from app.models.user import User
 from app.schemas.common import MessageResponse
 from app.schemas.sessions import LogoutRequest, SessionCreate
@@ -39,6 +37,8 @@ from app.schemas.users import (
 )
 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
 
@@ -91,17 +91,18 @@ async def _create_login_session(
             location_country=device_info.location_country,
         )
 
-        await session_crud.create_session(db, obj_in=session_data)
+        await session_service.create_session(db, obj_in=session_data)
 
         logger.info(
-            f"{login_type.capitalize()} successful: {user.email} from {device_info.device_name} "
-            f"(IP: {device_info.ip_address})"
+            "%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.error(
-            f"Failed to create session for {user.email}: {session_err!s}", exc_info=True
-        )
+        logger.exception("Failed to create session for %s: %s", user.email, session_err)
 
 
 @router.post(
@@ -123,15 +124,21 @@ async def register_user(
     try:
         user = await AuthService.create_user(db, user_data)
         return user
-    except AuthenticationError as e:
+    except DuplicateError:
         # SECURITY: Don't reveal if email exists - generic error message
-        logger.warning(f"Registration failed: {e!s}")
+        logger.warning("Registration failed: duplicate email %s", user_data.email)
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            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: {e!s}", exc_info=True)
+        logger.exception("Unexpected error during registration: %s", e)
         raise DatabaseError(
             message="An unexpected error occurred. Please try again later.",
             error_code=ErrorCode.INTERNAL_ERROR,
@@ -159,7 +166,7 @@ async def login(
 
         # 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 AuthError(
                 message="Invalid email or password",
                 error_code=ErrorCode.INVALID_CREDENTIALS,
@@ -175,14 +182,11 @@ async def login(
 
     except AuthenticationError as e:
         # Handle specific authentication errors like inactive accounts
-        logger.warning(f"Authentication failed: {e!s}")
+        logger.warning("Authentication failed: %s", e)
         raise AuthError(message=str(e), error_code=ErrorCode.INVALID_CREDENTIALS)
-    except AuthError:
-        # Re-raise custom auth exceptions without modification
-        raise
     except Exception as e:
         # Handle unexpected errors
-        logger.error(f"Unexpected error during login: {e!s}", exc_info=True)
+        logger.exception("Unexpected error during login: %s", e)
         raise DatabaseError(
             message="An unexpected error occurred. Please try again later.",
             error_code=ErrorCode.INTERNAL_ERROR,
@@ -224,13 +228,10 @@ async def login_oauth(
         # Return full token response with user data
         return tokens
     except AuthenticationError as e:
-        logger.warning(f"OAuth authentication failed: {e!s}")
+        logger.warning("OAuth authentication failed: %s", e)
         raise AuthError(message=str(e), error_code=ErrorCode.INVALID_CREDENTIALS)
-    except AuthError:
-        # Re-raise custom auth exceptions without modification
-        raise
     except Exception as e:
-        logger.error(f"Unexpected error during OAuth login: {e!s}", exc_info=True)
+        logger.exception("Unexpected error during OAuth login: %s", e)
         raise DatabaseError(
             message="An unexpected error occurred. Please try again later.",
             error_code=ErrorCode.INTERNAL_ERROR,
@@ -259,11 +260,12 @@ async def refresh_token(
         )
 
         # Check if session exists and is active
-        session = await session_crud.get_active_by_jti(db, jti=refresh_payload.jti)
+        session = await session_service.get_active_by_jti(db, jti=refresh_payload.jti)
 
         if not session:
             logger.warning(
-                f"Refresh token used for inactive or non-existent session: {refresh_payload.jti}"
+                "Refresh token used for inactive or non-existent session: %s",
+                refresh_payload.jti,
             )
             raise HTTPException(
                 status_code=status.HTTP_401_UNAUTHORIZED,
@@ -279,16 +281,14 @@ async def refresh_token(
 
         # Update session with new refresh token JTI and expiration
         try:
-            await session_crud.update_refresh_token(
+            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.error(
-                f"Failed to update session {session.id}: {session_err!s}", exc_info=True
-            )
+            logger.exception("Failed to update session %s: %s", session.id, session_err)
             # Continue anyway - tokens are already issued
 
         return tokens
@@ -311,7 +311,7 @@ async def refresh_token(
         # Re-raise HTTP exceptions (like session revoked)
         raise
     except Exception as e:
-        logger.error(f"Unexpected error during token refresh: {e!s}")
+        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.",
@@ -347,7 +347,7 @@ async def request_password_reset(
     """
     try:
         # Look up user by email
-        user = await user_crud.get_by_email(db, email=reset_request.email)
+        user = await user_service.get_by_email(db, email=reset_request.email)
 
         # Only send email if user exists and is active
         if user and user.is_active:
@@ -358,11 +358,12 @@ async def request_password_reset(
             await email_service.send_password_reset_email(
                 to_email=user.email, reset_token=reset_token, user_name=user.first_name
             )
-            logger.info(f"Password reset requested for {user.email}")
+            logger.info("Password reset requested for %s", user.email)
         else:
             # Log attempt but don't reveal if email exists
             logger.warning(
-                f"Password reset requested for non-existent or inactive email: {reset_request.email}"
+                "Password reset requested for non-existent or inactive email: %s",
+                reset_request.email,
             )
 
         # Always return success to prevent email enumeration
@@ -371,7 +372,7 @@ async def request_password_reset(
             message="If your email is registered, you will receive a password reset link shortly",
         )
     except Exception as e:
-        logger.error(f"Error processing password reset request: {e!s}", exc_info=True)
+        logger.exception("Error processing password reset request: %s", e)
         # Still return success to prevent information leakage
         return MessageResponse(
             success=True,
@@ -412,40 +413,34 @@ async def confirm_password_reset(
                 detail="Invalid or expired password reset token",
             )
 
-        # Look up user
-        user = await user_crud.get_by_email(db, email=email)
-
-        if not user:
-            raise HTTPException(
-                status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
+        # 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
             )
-
-        if not user.is_active:
-            raise HTTPException(
-                status_code=status.HTTP_400_BAD_REQUEST,
-                detail="User account is inactive",
-            )
-
-        # Update password
-        user.password_hash = get_password_hash(reset_confirm.new_password)
-        db.add(user)
-        await db.commit()
+        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
-        from app.crud.session import session as session_crud
-
         try:
-            deactivated_count = await session_crud.deactivate_all_user_sessions(
+            deactivated_count = await session_service.deactivate_all_user_sessions(
                 db, user_id=str(user.id)
             )
             logger.info(
-                f"Password reset successful for {user.email}, invalidated {deactivated_count} sessions"
+                "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(
-                f"Failed to invalidate sessions after password reset: {session_error!s}"
+                "Failed to invalidate sessions after password reset: %s", session_error
             )
 
         return MessageResponse(
@@ -456,7 +451,7 @@ async def confirm_password_reset(
     except HTTPException:
         raise
     except Exception as e:
-        logger.error(f"Error confirming password reset: {e!s}", exc_info=True)
+        logger.exception("Error confirming password reset: %s", e)
         await db.rollback()
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
@@ -506,19 +501,21 @@ async def logout(
             )
         except (TokenExpiredError, TokenInvalidError) as e:
             # Even if token is expired/invalid, try to deactivate session
-            logger.warning(f"Logout with invalid/expired token: {e!s}")
+            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_crud.get_by_jti(db, jti=refresh_payload.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(
-                    f"User {current_user.id} attempted to logout session {session.id} "
-                    f"belonging to user {session.user_id}"
+                    "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,
@@ -526,17 +523,20 @@ async def logout(
                 )
 
             # Deactivate the session
-            await session_crud.deactivate(db, session_id=str(session.id))
+            await session_service.deactivate(db, session_id=str(session.id))
 
             logger.info(
-                f"User {current_user.id} logged out from {session.device_name} "
-                f"(session {session.id})"
+                "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(
-                f"Logout requested for non-existent session (JTI: {refresh_payload.jti})"
+                "Logout requested for non-existent session (JTI: %s)",
+                refresh_payload.jti,
             )
 
         return MessageResponse(success=True, message="Logged out successfully")
@@ -544,9 +544,7 @@ async def logout(
     except HTTPException:
         raise
     except Exception as e:
-        logger.error(
-            f"Error during logout for user {current_user.id}: {e!s}", exc_info=True
-        )
+        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")
 
@@ -584,12 +582,12 @@ async def logout_all(
     """
     try:
         # Deactivate all sessions for this user
-        count = await session_crud.deactivate_all_user_sessions(
+        count = await session_service.deactivate_all_user_sessions(
             db, user_id=str(current_user.id)
         )
 
         logger.info(
-            f"User {current_user.id} logged out from all devices ({count} sessions)"
+            "User %s logged out from all devices (%s sessions)", current_user.id, count
         )
 
         return MessageResponse(
@@ -598,9 +596,7 @@ async def logout_all(
         )
 
     except Exception as e:
-        logger.error(
-            f"Error during logout-all for user {current_user.id}: {e!s}", exc_info=True
-        )
+        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,

backend/app/api/routes/context.py

@@ -1,411 +0,0 @@
-"""
-Context Management API Endpoints.
-
-Provides REST endpoints for context assembly and optimization
-for LLM requests using the ContextEngine.
-"""
-
-import logging
-from typing import Annotated, Any
-
-from fastapi import APIRouter, Depends, HTTPException, Query, status
-from pydantic import BaseModel, Field
-
-from app.api.dependencies.permissions import require_superuser
-from app.models.user import User
-from app.services.context import (
-    AssemblyTimeoutError,
-    BudgetExceededError,
-    ContextEngine,
-    ContextSettings,
-    create_context_engine,
-    get_context_settings,
-)
-from app.services.mcp import MCPClientManager, get_mcp_client
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-
-# ============================================================================
-# Singleton Engine Management
-# ============================================================================
-
-_context_engine: ContextEngine | None = None
-
-
-def _get_or_create_engine(
-    mcp: MCPClientManager,
-    settings: ContextSettings | None = None,
-) -> ContextEngine:
-    """Get or create the singleton ContextEngine."""
-    global _context_engine
-    if _context_engine is None:
-        _context_engine = create_context_engine(
-            mcp_manager=mcp,
-            redis=None,  # Optional: add Redis caching later
-            settings=settings or get_context_settings(),
-        )
-        logger.info("ContextEngine initialized")
-    else:
-        # Ensure MCP manager is up to date
-        _context_engine.set_mcp_manager(mcp)
-    return _context_engine
-
-
-async def get_context_engine(
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> ContextEngine:
-    """FastAPI dependency to get the ContextEngine."""
-    return _get_or_create_engine(mcp)
-
-
-# ============================================================================
-# Request/Response Schemas
-# ============================================================================
-
-
-class ConversationTurn(BaseModel):
-    """A single conversation turn."""
-
-    role: str = Field(..., description="Role: 'user' or 'assistant'")
-    content: str = Field(..., description="Message content")
-
-
-class ToolResult(BaseModel):
-    """A tool execution result."""
-
-    tool_name: str = Field(..., description="Name of the tool")
-    content: str | dict[str, Any] = Field(..., description="Tool result content")
-    status: str = Field(default="success", description="Execution status")
-
-
-class AssembleContextRequest(BaseModel):
-    """Request to assemble context for an LLM request."""
-
-    project_id: str = Field(..., description="Project identifier")
-    agent_id: str = Field(..., description="Agent identifier")
-    query: str = Field(..., description="User's query or current request")
-    model: str = Field(
-        default="claude-3-sonnet",
-        description="Target model name",
-    )
-    max_tokens: int | None = Field(
-        None,
-        description="Maximum context tokens (uses model default if None)",
-    )
-    system_prompt: str | None = Field(
-        None,
-        description="System prompt/instructions",
-    )
-    task_description: str | None = Field(
-        None,
-        description="Current task description",
-    )
-    knowledge_query: str | None = Field(
-        None,
-        description="Query for knowledge base search",
-    )
-    knowledge_limit: int = Field(
-        default=10,
-        ge=1,
-        le=50,
-        description="Max number of knowledge results",
-    )
-    conversation_history: list[ConversationTurn] | None = Field(
-        None,
-        description="Previous conversation turns",
-    )
-    tool_results: list[ToolResult] | None = Field(
-        None,
-        description="Tool execution results to include",
-    )
-    compress: bool = Field(
-        default=True,
-        description="Whether to apply compression",
-    )
-    use_cache: bool = Field(
-        default=True,
-        description="Whether to use caching",
-    )
-
-
-class AssembledContextResponse(BaseModel):
-    """Response containing assembled context."""
-
-    content: str = Field(..., description="Assembled context content")
-    total_tokens: int = Field(..., description="Total token count")
-    context_count: int = Field(..., description="Number of context items included")
-    compressed: bool = Field(..., description="Whether compression was applied")
-    budget_used_percent: float = Field(
-        ...,
-        description="Percentage of token budget used",
-    )
-    metadata: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Additional metadata",
-    )
-
-
-class TokenCountRequest(BaseModel):
-    """Request to count tokens in content."""
-
-    content: str = Field(..., description="Content to count tokens in")
-    model: str | None = Field(
-        None,
-        description="Model for model-specific tokenization",
-    )
-
-
-class TokenCountResponse(BaseModel):
-    """Response containing token count."""
-
-    token_count: int = Field(..., description="Number of tokens")
-    model: str | None = Field(None, description="Model used for counting")
-
-
-class BudgetInfoResponse(BaseModel):
-    """Response containing budget information for a model."""
-
-    model: str = Field(..., description="Model name")
-    total_tokens: int = Field(..., description="Total token budget")
-    system_tokens: int = Field(..., description="Tokens reserved for system")
-    knowledge_tokens: int = Field(..., description="Tokens for knowledge")
-    conversation_tokens: int = Field(..., description="Tokens for conversation")
-    tool_tokens: int = Field(..., description="Tokens for tool results")
-    response_reserve: int = Field(..., description="Tokens reserved for response")
-
-
-class ContextEngineStatsResponse(BaseModel):
-    """Response containing engine statistics."""
-
-    cache: dict[str, Any] = Field(..., description="Cache statistics")
-    settings: dict[str, Any] = Field(..., description="Current settings")
-
-
-class HealthResponse(BaseModel):
-    """Health check response."""
-
-    status: str = Field(..., description="Health status")
-    mcp_connected: bool = Field(..., description="Whether MCP is connected")
-    cache_enabled: bool = Field(..., description="Whether caching is enabled")
-
-
-# ============================================================================
-# Endpoints
-# ============================================================================
-
-
-@router.get(
-    "/health",
-    response_model=HealthResponse,
-    summary="Context Engine Health",
-    description="Check health status of the context engine.",
-)
-async def health_check(
-    engine: ContextEngine = Depends(get_context_engine),
-) -> HealthResponse:
-    """Check context engine health."""
-    stats = await engine.get_stats()
-    return HealthResponse(
-        status="healthy",
-        mcp_connected=engine._mcp is not None,
-        cache_enabled=stats.get("settings", {}).get("cache_enabled", False),
-    )
-
-
-@router.post(
-    "/assemble",
-    response_model=AssembledContextResponse,
-    summary="Assemble Context",
-    description="Assemble optimized context for an LLM request.",
-)
-async def assemble_context(
-    request: AssembleContextRequest,
-    current_user: User = Depends(require_superuser),
-    engine: ContextEngine = Depends(get_context_engine),
-) -> AssembledContextResponse:
-    """
-    Assemble optimized context for an LLM request.
-
-    This endpoint gathers context from various sources, scores and ranks them,
-    compresses if needed, and formats for the target model.
-    """
-    logger.info(
-        "Context assembly for project=%s agent=%s by user=%s",
-        request.project_id,
-        request.agent_id,
-        current_user.id,
-    )
-
-    # Convert conversation history to dict format
-    conversation_history = None
-    if request.conversation_history:
-        conversation_history = [
-            {"role": turn.role, "content": turn.content}
-            for turn in request.conversation_history
-        ]
-
-    # Convert tool results to dict format
-    tool_results = None
-    if request.tool_results:
-        tool_results = [
-            {
-                "tool_name": tr.tool_name,
-                "content": tr.content,
-                "status": tr.status,
-            }
-            for tr in request.tool_results
-        ]
-
-    try:
-        result = await engine.assemble_context(
-            project_id=request.project_id,
-            agent_id=request.agent_id,
-            query=request.query,
-            model=request.model,
-            max_tokens=request.max_tokens,
-            system_prompt=request.system_prompt,
-            task_description=request.task_description,
-            knowledge_query=request.knowledge_query,
-            knowledge_limit=request.knowledge_limit,
-            conversation_history=conversation_history,
-            tool_results=tool_results,
-            compress=request.compress,
-            use_cache=request.use_cache,
-        )
-
-        # Calculate budget usage percentage
-        budget = await engine.get_budget_for_model(request.model, request.max_tokens)
-        budget_used_percent = (result.total_tokens / budget.total) * 100
-
-        # Check if compression was applied (from metadata if available)
-        was_compressed = result.metadata.get("compressed_contexts", 0) > 0
-
-        return AssembledContextResponse(
-            content=result.content,
-            total_tokens=result.total_tokens,
-            context_count=result.context_count,
-            compressed=was_compressed,
-            budget_used_percent=round(budget_used_percent, 2),
-            metadata={
-                "model": request.model,
-                "query": request.query,
-                "knowledge_included": bool(request.knowledge_query),
-                "conversation_turns": len(request.conversation_history or []),
-                "excluded_count": result.excluded_count,
-                "assembly_time_ms": result.assembly_time_ms,
-            },
-        )
-
-    except AssemblyTimeoutError as e:
-        raise HTTPException(
-            status_code=status.HTTP_504_GATEWAY_TIMEOUT,
-            detail=f"Context assembly timed out: {e}",
-        ) from e
-    except BudgetExceededError as e:
-        raise HTTPException(
-            status_code=status.HTTP_413_REQUEST_ENTITY_TOO_LARGE,
-            detail=f"Token budget exceeded: {e}",
-        ) from e
-    except Exception as e:
-        logger.exception("Context assembly failed")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Context assembly failed: {e}",
-        ) from e
-
-
-@router.post(
-    "/count-tokens",
-    response_model=TokenCountResponse,
-    summary="Count Tokens",
-    description="Count tokens in content using the LLM Gateway.",
-)
-async def count_tokens(
-    request: TokenCountRequest,
-    engine: ContextEngine = Depends(get_context_engine),
-) -> TokenCountResponse:
-    """Count tokens in content."""
-    try:
-        count = await engine.count_tokens(
-            content=request.content,
-            model=request.model,
-        )
-        return TokenCountResponse(
-            token_count=count,
-            model=request.model,
-        )
-    except Exception as e:
-        logger.warning(f"Token counting failed: {e}")
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=f"Token counting failed: {e}",
-        ) from e
-
-
-@router.get(
-    "/budget/{model}",
-    response_model=BudgetInfoResponse,
-    summary="Get Token Budget",
-    description="Get token budget allocation for a specific model.",
-)
-async def get_budget(
-    model: str,
-    max_tokens: Annotated[int | None, Query(description="Custom max tokens")] = None,
-    engine: ContextEngine = Depends(get_context_engine),
-) -> BudgetInfoResponse:
-    """Get token budget information for a model."""
-    budget = await engine.get_budget_for_model(model, max_tokens)
-    return BudgetInfoResponse(
-        model=model,
-        total_tokens=budget.total,
-        system_tokens=budget.system,
-        knowledge_tokens=budget.knowledge,
-        conversation_tokens=budget.conversation,
-        tool_tokens=budget.tools,
-        response_reserve=budget.response_reserve,
-    )
-
-
-@router.get(
-    "/stats",
-    response_model=ContextEngineStatsResponse,
-    summary="Engine Statistics",
-    description="Get context engine statistics and configuration.",
-)
-async def get_stats(
-    current_user: User = Depends(require_superuser),
-    engine: ContextEngine = Depends(get_context_engine),
-) -> ContextEngineStatsResponse:
-    """Get engine statistics."""
-    stats = await engine.get_stats()
-    return ContextEngineStatsResponse(
-        cache=stats.get("cache", {}),
-        settings=stats.get("settings", {}),
-    )
-
-
-@router.post(
-    "/cache/invalidate",
-    status_code=status.HTTP_204_NO_CONTENT,
-    summary="Invalidate Cache (Admin Only)",
-    description="Invalidate context cache entries.",
-)
-async def invalidate_cache(
-    project_id: Annotated[
-        str | None, Query(description="Project to invalidate")
-    ] = None,
-    pattern: Annotated[str | None, Query(description="Pattern to match")] = None,
-    current_user: User = Depends(require_superuser),
-    engine: ContextEngine = Depends(get_context_engine),
-) -> None:
-    """Invalidate cache entries."""
-    logger.info(
-        "Cache invalidation by user %s: project=%s pattern=%s",
-        current_user.id,
-        project_id,
-        pattern,
-    )
-    await engine.invalidate_cache(project_id=project_id, pattern=pattern)

backend/app/api/routes/events.py

@@ -1,316 +0,0 @@
-"""
-SSE endpoint for real-time project event streaming.
-
-This module provides Server-Sent Events (SSE) endpoints for streaming
-project events to connected clients. Events are scoped to projects,
-with authorization checks to ensure clients only receive events
-for projects they have access to.
-
-Features:
-- Real-time event streaming via SSE
-- Project-scoped authorization
-- Automatic reconnection support (Last-Event-ID)
-- Keepalive messages every 30 seconds
-- Graceful connection cleanup
-"""
-
-import asyncio
-import json
-import logging
-from typing import TYPE_CHECKING
-from uuid import UUID
-
-from fastapi import APIRouter, Depends, Header, Query, Request
-from slowapi import Limiter
-from slowapi.util import get_remote_address
-from sse_starlette.sse import EventSourceResponse
-
-from app.api.dependencies.auth import get_current_user, get_current_user_sse
-from app.api.dependencies.event_bus import get_event_bus
-from app.core.database import get_db
-from app.core.exceptions import AuthorizationError
-from app.models.user import User
-from app.schemas.errors import ErrorCode
-from app.schemas.events import EventType
-from app.services.event_bus import EventBus
-
-if TYPE_CHECKING:
-    from sqlalchemy.ext.asyncio import AsyncSession
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-limiter = Limiter(key_func=get_remote_address)
-
-# Keepalive interval in seconds
-KEEPALIVE_INTERVAL = 30
-
-
-async def check_project_access(
-    project_id: UUID,
-    user: User,
-    db: "AsyncSession",
-) -> bool:
-    """
-    Check if a user has access to a project's events.
-
-    Authorization rules:
-    - Superusers can access all projects
-    - Project owners can access their own projects
-
-    Args:
-        project_id: The project to check access for
-        user: The authenticated user
-        db: Database session for project lookup
-
-    Returns:
-        bool: True if user has access, False otherwise
-    """
-    # Superusers can access all projects
-    if user.is_superuser:
-        logger.debug(
-            f"Project access granted for superuser {user.id} on project {project_id}"
-        )
-        return True
-
-    # Check if user owns the project
-    from app.crud.syndarix import project as project_crud
-
-    project = await project_crud.get(db, id=project_id)
-    if not project:
-        logger.debug(f"Project {project_id} not found for access check")
-        return False
-
-    has_access = bool(project.owner_id == user.id)
-    logger.debug(
-        f"Project access {'granted' if has_access else 'denied'} "
-        f"for user {user.id} on project {project_id} (owner: {project.owner_id})"
-    )
-    return has_access
-
-
-async def event_generator(
-    project_id: UUID,
-    event_bus: EventBus,
-    last_event_id: str | None = None,
-):
-    """
-    Generate SSE events for a project.
-
-    This async generator yields SSE-formatted events from the event bus,
-    including keepalive comments to maintain the connection.
-
-    Args:
-        project_id: The project to stream events for
-        event_bus: The EventBus instance
-        last_event_id: Optional last received event ID for reconnection
-
-    Yields:
-        dict: SSE event data with 'event', 'data', and optional 'id' fields
-    """
-    try:
-        async for event_data in event_bus.subscribe_sse(
-            project_id=project_id,
-            last_event_id=last_event_id,
-            keepalive_interval=KEEPALIVE_INTERVAL,
-        ):
-            if event_data == "":
-                # Keepalive - yield SSE comment
-                yield {"comment": "keepalive"}
-            else:
-                # Parse event to extract type and id
-                try:
-                    event_dict = json.loads(event_data)
-                    event_type = event_dict.get("type", "message")
-                    event_id = event_dict.get("id")
-
-                    yield {
-                        "event": event_type,
-                        "data": event_data,
-                        "id": event_id,
-                    }
-                except json.JSONDecodeError:
-                    # If we can't parse, send as generic message
-                    yield {
-                        "event": "message",
-                        "data": event_data,
-                    }
-
-    except asyncio.CancelledError:
-        logger.info(f"Event stream cancelled for project {project_id}")
-        raise
-    except Exception as e:
-        logger.error(f"Error in event stream for project {project_id}: {e}")
-        raise
-
-
-@router.get(
-    "/projects/{project_id}/events/stream",
-    summary="Stream Project Events",
-    description="""
-    Stream real-time events for a project via Server-Sent Events (SSE).
-
-    **Authentication**: Required (Bearer token OR query parameter)
-    **Authorization**: Must have access to the project
-
-    **Authentication Methods**:
-    - Bearer token in Authorization header (preferred)
-    - Query parameter `token` (for EventSource compatibility)
-
-    Note: EventSource API doesn't support custom headers, so the query parameter
-    option is provided for browser-based SSE clients.
-
-    **SSE Event Format**:
-    ```
-    event: agent.status_changed
-    id: 550e8400-e29b-41d4-a716-446655440000
-    data: {"id": "...", "type": "agent.status_changed", "project_id": "...", ...}
-
-    : keepalive
-
-    event: issue.created
-    id: 550e8400-e29b-41d4-a716-446655440001
-    data: {...}
-    ```
-
-    **Reconnection**: Include the `Last-Event-ID` header with the last received
-    event ID to resume from where you left off.
-
-    **Keepalive**: The server sends a comment (`: keepalive`) every 30 seconds
-    to keep the connection alive.
-
-    **Rate Limit**: 10 connections/minute per IP
-    """,
-    response_class=EventSourceResponse,
-    responses={
-        200: {
-            "description": "SSE stream established",
-            "content": {"text/event-stream": {}},
-        },
-        401: {"description": "Not authenticated"},
-        403: {"description": "Not authorized to access this project"},
-        404: {"description": "Project not found"},
-    },
-    operation_id="stream_project_events",
-)
-@limiter.limit("10/minute")
-async def stream_project_events(
-    request: Request,
-    project_id: UUID,
-    db: "AsyncSession" = Depends(get_db),
-    event_bus: EventBus = Depends(get_event_bus),
-    token: str | None = Query(
-        None, description="Auth token (for EventSource compatibility)"
-    ),
-    authorization: str | None = Header(None, alias="Authorization"),
-    last_event_id: str | None = Header(None, alias="Last-Event-ID"),
-):
-    """
-    Stream real-time events for a project via SSE.
-
-    This endpoint establishes a persistent SSE connection that streams
-    project events to the client in real-time. The connection includes:
-
-    - Event streaming: All project events (agent updates, issues, etc.)
-    - Keepalive: Comment every 30 seconds to maintain connection
-    - Reconnection: Use Last-Event-ID header to resume after disconnect
-
-    The connection is automatically cleaned up when the client disconnects.
-    """
-    # Authenticate user (supports both header and query param tokens)
-    current_user = await get_current_user_sse(
-        db=db, authorization=authorization, token=token
-    )
-
-    logger.info(
-        f"SSE connection request for project {project_id} "
-        f"by user {current_user.id} "
-        f"(last_event_id={last_event_id})"
-    )
-
-    # Check project access
-    has_access = await check_project_access(project_id, current_user, db)
-    if not has_access:
-        raise AuthorizationError(
-            message=f"You don't have access to project {project_id}",
-            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
-        )
-
-    # Return SSE response
-    return EventSourceResponse(
-        event_generator(
-            project_id=project_id,
-            event_bus=event_bus,
-            last_event_id=last_event_id,
-        ),
-        media_type="text/event-stream",
-        headers={
-            "Cache-Control": "no-cache",
-            "Connection": "keep-alive",
-            "X-Accel-Buffering": "no",  # Disable nginx buffering
-        },
-    )
-
-
-@router.post(
-    "/projects/{project_id}/events/test",
-    summary="Send Test Event (Development Only)",
-    description="""
-    Send a test event to a project's event stream. This endpoint is
-    intended for development and testing purposes.
-
-    **Authentication**: Required (Bearer token)
-    **Authorization**: Must have access to the project
-
-    **Note**: This endpoint should be disabled or restricted in production.
-    """,
-    response_model=dict,
-    responses={
-        200: {"description": "Test event sent"},
-        401: {"description": "Not authenticated"},
-        403: {"description": "Not authorized to access this project"},
-    },
-    operation_id="send_test_event",
-)
-async def send_test_event(
-    project_id: UUID,
-    current_user: User = Depends(get_current_user),
-    event_bus: EventBus = Depends(get_event_bus),
-    db: "AsyncSession" = Depends(get_db),
-):
-    """
-    Send a test event to the project's event stream.
-
-    This is useful for testing SSE connections during development.
-    """
-    # Check project access
-    has_access = await check_project_access(project_id, current_user, db)
-    if not has_access:
-        raise AuthorizationError(
-            message=f"You don't have access to project {project_id}",
-            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
-        )
-
-    # Create and publish test event using the Event schema
-    event = EventBus.create_event(
-        event_type=EventType.AGENT_MESSAGE,
-        project_id=project_id,
-        actor_type="user",
-        actor_id=current_user.id,
-        payload={
-            "message": "Test event from SSE endpoint",
-            "message_type": "info",
-        },
-    )
-
-    channel = event_bus.get_project_channel(project_id)
-    await event_bus.publish(channel, event)
-
-    logger.info(f"Test event sent to project {project_id}: {event.id}")
-
-    return {
-        "success": True,
-        "event_id": event.id,
-        "event_type": event.type.value,
-        "message": "Test event sent successfully",
-    }

backend/app/api/routes/issues.py

@@ -1,968 +0,0 @@
-# app/api/routes/issues.py
-"""
-Issue CRUD API endpoints for Syndarix projects.
-
-Provides endpoints for managing issues within projects, including:
-- Create, read, update, delete operations
-- Filtering by status, priority, labels, sprint, assigned agent
-- Search across title and body
-- Assignment to agents
-- External issue tracker sync triggers
-"""
-
-import logging
-import os
-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_user
-from app.core.database import get_db
-from app.core.exceptions import (
-    AuthorizationError,
-    NotFoundError,
-    ValidationException,
-)
-from app.crud.syndarix.agent_instance import agent_instance as agent_instance_crud
-from app.crud.syndarix.issue import issue as issue_crud
-from app.crud.syndarix.project import project as project_crud
-from app.crud.syndarix.sprint import sprint as sprint_crud
-from app.models.syndarix.enums import (
-    AgentStatus,
-    IssuePriority,
-    IssueStatus,
-    SprintStatus,
-    SyncStatus,
-)
-from app.models.user import User
-from app.schemas.common import (
-    MessageResponse,
-    PaginatedResponse,
-    PaginationParams,
-    SortOrder,
-    create_pagination_meta,
-)
-from app.schemas.errors import ErrorCode
-from app.schemas.syndarix.issue import (
-    IssueAssign,
-    IssueCreate,
-    IssueResponse,
-    IssueStats,
-    IssueUpdate,
-)
-
-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 verify_project_ownership(
-    db: AsyncSession,
-    project_id: UUID,
-    user: User,
-) -> None:
-    """
-    Verify that the user owns the project or is a superuser.
-
-    Args:
-        db: Database session
-        project_id: Project UUID to verify
-        user: Current authenticated user
-
-    Raises:
-        NotFoundError: If project does not exist
-        AuthorizationError: If user does not own the project
-    """
-    project = await project_crud.get(db, id=project_id)
-    if not project:
-        raise NotFoundError(
-            message=f"Project {project_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    if not user.is_superuser and project.owner_id != user.id:
-        raise AuthorizationError(
-            message="You do not have access to this project",
-            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
-        )
-
-
-def _build_issue_response(
-    issue: Any,
-    project_name: str | None = None,
-    project_slug: str | None = None,
-    sprint_name: str | None = None,
-    assigned_agent_type_name: str | None = None,
-) -> IssueResponse:
-    """
-    Build an IssueResponse from an Issue model instance.
-
-    Args:
-        issue: Issue model instance
-        project_name: Optional project name from relationship
-        project_slug: Optional project slug from relationship
-        sprint_name: Optional sprint name from relationship
-        assigned_agent_type_name: Optional agent type name from relationship
-
-    Returns:
-        IssueResponse schema instance
-    """
-    return IssueResponse(
-        id=issue.id,
-        project_id=issue.project_id,
-        title=issue.title,
-        body=issue.body,
-        status=issue.status,
-        priority=issue.priority,
-        labels=issue.labels or [],
-        assigned_agent_id=issue.assigned_agent_id,
-        human_assignee=issue.human_assignee,
-        sprint_id=issue.sprint_id,
-        story_points=issue.story_points,
-        external_tracker_type=issue.external_tracker_type,
-        external_issue_id=issue.external_issue_id,
-        remote_url=issue.remote_url,
-        external_issue_number=issue.external_issue_number,
-        sync_status=issue.sync_status,
-        last_synced_at=issue.last_synced_at,
-        external_updated_at=issue.external_updated_at,
-        closed_at=issue.closed_at,
-        created_at=issue.created_at,
-        updated_at=issue.updated_at,
-        project_name=project_name,
-        project_slug=project_slug,
-        sprint_name=sprint_name,
-        assigned_agent_type_name=assigned_agent_type_name,
-    )
-
-
-# ===== Issue CRUD Endpoints =====
-
-
-@router.post(
-    "/projects/{project_id}/issues",
-    response_model=IssueResponse,
-    status_code=status.HTTP_201_CREATED,
-    summary="Create Issue",
-    description="Create a new issue in a project",
-    operation_id="create_issue",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def create_issue(
-    request: Request,
-    project_id: UUID,
-    issue_in: IssueCreate,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Create a new issue within a project.
-
-    The user must own the project or be a superuser.
-    The project_id in the path takes precedence over any project_id in the body.
-
-    Args:
-        request: FastAPI request object (for rate limiting)
-        project_id: UUID of the project to create the issue in
-        issue_in: Issue creation data
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Created issue with full details
-
-    Raises:
-        NotFoundError: If project not found
-        AuthorizationError: If user lacks access
-        ValidationException: If assigned agent not in project
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    # Override project_id from path
-    issue_in.project_id = project_id
-
-    # Validate assigned agent if provided
-    if issue_in.assigned_agent_id:
-        agent = await agent_instance_crud.get(db, id=issue_in.assigned_agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent instance {issue_in.assigned_agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-        if agent.project_id != project_id:
-            raise ValidationException(
-                message="Agent instance does not belong to this project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="assigned_agent_id",
-            )
-        if agent.status == AgentStatus.TERMINATED:
-            raise ValidationException(
-                message="Cannot assign issue to a terminated agent",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="assigned_agent_id",
-            )
-
-    # Validate sprint if provided (IDOR prevention)
-    if issue_in.sprint_id:
-        sprint = await sprint_crud.get(db, id=issue_in.sprint_id)
-        if not sprint:
-            raise NotFoundError(
-                message=f"Sprint {issue_in.sprint_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-        if sprint.project_id != project_id:
-            raise ValidationException(
-                message="Sprint does not belong to this project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="sprint_id",
-            )
-
-    try:
-        issue = await issue_crud.create(db, obj_in=issue_in)
-        logger.info(
-            f"User {current_user.email} created issue '{issue.title}' "
-            f"in project {project_id}"
-        )
-
-        # Get project details for response
-        project = await project_crud.get(db, id=project_id)
-
-        return _build_issue_response(
-            issue,
-            project_name=project.name if project else None,
-            project_slug=project.slug if project else None,
-        )
-
-    except ValueError as e:
-        logger.warning(f"Failed to create issue: {e!s}")
-        raise ValidationException(
-            message=str(e),
-            error_code=ErrorCode.VALIDATION_ERROR,
-        )
-    except Exception as e:
-        logger.error(f"Error creating issue: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/projects/{project_id}/issues",
-    response_model=PaginatedResponse[IssueResponse],
-    summary="List Issues",
-    description="Get paginated list of issues in a project with filtering",
-    operation_id="list_issues",
-)
-@limiter.limit(f"{120 * RATE_MULTIPLIER}/minute")
-async def list_issues(
-    request: Request,
-    project_id: UUID,
-    pagination: PaginationParams = Depends(),
-    status_filter: IssueStatus | None = Query(
-        None, alias="status", description="Filter by issue status"
-    ),
-    priority: IssuePriority | None = Query(None, description="Filter by priority"),
-    labels: list[str] | None = Query(
-        None, description="Filter by labels (comma-separated)"
-    ),
-    sprint_id: UUID | None = Query(None, description="Filter by sprint ID"),
-    assigned_agent_id: UUID | None = Query(
-        None, description="Filter by assigned agent ID"
-    ),
-    sync_status: SyncStatus | None = Query(None, description="Filter by sync status"),
-    search: str | None = Query(
-        None, min_length=1, max_length=100, description="Search in title and body"
-    ),
-    sort_by: str = Query(
-        "created_at",
-        description="Field to sort by (created_at, updated_at, priority, status, title)",
-    ),
-    sort_order: SortOrder = Query(SortOrder.DESC, description="Sort order"),
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    List issues in a project with comprehensive filtering options.
-
-    Supports filtering by:
-    - status: Issue status (open, in_progress, in_review, blocked, closed)
-    - priority: Issue priority (low, medium, high, critical)
-    - labels: Match issues containing any of the provided labels
-    - sprint_id: Issues in a specific sprint
-    - assigned_agent_id: Issues assigned to a specific agent
-    - sync_status: External tracker sync status
-    - search: Full-text search in title and body
-
-    Args:
-        request: FastAPI request object
-        project_id: Project UUID
-        pagination: Pagination parameters
-        status_filter: Optional status filter
-        priority: Optional priority filter
-        labels: Optional labels filter
-        sprint_id: Optional sprint filter
-        assigned_agent_id: Optional agent assignment filter
-        sync_status: Optional sync status filter
-        search: Optional search query
-        sort_by: Field to sort by
-        sort_order: Sort direction
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Paginated list of issues matching filters
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    try:
-        # Get filtered issues
-        issues, total = await issue_crud.get_by_project(
-            db,
-            project_id=project_id,
-            status=status_filter,
-            priority=priority,
-            sprint_id=sprint_id,
-            assigned_agent_id=assigned_agent_id,
-            labels=labels,
-            search=search,
-            skip=pagination.offset,
-            limit=pagination.limit,
-            sort_by=sort_by,
-            sort_order=sort_order.value,
-        )
-
-        # Build response objects
-        issue_responses = [_build_issue_response(issue) for issue in issues]
-
-        pagination_meta = create_pagination_meta(
-            total=total,
-            page=pagination.page,
-            limit=pagination.limit,
-            items_count=len(issue_responses),
-        )
-
-        return PaginatedResponse(data=issue_responses, pagination=pagination_meta)
-
-    except Exception as e:
-        logger.error(
-            f"Error listing issues for project {project_id}: {e!s}", exc_info=True
-        )
-        raise
-
-
-# ===== Issue Statistics Endpoint =====
-# NOTE: This endpoint MUST be defined before /{issue_id} routes
-# to prevent FastAPI from trying to parse "stats" as a UUID
-
-
-@router.get(
-    "/projects/{project_id}/issues/stats",
-    response_model=IssueStats,
-    summary="Get Issue Statistics",
-    description="Get aggregated issue statistics for a project",
-    operation_id="get_issue_stats",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def get_issue_stats(
-    request: Request,
-    project_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get aggregated statistics for issues in a project.
-
-    Returns counts by status and priority, along with story point totals.
-
-    Args:
-        request: FastAPI request object
-        project_id: Project UUID
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Issue statistics including counts by status/priority and story points
-
-    Raises:
-        NotFoundError: If project not found
-        AuthorizationError: If user lacks access
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    try:
-        stats = await issue_crud.get_project_stats(db, project_id=project_id)
-        return IssueStats(**stats)
-
-    except Exception as e:
-        logger.error(
-            f"Error getting issue stats for project {project_id}: {e!s}",
-            exc_info=True,
-        )
-        raise
-
-
-@router.get(
-    "/projects/{project_id}/issues/{issue_id}",
-    response_model=IssueResponse,
-    summary="Get Issue",
-    description="Get detailed information about a specific issue",
-    operation_id="get_issue",
-)
-@limiter.limit(f"{120 * RATE_MULTIPLIER}/minute")
-async def get_issue(
-    request: Request,
-    project_id: UUID,
-    issue_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get detailed information about a specific issue.
-
-    Returns the issue with expanded relationship data including
-    project name, sprint name, and assigned agent type name.
-
-    Args:
-        request: FastAPI request object
-        project_id: Project UUID
-        issue_id: Issue UUID
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Issue details with relationship data
-
-    Raises:
-        NotFoundError: If project or issue not found
-        AuthorizationError: If user lacks access
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    # Get issue with details
-    issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
-
-    if not issue_data:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    issue = issue_data["issue"]
-
-    # Verify issue belongs to the project
-    if issue.project_id != project_id:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found in project {project_id}",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    return _build_issue_response(
-        issue,
-        project_name=issue_data.get("project_name"),
-        project_slug=issue_data.get("project_slug"),
-        sprint_name=issue_data.get("sprint_name"),
-        assigned_agent_type_name=issue_data.get("assigned_agent_type_name"),
-    )
-
-
-@router.patch(
-    "/projects/{project_id}/issues/{issue_id}",
-    response_model=IssueResponse,
-    summary="Update Issue",
-    description="Update an existing issue",
-    operation_id="update_issue",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def update_issue(
-    request: Request,
-    project_id: UUID,
-    issue_id: UUID,
-    issue_in: IssueUpdate,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Update an existing issue.
-
-    All fields are optional - only provided fields will be updated.
-    Validates that assigned agent belongs to the same project.
-
-    Args:
-        request: FastAPI request object
-        project_id: Project UUID
-        issue_id: Issue UUID
-        issue_in: Fields to update
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Updated issue details
-
-    Raises:
-        NotFoundError: If project or issue not found
-        AuthorizationError: If user lacks access
-        ValidationException: If validation fails
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    # Get existing issue
-    issue = await issue_crud.get(db, id=issue_id)
-    if not issue:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Verify issue belongs to the project
-    if issue.project_id != project_id:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found in project {project_id}",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Validate assigned agent if being updated
-    if issue_in.assigned_agent_id is not None:
-        agent = await agent_instance_crud.get(db, id=issue_in.assigned_agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent instance {issue_in.assigned_agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-        if agent.project_id != project_id:
-            raise ValidationException(
-                message="Agent instance does not belong to this project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="assigned_agent_id",
-            )
-        if agent.status == AgentStatus.TERMINATED:
-            raise ValidationException(
-                message="Cannot assign issue to a terminated agent",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="assigned_agent_id",
-            )
-
-    # Validate sprint if being updated (IDOR prevention and status validation)
-    if issue_in.sprint_id is not None:
-        sprint = await sprint_crud.get(db, id=issue_in.sprint_id)
-        if not sprint:
-            raise NotFoundError(
-                message=f"Sprint {issue_in.sprint_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-        if sprint.project_id != project_id:
-            raise ValidationException(
-                message="Sprint does not belong to this project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="sprint_id",
-            )
-        # Cannot add issues to completed or cancelled sprints
-        if sprint.status in [SprintStatus.COMPLETED, SprintStatus.CANCELLED]:
-            raise ValidationException(
-                message=f"Cannot add issues to sprint with status '{sprint.status.value}'",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="sprint_id",
-            )
-
-    try:
-        updated_issue = await issue_crud.update(db, db_obj=issue, obj_in=issue_in)
-        logger.info(
-            f"User {current_user.email} updated issue {issue_id} in project {project_id}"
-        )
-
-        # Get full details for response
-        issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
-
-        return _build_issue_response(
-            updated_issue,
-            project_name=issue_data.get("project_name") if issue_data else None,
-            project_slug=issue_data.get("project_slug") if issue_data else None,
-            sprint_name=issue_data.get("sprint_name") if issue_data else None,
-            assigned_agent_type_name=issue_data.get("assigned_agent_type_name")
-            if issue_data
-            else None,
-        )
-
-    except ValueError as e:
-        logger.warning(f"Failed to update issue {issue_id}: {e!s}")
-        raise ValidationException(
-            message=str(e),
-            error_code=ErrorCode.VALIDATION_ERROR,
-        )
-    except Exception as e:
-        logger.error(f"Error updating issue {issue_id}: {e!s}", exc_info=True)
-        raise
-
-
-@router.delete(
-    "/projects/{project_id}/issues/{issue_id}",
-    response_model=MessageResponse,
-    summary="Delete Issue",
-    description="Delete an issue permanently",
-    operation_id="delete_issue",
-)
-@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
-async def delete_issue(
-    request: Request,
-    project_id: UUID,
-    issue_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Delete an issue permanently.
-
-    The issue will be permanently removed from the database.
-
-    Args:
-        request: FastAPI request object
-        project_id: Project UUID
-        issue_id: Issue UUID
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Success message
-
-    Raises:
-        NotFoundError: If project or issue not found
-        AuthorizationError: If user lacks access
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    # Get existing issue
-    issue = await issue_crud.get(db, id=issue_id)
-    if not issue:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Verify issue belongs to the project
-    if issue.project_id != project_id:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found in project {project_id}",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    try:
-        issue_title = issue.title
-        await issue_crud.remove(db, id=issue_id)
-        logger.info(
-            f"User {current_user.email} deleted issue {issue_id} "
-            f"('{issue_title}') from project {project_id}"
-        )
-
-        return MessageResponse(
-            success=True,
-            message=f"Issue '{issue_title}' has been deleted",
-        )
-
-    except Exception as e:
-        logger.error(f"Error deleting issue {issue_id}: {e!s}", exc_info=True)
-        raise
-
-
-# ===== Issue Assignment Endpoint =====
-
-
-@router.post(
-    "/projects/{project_id}/issues/{issue_id}/assign",
-    response_model=IssueResponse,
-    summary="Assign Issue",
-    description="Assign an issue to an agent or human",
-    operation_id="assign_issue",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def assign_issue(
-    request: Request,
-    project_id: UUID,
-    issue_id: UUID,
-    assignment: IssueAssign,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Assign an issue to an agent or human.
-
-    Only one type of assignment is allowed at a time:
-    - assigned_agent_id: Assign to an AI agent instance
-    - human_assignee: Assign to a human (name/email string)
-
-    To unassign, pass both as null/None.
-
-    Args:
-        request: FastAPI request object
-        project_id: Project UUID
-        issue_id: Issue UUID
-        assignment: Assignment data
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Updated issue with assignment
-
-    Raises:
-        NotFoundError: If project, issue, or agent not found
-        AuthorizationError: If user lacks access
-        ValidationException: If agent not in project
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    # Get existing issue
-    issue = await issue_crud.get(db, id=issue_id)
-    if not issue:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Verify issue belongs to the project
-    if issue.project_id != project_id:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found in project {project_id}",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Process assignment based on type
-    if assignment.assigned_agent_id:
-        # Validate agent exists and belongs to project
-        agent = await agent_instance_crud.get(db, id=assignment.assigned_agent_id)
-        if not agent:
-            raise NotFoundError(
-                message=f"Agent instance {assignment.assigned_agent_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-        if agent.project_id != project_id:
-            raise ValidationException(
-                message="Agent instance does not belong to this project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="assigned_agent_id",
-            )
-        if agent.status == AgentStatus.TERMINATED:
-            raise ValidationException(
-                message="Cannot assign issue to a terminated agent",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="assigned_agent_id",
-            )
-
-        updated_issue = await issue_crud.assign_to_agent(
-            db, issue_id=issue_id, agent_id=assignment.assigned_agent_id
-        )
-        logger.info(
-            f"User {current_user.email} assigned issue {issue_id} to agent {agent.name}"
-        )
-
-    elif assignment.human_assignee:
-        updated_issue = await issue_crud.assign_to_human(
-            db, issue_id=issue_id, human_assignee=assignment.human_assignee
-        )
-        logger.info(
-            f"User {current_user.email} assigned issue {issue_id} "
-            f"to human '{assignment.human_assignee}'"
-        )
-
-    else:
-        # Unassign - clear both agent and human
-        updated_issue = await issue_crud.assign_to_agent(
-            db, issue_id=issue_id, agent_id=None
-        )
-        logger.info(f"User {current_user.email} unassigned issue {issue_id}")
-
-    if not updated_issue:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Get full details for response
-    issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
-
-    return _build_issue_response(
-        updated_issue,
-        project_name=issue_data.get("project_name") if issue_data else None,
-        project_slug=issue_data.get("project_slug") if issue_data else None,
-        sprint_name=issue_data.get("sprint_name") if issue_data else None,
-        assigned_agent_type_name=issue_data.get("assigned_agent_type_name")
-        if issue_data
-        else None,
-    )
-
-
-@router.delete(
-    "/projects/{project_id}/issues/{issue_id}/assignment",
-    response_model=IssueResponse,
-    summary="Unassign Issue",
-    description="""
-    Remove agent/human assignment from an issue.
-
-    **Authentication**: Required (Bearer token)
-    **Authorization**: Project owner or superuser
-
-    This clears both agent and human assignee fields.
-
-    **Rate Limit**: 60 requests/minute
-    """,
-    operation_id="unassign_issue",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def unassign_issue(
-    request: Request,
-    project_id: UUID,
-    issue_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Remove assignment from an issue.
-
-    Clears both assigned_agent_id and human_assignee fields.
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    # Get existing issue
-    issue = await issue_crud.get(db, id=issue_id)
-    if not issue:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Verify issue belongs to project (IDOR prevention)
-    if issue.project_id != project_id:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found in project {project_id}",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Unassign the issue
-    updated_issue = await issue_crud.unassign(db, issue_id=issue_id)
-
-    if not updated_issue:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    logger.info(f"User {current_user.email} unassigned issue {issue_id}")
-
-    # Get full details for response
-    issue_data = await issue_crud.get_with_details(db, issue_id=issue_id)
-
-    return _build_issue_response(
-        updated_issue,
-        project_name=issue_data.get("project_name") if issue_data else None,
-        project_slug=issue_data.get("project_slug") if issue_data else None,
-        sprint_name=issue_data.get("sprint_name") if issue_data else None,
-        assigned_agent_type_name=issue_data.get("assigned_agent_type_name")
-        if issue_data
-        else None,
-    )
-
-
-# ===== Issue Sync Endpoint =====
-
-
-@router.post(
-    "/projects/{project_id}/issues/{issue_id}/sync",
-    response_model=MessageResponse,
-    summary="Trigger Issue Sync",
-    description="Trigger synchronization with external issue tracker",
-    operation_id="sync_issue",
-)
-@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
-async def sync_issue(
-    request: Request,
-    project_id: UUID,
-    issue_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Trigger synchronization of an issue with its external tracker.
-
-    This endpoint queues a sync task for the issue. The actual synchronization
-    happens asynchronously via Celery.
-
-    Prerequisites:
-    - Issue must have external_tracker_type configured
-    - Project must have integration settings for the tracker
-
-    Args:
-        request: FastAPI request object
-        project_id: Project UUID
-        issue_id: Issue UUID
-        current_user: Authenticated user
-        db: Database session
-
-    Returns:
-        Message indicating sync has been triggered
-
-    Raises:
-        NotFoundError: If project or issue not found
-        AuthorizationError: If user lacks access
-        ValidationException: If issue has no external tracker
-    """
-    # Verify project access
-    await verify_project_ownership(db, project_id, current_user)
-
-    # Get existing issue
-    issue = await issue_crud.get(db, id=issue_id)
-    if not issue:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Verify issue belongs to the project
-    if issue.project_id != project_id:
-        raise NotFoundError(
-            message=f"Issue {issue_id} not found in project {project_id}",
-            error_code=ErrorCode.NOT_FOUND,
-        )
-
-    # Check if issue has external tracker configured
-    if not issue.external_tracker_type:
-        raise ValidationException(
-            message="Issue does not have an external tracker configured",
-            error_code=ErrorCode.VALIDATION_ERROR,
-            field="external_tracker_type",
-        )
-
-    # Update sync status to pending
-    await issue_crud.update_sync_status(
-        db,
-        issue_id=issue_id,
-        sync_status=SyncStatus.PENDING,
-    )
-
-    # TODO: Queue Celery task for actual sync
-    # When Celery is set up, this will be:
-    # from app.tasks.sync import sync_issue_task
-    # sync_issue_task.delay(str(issue_id))
-
-    logger.info(
-        f"User {current_user.email} triggered sync for issue {issue_id} "
-        f"(tracker: {issue.external_tracker_type})"
-    )
-
-    return MessageResponse(
-        success=True,
-        message=f"Sync triggered for issue '{issue.title}'. "
-        f"Status will update when complete.",
-    )

backend/app/api/routes/mcp.py

@@ -1,446 +0,0 @@
-"""
-MCP (Model Context Protocol) API Endpoints
-
-Provides REST endpoints for managing MCP server connections
-and executing tool calls.
-"""
-
-import logging
-import re
-from typing import Annotated, Any
-
-from fastapi import APIRouter, Depends, HTTPException, Path, status
-from pydantic import BaseModel, Field
-
-from app.api.dependencies.permissions import require_superuser
-from app.models.user import User
-from app.services.mcp import (
-    MCPCircuitOpenError,
-    MCPClientManager,
-    MCPConnectionError,
-    MCPError,
-    MCPServerNotFoundError,
-    MCPTimeoutError,
-    MCPToolError,
-    MCPToolNotFoundError,
-    get_mcp_client,
-)
-
-logger = logging.getLogger(__name__)
-
-router = APIRouter()
-
-# Server name validation pattern: alphanumeric, hyphens, underscores, 1-64 chars
-SERVER_NAME_PATTERN = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
-
-# Type alias for validated server name path parameter
-ServerNamePath = Annotated[
-    str,
-    Path(
-        description="MCP server name",
-        min_length=1,
-        max_length=64,
-        pattern=r"^[a-zA-Z0-9_-]+$",
-    ),
-]
-
-
-# ============================================================================
-# Request/Response Schemas
-# ============================================================================
-
-
-class ServerInfo(BaseModel):
-    """Information about an MCP server."""
-
-    name: str = Field(..., description="Server name")
-    url: str = Field(..., description="Server URL")
-    enabled: bool = Field(..., description="Whether server is enabled")
-    timeout: int = Field(..., description="Request timeout in seconds")
-    transport: str = Field(..., description="Transport type (http, stdio, sse)")
-    description: str | None = Field(None, description="Server description")
-
-
-class ServerListResponse(BaseModel):
-    """Response containing list of MCP servers."""
-
-    servers: list[ServerInfo]
-    total: int
-
-
-class ToolInfoResponse(BaseModel):
-    """Information about an MCP tool."""
-
-    name: str = Field(..., description="Tool name")
-    description: str | None = Field(None, description="Tool description")
-    server_name: str | None = Field(None, description="Server providing the tool")
-    input_schema: dict[str, Any] | None = Field(
-        None, description="JSON schema for input"
-    )
-
-
-class ToolListResponse(BaseModel):
-    """Response containing list of tools."""
-
-    tools: list[ToolInfoResponse]
-    total: int
-
-
-class ServerHealthStatus(BaseModel):
-    """Health status for a server."""
-
-    name: str
-    healthy: bool
-    state: str
-    url: str
-    error: str | None = None
-    tools_count: int = 0
-
-
-class HealthCheckResponse(BaseModel):
-    """Response containing health status of all servers."""
-
-    servers: dict[str, ServerHealthStatus]
-    healthy_count: int
-    unhealthy_count: int
-    total: int
-
-
-class ToolCallRequest(BaseModel):
-    """Request to execute a tool."""
-
-    server: str = Field(..., description="MCP server name")
-    tool: str = Field(..., description="Tool name to execute")
-    arguments: dict[str, Any] = Field(
-        default_factory=dict,
-        description="Tool arguments",
-    )
-    timeout: float | None = Field(
-        None,
-        description="Optional timeout override in seconds",
-    )
-
-
-class ToolCallResponse(BaseModel):
-    """Response from tool execution."""
-
-    success: bool
-    data: Any | None = None
-    error: str | None = None
-    error_code: str | None = None
-    tool_name: str | None = None
-    server_name: str | None = None
-    execution_time_ms: float = 0.0
-    request_id: str | None = None
-
-
-class CircuitBreakerStatus(BaseModel):
-    """Status of a circuit breaker."""
-
-    server_name: str
-    state: str
-    failure_count: int
-
-
-class CircuitBreakerListResponse(BaseModel):
-    """Response containing circuit breaker statuses."""
-
-    circuit_breakers: list[CircuitBreakerStatus]
-
-
-# ============================================================================
-# Endpoints
-# ============================================================================
-
-
-@router.get(
-    "/servers",
-    response_model=ServerListResponse,
-    summary="List MCP Servers",
-    description="Get list of all registered MCP servers with their configurations.",
-)
-async def list_servers(
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> ServerListResponse:
-    """List all registered MCP servers."""
-    servers = []
-
-    for name in mcp.list_servers():
-        try:
-            config = mcp.get_server_config(name)
-            servers.append(
-                ServerInfo(
-                    name=name,
-                    url=config.url,
-                    enabled=config.enabled,
-                    timeout=config.timeout,
-                    transport=config.transport.value,
-                    description=config.description,
-                )
-            )
-        except MCPServerNotFoundError:
-            continue
-
-    return ServerListResponse(
-        servers=servers,
-        total=len(servers),
-    )
-
-
-@router.get(
-    "/servers/{server_name}/tools",
-    response_model=ToolListResponse,
-    summary="List Server Tools",
-    description="Get list of tools available on a specific MCP server.",
-)
-async def list_server_tools(
-    server_name: ServerNamePath,
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> ToolListResponse:
-    """List all tools available on a specific server."""
-    try:
-        tools = await mcp.list_tools(server_name)
-        return ToolListResponse(
-            tools=[
-                ToolInfoResponse(
-                    name=t.name,
-                    description=t.description,
-                    server_name=t.server_name,
-                    input_schema=t.input_schema,
-                )
-                for t in tools
-            ],
-            total=len(tools),
-        )
-    except MCPServerNotFoundError as e:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Server not found: {server_name}",
-        ) from e
-
-
-@router.get(
-    "/tools",
-    response_model=ToolListResponse,
-    summary="List All Tools",
-    description="Get list of all tools from all MCP servers.",
-)
-async def list_all_tools(
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> ToolListResponse:
-    """List all tools from all servers."""
-    tools = await mcp.list_all_tools()
-    return ToolListResponse(
-        tools=[
-            ToolInfoResponse(
-                name=t.name,
-                description=t.description,
-                server_name=t.server_name,
-                input_schema=t.input_schema,
-            )
-            for t in tools
-        ],
-        total=len(tools),
-    )
-
-
-@router.get(
-    "/health",
-    response_model=HealthCheckResponse,
-    summary="Health Check",
-    description="Check health status of all MCP servers.",
-)
-async def health_check(
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> HealthCheckResponse:
-    """Perform health check on all MCP servers."""
-    health_results = await mcp.health_check()
-
-    servers = {
-        name: ServerHealthStatus(
-            name=status.name,
-            healthy=status.healthy,
-            state=status.state,
-            url=status.url,
-            error=status.error,
-            tools_count=status.tools_count,
-        )
-        for name, status in health_results.items()
-    }
-
-    healthy_count = sum(1 for s in servers.values() if s.healthy)
-    unhealthy_count = len(servers) - healthy_count
-
-    return HealthCheckResponse(
-        servers=servers,
-        healthy_count=healthy_count,
-        unhealthy_count=unhealthy_count,
-        total=len(servers),
-    )
-
-
-@router.post(
-    "/call",
-    response_model=ToolCallResponse,
-    summary="Execute Tool (Admin Only)",
-    description="Execute a tool on an MCP server. Requires superuser privileges.",
-)
-async def call_tool(
-    request: ToolCallRequest,
-    current_user: User = Depends(require_superuser),
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> ToolCallResponse:
-    """
-    Execute a tool on an MCP server.
-
-    This endpoint is restricted to superusers for direct tool execution.
-    Normal tool execution should go through agent workflows.
-    """
-    logger.info(
-        "Tool call by user %s: %s.%s",
-        current_user.id,
-        request.server,
-        request.tool,
-    )
-
-    try:
-        result = await mcp.call_tool(
-            server=request.server,
-            tool=request.tool,
-            args=request.arguments,
-            timeout=request.timeout,
-        )
-
-        return ToolCallResponse(
-            success=result.success,
-            data=result.data,
-            error=result.error,
-            error_code=result.error_code,
-            tool_name=result.tool_name,
-            server_name=result.server_name,
-            execution_time_ms=result.execution_time_ms,
-            request_id=result.request_id,
-        )
-
-    except MCPCircuitOpenError as e:
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail=f"Server temporarily unavailable: {e.server_name}",
-        ) from e
-    except MCPToolNotFoundError as e:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Tool not found: {e.tool_name}",
-        ) from e
-    except MCPServerNotFoundError as e:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Server not found: {e.server_name}",
-        ) from e
-    except MCPTimeoutError as e:
-        raise HTTPException(
-            status_code=status.HTTP_504_GATEWAY_TIMEOUT,
-            detail=str(e),
-        ) from e
-    except MCPConnectionError as e:
-        raise HTTPException(
-            status_code=status.HTTP_502_BAD_GATEWAY,
-            detail=str(e),
-        ) from e
-    except MCPToolError as e:
-        # Tool errors are returned in the response, not as HTTP errors
-        return ToolCallResponse(
-            success=False,
-            error=str(e),
-            error_code=e.error_code,
-            tool_name=e.tool_name,
-            server_name=e.server_name,
-        )
-    except MCPError as e:
-        raise HTTPException(
-            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
-            detail=str(e),
-        ) from e
-
-
-@router.get(
-    "/circuit-breakers",
-    response_model=CircuitBreakerListResponse,
-    summary="List Circuit Breakers",
-    description="Get status of all circuit breakers.",
-)
-async def list_circuit_breakers(
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> CircuitBreakerListResponse:
-    """Get status of all circuit breakers."""
-    status_dict = mcp.get_circuit_breaker_status()
-
-    return CircuitBreakerListResponse(
-        circuit_breakers=[
-            CircuitBreakerStatus(
-                server_name=name,
-                state=info.get("state", "unknown"),
-                failure_count=info.get("failure_count", 0),
-            )
-            for name, info in status_dict.items()
-        ]
-    )
-
-
-@router.post(
-    "/circuit-breakers/{server_name}/reset",
-    status_code=status.HTTP_204_NO_CONTENT,
-    summary="Reset Circuit Breaker (Admin Only)",
-    description="Manually reset a circuit breaker for a server.",
-)
-async def reset_circuit_breaker(
-    server_name: ServerNamePath,
-    current_user: User = Depends(require_superuser),
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> None:
-    """Manually reset a circuit breaker."""
-    logger.info(
-        "Circuit breaker reset by user %s for server %s",
-        current_user.id,
-        server_name,
-    )
-
-    success = await mcp.reset_circuit_breaker(server_name)
-    if not success:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"No circuit breaker found for server: {server_name}",
-        )
-
-
-@router.post(
-    "/servers/{server_name}/reconnect",
-    status_code=status.HTTP_204_NO_CONTENT,
-    summary="Reconnect to Server (Admin Only)",
-    description="Force reconnection to an MCP server.",
-)
-async def reconnect_server(
-    server_name: ServerNamePath,
-    current_user: User = Depends(require_superuser),
-    mcp: MCPClientManager = Depends(get_mcp_client),
-) -> None:
-    """Force reconnection to an MCP server."""
-    logger.info(
-        "Reconnect requested by user %s for server %s",
-        current_user.id,
-        server_name,
-    )
-
-    try:
-        await mcp.disconnect(server_name)
-        await mcp.connect(server_name)
-    except MCPServerNotFoundError as e:
-        raise HTTPException(
-            status_code=status.HTTP_404_NOT_FOUND,
-            detail=f"Server not found: {server_name}",
-        ) from e
-    except MCPConnectionError as e:
-        raise HTTPException(
-            status_code=status.HTTP_502_BAD_GATEWAY,
-            detail=f"Failed to reconnect: {e}",
-        ) from e

backend/app/api/routes/oauth.py

@@ -25,8 +25,6 @@ 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.crud import oauth_account
-from app.crud.session import session as session_crud
 from app.models.user import User
 from app.schemas.oauth import (
     OAuthAccountsListResponse,
@@ -38,6 +36,7 @@ from app.schemas.oauth import (
 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()
@@ -82,17 +81,19 @@ async def _create_oauth_login_session(
             location_country=device_info.location_country,
         )
 
-        await session_crud.create_session(db, obj_in=session_data)
+        await session_service.create_session(db, obj_in=session_data)
 
         logger.info(
-            f"OAuth login successful: {user.email} via {provider} "
-            f"from {device_info.device_name} (IP: {device_info.ip_address})"
+            "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.error(
-            f"Failed to create session for OAuth login {user.email}: {session_err!s}",
-            exc_info=True,
+        logger.exception(
+            "Failed to create session for OAuth login %s: %s", user.email, session_err
         )
 
 
@@ -177,13 +178,13 @@ async def get_authorization_url(
         }
 
     except AuthError as e:
-        logger.warning(f"OAuth authorization failed: {e!s}")
+        logger.warning("OAuth authorization failed: %s", e)
         raise HTTPException(
             status_code=status.HTTP_400_BAD_REQUEST,
             detail=str(e),
         )
     except Exception as e:
-        logger.error(f"OAuth authorization error: {e!s}", exc_info=True)
+        logger.exception("OAuth authorization error: %s", e)
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="Failed to create authorization URL",
@@ -251,13 +252,13 @@ async def handle_callback(
         return result
 
     except AuthError as e:
-        logger.warning(f"OAuth callback failed: {e!s}")
+        logger.warning("OAuth callback failed: %s", e)
         raise HTTPException(
             status_code=status.HTTP_401_UNAUTHORIZED,
             detail=str(e),
         )
     except Exception as e:
-        logger.error(f"OAuth callback error: {e!s}", exc_info=True)
+        logger.exception("OAuth callback error: %s", e)
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="OAuth authentication failed",
@@ -289,7 +290,7 @@ async def list_accounts(
     Returns:
         List of linked OAuth accounts
     """
-    accounts = await oauth_account.get_user_accounts(db, user_id=current_user.id)
+    accounts = await OAuthService.get_user_accounts(db, user_id=current_user.id)
     return OAuthAccountsListResponse(accounts=accounts)
 
 
@@ -338,13 +339,13 @@ async def unlink_account(
         )
 
     except AuthError as e:
-        logger.warning(f"OAuth unlink failed for {current_user.email}: {e!s}")
+        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.error(f"OAuth unlink error: {e!s}", exc_info=True)
+        logger.exception("OAuth unlink error: %s", e)
         raise HTTPException(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="Failed to unlink OAuth account",
@@ -397,7 +398,7 @@ async def start_link(
         )
 
     # Check if user already has this provider linked
-    existing = await oauth_account.get_user_account_by_provider(
+    existing = await OAuthService.get_user_account_by_provider(
         db, user_id=current_user.id, provider=provider
     )
     if existing:
@@ -420,13 +421,13 @@ async def start_link(
         }
 
     except AuthError as e:
-        logger.warning(f"OAuth link authorization failed: {e!s}")
+        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.error(f"OAuth link error: {e!s}", exc_info=True)
+        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

@@ -34,7 +34,6 @@ from app.api.dependencies.auth import (
 )
 from app.core.config import settings
 from app.core.database import get_db
-from app.crud import oauth_client as oauth_client_crud
 from app.models.user import User
 from app.schemas.oauth import (
     OAuthClientCreate,
@@ -453,7 +452,7 @@ async def token(
             except Exception as e:
                 # Log malformed Basic auth for security monitoring
                 logger.warning(
-                    f"Malformed Basic auth header in token request: {type(e).__name__}"
+                    "Malformed Basic auth header in token request: %s", type(e).__name__
                 )
                 # Fall back to form body
 
@@ -564,7 +563,8 @@ async def revoke(
             except Exception as e:
                 # Log malformed Basic auth for security monitoring
                 logger.warning(
-                    f"Malformed Basic auth header in revoke request: {type(e).__name__}"
+                    "Malformed Basic auth header in revoke request: %s",
+                    type(e).__name__,
                 )
                 # Fall back to form body
 
@@ -586,7 +586,7 @@ async def revoke(
         )
     except Exception as e:
         # Log but don't expose errors per RFC 7009
-        logger.warning(f"Token revocation error: {e}")
+        logger.warning("Token revocation error: %s", e)
 
     # Always return 200 OK per RFC 7009
     return {"status": "ok"}
@@ -635,7 +635,8 @@ async def introspect(
             except Exception as e:
                 # Log malformed Basic auth for security monitoring
                 logger.warning(
-                    f"Malformed Basic auth header in introspect request: {type(e).__name__}"
+                    "Malformed Basic auth header in introspect request: %s",
+                    type(e).__name__,
                 )
                 # Fall back to form body
 
@@ -655,8 +656,8 @@ async def introspect(
             headers={"WWW-Authenticate": "Basic"},
         )
     except Exception as e:
-        logger.warning(f"Token introspection error: {e}")
-        return OAuthTokenIntrospectionResponse(active=False)
+        logger.warning("Token introspection error: %s", e)
+        return OAuthTokenIntrospectionResponse(active=False)  # pyright: ignore[reportCallIssue]
 
 
 # ============================================================================
@@ -712,7 +713,7 @@ async def register_client(
         client_type=client_type,
     )
 
-    client, secret = await oauth_client_crud.create_client(db, obj_in=client_data)
+    client, secret = await provider_service.register_client(db, client_data)
 
     # Update MCP server URL if provided
     if mcp_server_url:
@@ -750,7 +751,7 @@ async def list_clients(
     current_user: User = Depends(get_current_superuser),
 ) -> list[OAuthClientResponse]:
     """List all OAuth clients."""
-    clients = await oauth_client_crud.get_all_clients(db)
+    clients = await provider_service.list_clients(db)
     return [OAuthClientResponse.model_validate(c) for c in clients]
 
 
@@ -776,7 +777,7 @@ async def delete_client(
             detail="Client not found",
         )
 
-    await oauth_client_crud.delete_client(db, client_id=client_id)
+    await provider_service.delete_client_by_id(db, client_id=client_id)
 
 
 # ============================================================================
@@ -797,30 +798,7 @@ async def list_my_consents(
     current_user: User = Depends(get_current_active_user),
 ) -> list[dict]:
     """List applications the user has authorized."""
-    from sqlalchemy import select
-
-    from app.models.oauth_client import OAuthClient
-    from app.models.oauth_provider_token import OAuthConsent
-
-    result = await db.execute(
-        select(OAuthConsent, OAuthClient)
-        .join(OAuthClient, OAuthConsent.client_id == OAuthClient.client_id)
-        .where(OAuthConsent.user_id == current_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
-    ]
+    return await provider_service.list_user_consents(db, user_id=current_user.id)
 
 
 @router.delete(

backend/app/api/routes/organizations.py

@@ -15,8 +15,6 @@ 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.core.exceptions import ErrorCode, NotFoundError
-from app.crud.organization import organization as organization_crud
 from app.models.user import User
 from app.schemas.common import (
     PaginatedResponse,
@@ -28,6 +26,7 @@ from app.schemas.organizations import (
     OrganizationResponse,
     OrganizationUpdate,
 )
+from app.services.organization_service import organization_service
 
 logger = logging.getLogger(__name__)
 
@@ -54,7 +53,7 @@ async def get_my_organizations(
     """
     try:
         # Get all org data in single query with JOIN and subquery
-        orgs_data = await organization_crud.get_user_organizations_with_details(
+        orgs_data = await organization_service.get_user_organizations_with_details(
             db, user_id=current_user.id, is_active=is_active
         )
 
@@ -78,7 +77,7 @@ async def get_my_organizations(
         return orgs_with_data
 
     except Exception as e:
-        logger.error(f"Error getting user organizations: {e!s}", exc_info=True)
+        logger.exception("Error getting user organizations: %s", e)
         raise
 
 
@@ -100,13 +99,7 @@ async def get_organization(
     User must be a member of the organization.
     """
     try:
-        org = await organization_crud.get(db, id=organization_id)
-        if not org:  # pragma: no cover - Permission check prevents this (see docs/UNREACHABLE_DEFENSIVE_CODE_ANALYSIS.md)
-            raise NotFoundError(
-                detail=f"Organization {organization_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
+        org = await organization_service.get_organization(db, str(organization_id))
         org_dict = {
             "id": org.id,
             "name": org.name,
@@ -116,16 +109,14 @@ async def get_organization(
             "settings": org.settings,
             "created_at": org.created_at,
             "updated_at": org.updated_at,
-            "member_count": await organization_crud.get_member_count(
+            "member_count": await organization_service.get_member_count(
                 db, organization_id=org.id
             ),
         }
         return OrganizationResponse(**org_dict)
 
-    except NotFoundError:  # pragma: no cover - See above
-        raise
     except Exception as e:
-        logger.error(f"Error getting organization: {e!s}", exc_info=True)
+        logger.exception("Error getting organization: %s", e)
         raise
 
 
@@ -149,7 +140,7 @@ async def get_organization_members(
     User must be a member of the organization to view members.
     """
     try:
-        members, total = await organization_crud.get_organization_members(
+        members, total = await organization_service.get_organization_members(
             db,
             organization_id=organization_id,
             skip=pagination.offset,
@@ -169,7 +160,7 @@ async def get_organization_members(
         return PaginatedResponse(data=member_responses, pagination=pagination_meta)
 
     except Exception as e:
-        logger.error(f"Error getting organization members: {e!s}", exc_info=True)
+        logger.exception("Error getting organization members: %s", e)
         raise
 
 
@@ -192,16 +183,12 @@ async def update_organization(
     Requires owner or admin role in the organization.
     """
     try:
-        org = await organization_crud.get(db, id=organization_id)
-        if not org:  # pragma: no cover - Permission check prevents this (see docs/UNREACHABLE_DEFENSIVE_CODE_ANALYSIS.md)
-            raise NotFoundError(
-                detail=f"Organization {organization_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        updated_org = await organization_crud.update(db, db_obj=org, obj_in=org_in)
+        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(
-            f"User {current_user.email} updated organization {updated_org.name}"
+            "User %s updated organization %s", current_user.email, updated_org.name
         )
 
         org_dict = {
@@ -213,14 +200,12 @@ async def update_organization(
             "settings": updated_org.settings,
             "created_at": updated_org.created_at,
             "updated_at": updated_org.updated_at,
-            "member_count": await organization_crud.get_member_count(
+            "member_count": await organization_service.get_member_count(
                 db, organization_id=updated_org.id
             ),
         }
         return OrganizationResponse(**org_dict)
 
-    except NotFoundError:  # pragma: no cover - See above
-        raise
     except Exception as e:
-        logger.error(f"Error updating organization: {e!s}", exc_info=True)
+        logger.exception("Error updating organization: %s", e)
         raise

backend/app/api/routes/projects.py

@@ -1,659 +0,0 @@
-# app/api/routes/projects.py
-"""
-Project management API endpoints for Syndarix.
-
-These endpoints allow users to manage their AI-powered software consulting projects.
-Users can create, read, update, and manage the lifecycle of their projects.
-"""
-
-import logging
-import os
-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_user
-from app.core.database import get_db
-from app.core.exceptions import (
-    AuthorizationError,
-    DuplicateError,
-    ErrorCode,
-    NotFoundError,
-    ValidationException,
-)
-from app.crud.syndarix.project import project as project_crud
-from app.models.syndarix.enums import ProjectStatus
-from app.models.user import User
-from app.schemas.common import (
-    MessageResponse,
-    PaginatedResponse,
-    PaginationParams,
-    create_pagination_meta,
-)
-from app.schemas.syndarix.project import (
-    ProjectCreate,
-    ProjectResponse,
-    ProjectUpdate,
-)
-
-router = APIRouter()
-logger = logging.getLogger(__name__)
-
-# Initialize rate limiter
-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
-
-
-def _build_project_response(project_data: dict[str, Any]) -> ProjectResponse:
-    """
-    Build a ProjectResponse from project data dictionary.
-
-    Args:
-        project_data: Dictionary containing project and related counts
-
-    Returns:
-        ProjectResponse with all fields populated
-    """
-    project = project_data["project"]
-    return ProjectResponse(
-        id=project.id,
-        name=project.name,
-        slug=project.slug,
-        description=project.description,
-        autonomy_level=project.autonomy_level,
-        status=project.status,
-        settings=project.settings,
-        owner_id=project.owner_id,
-        created_at=project.created_at,
-        updated_at=project.updated_at,
-        agent_count=project_data.get("agent_count", 0),
-        issue_count=project_data.get("issue_count", 0),
-        active_sprint_name=project_data.get("active_sprint_name"),
-    )
-
-
-def _check_project_ownership(project: Any, current_user: User) -> None:
-    """
-    Check if the current user owns the project or is a superuser.
-
-    Args:
-        project: The project to check ownership of
-        current_user: The authenticated user
-
-    Raises:
-        AuthorizationError: If user doesn't own the project and isn't a superuser
-    """
-    if not current_user.is_superuser and project.owner_id != current_user.id:
-        raise AuthorizationError(
-            message="You do not have permission to access this project",
-            error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
-        )
-
-
-# =============================================================================
-# Project CRUD Endpoints
-# =============================================================================
-
-
-@router.post(
-    "",
-    response_model=ProjectResponse,
-    status_code=status.HTTP_201_CREATED,
-    summary="Create Project",
-    description="""
-    Create a new project for the current user.
-
-    The project will be owned by the authenticated user.
-    A unique slug is required for URL-friendly project identification.
-
-    **Rate Limit**: 10 requests/minute
-    """,
-    operation_id="create_project",
-)
-@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
-async def create_project(
-    request: Request,
-    project_in: ProjectCreate,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Create a new project.
-
-    The authenticated user becomes the owner of the project.
-    """
-    try:
-        # Set the owner to the current user
-        project_data = ProjectCreate(
-            name=project_in.name,
-            slug=project_in.slug,
-            description=project_in.description,
-            autonomy_level=project_in.autonomy_level,
-            status=project_in.status,
-            settings=project_in.settings,
-            owner_id=current_user.id,
-        )
-
-        project = await project_crud.create(db, obj_in=project_data)
-        logger.info(f"User {current_user.email} created project {project.slug}")
-
-        return ProjectResponse(
-            id=project.id,
-            name=project.name,
-            slug=project.slug,
-            description=project.description,
-            autonomy_level=project.autonomy_level,
-            status=project.status,
-            settings=project.settings,
-            owner_id=project.owner_id,
-            created_at=project.created_at,
-            updated_at=project.updated_at,
-            agent_count=0,
-            issue_count=0,
-            active_sprint_name=None,
-        )
-
-    except ValueError as e:
-        error_msg = str(e)
-        if "already exists" in error_msg.lower():
-            logger.warning(f"Duplicate project slug attempted: {project_in.slug}")
-            raise DuplicateError(
-                message=error_msg,
-                error_code=ErrorCode.DUPLICATE_ENTRY,
-                field="slug",
-            )
-        logger.error(f"Error creating project: {error_msg}", exc_info=True)
-        raise
-    except Exception as e:
-        logger.error(f"Unexpected error creating project: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "",
-    response_model=PaginatedResponse[ProjectResponse],
-    summary="List Projects",
-    description="""
-    List projects for the current user with filtering and pagination.
-
-    Regular users see only their own projects.
-    Superusers can see all projects by setting `all_projects=true`.
-
-    **Rate Limit**: 30 requests/minute
-    """,
-    operation_id="list_projects",
-)
-@limiter.limit(f"{30 * RATE_MULTIPLIER}/minute")
-async def list_projects(
-    request: Request,
-    pagination: PaginationParams = Depends(),
-    status_filter: ProjectStatus | None = Query(
-        None, alias="status", description="Filter by project status"
-    ),
-    search: str | None = Query(
-        None, description="Search by name, slug, or description"
-    ),
-    all_projects: bool = Query(False, description="Show all projects (superuser only)"),
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    List projects with filtering, search, and pagination.
-
-    Regular users only see their own projects.
-    Superusers can view all projects if all_projects is true.
-    """
-    try:
-        # Determine owner filter based on user role and request
-        owner_id = (
-            None if (current_user.is_superuser and all_projects) else current_user.id
-        )
-
-        projects_data, total = await project_crud.get_multi_with_counts(
-            db,
-            skip=pagination.offset,
-            limit=pagination.limit,
-            status=status_filter,
-            owner_id=owner_id,
-            search=search,
-        )
-
-        # Build response objects
-        project_responses = [_build_project_response(data) for data in projects_data]
-
-        pagination_meta = create_pagination_meta(
-            total=total,
-            page=pagination.page,
-            limit=pagination.limit,
-            items_count=len(project_responses),
-        )
-
-        return PaginatedResponse(data=project_responses, pagination=pagination_meta)
-
-    except Exception as e:
-        logger.error(f"Error listing projects: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/{project_id}",
-    response_model=ProjectResponse,
-    summary="Get Project",
-    description="""
-    Get detailed information about a specific project.
-
-    Users can only access their own projects unless they are superusers.
-
-    **Rate Limit**: 60 requests/minute
-    """,
-    operation_id="get_project",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def get_project(
-    request: Request,
-    project_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get detailed information about a project by ID.
-
-    Includes agent count, issue count, and active sprint name.
-    """
-    try:
-        project_data = await project_crud.get_with_counts(db, project_id=project_id)
-
-        if not project_data:
-            raise NotFoundError(
-                message=f"Project {project_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        project = project_data["project"]
-        _check_project_ownership(project, current_user)
-
-        return _build_project_response(project_data)
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except Exception as e:
-        logger.error(f"Error getting project {project_id}: {e!s}", exc_info=True)
-        raise
-
-
-@router.get(
-    "/slug/{slug}",
-    response_model=ProjectResponse,
-    summary="Get Project by Slug",
-    description="""
-    Get detailed information about a project by its slug.
-
-    Users can only access their own projects unless they are superusers.
-
-    **Rate Limit**: 60 requests/minute
-    """,
-    operation_id="get_project_by_slug",
-)
-@limiter.limit(f"{60 * RATE_MULTIPLIER}/minute")
-async def get_project_by_slug(
-    request: Request,
-    slug: str,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Get detailed information about a project by slug.
-
-    Includes agent count, issue count, and active sprint name.
-    """
-    try:
-        project = await project_crud.get_by_slug(db, slug=slug)
-
-        if not project:
-            raise NotFoundError(
-                message=f"Project with slug '{slug}' not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        _check_project_ownership(project, current_user)
-
-        # Get project with counts
-        project_data = await project_crud.get_with_counts(db, project_id=project.id)
-
-        if not project_data:
-            raise NotFoundError(
-                message=f"Project with slug '{slug}' not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        return _build_project_response(project_data)
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except Exception as e:
-        logger.error(f"Error getting project by slug {slug}: {e!s}", exc_info=True)
-        raise
-
-
-@router.patch(
-    "/{project_id}",
-    response_model=ProjectResponse,
-    summary="Update Project",
-    description="""
-    Update an existing project.
-
-    Only the project owner or a superuser can update a project.
-    Only provided fields will be updated.
-
-    **Rate Limit**: 20 requests/minute
-    """,
-    operation_id="update_project",
-)
-@limiter.limit(f"{20 * RATE_MULTIPLIER}/minute")
-async def update_project(
-    request: Request,
-    project_id: UUID,
-    project_in: ProjectUpdate,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Update a project's information.
-
-    Only the project owner or superusers can perform updates.
-    """
-    try:
-        project = await project_crud.get(db, id=project_id)
-
-        if not project:
-            raise NotFoundError(
-                message=f"Project {project_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        _check_project_ownership(project, current_user)
-
-        # Update the project
-        updated_project = await project_crud.update(
-            db, db_obj=project, obj_in=project_in
-        )
-        logger.info(f"User {current_user.email} updated project {updated_project.slug}")
-
-        # Get updated project with counts
-        project_data = await project_crud.get_with_counts(
-            db, project_id=updated_project.id
-        )
-
-        if not project_data:
-            # This shouldn't happen, but handle gracefully
-            raise NotFoundError(
-                message=f"Project {project_id} not found after update",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        return _build_project_response(project_data)
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except ValueError as e:
-        error_msg = str(e)
-        if "already exists" in error_msg.lower():
-            logger.warning(f"Duplicate project slug attempted: {project_in.slug}")
-            raise DuplicateError(
-                message=error_msg,
-                error_code=ErrorCode.DUPLICATE_ENTRY,
-                field="slug",
-            )
-        logger.error(f"Error updating project: {error_msg}", exc_info=True)
-        raise
-    except Exception as e:
-        logger.error(f"Error updating project {project_id}: {e!s}", exc_info=True)
-        raise
-
-
-@router.delete(
-    "/{project_id}",
-    response_model=MessageResponse,
-    summary="Archive Project",
-    description="""
-    Archive a project (soft delete).
-
-    Only the project owner or a superuser can archive a project.
-    Archived projects are not deleted but are no longer accessible for active work.
-
-    **Rate Limit**: 10 requests/minute
-    """,
-    operation_id="archive_project",
-)
-@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
-async def archive_project(
-    request: Request,
-    project_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Archive a project by setting its status to ARCHIVED.
-
-    This is a soft delete operation. The project data is preserved.
-    """
-    try:
-        project = await project_crud.get(db, id=project_id)
-
-        if not project:
-            raise NotFoundError(
-                message=f"Project {project_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        _check_project_ownership(project, current_user)
-
-        # Check if project is already archived
-        if project.status == ProjectStatus.ARCHIVED:
-            return MessageResponse(
-                success=True,
-                message=f"Project '{project.name}' is already archived",
-            )
-
-        archived_project = await project_crud.archive_project(db, project_id=project_id)
-
-        if not archived_project:
-            raise NotFoundError(
-                message=f"Failed to archive project {project_id}",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        logger.info(f"User {current_user.email} archived project {project.slug}")
-
-        return MessageResponse(
-            success=True,
-            message=f"Project '{archived_project.name}' has been archived",
-        )
-
-    except (NotFoundError, AuthorizationError):
-        raise
-    except Exception as e:
-        logger.error(f"Error archiving project {project_id}: {e!s}", exc_info=True)
-        raise
-
-
-# =============================================================================
-# Project Lifecycle Endpoints
-# =============================================================================
-
-
-@router.post(
-    "/{project_id}/pause",
-    response_model=ProjectResponse,
-    summary="Pause Project",
-    description="""
-    Pause an active project.
-
-    Only ACTIVE projects can be paused.
-    Only the project owner or a superuser can pause a project.
-
-    **Rate Limit**: 10 requests/minute
-    """,
-    operation_id="pause_project",
-)
-@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
-async def pause_project(
-    request: Request,
-    project_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Pause an active project.
-
-    Sets the project status to PAUSED. Only ACTIVE projects can be paused.
-    """
-    try:
-        project = await project_crud.get(db, id=project_id)
-
-        if not project:
-            raise NotFoundError(
-                message=f"Project {project_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        _check_project_ownership(project, current_user)
-
-        # Validate current status (business logic validation, not authorization)
-        if project.status == ProjectStatus.PAUSED:
-            raise ValidationException(
-                message="Project is already paused",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="status",
-            )
-
-        if project.status == ProjectStatus.ARCHIVED:
-            raise ValidationException(
-                message="Cannot pause an archived project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="status",
-            )
-
-        if project.status == ProjectStatus.COMPLETED:
-            raise ValidationException(
-                message="Cannot pause a completed project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="status",
-            )
-
-        # Update status to PAUSED
-        updated_project = await project_crud.update(
-            db, db_obj=project, obj_in=ProjectUpdate(status=ProjectStatus.PAUSED)
-        )
-        logger.info(f"User {current_user.email} paused project {project.slug}")
-
-        # Get project with counts
-        project_data = await project_crud.get_with_counts(
-            db, project_id=updated_project.id
-        )
-
-        if not project_data:
-            raise NotFoundError(
-                message=f"Project {project_id} not found after update",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        return _build_project_response(project_data)
-
-    except (NotFoundError, AuthorizationError, ValidationException):
-        raise
-    except Exception as e:
-        logger.error(f"Error pausing project {project_id}: {e!s}", exc_info=True)
-        raise
-
-
-@router.post(
-    "/{project_id}/resume",
-    response_model=ProjectResponse,
-    summary="Resume Project",
-    description="""
-    Resume a paused project.
-
-    Only PAUSED projects can be resumed.
-    Only the project owner or a superuser can resume a project.
-
-    **Rate Limit**: 10 requests/minute
-    """,
-    operation_id="resume_project",
-)
-@limiter.limit(f"{10 * RATE_MULTIPLIER}/minute")
-async def resume_project(
-    request: Request,
-    project_id: UUID,
-    current_user: User = Depends(get_current_user),
-    db: AsyncSession = Depends(get_db),
-) -> Any:
-    """
-    Resume a paused project.
-
-    Sets the project status back to ACTIVE. Only PAUSED projects can be resumed.
-    """
-    try:
-        project = await project_crud.get(db, id=project_id)
-
-        if not project:
-            raise NotFoundError(
-                message=f"Project {project_id} not found",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        _check_project_ownership(project, current_user)
-
-        # Validate current status (business logic validation, not authorization)
-        if project.status == ProjectStatus.ACTIVE:
-            raise ValidationException(
-                message="Project is already active",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="status",
-            )
-
-        if project.status == ProjectStatus.ARCHIVED:
-            raise ValidationException(
-                message="Cannot resume an archived project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="status",
-            )
-
-        if project.status == ProjectStatus.COMPLETED:
-            raise ValidationException(
-                message="Cannot resume a completed project",
-                error_code=ErrorCode.VALIDATION_ERROR,
-                field="status",
-            )
-
-        # Update status to ACTIVE
-        updated_project = await project_crud.update(
-            db, db_obj=project, obj_in=ProjectUpdate(status=ProjectStatus.ACTIVE)
-        )
-        logger.info(f"User {current_user.email} resumed project {project.slug}")
-
-        # Get project with counts
-        project_data = await project_crud.get_with_counts(
-            db, project_id=updated_project.id
-        )
-
-        if not project_data:
-            raise NotFoundError(
-                message=f"Project {project_id} not found after update",
-                error_code=ErrorCode.NOT_FOUND,
-            )
-
-        return _build_project_response(project_data)
-
-    except (NotFoundError, AuthorizationError, ValidationException):
-        raise
-    except Exception as e:
-        logger.error(f"Error resuming project {project_id}: {e!s}", exc_info=True)
-        raise

backend/app/api/routes/sessions.py

@@ -17,10 +17,10 @@ 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.crud.session import session as session_crud
 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__)
@@ -60,7 +60,7 @@ async def list_my_sessions(
     """
     try:
         # Get all active sessions for user
-        sessions = await session_crud.get_user_sessions(
+        sessions = await session_service.get_user_sessions(
             db, user_id=str(current_user.id), active_only=True
         )
 
@@ -74,9 +74,7 @@ async def list_my_sessions(
                 # For now, we'll mark current based on most recent activity
             except Exception as e:
                 # Optional token parsing - silently ignore failures
-                logger.debug(
-                    f"Failed to decode access token for session marking: {e!s}"
-                )
+                logger.debug("Failed to decode access token for session marking: %s", e)
 
         # Convert to response format
         session_responses = []
@@ -98,7 +96,7 @@ async def list_my_sessions(
             session_responses.append(session_response)
 
         logger.info(
-            f"User {current_user.id} listed {len(session_responses)} active sessions"
+            "User %s listed %s active sessions", current_user.id, len(session_responses)
         )
 
         return SessionListResponse(
@@ -106,9 +104,7 @@ async def list_my_sessions(
         )
 
     except Exception as e:
-        logger.error(
-            f"Error listing sessions for user {current_user.id}: {e!s}", exc_info=True
-        )
+        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",
@@ -150,7 +146,7 @@ async def revoke_session(
     """
     try:
         # Get the session
-        session = await session_crud.get(db, id=str(session_id))
+        session = await session_service.get_session(db, str(session_id))
 
         if not session:
             raise NotFoundError(
@@ -161,8 +157,10 @@ async def revoke_session(
         # Verify session belongs to current user
         if str(session.user_id) != str(current_user.id):
             logger.warning(
-                f"User {current_user.id} attempted to revoke session {session_id} "
-                f"belonging to user {session.user_id}"
+                "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",
@@ -170,11 +168,13 @@ async def revoke_session(
             )
 
         # Deactivate the session
-        await session_crud.deactivate(db, session_id=str(session_id))
+        await session_service.deactivate(db, session_id=str(session_id))
 
         logger.info(
-            f"User {current_user.id} revoked session {session_id} "
-            f"({session.device_name})"
+            "User %s revoked session %s (%s)",
+            current_user.id,
+            session_id,
+            session.device_name,
         )
 
         return MessageResponse(
@@ -185,7 +185,7 @@ async def revoke_session(
     except (NotFoundError, AuthorizationError):
         raise
     except Exception as e:
-        logger.error(f"Error revoking session {session_id}: {e!s}", exc_info=True)
+        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",
@@ -224,12 +224,12 @@ async def cleanup_expired_sessions(
     """
     try:
         # Use optimized bulk DELETE instead of N individual deletes
-        deleted_count = await session_crud.cleanup_expired_for_user(
+        deleted_count = await session_service.cleanup_expired_for_user(
             db, user_id=str(current_user.id)
         )
 
         logger.info(
-            f"User {current_user.id} cleaned up {deleted_count} expired sessions"
+            "User %s cleaned up %s expired sessions", current_user.id, deleted_count
         )
 
         return MessageResponse(
@@ -237,9 +237,8 @@ async def cleanup_expired_sessions(
         )
 
     except Exception as e:
-        logger.error(
-            f"Error cleaning up sessions for user {current_user.id}: {e!s}",
-            exc_info=True,
+        logger.exception(
+            "Error cleaning up sessions for user %s: %s", current_user.id, e
         )
         await db.rollback()
         raise HTTPException(

backend/app/api/routes/users.py

@@ -1,5 +1,5 @@
 """
-User management endpoints for CRUD operations.
+User management endpoints for database operations.
 """
 
 import logging
@@ -13,8 +13,7 @@ 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, NotFoundError
-from app.crud.user import user as user_crud
+from app.core.exceptions import AuthorizationError, ErrorCode
 from app.models.user import User
 from app.schemas.common import (
     MessageResponse,
@@ -25,6 +24,7 @@ from app.schemas.common import (
 )
 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__)
 
@@ -71,7 +71,7 @@ async def list_users(
             filters["is_superuser"] = is_superuser
 
         # Get paginated users with total count
-        users, total = await user_crud.get_multi_with_total(
+        users, total = await user_service.list_users(
             db,
             skip=pagination.offset,
             limit=pagination.limit,
@@ -90,7 +90,7 @@ async def list_users(
 
         return PaginatedResponse(data=users, pagination=pagination_meta)
     except Exception as e:
-        logger.error(f"Error listing users: {e!s}", exc_info=True)
+        logger.exception("Error listing users: %s", e)
         raise
 
 
@@ -107,7 +107,9 @@ async def list_users(
     """,
     operation_id="get_current_user_profile",
 )
-def get_current_user_profile(current_user: User = Depends(get_current_user)) -> Any:
+async def get_current_user_profile(
+    current_user: User = Depends(get_current_user),
+) -> Any:
     """Get current user's profile."""
     return current_user
 
@@ -138,18 +140,16 @@ async def update_current_user(
     Users cannot elevate their own permissions (protected by UserUpdate schema validator).
     """
     try:
-        updated_user = await user_crud.update(
-            db, db_obj=current_user, obj_in=user_update
+        updated_user = await user_service.update_user(
+            db, user=current_user, obj_in=user_update
         )
-        logger.info(f"User {current_user.id} updated their profile")
+        logger.info("User %s updated their profile", current_user.id)
         return updated_user
     except ValueError as e:
-        logger.error(f"Error updating user {current_user.id}: {e!s}")
+        logger.error("Error updating user %s: %s", current_user.id, e)
         raise
     except Exception as e:
-        logger.error(
-            f"Unexpected error updating user {current_user.id}: {e!s}", exc_info=True
-        )
+        logger.exception("Unexpected error updating user %s: %s", current_user.id, e)
         raise
 
 
@@ -182,7 +182,9 @@ async def get_user_by_id(
     # Check permissions
     if str(user_id) != str(current_user.id) and not current_user.is_superuser:
         logger.warning(
-            f"User {current_user.id} attempted to access user {user_id} without permission"
+            "User %s attempted to access user %s without permission",
+            current_user.id,
+            user_id,
         )
         raise AuthorizationError(
             message="Not enough permissions to view this user",
@@ -190,13 +192,7 @@ async def get_user_by_id(
         )
 
     # Get user
-    user = await user_crud.get(db, id=str(user_id))
-    if not user:
-        raise NotFoundError(
-            message=f"User with id {user_id} not found",
-            error_code=ErrorCode.USER_NOT_FOUND,
-        )
-
+    user = await user_service.get_user(db, str(user_id))
     return user
 
 
@@ -233,7 +229,9 @@ async def update_user(
 
     if not is_own_profile and not current_user.is_superuser:
         logger.warning(
-            f"User {current_user.id} attempted to update user {user_id} without permission"
+            "User %s attempted to update user %s without permission",
+            current_user.id,
+            user_id,
         )
         raise AuthorizationError(
             message="Not enough permissions to update this user",
@@ -241,22 +239,17 @@ async def update_user(
         )
 
     # Get user
-    user = await user_crud.get(db, id=str(user_id))
-    if not user:
-        raise NotFoundError(
-            message=f"User with id {user_id} not found",
-            error_code=ErrorCode.USER_NOT_FOUND,
-        )
+    user = await user_service.get_user(db, str(user_id))
 
     try:
-        updated_user = await user_crud.update(db, db_obj=user, obj_in=user_update)
-        logger.info(f"User {user_id} updated by {current_user.id}")
+        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(f"Error updating user {user_id}: {e!s}")
+        logger.error("Error updating user %s: %s", user_id, e)
         raise
     except Exception as e:
-        logger.error(f"Unexpected error updating user {user_id}: {e!s}", exc_info=True)
+        logger.exception("Unexpected error updating user %s: %s", user_id, e)
         raise
 
 
@@ -296,19 +289,19 @@ async def change_current_user_password(
         )
 
         if success:
-            logger.info(f"User {current_user.id} changed their password")
+            logger.info("User %s changed their password", current_user.id)
             return MessageResponse(
                 success=True, message="Password changed successfully"
             )
     except AuthenticationError as e:
         logger.warning(
-            f"Failed password change attempt for user {current_user.id}: {e!s}"
+            "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(f"Error changing password for user {current_user.id}: {e!s}")
+        logger.error("Error changing password for user %s: %s", current_user.id, e)
         raise
 
 
@@ -346,24 +339,19 @@ async def delete_user(
             error_code=ErrorCode.INSUFFICIENT_PERMISSIONS,
         )
 
-    # Get user
-    user = await user_crud.get(db, id=str(user_id))
-    if not user:
-        raise NotFoundError(
-            message=f"User with id {user_id} not found",
-            error_code=ErrorCode.USER_NOT_FOUND,
-        )
+    # 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_crud.soft_delete(db, id=str(user_id))
-        logger.info(f"User {user_id} soft-deleted by {current_user.id}")
+        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(f"Error deleting user {user_id}: {e!s}")
+        logger.error("Error deleting user %s: %s", user_id, e)
         raise
     except Exception as e:
-        logger.error(f"Unexpected error deleting user {user_id}: {e!s}", exc_info=True)
+        logger.exception("Unexpected error deleting user %s: %s", user_id, e)
         raise

backend/app/celery_app.py

@@ -1,116 +0,0 @@
-# app/celery_app.py
-"""
-Celery application configuration for Syndarix.
-
-This module configures the Celery app for background task processing:
-- Agent execution tasks (LLM calls, tool execution)
-- Git operations (clone, commit, push, PR creation)
-- Issue synchronization with external trackers
-- Workflow state management
-- Cost tracking and budget monitoring
-
-Architecture:
-- Redis as message broker and result backend
-- Queue routing for task isolation
-- JSON serialization for cross-language compatibility
-- Beat scheduler for periodic tasks
-"""
-
-from celery import Celery
-
-from app.core.config import settings
-
-# Create Celery application instance
-celery_app = Celery(
-    "syndarix",
-    broker=settings.celery_broker_url,
-    backend=settings.celery_result_backend,
-)
-
-# Define task queues with their own exchanges and routing keys
-TASK_QUEUES = {
-    "agent": {"exchange": "agent", "routing_key": "agent"},
-    "git": {"exchange": "git", "routing_key": "git"},
-    "sync": {"exchange": "sync", "routing_key": "sync"},
-    "default": {"exchange": "default", "routing_key": "default"},
-}
-
-# Configure Celery
-celery_app.conf.update(
-    # Serialization
-    task_serializer="json",
-    accept_content=["json"],
-    result_serializer="json",
-    # Timezone
-    timezone="UTC",
-    enable_utc=True,
-    # Task imports for auto-discovery
-    imports=("app.tasks",),
-    # Default queue
-    task_default_queue="default",
-    # Task queues configuration
-    task_queues=TASK_QUEUES,
-    # Task routing - route tasks to appropriate queues
-    task_routes={
-        "app.tasks.agent.*": {"queue": "agent"},
-        "app.tasks.git.*": {"queue": "git"},
-        "app.tasks.sync.*": {"queue": "sync"},
-        "app.tasks.*": {"queue": "default"},
-    },
-    # Time limits per ADR-003
-    task_soft_time_limit=300,  # 5 minutes soft limit
-    task_time_limit=600,  # 10 minutes hard limit
-    # Result expiration - 24 hours
-    result_expires=86400,
-    # Broker connection retry
-    broker_connection_retry_on_startup=True,
-    # Retry configuration per ADR-003 (built-in retry with backoff)
-    task_autoretry_for=(Exception,),  # Retry on all exceptions
-    task_retry_kwargs={"max_retries": 3, "countdown": 5},  # Initial 5s delay
-    task_retry_backoff=True,  # Enable exponential backoff
-    task_retry_backoff_max=600,  # Max 10 minutes between retries
-    task_retry_jitter=True,  # Add jitter to prevent thundering herd
-    # Beat schedule for periodic tasks
-    beat_schedule={
-        # Cost aggregation every hour per ADR-012
-        "aggregate-daily-costs": {
-            "task": "app.tasks.cost.aggregate_daily_costs",
-            "schedule": 3600.0,  # 1 hour in seconds
-        },
-        # Reset daily budget counters at midnight UTC
-        "reset-daily-budget-counters": {
-            "task": "app.tasks.cost.reset_daily_budget_counters",
-            "schedule": 86400.0,  # 24 hours in seconds
-        },
-        # Check for stale workflows every 5 minutes
-        "recover-stale-workflows": {
-            "task": "app.tasks.workflow.recover_stale_workflows",
-            "schedule": 300.0,  # 5 minutes in seconds
-        },
-        # Incremental issue sync every minute per ADR-011
-        "sync-issues-incremental": {
-            "task": "app.tasks.sync.sync_issues_incremental",
-            "schedule": 60.0,  # 1 minute in seconds
-        },
-        # Full issue reconciliation every 15 minutes per ADR-011
-        "sync-issues-full": {
-            "task": "app.tasks.sync.sync_issues_full",
-            "schedule": 900.0,  # 15 minutes in seconds
-        },
-    },
-    # Task execution settings
-    task_acks_late=True,  # Acknowledge tasks after execution
-    task_reject_on_worker_lost=True,  # Reject tasks if worker dies
-    worker_prefetch_multiplier=1,  # Fair task distribution
-)
-
-# Auto-discover tasks from task modules
-celery_app.autodiscover_tasks(
-    [
-        "app.tasks.agent",
-        "app.tasks.git",
-        "app.tasks.sync",
-        "app.tasks.workflow",
-        "app.tasks.cost",
-    ]
-)

backend/app/core/auth.py

@@ -1,23 +1,21 @@
 import asyncio
-import logging
 import uuid
 from datetime import UTC, datetime, timedelta
 from functools import partial
 from typing import Any
 
-from jose import JWTError, jwt
-from passlib.context import CryptContext
+import bcrypt
+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
 
-# Suppress passlib bcrypt warnings about ident
-logging.getLogger("passlib").setLevel(logging.ERROR)
-
-# Password hashing context
-pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
-
 
 # Custom exceptions for auth
 class AuthError(Exception):
@@ -37,13 +35,16 @@ class TokenMissingClaimError(AuthError):
 
 
 def verify_password(plain_password: str, hashed_password: str) -> bool:
-    """Verify a password against a hash."""
-    return pwd_context.verify(plain_password, hashed_password)
+    """Verify a password against a bcrypt hash."""
+    return bcrypt.checkpw(
+        plain_password.encode("utf-8"), hashed_password.encode("utf-8")
+    )
 
 
 def get_password_hash(password: str) -> str:
-    """Generate a password hash."""
-    return pwd_context.hash(password)
+    """Generate a bcrypt password hash."""
+    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:
@@ -60,9 +61,9 @@ async def verify_password_async(plain_password: str, hashed_password: str) -> bo
     Returns:
         True if password matches, False otherwise
     """
-    loop = asyncio.get_event_loop()
+    loop = asyncio.get_running_loop()
     return await loop.run_in_executor(
-        None, partial(pwd_context.verify, plain_password, hashed_password)
+        None, partial(verify_password, plain_password, hashed_password)
     )
 
 
@@ -80,8 +81,8 @@ async def get_password_hash_async(password: str) -> str:
     Returns:
         Hashed password string
     """
-    loop = asyncio.get_event_loop()
-    return await loop.run_in_executor(None, pwd_context.hash, password)
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, get_password_hash, password)
 
 
 def create_access_token(
@@ -121,11 +122,7 @@ def create_access_token(
         to_encode.update(claims)
 
     # Create the JWT
-    encoded_jwt = jwt.encode(
-        to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM
-    )
-
-    return encoded_jwt
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
 
 
 def create_refresh_token(
@@ -154,11 +151,7 @@ def create_refresh_token(
         "type": "refresh",
     }
 
-    encoded_jwt = jwt.encode(
-        to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM
-    )
-
-    return encoded_jwt
+    return jwt.encode(to_encode, settings.SECRET_KEY, algorithm=settings.ALGORITHM)
 
 
 def decode_token(token: str, verify_type: str | None = None) -> TokenPayload:
@@ -198,7 +191,7 @@ def decode_token(token: str, verify_type: str | None = None) -> TokenPayload:
 
         # Reject weak or unexpected algorithms
         # NOTE: These are defensive checks that provide defense-in-depth.
-        # The python-jose library rejects these tokens BEFORE we reach here,
+        # 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
@@ -219,10 +212,11 @@ def decode_token(token: str, verify_type: str | None = None) -> TokenPayload:
         token_data = TokenPayload(**payload)
         return token_data
 
-    except JWTError as e:
-        # Check if the error is due to an expired token
-        if "expired" in str(e).lower():
-            raise TokenExpiredError("Token has expired")
+    except ExpiredSignatureError:
+        raise TokenExpiredError("Token has expired")
+    except MissingRequiredClaimError as e:
+        raise TokenMissingClaimError(f"Token missing required claim: {e}")
+    except InvalidTokenError:
         raise TokenInvalidError("Invalid authentication token")
     except ValidationError:
         raise TokenInvalidError("Invalid token payload")

backend/app/core/config.py

@@ -5,7 +5,7 @@ from pydantic_settings import BaseSettings
 
 
 class Settings(BaseSettings):
-    PROJECT_NAME: str = "Syndarix"
+    PROJECT_NAME: str = "PragmaStack"
     VERSION: str = "1.0.0"
     API_V1_STR: str = "/api/v1"
 
@@ -39,32 +39,6 @@ class Settings(BaseSettings):
     db_pool_timeout: int = 30  # Seconds to wait for a connection
     db_pool_recycle: int = 3600  # Recycle connections after 1 hour
 
-    # Redis configuration (Syndarix: cache, pub/sub, Celery broker)
-    REDIS_URL: str = Field(
-        default="redis://localhost:6379/0",
-        description="Redis URL for cache, pub/sub, and Celery broker",
-    )
-
-    # Celery configuration (Syndarix: background task processing)
-    CELERY_BROKER_URL: str | None = Field(
-        default=None,
-        description="Celery broker URL (defaults to REDIS_URL if not set)",
-    )
-    CELERY_RESULT_BACKEND: str | None = Field(
-        default=None,
-        description="Celery result backend URL (defaults to REDIS_URL if not set)",
-    )
-
-    @property
-    def celery_broker_url(self) -> str:
-        """Get Celery broker URL, defaulting to Redis."""
-        return self.CELERY_BROKER_URL or self.REDIS_URL
-
-    @property
-    def celery_result_backend(self) -> str:
-        """Get Celery result backend URL, defaulting to Redis."""
-        return self.CELERY_RESULT_BACKEND or self.REDIS_URL
-
     # SQL debugging (disable in production)
     sql_echo: bool = False  # Log SQL statements
     sql_echo_pool: bool = False  # Log connection pool events

backend/app/core/database.py

@@ -128,8 +128,8 @@ async def async_transaction_scope() -> AsyncGenerator[AsyncSession, None]:
 
     Usage:
         async with async_transaction_scope() as db:
-            user = await user_crud.create(db, obj_in=user_create)
-            profile = await profile_crud.create(db, obj_in=profile_create)
+            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:
@@ -139,7 +139,7 @@ async def async_transaction_scope() -> AsyncGenerator[AsyncSession, None]:
             logger.debug("Async transaction committed successfully")
         except Exception as e:
             await session.rollback()
-            logger.error(f"Async transaction failed, rolling back: {e!s}")
+            logger.error("Async transaction failed, rolling back: %s", e)
             raise
         finally:
             await session.close()
@@ -155,7 +155,7 @@ async def check_async_database_health() -> bool:
             await db.execute(text("SELECT 1"))
         return True
     except Exception as e:
-        logger.error(f"Async database health check failed: {e!s}")
+        logger.error("Async database health check failed: %s", e)
         return False
 
 

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

@@ -143,8 +143,11 @@ async def api_exception_handler(request: Request, exc: APIException) -> JSONResp
     Returns a standardized error response with error code and message.
     """
     logger.warning(
-        f"API exception: {exc.error_code} - {exc.message} "
-        f"(status: {exc.status_code}, path: {request.url.path})"
+        "API exception: %s - %s (status: %s, path: %s)",
+        exc.error_code,
+        exc.message,
+        exc.status_code,
+        request.url.path,
     )
 
     error_response = ErrorResponse(
@@ -186,7 +189,9 @@ async def validation_exception_handler(
             )
         )
 
-    logger.warning(f"Validation error: {len(errors)} errors (path: {request.url.path})")
+    logger.warning(
+        "Validation error: %s errors (path: %s)", len(errors), request.url.path
+    )
 
     error_response = ErrorResponse(errors=errors)
 
@@ -218,11 +223,14 @@ async def http_exception_handler(request: Request, exc: HTTPException) -> JSONRe
     )
 
     logger.warning(
-        f"HTTP exception: {exc.status_code} - {exc.detail} (path: {request.url.path})"
+        "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))]
+        errors=[ErrorDetail(code=error_code, message=str(exc.detail), field=None)]
     )
 
     return JSONResponse(
@@ -239,10 +247,11 @@ async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONR
     Logs the full exception and returns a generic error response to avoid
     leaking sensitive information in production.
     """
-    logger.error(
-        f"Unhandled exception: {type(exc).__name__} - {exc!s} "
-        f"(path: {request.url.path})",
-        exc_info=True,
+    logger.exception(
+        "Unhandled exception: %s - %s (path: %s)",
+        type(exc).__name__,
+        exc,
+        request.url.path,
     )
 
     # In production, don't expose internal error details
@@ -254,7 +263,7 @@ async def unhandled_exception_handler(request: Request, exc: Exception) -> JSONR
         message = f"{type(exc).__name__}: {exc!s}"
 
     error_response = ErrorResponse(
-        errors=[ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=message)]
+        errors=[ErrorDetail(code=ErrorCode.INTERNAL_ERROR, message=message, field=None)]
     )
 
     return JSONResponse(

backend/app/core/redis.py

@@ -1,474 +0,0 @@
-# app/core/redis.py
-"""
-Redis client configuration for caching and pub/sub.
-
-This module provides async Redis connectivity with connection pooling
-for FastAPI endpoints and background tasks.
-
-Features:
-- Connection pooling for efficient resource usage
-- Cache operations (get, set, delete, expire)
-- Pub/sub operations (publish, subscribe)
-- Health check for monitoring
-"""
-
-import asyncio
-import json
-import logging
-from collections.abc import AsyncGenerator
-from contextlib import asynccontextmanager
-from typing import Any
-
-from redis.asyncio import ConnectionPool, Redis
-from redis.asyncio.client import PubSub
-from redis.exceptions import ConnectionError, RedisError, TimeoutError
-
-from app.core.config import settings
-
-# Configure logging
-logger = logging.getLogger(__name__)
-
-# Default TTL for cache entries (1 hour)
-DEFAULT_CACHE_TTL = 3600
-
-# Connection pool settings
-POOL_MAX_CONNECTIONS = 50
-POOL_TIMEOUT = 10  # seconds
-
-
-class RedisClient:
-    """
-    Async Redis client with connection pooling.
-
-    Provides high-level operations for caching and pub/sub
-    with proper error handling and connection management.
-    """
-
-    def __init__(self, url: str | None = None) -> None:
-        """
-        Initialize Redis client.
-
-        Args:
-            url: Redis connection URL. Defaults to settings.REDIS_URL.
-        """
-        self._url = url or settings.REDIS_URL
-        self._pool: ConnectionPool | None = None
-        self._client: Redis | None = None
-        self._lock = asyncio.Lock()
-
-    async def _ensure_pool(self) -> ConnectionPool:
-        """Ensure connection pool is initialized (thread-safe)."""
-        if self._pool is None:
-            async with self._lock:
-                # Double-check after acquiring lock
-                if self._pool is None:
-                    self._pool = ConnectionPool.from_url(
-                        self._url,
-                        max_connections=POOL_MAX_CONNECTIONS,
-                        socket_timeout=POOL_TIMEOUT,
-                        socket_connect_timeout=POOL_TIMEOUT,
-                        decode_responses=True,
-                        health_check_interval=30,
-                    )
-                    logger.info("Redis connection pool initialized")
-        return self._pool
-
-    async def _get_client(self) -> Redis:
-        """Get Redis client instance from pool."""
-        pool = await self._ensure_pool()
-        if self._client is None:
-            self._client = Redis(connection_pool=pool)
-        return self._client
-
-    # =========================================================================
-    # Cache Operations
-    # =========================================================================
-
-    async def cache_get(self, key: str) -> str | None:
-        """
-        Get a value from cache.
-
-        Args:
-            key: Cache key.
-
-        Returns:
-            Cached value or None if not found.
-        """
-        try:
-            client = await self._get_client()
-            value = await client.get(key)
-            if value is not None:
-                logger.debug(f"Cache hit for key: {key}")
-            else:
-                logger.debug(f"Cache miss for key: {key}")
-            return value
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis cache_get failed for key '{key}': {e}")
-            return None
-        except RedisError as e:
-            logger.error(f"Redis error in cache_get for key '{key}': {e}")
-            return None
-
-    async def cache_get_json(self, key: str) -> Any | None:
-        """
-        Get a JSON-serialized value from cache.
-
-        Args:
-            key: Cache key.
-
-        Returns:
-            Deserialized value or None if not found.
-        """
-        value = await self.cache_get(key)
-        if value is not None:
-            try:
-                return json.loads(value)
-            except json.JSONDecodeError as e:
-                logger.error(f"Failed to decode JSON for key '{key}': {e}")
-                return None
-        return None
-
-    async def cache_set(
-        self,
-        key: str,
-        value: str,
-        ttl: int | None = None,
-    ) -> bool:
-        """
-        Set a value in cache.
-
-        Args:
-            key: Cache key.
-            value: Value to cache.
-            ttl: Time-to-live in seconds. Defaults to DEFAULT_CACHE_TTL.
-
-        Returns:
-            True if successful, False otherwise.
-        """
-        try:
-            client = await self._get_client()
-            ttl = ttl if ttl is not None else DEFAULT_CACHE_TTL
-            await client.set(key, value, ex=ttl)
-            logger.debug(f"Cache set for key: {key} (TTL: {ttl}s)")
-            return True
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis cache_set failed for key '{key}': {e}")
-            return False
-        except RedisError as e:
-            logger.error(f"Redis error in cache_set for key '{key}': {e}")
-            return False
-
-    async def cache_set_json(
-        self,
-        key: str,
-        value: Any,
-        ttl: int | None = None,
-    ) -> bool:
-        """
-        Set a JSON-serialized value in cache.
-
-        Args:
-            key: Cache key.
-            value: Value to serialize and cache.
-            ttl: Time-to-live in seconds.
-
-        Returns:
-            True if successful, False otherwise.
-        """
-        try:
-            serialized = json.dumps(value)
-            return await self.cache_set(key, serialized, ttl)
-        except (TypeError, ValueError) as e:
-            logger.error(f"Failed to serialize value for key '{key}': {e}")
-            return False
-
-    async def cache_delete(self, key: str) -> bool:
-        """
-        Delete a key from cache.
-
-        Args:
-            key: Cache key to delete.
-
-        Returns:
-            True if key was deleted, False otherwise.
-        """
-        try:
-            client = await self._get_client()
-            result = await client.delete(key)
-            logger.debug(f"Cache delete for key: {key} (deleted: {result > 0})")
-            return result > 0
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis cache_delete failed for key '{key}': {e}")
-            return False
-        except RedisError as e:
-            logger.error(f"Redis error in cache_delete for key '{key}': {e}")
-            return False
-
-    async def cache_delete_pattern(self, pattern: str) -> int:
-        """
-        Delete all keys matching a pattern.
-
-        Args:
-            pattern: Glob-style pattern (e.g., "user:*").
-
-        Returns:
-            Number of keys deleted.
-        """
-        try:
-            client = await self._get_client()
-            deleted = 0
-            async for key in client.scan_iter(pattern):
-                await client.delete(key)
-                deleted += 1
-            logger.debug(f"Cache delete pattern '{pattern}': {deleted} keys deleted")
-            return deleted
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis cache_delete_pattern failed for '{pattern}': {e}")
-            return 0
-        except RedisError as e:
-            logger.error(f"Redis error in cache_delete_pattern for '{pattern}': {e}")
-            return 0
-
-    async def cache_expire(self, key: str, ttl: int) -> bool:
-        """
-        Set or update TTL for a key.
-
-        Args:
-            key: Cache key.
-            ttl: New TTL in seconds.
-
-        Returns:
-            True if TTL was set, False if key doesn't exist.
-        """
-        try:
-            client = await self._get_client()
-            result = await client.expire(key, ttl)
-            logger.debug(
-                f"Cache expire for key: {key} (TTL: {ttl}s, success: {result})"
-            )
-            return result
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis cache_expire failed for key '{key}': {e}")
-            return False
-        except RedisError as e:
-            logger.error(f"Redis error in cache_expire for key '{key}': {e}")
-            return False
-
-    async def cache_exists(self, key: str) -> bool:
-        """
-        Check if a key exists in cache.
-
-        Args:
-            key: Cache key.
-
-        Returns:
-            True if key exists, False otherwise.
-        """
-        try:
-            client = await self._get_client()
-            result = await client.exists(key)
-            return result > 0
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis cache_exists failed for key '{key}': {e}")
-            return False
-        except RedisError as e:
-            logger.error(f"Redis error in cache_exists for key '{key}': {e}")
-            return False
-
-    async def cache_ttl(self, key: str) -> int:
-        """
-        Get remaining TTL for a key.
-
-        Args:
-            key: Cache key.
-
-        Returns:
-            TTL in seconds, -1 if no TTL, -2 if key doesn't exist.
-        """
-        try:
-            client = await self._get_client()
-            return await client.ttl(key)
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis cache_ttl failed for key '{key}': {e}")
-            return -2
-        except RedisError as e:
-            logger.error(f"Redis error in cache_ttl for key '{key}': {e}")
-            return -2
-
-    # =========================================================================
-    # Pub/Sub Operations
-    # =========================================================================
-
-    async def publish(self, channel: str, message: str | dict) -> int:
-        """
-        Publish a message to a channel.
-
-        Args:
-            channel: Channel name.
-            message: Message to publish (string or dict for JSON serialization).
-
-        Returns:
-            Number of subscribers that received the message.
-        """
-        try:
-            client = await self._get_client()
-            if isinstance(message, dict):
-                message = json.dumps(message)
-            result = await client.publish(channel, message)
-            logger.debug(f"Published to channel '{channel}': {result} subscribers")
-            return result
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis publish failed for channel '{channel}': {e}")
-            return 0
-        except RedisError as e:
-            logger.error(f"Redis error in publish for channel '{channel}': {e}")
-            return 0
-
-    @asynccontextmanager
-    async def subscribe(self, *channels: str) -> AsyncGenerator[PubSub, None]:
-        """
-        Subscribe to one or more channels.
-
-        Usage:
-            async with redis_client.subscribe("channel1", "channel2") as pubsub:
-                async for message in pubsub.listen():
-                    if message["type"] == "message":
-                        print(message["data"])
-
-        Args:
-            channels: Channel names to subscribe to.
-
-        Yields:
-            PubSub instance for receiving messages.
-        """
-        client = await self._get_client()
-        pubsub = client.pubsub()
-        try:
-            await pubsub.subscribe(*channels)
-            logger.debug(f"Subscribed to channels: {channels}")
-            yield pubsub
-        finally:
-            await pubsub.unsubscribe(*channels)
-            await pubsub.close()
-            logger.debug(f"Unsubscribed from channels: {channels}")
-
-    @asynccontextmanager
-    async def psubscribe(self, *patterns: str) -> AsyncGenerator[PubSub, None]:
-        """
-        Subscribe to channels matching patterns.
-
-        Usage:
-            async with redis_client.psubscribe("user:*") as pubsub:
-                async for message in pubsub.listen():
-                    if message["type"] == "pmessage":
-                        print(message["pattern"], message["channel"], message["data"])
-
-        Args:
-            patterns: Glob-style patterns to subscribe to.
-
-        Yields:
-            PubSub instance for receiving messages.
-        """
-        client = await self._get_client()
-        pubsub = client.pubsub()
-        try:
-            await pubsub.psubscribe(*patterns)
-            logger.debug(f"Pattern subscribed: {patterns}")
-            yield pubsub
-        finally:
-            await pubsub.punsubscribe(*patterns)
-            await pubsub.close()
-            logger.debug(f"Pattern unsubscribed: {patterns}")
-
-    # =========================================================================
-    # Health & Connection Management
-    # =========================================================================
-
-    async def health_check(self) -> bool:
-        """
-        Check if Redis connection is healthy.
-
-        Returns:
-            True if connection is successful, False otherwise.
-        """
-        try:
-            client = await self._get_client()
-            result = await client.ping()
-            return result is True
-        except (ConnectionError, TimeoutError) as e:
-            logger.error(f"Redis health check failed: {e}")
-            return False
-        except RedisError as e:
-            logger.error(f"Redis health check error: {e}")
-            return False
-
-    async def close(self) -> None:
-        """
-        Close Redis connections and cleanup resources.
-
-        Should be called during application shutdown.
-        """
-        if self._client:
-            await self._client.close()
-            self._client = None
-            logger.debug("Redis client closed")
-
-        if self._pool:
-            await self._pool.disconnect()
-            self._pool = None
-            logger.info("Redis connection pool closed")
-
-    async def get_pool_info(self) -> dict[str, Any]:
-        """
-        Get connection pool statistics.
-
-        Returns:
-            Dictionary with pool information.
-        """
-        if self._pool is None:
-            return {"status": "not_initialized"}
-
-        return {
-            "status": "active",
-            "max_connections": POOL_MAX_CONNECTIONS,
-            "url": self._url.split("@")[-1] if "@" in self._url else self._url,
-        }
-
-
-# Global Redis client instance
-redis_client = RedisClient()
-
-
-# FastAPI dependency for Redis client
-async def get_redis() -> AsyncGenerator[RedisClient, None]:
-    """
-    FastAPI dependency that provides the Redis client.
-
-    Usage:
-        @router.get("/cached-data")
-        async def get_data(redis: RedisClient = Depends(get_redis)):
-            cached = await redis.cache_get("my-key")
-            ...
-    """
-    yield redis_client
-
-
-# Health check function for use in /health endpoint
-async def check_redis_health() -> bool:
-    """
-    Check if Redis connection is healthy.
-
-    Returns:
-        True if connection is successful, False otherwise.
-    """
-    return await redis_client.health_check()
-
-
-# Cleanup function for application shutdown
-async def close_redis() -> None:
-    """
-    Close Redis connections.
-
-    Should be called during application shutdown.
-    """
-    await redis_client.close()

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/__init__.py

@@ -1,14 +0,0 @@
-# app/crud/__init__.py
-from .oauth import oauth_account, oauth_client, oauth_state
-from .organization import organization
-from .session import session as session_crud
-from .user import user
-
-__all__ = [
-    "oauth_account",
-    "oauth_client",
-    "oauth_state",
-    "organization",
-    "session_crud",
-    "user",
-]

backend/app/crud/oauth.py

@@ -1,718 +0,0 @@
-"""
-Async CRUD operations for OAuth models using SQLAlchemy 2.0 patterns.
-
-Provides operations for:
-- OAuthAccount: Managing linked OAuth provider accounts
-- OAuthState: CSRF protection state during OAuth flows
-- OAuthClient: Registered OAuth clients (provider mode skeleton)
-"""
-
-import logging
-import secrets
-from datetime import UTC, 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.crud.base import CRUDBase
-from app.models.oauth_account import OAuthAccount
-from app.models.oauth_client import OAuthClient
-from app.models.oauth_state import OAuthState
-from app.schemas.oauth import OAuthAccountCreate, OAuthClientCreate, OAuthStateCreate
-
-logger = logging.getLogger(__name__)
-
-
-# ============================================================================
-# OAuth Account CRUD
-# ============================================================================
-
-
-class EmptySchema(BaseModel):
-    """Placeholder schema for CRUD operations that don't need update schemas."""
-
-
-class CRUDOAuthAccount(CRUDBase[OAuthAccount, OAuthAccountCreate, EmptySchema]):
-    """CRUD operations 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.
-
-        Args:
-            db: Database session
-            provider: OAuth provider name (google, github)
-            provider_user_id: User ID from the OAuth provider
-
-        Returns:
-            OAuthAccount if found, None otherwise
-        """
-        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  # pragma: no cover
-            logger.error(
-                f"Error getting OAuth account for {provider}:{provider_user_id}: {e!s}"
-            )
-            raise
-
-    async def get_by_provider_email(
-        self,
-        db: AsyncSession,
-        *,
-        provider: str,
-        email: str,
-    ) -> OAuthAccount | None:
-        """
-        Get OAuth account by provider and email.
-
-        Used for auto-linking existing accounts by email.
-
-        Args:
-            db: Database session
-            provider: OAuth provider name
-            email: Email address from the OAuth provider
-
-        Returns:
-            OAuthAccount if found, None otherwise
-        """
-        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  # pragma: no cover
-            logger.error(
-                f"Error getting OAuth account for {provider} email {email}: {e!s}"
-            )
-            raise
-
-    async def get_user_accounts(
-        self,
-        db: AsyncSession,
-        *,
-        user_id: str | UUID,
-    ) -> list[OAuthAccount]:
-        """
-        Get all OAuth accounts linked to a user.
-
-        Args:
-            db: Database session
-            user_id: User ID
-
-        Returns:
-            List of OAuthAccount objects
-        """
-        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(f"Error getting OAuth accounts for user {user_id}: {e!s}")
-            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.
-
-        Args:
-            db: Database session
-            user_id: User ID
-            provider: OAuth provider name
-
-        Returns:
-            OAuthAccount if found, None otherwise
-        """
-        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(
-                f"Error getting OAuth account for user {user_id}, provider {provider}: {e!s}"
-            )
-            raise
-
-    async def create_account(
-        self, db: AsyncSession, *, obj_in: OAuthAccountCreate
-    ) -> OAuthAccount:
-        """
-        Create a new OAuth account link.
-
-        Args:
-            db: Database session
-            obj_in: OAuth account creation data
-
-        Returns:
-            Created OAuthAccount
-
-        Raises:
-            ValueError: If account already exists or creation fails
-        """
-        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_encrypted=obj_in.access_token_encrypted,
-                refresh_token_encrypted=obj_in.refresh_token_encrypted,
-                token_expires_at=obj_in.token_expires_at,
-            )
-            db.add(db_obj)
-            await db.commit()
-            await db.refresh(db_obj)
-
-            logger.info(
-                f"OAuth account created: {obj_in.provider} linked to user {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(
-                    f"OAuth account already exists: {obj_in.provider}:{obj_in.provider_user_id}"
-                )
-                raise ValueError(
-                    f"This {obj_in.provider} account is already linked to another user"
-                )
-            logger.error(f"Integrity error creating OAuth account: {error_msg}")
-            raise ValueError(f"Failed to create OAuth account: {error_msg}")
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(f"Error creating OAuth account: {e!s}", exc_info=True)
-            raise
-
-    async def delete_account(
-        self,
-        db: AsyncSession,
-        *,
-        user_id: str | UUID,
-        provider: str,
-    ) -> bool:
-        """
-        Delete an OAuth account link.
-
-        Args:
-            db: Database session
-            user_id: User ID
-            provider: OAuth provider name
-
-        Returns:
-            True if deleted, False if not found
-        """
-        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(
-                    f"OAuth account deleted: {provider} unlinked from user {user_id}"
-                )
-            else:
-                logger.warning(
-                    f"OAuth account not found for deletion: {provider} for user {user_id}"
-                )
-
-            return deleted
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(
-                f"Error deleting OAuth account {provider} for user {user_id}: {e!s}"
-            )
-            raise
-
-    async def update_tokens(
-        self,
-        db: AsyncSession,
-        *,
-        account: OAuthAccount,
-        access_token_encrypted: str | None = None,
-        refresh_token_encrypted: str | None = None,
-        token_expires_at: datetime | None = None,
-    ) -> OAuthAccount:
-        """
-        Update OAuth tokens for an account.
-
-        Args:
-            db: Database session
-            account: OAuthAccount to update
-            access_token_encrypted: New encrypted access token
-            refresh_token_encrypted: New encrypted refresh token
-            token_expires_at: New token expiration time
-
-        Returns:
-            Updated OAuthAccount
-        """
-        try:
-            if access_token_encrypted is not None:
-                account.access_token_encrypted = access_token_encrypted
-            if refresh_token_encrypted is not None:
-                account.refresh_token_encrypted = refresh_token_encrypted
-            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(f"Error updating OAuth tokens: {e!s}")
-            raise
-
-
-# ============================================================================
-# OAuth State CRUD
-# ============================================================================
-
-
-class CRUDOAuthState(CRUDBase[OAuthState, OAuthStateCreate, EmptySchema]):
-    """CRUD operations for OAuth state (CSRF protection)."""
-
-    async def create_state(
-        self, db: AsyncSession, *, obj_in: OAuthStateCreate
-    ) -> OAuthState:
-        """
-        Create a new OAuth state for CSRF protection.
-
-        Args:
-            db: Database session
-            obj_in: OAuth state creation data
-
-        Returns:
-            Created OAuthState
-        """
-        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(f"OAuth state created for {obj_in.provider}")
-            return db_obj
-        except IntegrityError as e:  # pragma: no cover
-            await db.rollback()
-            # State collision (extremely rare with cryptographic random)
-            error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
-            logger.error(f"OAuth state collision: {error_msg}")
-            raise ValueError("Failed to create OAuth state, please retry")
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(f"Error creating OAuth state: {e!s}", exc_info=True)
-            raise
-
-    async def get_and_consume_state(
-        self, db: AsyncSession, *, state: str
-    ) -> OAuthState | None:
-        """
-        Get and delete OAuth state (consume it).
-
-        This ensures each state can only be used once (replay protection).
-
-        Args:
-            db: Database session
-            state: State string to look up
-
-        Returns:
-            OAuthState if found and valid, None otherwise
-        """
-        try:
-            # Get the state
-            result = await db.execute(
-                select(OAuthState).where(OAuthState.state == state)
-            )
-            db_obj = result.scalar_one_or_none()
-
-            if db_obj is None:
-                logger.warning(f"OAuth state not found: {state[:8]}...")
-                return None
-
-            # Check expiration
-            # Handle both timezone-aware and timezone-naive datetimes
-            now = datetime.now(UTC)
-            expires_at = db_obj.expires_at
-            if expires_at.tzinfo is None:
-                # SQLite returns naive datetimes, assume UTC
-                expires_at = expires_at.replace(tzinfo=UTC)
-
-            if expires_at < now:
-                logger.warning(f"OAuth state expired: {state[:8]}...")
-                await db.delete(db_obj)
-                await db.commit()
-                return None
-
-            # Delete it (consume)
-            await db.delete(db_obj)
-            await db.commit()
-
-            logger.debug(f"OAuth state consumed: {state[:8]}...")
-            return db_obj
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(f"Error consuming OAuth state: {e!s}")
-            raise
-
-    async def cleanup_expired(self, db: AsyncSession) -> int:
-        """
-        Clean up expired OAuth states.
-
-        Should be called periodically to remove stale states.
-
-        Args:
-            db: Database session
-
-        Returns:
-            Number of states deleted
-        """
-        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(f"Cleaned up {count} expired OAuth states")
-
-            return count
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(f"Error cleaning up expired OAuth states: {e!s}")
-            raise
-
-
-# ============================================================================
-# OAuth Client CRUD (Provider Mode - Skeleton)
-# ============================================================================
-
-
-class CRUDOAuthClient(CRUDBase[OAuthClient, OAuthClientCreate, EmptySchema]):
-    """
-    CRUD operations for OAuth clients (provider mode).
-
-    This is a skeleton implementation for MCP client registration.
-    Full implementation can be expanded when needed.
-    """
-
-    async def get_by_client_id(
-        self, db: AsyncSession, *, client_id: str
-    ) -> OAuthClient | None:
-        """
-        Get OAuth client by client_id.
-
-        Args:
-            db: Database session
-            client_id: OAuth client ID
-
-        Returns:
-            OAuthClient if found, None otherwise
-        """
-        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(f"Error getting OAuth client {client_id}: {e!s}")
-            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.
-
-        Args:
-            db: Database session
-            obj_in: OAuth client creation data
-            owner_user_id: Optional owner user ID
-
-        Returns:
-            Tuple of (created OAuthClient, client_secret or None for public clients)
-        """
-        try:
-            # Generate client_id
-            client_id = secrets.token_urlsafe(32)
-
-            # Generate client_secret for confidential clients
-            client_secret = None
-            client_secret_hash = None
-            if obj_in.client_type == "confidential":
-                client_secret = secrets.token_urlsafe(48)
-                # SECURITY: Use bcrypt for secret storage (not SHA-256)
-                # bcrypt is computationally expensive, making brute-force attacks infeasible
-                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(
-                f"OAuth client created: {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(f"Error creating OAuth client: {error_msg}")
-            raise ValueError(f"Failed to create OAuth client: {error_msg}")
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(f"Error creating OAuth client: {e!s}", exc_info=True)
-            raise
-
-    async def deactivate_client(
-        self, db: AsyncSession, *, client_id: str
-    ) -> OAuthClient | None:
-        """
-        Deactivate an OAuth client.
-
-        Args:
-            db: Database session
-            client_id: OAuth client ID
-
-        Returns:
-            Deactivated OAuthClient if found, None otherwise
-        """
-        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(f"OAuth client deactivated: {client.client_name}")
-            return client
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(f"Error deactivating OAuth client {client_id}: {e!s}")
-            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.
-
-        Args:
-            db: Database session
-            client_id: OAuth client ID
-            redirect_uri: Redirect URI to validate
-
-        Returns:
-            True if valid, False otherwise
-        """
-        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(f"Error validating redirect URI: {e!s}")
-            return False
-
-    async def verify_client_secret(
-        self, db: AsyncSession, *, client_id: str, client_secret: str
-    ) -> bool:
-        """
-        Verify client credentials.
-
-        Args:
-            db: Database session
-            client_id: OAuth client ID
-            client_secret: Client secret to verify
-
-        Returns:
-            True if valid, False otherwise
-        """
-        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
-
-            # SECURITY: Verify secret using bcrypt (not SHA-256)
-            # This supports both old SHA-256 hashes (for migration) and new bcrypt hashes
-            from app.core.auth import verify_password
-
-            stored_hash: str = str(client.client_secret_hash)
-
-            # Check if it's a bcrypt hash (starts with $2b$) or legacy SHA-256
-            if stored_hash.startswith("$2"):
-                # New bcrypt format
-                return verify_password(client_secret, stored_hash)
-            else:
-                # Legacy SHA-256 format - still support for migration
-                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(f"Error verifying client secret: {e!s}")
-            return False
-
-    async def get_all_clients(
-        self, db: AsyncSession, *, include_inactive: bool = False
-    ) -> list[OAuthClient]:
-        """
-        Get all OAuth clients.
-
-        Args:
-            db: Database session
-            include_inactive: Whether to include inactive clients
-
-        Returns:
-            List of OAuthClient objects
-        """
-        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(f"Error getting all OAuth clients: {e!s}")
-            raise
-
-    async def delete_client(self, db: AsyncSession, *, client_id: str) -> bool:
-        """
-        Delete an OAuth client permanently.
-
-        Note: This will cascade delete related records (tokens, consents, etc.)
-        due to foreign key constraints.
-
-        Args:
-            db: Database session
-            client_id: OAuth client ID
-
-        Returns:
-            True if deleted, False if not found
-        """
-        try:
-            result = await db.execute(
-                delete(OAuthClient).where(OAuthClient.client_id == client_id)
-            )
-            await db.commit()
-
-            deleted = result.rowcount > 0
-            if deleted:
-                logger.info(f"OAuth client deleted: {client_id}")
-            else:
-                logger.warning(f"OAuth client not found for deletion: {client_id}")
-
-            return deleted
-        except Exception as e:  # pragma: no cover
-            await db.rollback()
-            logger.error(f"Error deleting OAuth client {client_id}: {e!s}")
-            raise
-
-
-# ============================================================================
-# Singleton instances
-# ============================================================================
-
-oauth_account = CRUDOAuthAccount(OAuthAccount)
-oauth_state = CRUDOAuthState(OAuthState)
-oauth_client = CRUDOAuthClient(OAuthClient)

backend/app/crud/syndarix/__init__.py

@@ -1,20 +0,0 @@
-# app/crud/syndarix/__init__.py
-"""
-Syndarix CRUD operations.
-
-This package contains CRUD operations for all Syndarix domain entities.
-"""
-
-from .agent_instance import agent_instance
-from .agent_type import agent_type
-from .issue import issue
-from .project import project
-from .sprint import sprint
-
-__all__ = [
-    "agent_instance",
-    "agent_type",
-    "issue",
-    "project",
-    "sprint",
-]

backend/app/crud/syndarix/agent_instance.py

@@ -1,394 +0,0 @@
-# app/crud/syndarix/agent_instance.py
-"""Async CRUD operations for AgentInstance model using SQLAlchemy 2.0 patterns."""
-
-import logging
-from datetime import UTC, datetime
-from decimal import Decimal
-from typing import Any
-from uuid import UUID
-
-from sqlalchemy import func, select, update
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import joinedload
-
-from app.crud.base import CRUDBase
-from app.models.syndarix import AgentInstance, Issue
-from app.models.syndarix.enums import AgentStatus
-from app.schemas.syndarix import AgentInstanceCreate, AgentInstanceUpdate
-
-logger = logging.getLogger(__name__)
-
-
-class CRUDAgentInstance(
-    CRUDBase[AgentInstance, AgentInstanceCreate, AgentInstanceUpdate]
-):
-    """Async CRUD operations for AgentInstance model."""
-
-    async def create(
-        self, db: AsyncSession, *, obj_in: AgentInstanceCreate
-    ) -> AgentInstance:
-        """Create a new agent instance with error handling."""
-        try:
-            db_obj = AgentInstance(
-                agent_type_id=obj_in.agent_type_id,
-                project_id=obj_in.project_id,
-                name=obj_in.name,
-                status=obj_in.status,
-                current_task=obj_in.current_task,
-                short_term_memory=obj_in.short_term_memory,
-                long_term_memory_ref=obj_in.long_term_memory_ref,
-                session_id=obj_in.session_id,
-            )
-            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)
-            logger.error(f"Integrity error creating agent instance: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Unexpected error creating agent instance: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_with_details(
-        self,
-        db: AsyncSession,
-        *,
-        instance_id: UUID,
-    ) -> dict[str, Any] | None:
-        """
-        Get an agent instance with full details including related entities.
-
-        Returns:
-            Dictionary with instance and related entity details
-        """
-        try:
-            # Get instance with joined relationships
-            result = await db.execute(
-                select(AgentInstance)
-                .options(
-                    joinedload(AgentInstance.agent_type),
-                    joinedload(AgentInstance.project),
-                )
-                .where(AgentInstance.id == instance_id)
-            )
-            instance = result.scalar_one_or_none()
-
-            if not instance:
-                return None
-
-            # Get assigned issues count
-            issues_count_result = await db.execute(
-                select(func.count(Issue.id)).where(
-                    Issue.assigned_agent_id == instance_id
-                )
-            )
-            assigned_issues_count = issues_count_result.scalar_one()
-
-            return {
-                "instance": instance,
-                "agent_type_name": instance.agent_type.name
-                if instance.agent_type
-                else None,
-                "agent_type_slug": instance.agent_type.slug
-                if instance.agent_type
-                else None,
-                "project_name": instance.project.name if instance.project else None,
-                "project_slug": instance.project.slug if instance.project else None,
-                "assigned_issues_count": assigned_issues_count,
-            }
-        except Exception as e:
-            logger.error(
-                f"Error getting agent instance with details {instance_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def get_by_project(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-        status: AgentStatus | None = None,
-        skip: int = 0,
-        limit: int = 100,
-    ) -> tuple[list[AgentInstance], int]:
-        """Get agent instances for a specific project."""
-        try:
-            query = select(AgentInstance).where(AgentInstance.project_id == project_id)
-
-            if status is not None:
-                query = query.where(AgentInstance.status == status)
-
-            # Get total count
-            count_query = select(func.count()).select_from(query.alias())
-            count_result = await db.execute(count_query)
-            total = count_result.scalar_one()
-
-            # Apply pagination
-            query = query.order_by(AgentInstance.created_at.desc())
-            query = query.offset(skip).limit(limit)
-            result = await db.execute(query)
-            instances = list(result.scalars().all())
-
-            return instances, total
-        except Exception as e:
-            logger.error(
-                f"Error getting instances by project {project_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def get_by_agent_type(
-        self,
-        db: AsyncSession,
-        *,
-        agent_type_id: UUID,
-        status: AgentStatus | None = None,
-    ) -> list[AgentInstance]:
-        """Get all instances of a specific agent type."""
-        try:
-            query = select(AgentInstance).where(
-                AgentInstance.agent_type_id == agent_type_id
-            )
-
-            if status is not None:
-                query = query.where(AgentInstance.status == status)
-
-            query = query.order_by(AgentInstance.created_at.desc())
-            result = await db.execute(query)
-            return list(result.scalars().all())
-        except Exception as e:
-            logger.error(
-                f"Error getting instances by agent type {agent_type_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def update_status(
-        self,
-        db: AsyncSession,
-        *,
-        instance_id: UUID,
-        status: AgentStatus,
-        current_task: str | None = None,
-    ) -> AgentInstance | None:
-        """Update the status of an agent instance."""
-        try:
-            result = await db.execute(
-                select(AgentInstance).where(AgentInstance.id == instance_id)
-            )
-            instance = result.scalar_one_or_none()
-
-            if not instance:
-                return None
-
-            instance.status = status
-            instance.last_activity_at = datetime.now(UTC)
-            if current_task is not None:
-                instance.current_task = current_task
-
-            await db.commit()
-            await db.refresh(instance)
-            return instance
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error updating instance status {instance_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def terminate(
-        self,
-        db: AsyncSession,
-        *,
-        instance_id: UUID,
-    ) -> AgentInstance | None:
-        """Terminate an agent instance.
-
-        Also unassigns all issues from this agent to prevent orphaned assignments.
-        """
-        try:
-            result = await db.execute(
-                select(AgentInstance).where(AgentInstance.id == instance_id)
-            )
-            instance = result.scalar_one_or_none()
-
-            if not instance:
-                return None
-
-            # Unassign all issues from this agent before terminating
-            await db.execute(
-                update(Issue)
-                .where(Issue.assigned_agent_id == instance_id)
-                .values(assigned_agent_id=None)
-            )
-
-            instance.status = AgentStatus.TERMINATED
-            instance.terminated_at = datetime.now(UTC)
-            instance.current_task = None
-            instance.session_id = None
-
-            await db.commit()
-            await db.refresh(instance)
-            return instance
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error terminating instance {instance_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def record_task_completion(
-        self,
-        db: AsyncSession,
-        *,
-        instance_id: UUID,
-        tokens_used: int,
-        cost_incurred: Decimal,
-    ) -> AgentInstance | None:
-        """Record a completed task and update metrics.
-
-        Uses atomic SQL UPDATE to prevent lost updates under concurrent load.
-        This avoids the read-modify-write race condition that occurs when
-        multiple task completions happen simultaneously.
-        """
-        try:
-            now = datetime.now(UTC)
-
-            # Use atomic SQL UPDATE to increment counters without race conditions
-            # This is safe for concurrent updates - no read-modify-write pattern
-            result = await db.execute(
-                update(AgentInstance)
-                .where(AgentInstance.id == instance_id)
-                .values(
-                    tasks_completed=AgentInstance.tasks_completed + 1,
-                    tokens_used=AgentInstance.tokens_used + tokens_used,
-                    cost_incurred=AgentInstance.cost_incurred + cost_incurred,
-                    last_activity_at=now,
-                    updated_at=now,
-                )
-                .returning(AgentInstance)
-            )
-            instance = result.scalar_one_or_none()
-
-            if not instance:
-                return None
-
-            await db.commit()
-            return instance
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error recording task completion {instance_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_project_metrics(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-    ) -> dict[str, Any]:
-        """Get aggregated metrics for all agents in a project."""
-        try:
-            result = await db.execute(
-                select(
-                    func.count(AgentInstance.id).label("total_instances"),
-                    func.count(AgentInstance.id)
-                    .filter(AgentInstance.status == AgentStatus.WORKING)
-                    .label("active_instances"),
-                    func.count(AgentInstance.id)
-                    .filter(AgentInstance.status == AgentStatus.IDLE)
-                    .label("idle_instances"),
-                    func.sum(AgentInstance.tasks_completed).label("total_tasks"),
-                    func.sum(AgentInstance.tokens_used).label("total_tokens"),
-                    func.sum(AgentInstance.cost_incurred).label("total_cost"),
-                ).where(AgentInstance.project_id == project_id)
-            )
-            row = result.one()
-
-            return {
-                "total_instances": row.total_instances or 0,
-                "active_instances": row.active_instances or 0,
-                "idle_instances": row.idle_instances or 0,
-                "total_tasks_completed": row.total_tasks or 0,
-                "total_tokens_used": row.total_tokens or 0,
-                "total_cost_incurred": row.total_cost or Decimal("0.0000"),
-            }
-        except Exception as e:
-            logger.error(
-                f"Error getting project metrics {project_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def bulk_terminate_by_project(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-    ) -> int:
-        """Terminate all active instances in a project.
-
-        Also unassigns all issues from these agents to prevent orphaned assignments.
-        """
-        try:
-            # First, unassign all issues from agents in this project
-            # Get all agent IDs that will be terminated
-            agents_to_terminate = await db.execute(
-                select(AgentInstance.id).where(
-                    AgentInstance.project_id == project_id,
-                    AgentInstance.status != AgentStatus.TERMINATED,
-                )
-            )
-            agent_ids = [row[0] for row in agents_to_terminate.fetchall()]
-
-            # Unassign issues from these agents
-            if agent_ids:
-                await db.execute(
-                    update(Issue)
-                    .where(Issue.assigned_agent_id.in_(agent_ids))
-                    .values(assigned_agent_id=None)
-                )
-
-            now = datetime.now(UTC)
-            stmt = (
-                update(AgentInstance)
-                .where(
-                    AgentInstance.project_id == project_id,
-                    AgentInstance.status != AgentStatus.TERMINATED,
-                )
-                .values(
-                    status=AgentStatus.TERMINATED,
-                    terminated_at=now,
-                    current_task=None,
-                    session_id=None,
-                    updated_at=now,
-                )
-            )
-
-            result = await db.execute(stmt)
-            await db.commit()
-
-            terminated_count = result.rowcount
-            logger.info(
-                f"Bulk terminated {terminated_count} instances in project {project_id}"
-            )
-            return terminated_count
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error bulk terminating instances for project {project_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-
-# Create a singleton instance for use across the application
-agent_instance = CRUDAgentInstance(AgentInstance)

backend/app/crud/syndarix/agent_type.py

@@ -1,316 +0,0 @@
-# app/crud/syndarix/agent_type.py
-"""Async CRUD operations for AgentType model using SQLAlchemy 2.0 patterns."""
-
-import logging
-from typing import Any
-from uuid import UUID
-
-from sqlalchemy import func, or_, select
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.crud.base import CRUDBase
-from app.models.syndarix import AgentInstance, AgentType
-from app.schemas.syndarix import AgentTypeCreate, AgentTypeUpdate
-
-logger = logging.getLogger(__name__)
-
-
-class CRUDAgentType(CRUDBase[AgentType, AgentTypeCreate, AgentTypeUpdate]):
-    """Async CRUD operations for AgentType model."""
-
-    async def get_by_slug(self, db: AsyncSession, *, slug: str) -> AgentType | None:
-        """Get agent type by slug."""
-        try:
-            result = await db.execute(select(AgentType).where(AgentType.slug == slug))
-            return result.scalar_one_or_none()
-        except Exception as e:
-            logger.error(f"Error getting agent type by slug {slug}: {e!s}")
-            raise
-
-    async def create(self, db: AsyncSession, *, obj_in: AgentTypeCreate) -> AgentType:
-        """Create a new agent type with error handling."""
-        try:
-            db_obj = AgentType(
-                name=obj_in.name,
-                slug=obj_in.slug,
-                description=obj_in.description,
-                expertise=obj_in.expertise,
-                personality_prompt=obj_in.personality_prompt,
-                primary_model=obj_in.primary_model,
-                fallback_models=obj_in.fallback_models,
-                model_params=obj_in.model_params,
-                mcp_servers=obj_in.mcp_servers,
-                tool_permissions=obj_in.tool_permissions,
-                is_active=obj_in.is_active,
-                # Category and display fields
-                category=obj_in.category.value if obj_in.category else None,
-                icon=obj_in.icon,
-                color=obj_in.color,
-                sort_order=obj_in.sort_order,
-                typical_tasks=obj_in.typical_tasks,
-                collaboration_hints=obj_in.collaboration_hints,
-            )
-            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():
-                logger.warning(f"Duplicate slug attempted: {obj_in.slug}")
-                raise ValueError(f"Agent type with slug '{obj_in.slug}' already exists")
-            logger.error(f"Integrity error creating agent type: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Unexpected error creating agent type: {e!s}", exc_info=True)
-            raise
-
-    async def get_multi_with_filters(
-        self,
-        db: AsyncSession,
-        *,
-        skip: int = 0,
-        limit: int = 100,
-        is_active: bool | None = None,
-        category: str | None = None,
-        search: str | None = None,
-        sort_by: str = "created_at",
-        sort_order: str = "desc",
-    ) -> tuple[list[AgentType], int]:
-        """
-        Get multiple agent types with filtering, searching, and sorting.
-
-        Returns:
-            Tuple of (agent types list, total count)
-        """
-        try:
-            query = select(AgentType)
-
-            # Apply filters
-            if is_active is not None:
-                query = query.where(AgentType.is_active == is_active)
-
-            if category:
-                query = query.where(AgentType.category == category)
-
-            if search:
-                search_filter = or_(
-                    AgentType.name.ilike(f"%{search}%"),
-                    AgentType.slug.ilike(f"%{search}%"),
-                    AgentType.description.ilike(f"%{search}%"),
-                )
-                query = query.where(search_filter)
-
-            # Get total count before pagination
-            count_query = select(func.count()).select_from(query.alias())
-            count_result = await db.execute(count_query)
-            total = count_result.scalar_one()
-
-            # Apply sorting
-            sort_column = getattr(AgentType, sort_by, AgentType.created_at)
-            if sort_order == "desc":
-                query = query.order_by(sort_column.desc())
-            else:
-                query = query.order_by(sort_column.asc())
-
-            # Apply pagination
-            query = query.offset(skip).limit(limit)
-            result = await db.execute(query)
-            agent_types = list(result.scalars().all())
-
-            return agent_types, total
-        except Exception as e:
-            logger.error(f"Error getting agent types with filters: {e!s}")
-            raise
-
-    async def get_with_instance_count(
-        self,
-        db: AsyncSession,
-        *,
-        agent_type_id: UUID,
-    ) -> dict[str, Any] | None:
-        """
-        Get a single agent type with its instance count.
-
-        Returns:
-            Dictionary with agent_type and instance_count
-        """
-        try:
-            result = await db.execute(
-                select(AgentType).where(AgentType.id == agent_type_id)
-            )
-            agent_type = result.scalar_one_or_none()
-
-            if not agent_type:
-                return None
-
-            # Get instance count
-            count_result = await db.execute(
-                select(func.count(AgentInstance.id)).where(
-                    AgentInstance.agent_type_id == agent_type_id
-                )
-            )
-            instance_count = count_result.scalar_one()
-
-            return {
-                "agent_type": agent_type,
-                "instance_count": instance_count,
-            }
-        except Exception as e:
-            logger.error(
-                f"Error getting agent type with count {agent_type_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def get_multi_with_instance_counts(
-        self,
-        db: AsyncSession,
-        *,
-        skip: int = 0,
-        limit: int = 100,
-        is_active: bool | None = None,
-        category: str | None = None,
-        search: str | None = None,
-    ) -> tuple[list[dict[str, Any]], int]:
-        """
-        Get agent types with instance counts in optimized queries.
-
-        Returns:
-            Tuple of (list of dicts with agent_type and instance_count, total count)
-        """
-        try:
-            # Get filtered agent types
-            agent_types, total = await self.get_multi_with_filters(
-                db,
-                skip=skip,
-                limit=limit,
-                is_active=is_active,
-                category=category,
-                search=search,
-            )
-
-            if not agent_types:
-                return [], 0
-
-            agent_type_ids = [at.id for at in agent_types]
-
-            # Get instance counts in bulk
-            counts_result = await db.execute(
-                select(
-                    AgentInstance.agent_type_id,
-                    func.count(AgentInstance.id).label("count"),
-                )
-                .where(AgentInstance.agent_type_id.in_(agent_type_ids))
-                .group_by(AgentInstance.agent_type_id)
-            )
-            counts = {row.agent_type_id: row.count for row in counts_result}
-
-            # Combine results
-            results = [
-                {
-                    "agent_type": agent_type,
-                    "instance_count": counts.get(agent_type.id, 0),
-                }
-                for agent_type in agent_types
-            ]
-
-            return results, total
-        except Exception as e:
-            logger.error(f"Error getting agent types with counts: {e!s}", exc_info=True)
-            raise
-
-    async def get_by_expertise(
-        self,
-        db: AsyncSession,
-        *,
-        expertise: str,
-        is_active: bool = True,
-    ) -> list[AgentType]:
-        """Get agent types that have a specific expertise."""
-        try:
-            # Use PostgreSQL JSONB contains operator
-            query = select(AgentType).where(
-                AgentType.expertise.contains([expertise.lower()]),
-                AgentType.is_active == is_active,
-            )
-            result = await db.execute(query)
-            return list(result.scalars().all())
-        except Exception as e:
-            logger.error(
-                f"Error getting agent types by expertise {expertise}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def deactivate(
-        self,
-        db: AsyncSession,
-        *,
-        agent_type_id: UUID,
-    ) -> AgentType | None:
-        """Deactivate an agent type (soft delete)."""
-        try:
-            result = await db.execute(
-                select(AgentType).where(AgentType.id == agent_type_id)
-            )
-            agent_type = result.scalar_one_or_none()
-
-            if not agent_type:
-                return None
-
-            agent_type.is_active = False
-            await db.commit()
-            await db.refresh(agent_type)
-            return agent_type
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error deactivating agent type {agent_type_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_grouped_by_category(
-        self,
-        db: AsyncSession,
-        *,
-        is_active: bool = True,
-    ) -> dict[str, list[AgentType]]:
-        """
-        Get agent types grouped by category, sorted by sort_order within each group.
-
-        Args:
-            db: Database session
-            is_active: Filter by active status (default: True)
-
-        Returns:
-            Dictionary mapping category to list of agent types
-        """
-        try:
-            query = (
-                select(AgentType)
-                .where(AgentType.is_active == is_active)
-                .order_by(AgentType.category, AgentType.sort_order, AgentType.name)
-            )
-            result = await db.execute(query)
-            agent_types = list(result.scalars().all())
-
-            # Group by category
-            grouped: dict[str, list[AgentType]] = {}
-            for at in agent_types:
-                cat: str = str(at.category) if at.category else "uncategorized"
-                if cat not in grouped:
-                    grouped[cat] = []
-                grouped[cat].append(at)
-
-            return grouped
-        except Exception as e:
-            logger.error(f"Error getting grouped agent types: {e!s}", exc_info=True)
-            raise
-
-
-# Create a singleton instance for use across the application
-agent_type = CRUDAgentType(AgentType)

backend/app/crud/syndarix/issue.py

@@ -1,525 +0,0 @@
-# app/crud/syndarix/issue.py
-"""Async CRUD operations for Issue model using SQLAlchemy 2.0 patterns."""
-
-import logging
-from datetime import UTC, datetime
-from typing import Any
-from uuid import UUID
-
-from sqlalchemy import func, or_, select
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import joinedload
-
-from app.crud.base import CRUDBase
-from app.models.syndarix import AgentInstance, Issue
-from app.models.syndarix.enums import IssuePriority, IssueStatus, SyncStatus
-from app.schemas.syndarix import IssueCreate, IssueUpdate
-
-logger = logging.getLogger(__name__)
-
-
-class CRUDIssue(CRUDBase[Issue, IssueCreate, IssueUpdate]):
-    """Async CRUD operations for Issue model."""
-
-    async def create(self, db: AsyncSession, *, obj_in: IssueCreate) -> Issue:
-        """Create a new issue with error handling."""
-        try:
-            db_obj = Issue(
-                project_id=obj_in.project_id,
-                title=obj_in.title,
-                body=obj_in.body,
-                status=obj_in.status,
-                priority=obj_in.priority,
-                labels=obj_in.labels,
-                assigned_agent_id=obj_in.assigned_agent_id,
-                human_assignee=obj_in.human_assignee,
-                sprint_id=obj_in.sprint_id,
-                story_points=obj_in.story_points,
-                external_tracker_type=obj_in.external_tracker_type,
-                external_issue_id=obj_in.external_issue_id,
-                remote_url=obj_in.remote_url,
-                external_issue_number=obj_in.external_issue_number,
-                sync_status=SyncStatus.SYNCED,
-            )
-            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)
-            logger.error(f"Integrity error creating issue: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Unexpected error creating issue: {e!s}", exc_info=True)
-            raise
-
-    async def get_with_details(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-    ) -> dict[str, Any] | None:
-        """
-        Get an issue with full details including related entity names.
-
-        Returns:
-            Dictionary with issue and related entity details
-        """
-        try:
-            # Get issue with joined relationships
-            result = await db.execute(
-                select(Issue)
-                .options(
-                    joinedload(Issue.project),
-                    joinedload(Issue.sprint),
-                    joinedload(Issue.assigned_agent).joinedload(
-                        AgentInstance.agent_type
-                    ),
-                )
-                .where(Issue.id == issue_id)
-            )
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            return {
-                "issue": issue,
-                "project_name": issue.project.name if issue.project else None,
-                "project_slug": issue.project.slug if issue.project else None,
-                "sprint_name": issue.sprint.name if issue.sprint else None,
-                "assigned_agent_type_name": (
-                    issue.assigned_agent.agent_type.name
-                    if issue.assigned_agent and issue.assigned_agent.agent_type
-                    else None
-                ),
-            }
-        except Exception as e:
-            logger.error(
-                f"Error getting issue with details {issue_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_by_project(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-        status: IssueStatus | None = None,
-        priority: IssuePriority | None = None,
-        sprint_id: UUID | None = None,
-        assigned_agent_id: UUID | None = None,
-        labels: list[str] | None = None,
-        search: str | None = None,
-        skip: int = 0,
-        limit: int = 100,
-        sort_by: str = "created_at",
-        sort_order: str = "desc",
-    ) -> tuple[list[Issue], int]:
-        """Get issues for a specific project with filters."""
-        try:
-            query = select(Issue).where(Issue.project_id == project_id)
-
-            # Apply filters
-            if status is not None:
-                query = query.where(Issue.status == status)
-
-            if priority is not None:
-                query = query.where(Issue.priority == priority)
-
-            if sprint_id is not None:
-                query = query.where(Issue.sprint_id == sprint_id)
-
-            if assigned_agent_id is not None:
-                query = query.where(Issue.assigned_agent_id == assigned_agent_id)
-
-            if labels:
-                # Match any of the provided labels
-                for label in labels:
-                    query = query.where(Issue.labels.contains([label.lower()]))
-
-            if search:
-                search_filter = or_(
-                    Issue.title.ilike(f"%{search}%"),
-                    Issue.body.ilike(f"%{search}%"),
-                )
-                query = query.where(search_filter)
-
-            # Get total count
-            count_query = select(func.count()).select_from(query.alias())
-            count_result = await db.execute(count_query)
-            total = count_result.scalar_one()
-
-            # Apply sorting
-            sort_column = getattr(Issue, sort_by, Issue.created_at)
-            if sort_order == "desc":
-                query = query.order_by(sort_column.desc())
-            else:
-                query = query.order_by(sort_column.asc())
-
-            # Apply pagination
-            query = query.offset(skip).limit(limit)
-            result = await db.execute(query)
-            issues = list(result.scalars().all())
-
-            return issues, total
-        except Exception as e:
-            logger.error(
-                f"Error getting issues by project {project_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_by_sprint(
-        self,
-        db: AsyncSession,
-        *,
-        sprint_id: UUID,
-        status: IssueStatus | None = None,
-    ) -> list[Issue]:
-        """Get all issues in a sprint."""
-        try:
-            query = select(Issue).where(Issue.sprint_id == sprint_id)
-
-            if status is not None:
-                query = query.where(Issue.status == status)
-
-            query = query.order_by(Issue.priority.desc(), Issue.created_at.asc())
-            result = await db.execute(query)
-            return list(result.scalars().all())
-        except Exception as e:
-            logger.error(
-                f"Error getting issues by sprint {sprint_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def assign_to_agent(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-        agent_id: UUID | None,
-    ) -> Issue | None:
-        """Assign an issue to an agent (or unassign if agent_id is None)."""
-        try:
-            result = await db.execute(select(Issue).where(Issue.id == issue_id))
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            issue.assigned_agent_id = agent_id
-            issue.human_assignee = None  # Clear human assignee when assigning to agent
-            await db.commit()
-            await db.refresh(issue)
-            return issue
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error assigning issue {issue_id} to agent {agent_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def assign_to_human(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-        human_assignee: str | None,
-    ) -> Issue | None:
-        """Assign an issue to a human (or unassign if human_assignee is None)."""
-        try:
-            result = await db.execute(select(Issue).where(Issue.id == issue_id))
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            issue.human_assignee = human_assignee
-            issue.assigned_agent_id = None  # Clear agent when assigning to human
-            await db.commit()
-            await db.refresh(issue)
-            return issue
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error assigning issue {issue_id} to human {human_assignee}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def close_issue(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-    ) -> Issue | None:
-        """Close an issue by setting status and closed_at timestamp."""
-        try:
-            result = await db.execute(select(Issue).where(Issue.id == issue_id))
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            issue.status = IssueStatus.CLOSED
-            issue.closed_at = datetime.now(UTC)
-            await db.commit()
-            await db.refresh(issue)
-            return issue
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Error closing issue {issue_id}: {e!s}", exc_info=True)
-            raise
-
-    async def reopen_issue(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-    ) -> Issue | None:
-        """Reopen a closed issue."""
-        try:
-            result = await db.execute(select(Issue).where(Issue.id == issue_id))
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            issue.status = IssueStatus.OPEN
-            issue.closed_at = None
-            await db.commit()
-            await db.refresh(issue)
-            return issue
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Error reopening issue {issue_id}: {e!s}", exc_info=True)
-            raise
-
-    async def update_sync_status(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-        sync_status: SyncStatus,
-        last_synced_at: datetime | None = None,
-        external_updated_at: datetime | None = None,
-    ) -> Issue | None:
-        """Update the sync status of an issue."""
-        try:
-            result = await db.execute(select(Issue).where(Issue.id == issue_id))
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            issue.sync_status = sync_status
-            if last_synced_at:
-                issue.last_synced_at = last_synced_at
-            if external_updated_at:
-                issue.external_updated_at = external_updated_at
-
-            await db.commit()
-            await db.refresh(issue)
-            return issue
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error updating sync status for issue {issue_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_project_stats(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-    ) -> dict[str, Any]:
-        """Get issue statistics for a project."""
-        try:
-            # Get counts by status
-            status_counts = await db.execute(
-                select(Issue.status, func.count(Issue.id).label("count"))
-                .where(Issue.project_id == project_id)
-                .group_by(Issue.status)
-            )
-            by_status = {row.status.value: row.count for row in status_counts}
-
-            # Get counts by priority
-            priority_counts = await db.execute(
-                select(Issue.priority, func.count(Issue.id).label("count"))
-                .where(Issue.project_id == project_id)
-                .group_by(Issue.priority)
-            )
-            by_priority = {row.priority.value: row.count for row in priority_counts}
-
-            # Get story points
-            points_result = await db.execute(
-                select(
-                    func.sum(Issue.story_points).label("total"),
-                    func.sum(Issue.story_points)
-                    .filter(Issue.status == IssueStatus.CLOSED)
-                    .label("completed"),
-                ).where(Issue.project_id == project_id)
-            )
-            points_row = points_result.one()
-
-            total_issues = sum(by_status.values())
-
-            return {
-                "total": total_issues,
-                "open": by_status.get("open", 0),
-                "in_progress": by_status.get("in_progress", 0),
-                "in_review": by_status.get("in_review", 0),
-                "blocked": by_status.get("blocked", 0),
-                "closed": by_status.get("closed", 0),
-                "by_priority": by_priority,
-                "total_story_points": points_row.total,
-                "completed_story_points": points_row.completed,
-            }
-        except Exception as e:
-            logger.error(
-                f"Error getting issue stats for project {project_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def get_by_external_id(
-        self,
-        db: AsyncSession,
-        *,
-        external_tracker_type: str,
-        external_issue_id: str,
-    ) -> Issue | None:
-        """Get an issue by its external tracker ID."""
-        try:
-            result = await db.execute(
-                select(Issue).where(
-                    Issue.external_tracker_type == external_tracker_type,
-                    Issue.external_issue_id == external_issue_id,
-                )
-            )
-            return result.scalar_one_or_none()
-        except Exception as e:
-            logger.error(
-                f"Error getting issue by external ID {external_tracker_type}:{external_issue_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def get_pending_sync(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID | None = None,
-        limit: int = 100,
-    ) -> list[Issue]:
-        """Get issues that need to be synced with external tracker."""
-        try:
-            query = select(Issue).where(
-                Issue.external_tracker_type.isnot(None),
-                Issue.sync_status.in_([SyncStatus.PENDING, SyncStatus.ERROR]),
-            )
-
-            if project_id:
-                query = query.where(Issue.project_id == project_id)
-
-            query = query.order_by(Issue.updated_at.asc()).limit(limit)
-            result = await db.execute(query)
-            return list(result.scalars().all())
-        except Exception as e:
-            logger.error(f"Error getting pending sync issues: {e!s}", exc_info=True)
-            raise
-
-    async def remove_sprint_from_issues(
-        self,
-        db: AsyncSession,
-        *,
-        sprint_id: UUID,
-    ) -> int:
-        """Remove sprint assignment from all issues in a sprint.
-
-        Used when deleting a sprint to clean up references.
-
-        Returns:
-            Number of issues updated
-        """
-        try:
-            from sqlalchemy import update
-
-            result = await db.execute(
-                update(Issue).where(Issue.sprint_id == sprint_id).values(sprint_id=None)
-            )
-            await db.commit()
-            return result.rowcount
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error removing sprint {sprint_id} from issues: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def unassign(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-    ) -> Issue | None:
-        """Remove agent assignment from an issue.
-
-        Returns:
-            Updated issue or None if not found
-        """
-        try:
-            result = await db.execute(select(Issue).where(Issue.id == issue_id))
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            issue.assigned_agent_id = None
-            await db.commit()
-            await db.refresh(issue)
-            return issue
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Error unassigning issue {issue_id}: {e!s}", exc_info=True)
-            raise
-
-    async def remove_from_sprint(
-        self,
-        db: AsyncSession,
-        *,
-        issue_id: UUID,
-    ) -> Issue | None:
-        """Remove an issue from its current sprint.
-
-        Returns:
-            Updated issue or None if not found
-        """
-        try:
-            result = await db.execute(select(Issue).where(Issue.id == issue_id))
-            issue = result.scalar_one_or_none()
-
-            if not issue:
-                return None
-
-            issue.sprint_id = None
-            await db.commit()
-            await db.refresh(issue)
-            return issue
-        except Exception as e:
-            await db.rollback()
-            logger.error(
-                f"Error removing issue {issue_id} from sprint: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-
-# Create a singleton instance for use across the application
-issue = CRUDIssue(Issue)

backend/app/crud/syndarix/project.py

@@ -1,362 +0,0 @@
-# app/crud/syndarix/project.py
-"""Async CRUD operations for Project model using SQLAlchemy 2.0 patterns."""
-
-import logging
-from datetime import UTC, datetime
-from typing import Any
-from uuid import UUID
-
-from sqlalchemy import func, or_, select, update
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.asyncio import AsyncSession
-
-from app.crud.base import CRUDBase
-from app.models.syndarix import AgentInstance, Issue, Project, Sprint
-from app.models.syndarix.enums import AgentStatus, ProjectStatus, SprintStatus
-from app.schemas.syndarix import ProjectCreate, ProjectUpdate
-
-logger = logging.getLogger(__name__)
-
-
-class CRUDProject(CRUDBase[Project, ProjectCreate, ProjectUpdate]):
-    """Async CRUD operations for Project model."""
-
-    async def get_by_slug(self, db: AsyncSession, *, slug: str) -> Project | None:
-        """Get project by slug."""
-        try:
-            result = await db.execute(select(Project).where(Project.slug == slug))
-            return result.scalar_one_or_none()
-        except Exception as e:
-            logger.error(f"Error getting project by slug {slug}: {e!s}")
-            raise
-
-    async def create(self, db: AsyncSession, *, obj_in: ProjectCreate) -> Project:
-        """Create a new project with error handling."""
-        try:
-            db_obj = Project(
-                name=obj_in.name,
-                slug=obj_in.slug,
-                description=obj_in.description,
-                autonomy_level=obj_in.autonomy_level,
-                status=obj_in.status,
-                settings=obj_in.settings or {},
-                owner_id=obj_in.owner_id,
-            )
-            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():
-                logger.warning(f"Duplicate slug attempted: {obj_in.slug}")
-                raise ValueError(f"Project with slug '{obj_in.slug}' already exists")
-            logger.error(f"Integrity error creating project: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Unexpected error creating project: {e!s}", exc_info=True)
-            raise
-
-    async def get_multi_with_filters(
-        self,
-        db: AsyncSession,
-        *,
-        skip: int = 0,
-        limit: int = 100,
-        status: ProjectStatus | None = None,
-        owner_id: UUID | None = None,
-        search: str | None = None,
-        sort_by: str = "created_at",
-        sort_order: str = "desc",
-    ) -> tuple[list[Project], int]:
-        """
-        Get multiple projects with filtering, searching, and sorting.
-
-        Returns:
-            Tuple of (projects list, total count)
-        """
-        try:
-            query = select(Project)
-
-            # Apply filters
-            if status is not None:
-                query = query.where(Project.status == status)
-
-            if owner_id is not None:
-                query = query.where(Project.owner_id == owner_id)
-
-            if search:
-                search_filter = or_(
-                    Project.name.ilike(f"%{search}%"),
-                    Project.slug.ilike(f"%{search}%"),
-                    Project.description.ilike(f"%{search}%"),
-                )
-                query = query.where(search_filter)
-
-            # Get total count before pagination
-            count_query = select(func.count()).select_from(query.alias())
-            count_result = await db.execute(count_query)
-            total = count_result.scalar_one()
-
-            # Apply sorting
-            sort_column = getattr(Project, sort_by, Project.created_at)
-            if sort_order == "desc":
-                query = query.order_by(sort_column.desc())
-            else:
-                query = query.order_by(sort_column.asc())
-
-            # Apply pagination
-            query = query.offset(skip).limit(limit)
-            result = await db.execute(query)
-            projects = list(result.scalars().all())
-
-            return projects, total
-        except Exception as e:
-            logger.error(f"Error getting projects with filters: {e!s}")
-            raise
-
-    async def get_with_counts(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-    ) -> dict[str, Any] | None:
-        """
-        Get a single project with agent and issue counts.
-
-        Returns:
-            Dictionary with project, agent_count, issue_count, active_sprint_name
-        """
-        try:
-            # Get project
-            result = await db.execute(select(Project).where(Project.id == project_id))
-            project = result.scalar_one_or_none()
-
-            if not project:
-                return None
-
-            # Get agent count
-            agent_count_result = await db.execute(
-                select(func.count(AgentInstance.id)).where(
-                    AgentInstance.project_id == project_id
-                )
-            )
-            agent_count = agent_count_result.scalar_one()
-
-            # Get issue count
-            issue_count_result = await db.execute(
-                select(func.count(Issue.id)).where(Issue.project_id == project_id)
-            )
-            issue_count = issue_count_result.scalar_one()
-
-            # Get active sprint name
-            active_sprint_result = await db.execute(
-                select(Sprint.name).where(
-                    Sprint.project_id == project_id,
-                    Sprint.status == SprintStatus.ACTIVE,
-                )
-            )
-            active_sprint_name = active_sprint_result.scalar_one_or_none()
-
-            return {
-                "project": project,
-                "agent_count": agent_count,
-                "issue_count": issue_count,
-                "active_sprint_name": active_sprint_name,
-            }
-        except Exception as e:
-            logger.error(
-                f"Error getting project with counts {project_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_multi_with_counts(
-        self,
-        db: AsyncSession,
-        *,
-        skip: int = 0,
-        limit: int = 100,
-        status: ProjectStatus | None = None,
-        owner_id: UUID | None = None,
-        search: str | None = None,
-    ) -> tuple[list[dict[str, Any]], int]:
-        """
-        Get projects with agent/issue counts in optimized queries.
-
-        Returns:
-            Tuple of (list of dicts with project and counts, total count)
-        """
-        try:
-            # Get filtered projects
-            projects, total = await self.get_multi_with_filters(
-                db,
-                skip=skip,
-                limit=limit,
-                status=status,
-                owner_id=owner_id,
-                search=search,
-            )
-
-            if not projects:
-                return [], 0
-
-            project_ids = [p.id for p in projects]
-
-            # Get agent counts in bulk
-            agent_counts_result = await db.execute(
-                select(
-                    AgentInstance.project_id,
-                    func.count(AgentInstance.id).label("count"),
-                )
-                .where(AgentInstance.project_id.in_(project_ids))
-                .group_by(AgentInstance.project_id)
-            )
-            agent_counts = {row.project_id: row.count for row in agent_counts_result}
-
-            # Get issue counts in bulk
-            issue_counts_result = await db.execute(
-                select(
-                    Issue.project_id,
-                    func.count(Issue.id).label("count"),
-                )
-                .where(Issue.project_id.in_(project_ids))
-                .group_by(Issue.project_id)
-            )
-            issue_counts = {row.project_id: row.count for row in issue_counts_result}
-
-            # Get active sprint names
-            active_sprints_result = await db.execute(
-                select(Sprint.project_id, Sprint.name).where(
-                    Sprint.project_id.in_(project_ids),
-                    Sprint.status == SprintStatus.ACTIVE,
-                )
-            )
-            active_sprints = {row.project_id: row.name for row in active_sprints_result}
-
-            # Combine results
-            results = [
-                {
-                    "project": project,
-                    "agent_count": agent_counts.get(project.id, 0),
-                    "issue_count": issue_counts.get(project.id, 0),
-                    "active_sprint_name": active_sprints.get(project.id),
-                }
-                for project in projects
-            ]
-
-            return results, total
-        except Exception as e:
-            logger.error(f"Error getting projects with counts: {e!s}", exc_info=True)
-            raise
-
-    async def get_projects_by_owner(
-        self,
-        db: AsyncSession,
-        *,
-        owner_id: UUID,
-        status: ProjectStatus | None = None,
-    ) -> list[Project]:
-        """Get all projects owned by a specific user."""
-        try:
-            query = select(Project).where(Project.owner_id == owner_id)
-
-            if status is not None:
-                query = query.where(Project.status == status)
-
-            query = query.order_by(Project.created_at.desc())
-            result = await db.execute(query)
-            return list(result.scalars().all())
-        except Exception as e:
-            logger.error(
-                f"Error getting projects by owner {owner_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def archive_project(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-    ) -> Project | None:
-        """Archive a project by setting status to ARCHIVED.
-
-        This also performs cascading cleanup:
-        - Terminates all active agent instances
-        - Cancels all planned/active sprints
-        - Unassigns issues from terminated agents
-        """
-        try:
-            result = await db.execute(select(Project).where(Project.id == project_id))
-            project = result.scalar_one_or_none()
-
-            if not project:
-                return None
-
-            now = datetime.now(UTC)
-
-            # 1. Get all agent IDs that will be terminated
-            agents_to_terminate = await db.execute(
-                select(AgentInstance.id).where(
-                    AgentInstance.project_id == project_id,
-                    AgentInstance.status != AgentStatus.TERMINATED,
-                )
-            )
-            agent_ids = [row[0] for row in agents_to_terminate.fetchall()]
-
-            # 2. Unassign issues from these agents to prevent orphaned assignments
-            if agent_ids:
-                await db.execute(
-                    update(Issue)
-                    .where(Issue.assigned_agent_id.in_(agent_ids))
-                    .values(assigned_agent_id=None)
-                )
-
-            # 3. Terminate all active agents
-            await db.execute(
-                update(AgentInstance)
-                .where(
-                    AgentInstance.project_id == project_id,
-                    AgentInstance.status != AgentStatus.TERMINATED,
-                )
-                .values(
-                    status=AgentStatus.TERMINATED,
-                    terminated_at=now,
-                    current_task=None,
-                    session_id=None,
-                    updated_at=now,
-                )
-            )
-
-            # 4. Cancel all planned/active sprints
-            await db.execute(
-                update(Sprint)
-                .where(
-                    Sprint.project_id == project_id,
-                    Sprint.status.in_([SprintStatus.PLANNED, SprintStatus.ACTIVE]),
-                )
-                .values(
-                    status=SprintStatus.CANCELLED,
-                    updated_at=now,
-                )
-            )
-
-            # 5. Archive the project
-            project.status = ProjectStatus.ARCHIVED
-            await db.commit()
-            await db.refresh(project)
-
-            logger.info(
-                f"Archived project {project_id}: terminated agents={len(agent_ids)}"
-            )
-
-            return project
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Error archiving project {project_id}: {e!s}", exc_info=True)
-            raise
-
-
-# Create a singleton instance for use across the application
-project = CRUDProject(Project)

backend/app/crud/syndarix/sprint.py

@@ -1,439 +0,0 @@
-# app/crud/syndarix/sprint.py
-"""Async CRUD operations for Sprint model using SQLAlchemy 2.0 patterns."""
-
-import logging
-from datetime import date
-from typing import Any
-from uuid import UUID
-
-from sqlalchemy import func, select
-from sqlalchemy.exc import IntegrityError
-from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy.orm import joinedload
-
-from app.crud.base import CRUDBase
-from app.models.syndarix import Issue, Sprint
-from app.models.syndarix.enums import IssueStatus, SprintStatus
-from app.schemas.syndarix import SprintCreate, SprintUpdate
-
-logger = logging.getLogger(__name__)
-
-
-class CRUDSprint(CRUDBase[Sprint, SprintCreate, SprintUpdate]):
-    """Async CRUD operations for Sprint model."""
-
-    async def create(self, db: AsyncSession, *, obj_in: SprintCreate) -> Sprint:
-        """Create a new sprint with error handling."""
-        try:
-            db_obj = Sprint(
-                project_id=obj_in.project_id,
-                name=obj_in.name,
-                number=obj_in.number,
-                goal=obj_in.goal,
-                start_date=obj_in.start_date,
-                end_date=obj_in.end_date,
-                status=obj_in.status,
-                planned_points=obj_in.planned_points,
-                velocity=obj_in.velocity,
-            )
-            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)
-            logger.error(f"Integrity error creating sprint: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Unexpected error creating sprint: {e!s}", exc_info=True)
-            raise
-
-    async def get_with_details(
-        self,
-        db: AsyncSession,
-        *,
-        sprint_id: UUID,
-    ) -> dict[str, Any] | None:
-        """
-        Get a sprint with full details including issue counts.
-
-        Returns:
-            Dictionary with sprint and related details
-        """
-        try:
-            # Get sprint with joined project
-            result = await db.execute(
-                select(Sprint)
-                .options(joinedload(Sprint.project))
-                .where(Sprint.id == sprint_id)
-            )
-            sprint = result.scalar_one_or_none()
-
-            if not sprint:
-                return None
-
-            # Get issue counts
-            issue_counts = await db.execute(
-                select(
-                    func.count(Issue.id).label("total"),
-                    func.count(Issue.id)
-                    .filter(Issue.status == IssueStatus.OPEN)
-                    .label("open"),
-                    func.count(Issue.id)
-                    .filter(Issue.status == IssueStatus.CLOSED)
-                    .label("completed"),
-                ).where(Issue.sprint_id == sprint_id)
-            )
-            counts = issue_counts.one()
-
-            return {
-                "sprint": sprint,
-                "project_name": sprint.project.name if sprint.project else None,
-                "project_slug": sprint.project.slug if sprint.project else None,
-                "issue_count": counts.total,
-                "open_issues": counts.open,
-                "completed_issues": counts.completed,
-            }
-        except Exception as e:
-            logger.error(
-                f"Error getting sprint with details {sprint_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_by_project(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-        status: SprintStatus | None = None,
-        skip: int = 0,
-        limit: int = 100,
-    ) -> tuple[list[Sprint], int]:
-        """Get sprints for a specific project."""
-        try:
-            query = select(Sprint).where(Sprint.project_id == project_id)
-
-            if status is not None:
-                query = query.where(Sprint.status == status)
-
-            # Get total count
-            count_query = select(func.count()).select_from(query.alias())
-            count_result = await db.execute(count_query)
-            total = count_result.scalar_one()
-
-            # Apply sorting (by number descending - newest first)
-            query = query.order_by(Sprint.number.desc())
-            query = query.offset(skip).limit(limit)
-            result = await db.execute(query)
-            sprints = list(result.scalars().all())
-
-            return sprints, total
-        except Exception as e:
-            logger.error(
-                f"Error getting sprints by project {project_id}: {e!s}", exc_info=True
-            )
-            raise
-
-    async def get_active_sprint(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-    ) -> Sprint | None:
-        """Get the currently active sprint for a project."""
-        try:
-            result = await db.execute(
-                select(Sprint).where(
-                    Sprint.project_id == project_id,
-                    Sprint.status == SprintStatus.ACTIVE,
-                )
-            )
-            return result.scalar_one_or_none()
-        except Exception as e:
-            logger.error(
-                f"Error getting active sprint for project {project_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def get_next_sprint_number(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-    ) -> int:
-        """Get the next sprint number for a project."""
-        try:
-            result = await db.execute(
-                select(func.max(Sprint.number)).where(Sprint.project_id == project_id)
-            )
-            max_number = result.scalar_one_or_none()
-            return (max_number or 0) + 1
-        except Exception as e:
-            logger.error(
-                f"Error getting next sprint number for project {project_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def start_sprint(
-        self,
-        db: AsyncSession,
-        *,
-        sprint_id: UUID,
-        start_date: date | None = None,
-    ) -> Sprint | None:
-        """Start a planned sprint.
-
-        Uses row-level locking (SELECT FOR UPDATE) to prevent race conditions
-        when multiple requests try to start sprints concurrently.
-        """
-        try:
-            # Lock the sprint row to prevent concurrent modifications
-            result = await db.execute(
-                select(Sprint).where(Sprint.id == sprint_id).with_for_update()
-            )
-            sprint = result.scalar_one_or_none()
-
-            if not sprint:
-                return None
-
-            if sprint.status != SprintStatus.PLANNED:
-                raise ValueError(
-                    f"Cannot start sprint with status {sprint.status.value}"
-                )
-
-            # Check for existing active sprint with lock to prevent race condition
-            # Lock all sprints for this project to ensure atomic check-and-update
-            active_check = await db.execute(
-                select(Sprint)
-                .where(
-                    Sprint.project_id == sprint.project_id,
-                    Sprint.status == SprintStatus.ACTIVE,
-                )
-                .with_for_update()
-            )
-            active_sprint = active_check.scalar_one_or_none()
-            if active_sprint:
-                raise ValueError(
-                    f"Project already has an active sprint: {active_sprint.name}"
-                )
-
-            sprint.status = SprintStatus.ACTIVE
-            if start_date:
-                sprint.start_date = start_date
-
-            # Calculate planned points from issues
-            points_result = await db.execute(
-                select(func.sum(Issue.story_points)).where(Issue.sprint_id == sprint_id)
-            )
-            sprint.planned_points = points_result.scalar_one_or_none() or 0
-
-            await db.commit()
-            await db.refresh(sprint)
-            return sprint
-        except ValueError:
-            raise
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Error starting sprint {sprint_id}: {e!s}", exc_info=True)
-            raise
-
-    async def complete_sprint(
-        self,
-        db: AsyncSession,
-        *,
-        sprint_id: UUID,
-    ) -> Sprint | None:
-        """Complete an active sprint and calculate completed points.
-
-        Uses row-level locking (SELECT FOR UPDATE) to prevent race conditions
-        when velocity is being calculated and other operations might modify issues.
-        """
-        try:
-            # Lock the sprint row to prevent concurrent modifications
-            result = await db.execute(
-                select(Sprint).where(Sprint.id == sprint_id).with_for_update()
-            )
-            sprint = result.scalar_one_or_none()
-
-            if not sprint:
-                return None
-
-            if sprint.status != SprintStatus.ACTIVE:
-                raise ValueError(
-                    f"Cannot complete sprint with status {sprint.status.value}"
-                )
-
-            sprint.status = SprintStatus.COMPLETED
-
-            # Calculate velocity (completed points) from closed issues
-            # Note: Issues are not locked, but sprint lock ensures this sprint's
-            # completion is atomic and prevents concurrent completion attempts
-            points_result = await db.execute(
-                select(func.sum(Issue.story_points)).where(
-                    Issue.sprint_id == sprint_id,
-                    Issue.status == IssueStatus.CLOSED,
-                )
-            )
-            sprint.velocity = points_result.scalar_one_or_none() or 0
-
-            await db.commit()
-            await db.refresh(sprint)
-            return sprint
-        except ValueError:
-            raise
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Error completing sprint {sprint_id}: {e!s}", exc_info=True)
-            raise
-
-    async def cancel_sprint(
-        self,
-        db: AsyncSession,
-        *,
-        sprint_id: UUID,
-    ) -> Sprint | None:
-        """Cancel a sprint (only PLANNED or ACTIVE sprints can be cancelled).
-
-        Uses row-level locking to prevent race conditions with concurrent
-        sprint status modifications.
-        """
-        try:
-            # Lock the sprint row to prevent concurrent modifications
-            result = await db.execute(
-                select(Sprint).where(Sprint.id == sprint_id).with_for_update()
-            )
-            sprint = result.scalar_one_or_none()
-
-            if not sprint:
-                return None
-
-            if sprint.status not in [SprintStatus.PLANNED, SprintStatus.ACTIVE]:
-                raise ValueError(
-                    f"Cannot cancel sprint with status {sprint.status.value}"
-                )
-
-            sprint.status = SprintStatus.CANCELLED
-            await db.commit()
-            await db.refresh(sprint)
-            return sprint
-        except ValueError:
-            raise
-        except Exception as e:
-            await db.rollback()
-            logger.error(f"Error cancelling sprint {sprint_id}: {e!s}", exc_info=True)
-            raise
-
-    async def get_velocity(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-        limit: int = 5,
-    ) -> list[dict[str, Any]]:
-        """Get velocity data for completed sprints."""
-        try:
-            result = await db.execute(
-                select(Sprint)
-                .where(
-                    Sprint.project_id == project_id,
-                    Sprint.status == SprintStatus.COMPLETED,
-                )
-                .order_by(Sprint.number.desc())
-                .limit(limit)
-            )
-            sprints = list(result.scalars().all())
-
-            velocity_data = []
-            for sprint in reversed(sprints):  # Return in chronological order
-                velocity_ratio = None
-                if sprint.planned_points and sprint.planned_points > 0:
-                    velocity_ratio = (sprint.velocity or 0) / sprint.planned_points
-                velocity_data.append(
-                    {
-                        "sprint_number": sprint.number,
-                        "sprint_name": sprint.name,
-                        "planned_points": sprint.planned_points,
-                        "velocity": sprint.velocity,
-                        "velocity_ratio": velocity_ratio,
-                    }
-                )
-
-            return velocity_data
-        except Exception as e:
-            logger.error(
-                f"Error getting velocity for project {project_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-    async def get_sprints_with_issue_counts(
-        self,
-        db: AsyncSession,
-        *,
-        project_id: UUID,
-        skip: int = 0,
-        limit: int = 100,
-    ) -> tuple[list[dict[str, Any]], int]:
-        """Get sprints with issue counts in optimized queries."""
-        try:
-            # Get sprints
-            sprints, total = await self.get_by_project(
-                db, project_id=project_id, skip=skip, limit=limit
-            )
-
-            if not sprints:
-                return [], 0
-
-            sprint_ids = [s.id for s in sprints]
-
-            # Get issue counts in bulk
-            issue_counts = await db.execute(
-                select(
-                    Issue.sprint_id,
-                    func.count(Issue.id).label("total"),
-                    func.count(Issue.id)
-                    .filter(Issue.status == IssueStatus.OPEN)
-                    .label("open"),
-                    func.count(Issue.id)
-                    .filter(Issue.status == IssueStatus.CLOSED)
-                    .label("completed"),
-                )
-                .where(Issue.sprint_id.in_(sprint_ids))
-                .group_by(Issue.sprint_id)
-            )
-            counts_map = {
-                row.sprint_id: {
-                    "issue_count": row.total,
-                    "open_issues": row.open,
-                    "completed_issues": row.completed,
-                }
-                for row in issue_counts
-            }
-
-            # Combine results
-            results = [
-                {
-                    "sprint": sprint,
-                    **counts_map.get(
-                        sprint.id,
-                        {"issue_count": 0, "open_issues": 0, "completed_issues": 0},
-                    ),
-                }
-                for sprint in sprints
-            ]
-
-            return results, total
-        except Exception as e:
-            logger.error(
-                f"Error getting sprints with counts for project {project_id}: {e!s}",
-                exc_info=True,
-            )
-            raise
-
-
-# Create a singleton instance for use across the application
-sprint = CRUDSprint(Sprint)

backend/app/init_db.py

@@ -3,48 +3,27 @@
 Async database initialization script.
 
 Creates the first superuser if configured and doesn't already exist.
-Seeds default agent types (production data) and demo data (when DEMO_MODE is enabled).
 """
 
 import asyncio
 import json
 import logging
 import random
-from datetime import UTC, date, datetime, timedelta
+from datetime import UTC, datetime, timedelta
 from pathlib import Path
 
 from sqlalchemy import select, text
-from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.config import settings
 from app.core.database import SessionLocal, engine
-from app.crud.syndarix.agent_type import agent_type as agent_type_crud
-from app.crud.user import user as user_crud
 from app.models.organization import Organization
-from app.models.syndarix import AgentInstance, AgentType, Issue, Project, Sprint
-from app.models.syndarix.enums import (
-    AgentStatus,
-    AutonomyLevel,
-    ClientMode,
-    IssuePriority,
-    IssueStatus,
-    IssueType,
-    ProjectComplexity,
-    ProjectStatus,
-    SprintStatus,
-)
 from app.models.user import User
 from app.models.user_organization import UserOrganization
-from app.schemas.syndarix import AgentTypeCreate
+from app.repositories.user import user_repo as user_repo
 from app.schemas.users import UserCreate
 
 logger = logging.getLogger(__name__)
 
-# Data file paths
-DATA_DIR = Path(__file__).parent.parent / "data"
-DEFAULT_AGENT_TYPES_PATH = DATA_DIR / "default_agent_types.json"
-DEMO_DATA_PATH = DATA_DIR / "demo_data.json"
-
 
 async def init_db() -> User | None:
     """
@@ -65,43 +44,43 @@ async def init_db() -> User | None:
     if not settings.FIRST_SUPERUSER_EMAIL or not settings.FIRST_SUPERUSER_PASSWORD:
         logger.warning(
             "First superuser credentials not configured in settings. "
-            f"Using defaults: {superuser_email}"
+            "Using defaults: %s",
+            superuser_email,
         )
 
     async with SessionLocal() as session:
         try:
             # Check if superuser already exists
-            existing_user = await user_crud.get_by_email(session, email=superuser_email)
+            existing_user = await user_repo.get_by_email(session, email=superuser_email)
 
             if existing_user:
-                logger.info(f"Superuser already exists: {existing_user.email}")
-            else:
-                # Create superuser if doesn't exist
-                user_in = UserCreate(
-                    email=superuser_email,
-                    password=superuser_password,
-                    first_name="Admin",
-                    last_name="User",
-                    is_superuser=True,
-                )
+                logger.info("Superuser already exists: %s", existing_user.email)
+                return existing_user
 
-                existing_user = await user_crud.create(session, obj_in=user_in)
-                await session.commit()
-                await session.refresh(existing_user)
-                logger.info(f"Created first superuser: {existing_user.email}")
+            # Create superuser if doesn't exist
+            user_in = UserCreate(
+                email=superuser_email,
+                password=superuser_password,
+                first_name="Admin",
+                last_name="User",
+                is_superuser=True,
+            )
 
-            # ALWAYS load default agent types (production data)
-            await load_default_agent_types(session)
+            user = await user_repo.create(session, obj_in=user_in)
+            await session.commit()
+            await session.refresh(user)
 
-            # Only load demo data if in demo mode
+            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 existing_user
+            return user
 
         except Exception as e:
             await session.rollback()
-            logger.error(f"Error initializing database: {e}")
+            logger.error("Error initializing database: %s", e)
             raise
 
 
@@ -110,96 +89,26 @@ def _load_json_file(path: Path):
         return json.load(f)
 
 
-async def load_default_agent_types(session: AsyncSession) -> None:
-    """
-    Load default agent types from JSON file.
-
-    These are production defaults - created only if they don't exist, never overwritten.
-    This allows users to customize agent types without worrying about server restarts.
-    """
-    if not DEFAULT_AGENT_TYPES_PATH.exists():
-        logger.warning(
-            f"Default agent types file not found: {DEFAULT_AGENT_TYPES_PATH}"
-        )
+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:
-        data = await asyncio.to_thread(_load_json_file, DEFAULT_AGENT_TYPES_PATH)
+        # Use asyncio.to_thread to avoid blocking the event loop
+        data = await asyncio.to_thread(_load_json_file, demo_data_path)
 
-        for agent_type_data in data:
-            slug = agent_type_data["slug"]
-
-            # Check if agent type already exists
-            existing = await agent_type_crud.get_by_slug(session, slug=slug)
-
-            if existing:
-                logger.debug(f"Agent type already exists: {agent_type_data['name']}")
-                continue
-
-            # Create the agent type
-            agent_type_in = AgentTypeCreate(
-                name=agent_type_data["name"],
-                slug=slug,
-                description=agent_type_data.get("description"),
-                expertise=agent_type_data.get("expertise", []),
-                personality_prompt=agent_type_data["personality_prompt"],
-                primary_model=agent_type_data["primary_model"],
-                fallback_models=agent_type_data.get("fallback_models", []),
-                model_params=agent_type_data.get("model_params", {}),
-                mcp_servers=agent_type_data.get("mcp_servers", []),
-                tool_permissions=agent_type_data.get("tool_permissions", {}),
-                is_active=agent_type_data.get("is_active", True),
-                # Category and display fields
-                category=agent_type_data.get("category"),
-                icon=agent_type_data.get("icon", "bot"),
-                color=agent_type_data.get("color", "#3B82F6"),
-                sort_order=agent_type_data.get("sort_order", 0),
-                typical_tasks=agent_type_data.get("typical_tasks", []),
-                collaboration_hints=agent_type_data.get("collaboration_hints", []),
-            )
-
-            await agent_type_crud.create(session, obj_in=agent_type_in)
-            logger.info(f"Created default agent type: {agent_type_data['name']}")
-
-        logger.info("Default agent types loaded successfully")
-
-    except Exception as e:
-        logger.error(f"Error loading default agent types: {e}")
-        raise
-
-
-async def load_demo_data(session: AsyncSession) -> None:
-    """
-    Load demo data from JSON file.
-
-    Only runs when DEMO_MODE is enabled. Creates demo organizations, users,
-    projects, sprints, agent instances, and issues.
-    """
-    if not DEMO_DATA_PATH.exists():
-        logger.warning(f"Demo data file not found: {DEMO_DATA_PATH}")
-        return
-
-    try:
-        data = await asyncio.to_thread(_load_json_file, DEMO_DATA_PATH)
-
-        # Build lookup maps for FK resolution
-        org_map: dict[str, Organization] = {}
-        user_map: dict[str, User] = {}
-        project_map: dict[str, Project] = {}
-        sprint_map: dict[str, Sprint] = {}  # key: "project_slug:sprint_number"
-        agent_type_map: dict[str, AgentType] = {}
-        agent_instance_map: dict[
-            str, AgentInstance
-        ] = {}  # key: "project_slug:agent_name"
-
-        # ========================
-        # 1. Create Organizations
-        # ========================
+        # Create Organizations
+        org_map = {}
         for org_data in data.get("organizations", []):
-            org_result = await session.execute(
-                select(Organization).where(Organization.slug == org_data["slug"])
+            # Check if org exists
+            result = await session.execute(
+                text("SELECT * FROM organizations WHERE slug = :slug"),
+                {"slug": org_data["slug"]},
             )
-            existing_org = org_result.scalar_one_or_none()
+            existing_org = result.first()
 
             if not existing_org:
                 org = Organization(
@@ -209,20 +118,29 @@ async def load_demo_data(session: AsyncSession) -> None:
                     is_active=True,
                 )
                 session.add(org)
-                await session.flush()
-                org_map[str(org.slug)] = org
-                logger.info(f"Created demo organization: {org.name}")
+                await session.flush()  # Flush to get ID
+                org_map[org.slug] = org
+                logger.info("Created demo organization: %s", org.name)
             else:
-                org_map[str(existing_org.slug)] = existing_org
+                # 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
 
-        # ========================
-        # 2. Create Users
-        # ========================
+        # 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_crud.get_by_email(
+            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"],
@@ -231,16 +149,20 @@ async def load_demo_data(session: AsyncSession) -> None:
                     is_superuser=user_data["is_superuser"],
                     is_active=user_data.get("is_active", True),
                 )
-                user = await user_crud.create(session, obj_in=user_in)
+                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"
@@ -253,7 +175,10 @@ async def load_demo_data(session: AsyncSession) -> None:
                 )
 
                 logger.info(
-                    f"Created demo user: {user.email} (created {days_ago} days ago)"
+                    "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
@@ -261,229 +186,20 @@ async def load_demo_data(session: AsyncSession) -> None:
                 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(f"Added {user.email} to {org.name} as {role}")
-
-                user_map[str(user.email)] = user
+                    logger.info("Added %s to %s as %s", user.email, org.name, role)
             else:
-                user_map[str(existing_user.email)] = existing_user
-                logger.debug(f"Demo user already exists: {existing_user.email}")
-
-        await session.flush()
-
-        # Add admin user to map with special "__admin__" key
-        # This allows demo data to reference the admin user as owner
-        superuser_email = settings.FIRST_SUPERUSER_EMAIL or "admin@example.com"
-        admin_user = await user_crud.get_by_email(session, email=superuser_email)
-        if admin_user:
-            user_map["__admin__"] = admin_user
-            user_map[str(admin_user.email)] = admin_user
-            logger.debug(f"Added admin user to map: {admin_user.email}")
-
-        # ========================
-        # 3. Load Agent Types Map (for FK resolution)
-        # ========================
-        agent_types_result = await session.execute(select(AgentType))
-        for at in agent_types_result.scalars().all():
-            agent_type_map[str(at.slug)] = at
-
-        # ========================
-        # 4. Create Projects
-        # ========================
-        for project_data in data.get("projects", []):
-            project_result = await session.execute(
-                select(Project).where(Project.slug == project_data["slug"])
-            )
-            existing_project = project_result.scalar_one_or_none()
-
-            if not existing_project:
-                # Resolve owner email to user ID
-                owner_id = None
-                owner_email = project_data.get("owner_email")
-                if owner_email and owner_email in user_map:
-                    owner_id = user_map[owner_email].id
-
-                project = Project(
-                    name=project_data["name"],
-                    slug=project_data["slug"],
-                    description=project_data.get("description"),
-                    owner_id=owner_id,
-                    autonomy_level=AutonomyLevel(
-                        project_data.get("autonomy_level", "milestone")
-                    ),
-                    status=ProjectStatus(project_data.get("status", "active")),
-                    complexity=ProjectComplexity(
-                        project_data.get("complexity", "medium")
-                    ),
-                    client_mode=ClientMode(project_data.get("client_mode", "auto")),
-                    settings=project_data.get("settings", {}),
-                )
-                session.add(project)
-                await session.flush()
-                project_map[str(project.slug)] = project
-                logger.info(f"Created demo project: {project.name}")
-            else:
-                project_map[str(existing_project.slug)] = existing_project
-                logger.debug(f"Demo project already exists: {existing_project.name}")
-
-        # ========================
-        # 5. Create Sprints
-        # ========================
-        for sprint_data in data.get("sprints", []):
-            project_slug = sprint_data["project_slug"]
-            sprint_number = sprint_data["number"]
-            sprint_key = f"{project_slug}:{sprint_number}"
-
-            if project_slug not in project_map:
-                logger.warning(f"Project not found for sprint: {project_slug}")
-                continue
-
-            sprint_project = project_map[project_slug]
-
-            # Check if sprint exists
-            sprint_result = await session.execute(
-                select(Sprint).where(
-                    Sprint.project_id == sprint_project.id,
-                    Sprint.number == sprint_number,
-                )
-            )
-            existing_sprint = sprint_result.scalar_one_or_none()
-
-            if not existing_sprint:
-                sprint = Sprint(
-                    project_id=sprint_project.id,
-                    name=sprint_data["name"],
-                    number=sprint_number,
-                    goal=sprint_data.get("goal"),
-                    start_date=date.fromisoformat(sprint_data["start_date"]),
-                    end_date=date.fromisoformat(sprint_data["end_date"]),
-                    status=SprintStatus(sprint_data.get("status", "planned")),
-                    planned_points=sprint_data.get("planned_points"),
-                )
-                session.add(sprint)
-                await session.flush()
-                sprint_map[sprint_key] = sprint
-                logger.info(
-                    f"Created demo sprint: {sprint.name} for {sprint_project.name}"
-                )
-            else:
-                sprint_map[sprint_key] = existing_sprint
-                logger.debug(f"Demo sprint already exists: {existing_sprint.name}")
-
-        # ========================
-        # 6. Create Agent Instances
-        # ========================
-        for agent_data in data.get("agent_instances", []):
-            project_slug = agent_data["project_slug"]
-            agent_type_slug = agent_data["agent_type_slug"]
-            agent_name = agent_data["name"]
-            agent_key = f"{project_slug}:{agent_name}"
-
-            if project_slug not in project_map:
-                logger.warning(f"Project not found for agent: {project_slug}")
-                continue
-
-            if agent_type_slug not in agent_type_map:
-                logger.warning(f"Agent type not found: {agent_type_slug}")
-                continue
-
-            agent_project = project_map[project_slug]
-            agent_type = agent_type_map[agent_type_slug]
-
-            # Check if agent instance exists (by name within project)
-            agent_result = await session.execute(
-                select(AgentInstance).where(
-                    AgentInstance.project_id == agent_project.id,
-                    AgentInstance.name == agent_name,
-                )
-            )
-            existing_agent = agent_result.scalar_one_or_none()
-
-            if not existing_agent:
-                agent_instance = AgentInstance(
-                    project_id=agent_project.id,
-                    agent_type_id=agent_type.id,
-                    name=agent_name,
-                    status=AgentStatus(agent_data.get("status", "idle")),
-                    current_task=agent_data.get("current_task"),
-                )
-                session.add(agent_instance)
-                await session.flush()
-                agent_instance_map[agent_key] = agent_instance
-                logger.info(
-                    f"Created demo agent: {agent_name} ({agent_type.name}) "
-                    f"for {agent_project.name}"
-                )
-            else:
-                agent_instance_map[agent_key] = existing_agent
-                logger.debug(f"Demo agent already exists: {existing_agent.name}")
-
-        # ========================
-        # 7. Create Issues
-        # ========================
-        for issue_data in data.get("issues", []):
-            project_slug = issue_data["project_slug"]
-
-            if project_slug not in project_map:
-                logger.warning(f"Project not found for issue: {project_slug}")
-                continue
-
-            issue_project = project_map[project_slug]
-
-            # Check if issue exists (by title within project - simple heuristic)
-            issue_result = await session.execute(
-                select(Issue).where(
-                    Issue.project_id == issue_project.id,
-                    Issue.title == issue_data["title"],
-                )
-            )
-            existing_issue = issue_result.scalar_one_or_none()
-
-            if not existing_issue:
-                # Resolve sprint
-                sprint_id = None
-                sprint_number = issue_data.get("sprint_number")
-                if sprint_number:
-                    sprint_key = f"{project_slug}:{sprint_number}"
-                    if sprint_key in sprint_map:
-                        sprint_id = sprint_map[sprint_key].id
-
-                # Resolve assigned agent
-                assigned_agent_id = None
-                assigned_agent_name = issue_data.get("assigned_agent_name")
-                if assigned_agent_name:
-                    agent_key = f"{project_slug}:{assigned_agent_name}"
-                    if agent_key in agent_instance_map:
-                        assigned_agent_id = agent_instance_map[agent_key].id
-
-                issue = Issue(
-                    project_id=issue_project.id,
-                    sprint_id=sprint_id,
-                    type=IssueType(issue_data.get("type", "task")),
-                    title=issue_data["title"],
-                    body=issue_data.get("body", ""),
-                    status=IssueStatus(issue_data.get("status", "open")),
-                    priority=IssuePriority(issue_data.get("priority", "medium")),
-                    labels=issue_data.get("labels", []),
-                    story_points=issue_data.get("story_points"),
-                    assigned_agent_id=assigned_agent_id,
-                )
-                session.add(issue)
-                logger.info(f"Created demo issue: {issue.title[:50]}...")
-            else:
-                logger.debug(
-                    f"Demo issue already exists: {existing_issue.title[:50]}..."
-                )
+                logger.info("Demo user already exists: %s", existing_user.email)
 
         await session.commit()
         logger.info("Demo data loaded successfully")
 
     except Exception as e:
-        await session.rollback()
-        logger.error(f"Error loading demo data: {e}")
+        logger.error("Error loading demo data: %s", e)
         raise
 
 
@@ -498,12 +214,12 @@ async def main():
     try:
         user = await init_db()
         if user:
-            print("Database initialized successfully")
-            print(f"Superuser: {user.email}")
+            print("✓ Database initialized successfully")
+            print(f"✓ Superuser: {user.email}")
         else:
-            print("Failed to initialize database")
+            print("✗ Failed to initialize database")
     except Exception as e:
-        print(f"Error initializing database: {e}")
+        print(f"✗ Error initializing database: {e}")
         raise
     finally:
         # Close the engine

backend/app/main.py

@@ -1,7 +1,7 @@
 import logging
 import os
 from contextlib import asynccontextmanager
-from datetime import datetime
+from datetime import UTC, datetime
 from typing import Any
 
 from apscheduler.schedulers.asyncio import AsyncIOScheduler
@@ -16,7 +16,7 @@ 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
+from app.core.database import check_database_health, close_async_db
 from app.core.exceptions import (
     APIException,
     api_exception_handler,
@@ -72,6 +72,7 @@ async def lifespan(app: FastAPI):
     if os.getenv("IS_TEST", "False") != "True":
         scheduler.shutdown()
         logger.info("Scheduled jobs stopped")
+    await close_async_db()
 
 
 logger.info("Starting app!!!")
@@ -294,7 +295,7 @@ async def health_check() -> JSONResponse:
     """
     health_status: dict[str, Any] = {
         "status": "healthy",
-        "timestamp": datetime.utcnow().isoformat() + "Z",
+        "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
         "version": settings.VERSION,
         "environment": settings.ENVIRONMENT,
         "checks": {},
@@ -319,7 +320,7 @@ async def health_check() -> JSONResponse:
             "message": f"Database connection failed: {e!s}",
         }
         response_status = status.HTTP_503_SERVICE_UNAVAILABLE
-        logger.error(f"Health check failed - database error: {e}")
+        logger.error("Health check failed - database error: %s", e)
 
     return JSONResponse(status_code=response_status, content=health_status)
 

backend/app/models/__init__.py

@@ -8,19 +8,6 @@ from app.core.database import Base
 
 from .base import TimestampMixin, UUIDMixin
 
-# Memory system models
-from .memory import (
-    ConsolidationStatus,
-    ConsolidationType,
-    Episode,
-    EpisodeOutcome,
-    Fact,
-    MemoryConsolidationLog,
-    Procedure,
-    ScopeType,
-    WorkingMemory,
-)
-
 # OAuth models (client mode - authenticate via Google/GitHub)
 from .oauth_account import OAuthAccount
 
@@ -31,33 +18,13 @@ from .oauth_provider_token import OAuthConsent, OAuthProviderRefreshToken
 from .oauth_state import OAuthState
 from .organization import Organization
 
-# Syndarix domain models
-from .syndarix import (
-    AgentInstance,
-    AgentType,
-    Issue,
-    Project,
-    Sprint,
-)
-
 # Import models
 from .user import User
 from .user_organization import OrganizationRole, UserOrganization
 from .user_session import UserSession
 
 __all__ = [
-    # Syndarix models
-    "AgentInstance",
-    "AgentType",
     "Base",
-    # Memory models
-    "ConsolidationStatus",
-    "ConsolidationType",
-    "Episode",
-    "EpisodeOutcome",
-    "Fact",
-    "Issue",
-    "MemoryConsolidationLog",
     "OAuthAccount",
     "OAuthAuthorizationCode",
     "OAuthClient",
@@ -66,14 +33,9 @@ __all__ = [
     "OAuthState",
     "Organization",
     "OrganizationRole",
-    "Procedure",
-    "Project",
-    "ScopeType",
-    "Sprint",
     "TimestampMixin",
     "UUIDMixin",
     "User",
     "UserOrganization",
     "UserSession",
-    "WorkingMemory",
 ]

backend/app/models/memory/__init__.py

@@ -1,32 +0,0 @@
-# app/models/memory/__init__.py
-"""
-Memory System Database Models.
-
-Provides SQLAlchemy models for the Agent Memory System:
-- WorkingMemory: Key-value storage with TTL
-- Episode: Experiential memories
-- Fact: Semantic knowledge triples
-- Procedure: Learned skills
-- MemoryConsolidationLog: Consolidation job tracking
-"""
-
-from .consolidation import MemoryConsolidationLog
-from .enums import ConsolidationStatus, ConsolidationType, EpisodeOutcome, ScopeType
-from .episode import Episode
-from .fact import Fact
-from .procedure import Procedure
-from .working_memory import WorkingMemory
-
-__all__ = [
-    # Enums
-    "ConsolidationStatus",
-    "ConsolidationType",
-    # Models
-    "Episode",
-    "EpisodeOutcome",
-    "Fact",
-    "MemoryConsolidationLog",
-    "Procedure",
-    "ScopeType",
-    "WorkingMemory",
-]

backend/app/models/memory/consolidation.py

@@ -1,72 +0,0 @@
-# app/models/memory/consolidation.py
-"""
-Memory Consolidation Log database model.
-
-Tracks memory consolidation jobs that transfer knowledge
-between memory tiers.
-"""
-
-from sqlalchemy import Column, DateTime, Enum, Index, Integer, Text
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-from .enums import ConsolidationStatus, ConsolidationType
-
-
-class MemoryConsolidationLog(Base, UUIDMixin, TimestampMixin):
-    """
-    Memory consolidation job log.
-
-    Tracks consolidation operations:
-    - Working -> Episodic (session end)
-    - Episodic -> Semantic (fact extraction)
-    - Episodic -> Procedural (procedure learning)
-    - Pruning (removing low-value memories)
-    """
-
-    __tablename__ = "memory_consolidation_log"
-
-    # Consolidation type
-    consolidation_type: Column[ConsolidationType] = Column(
-        Enum(ConsolidationType),
-        nullable=False,
-        index=True,
-    )
-
-    # Counts
-    source_count = Column(Integer, nullable=False, default=0)
-    result_count = Column(Integer, nullable=False, default=0)
-
-    # Timing
-    started_at = Column(DateTime(timezone=True), nullable=False)
-    completed_at = Column(DateTime(timezone=True), nullable=True)
-
-    # Status
-    status: Column[ConsolidationStatus] = Column(
-        Enum(ConsolidationStatus),
-        nullable=False,
-        default=ConsolidationStatus.PENDING,
-        index=True,
-    )
-
-    # Error details if failed
-    error = Column(Text, nullable=True)
-
-    __table_args__ = (
-        # Query patterns
-        Index("ix_consolidation_type_status", "consolidation_type", "status"),
-        Index("ix_consolidation_started", "started_at"),
-    )
-
-    @property
-    def duration_seconds(self) -> float | None:
-        """Calculate duration of the consolidation job."""
-        if self.completed_at is None or self.started_at is None:
-            return None
-        return (self.completed_at - self.started_at).total_seconds()
-
-    def __repr__(self) -> str:
-        return (
-            f"<MemoryConsolidationLog {self.id} "
-            f"type={self.consolidation_type.value} status={self.status.value}>"
-        )

backend/app/models/memory/enums.py

@@ -1,73 +0,0 @@
-# app/models/memory/enums.py
-"""
-Enums for Memory System database models.
-
-These enums define the database-level constraints for memory types
-and scoping levels.
-"""
-
-from enum import Enum as PyEnum
-
-
-class ScopeType(str, PyEnum):
-    """
-    Memory scope levels matching the memory service types.
-
-    GLOBAL: System-wide memories accessible by all
-    PROJECT: Project-scoped memories
-    AGENT_TYPE: Type-specific memories (shared by instances of same type)
-    AGENT_INSTANCE: Instance-specific memories
-    SESSION: Session-scoped ephemeral memories
-    """
-
-    GLOBAL = "global"
-    PROJECT = "project"
-    AGENT_TYPE = "agent_type"
-    AGENT_INSTANCE = "agent_instance"
-    SESSION = "session"
-
-
-class EpisodeOutcome(str, PyEnum):
-    """
-    Outcome of an episode (task execution).
-
-    SUCCESS: Task completed successfully
-    FAILURE: Task failed
-    PARTIAL: Task partially completed
-    """
-
-    SUCCESS = "success"
-    FAILURE = "failure"
-    PARTIAL = "partial"
-
-
-class ConsolidationType(str, PyEnum):
-    """
-    Types of memory consolidation operations.
-
-    WORKING_TO_EPISODIC: Transfer session state to episodic
-    EPISODIC_TO_SEMANTIC: Extract facts from episodes
-    EPISODIC_TO_PROCEDURAL: Extract procedures from episodes
-    PRUNING: Remove low-value memories
-    """
-
-    WORKING_TO_EPISODIC = "working_to_episodic"
-    EPISODIC_TO_SEMANTIC = "episodic_to_semantic"
-    EPISODIC_TO_PROCEDURAL = "episodic_to_procedural"
-    PRUNING = "pruning"
-
-
-class ConsolidationStatus(str, PyEnum):
-    """
-    Status of a consolidation job.
-
-    PENDING: Job is queued
-    RUNNING: Job is currently executing
-    COMPLETED: Job finished successfully
-    FAILED: Job failed with errors
-    """
-
-    PENDING = "pending"
-    RUNNING = "running"
-    COMPLETED = "completed"
-    FAILED = "failed"

backend/app/models/memory/episode.py

@@ -1,139 +0,0 @@
-# app/models/memory/episode.py
-"""
-Episode database model.
-
-Stores experiential memories - records of past task executions
-with context, actions, outcomes, and lessons learned.
-"""
-
-from sqlalchemy import (
-    BigInteger,
-    CheckConstraint,
-    Column,
-    DateTime,
-    Enum,
-    Float,
-    ForeignKey,
-    Index,
-    String,
-    Text,
-)
-from sqlalchemy.dialects.postgresql import (
-    JSONB,
-    UUID as PGUUID,
-)
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-from .enums import EpisodeOutcome
-
-# Import pgvector type - will be available after migration enables extension
-try:
-    from pgvector.sqlalchemy import Vector  # type: ignore[import-not-found]
-except ImportError:
-    # Fallback for environments without pgvector
-    Vector = None
-
-
-class Episode(Base, UUIDMixin, TimestampMixin):
-    """
-    Episodic memory model.
-
-    Records experiential memories from agent task execution:
-    - What task was performed
-    - What actions were taken
-    - What was the outcome
-    - What lessons were learned
-    """
-
-    __tablename__ = "episodes"
-
-    # Foreign keys
-    project_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("projects.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-
-    agent_instance_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("agent_instances.id", ondelete="SET NULL"),
-        nullable=True,
-        index=True,
-    )
-
-    agent_type_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("agent_types.id", ondelete="SET NULL"),
-        nullable=True,
-        index=True,
-    )
-
-    # Session reference
-    session_id = Column(String(255), nullable=False, index=True)
-
-    # Task information
-    task_type = Column(String(100), nullable=False, index=True)
-    task_description = Column(Text, nullable=False)
-
-    # Actions taken (list of action dictionaries)
-    actions = Column(JSONB, default=list, nullable=False)
-
-    # Context summary
-    context_summary = Column(Text, nullable=False)
-
-    # Outcome
-    outcome: Column[EpisodeOutcome] = Column(
-        Enum(EpisodeOutcome),
-        nullable=False,
-        index=True,
-    )
-    outcome_details = Column(Text, nullable=True)
-
-    # Metrics
-    duration_seconds = Column(Float, nullable=False, default=0.0)
-    tokens_used = Column(BigInteger, nullable=False, default=0)
-
-    # Learning
-    lessons_learned = Column(JSONB, default=list, nullable=False)
-    importance_score = Column(Float, nullable=False, default=0.5, index=True)
-
-    # Vector embedding for semantic search
-    # Using 1536 dimensions for OpenAI text-embedding-3-small
-    embedding = Column(Vector(1536) if Vector else Text, nullable=True)
-
-    # When the episode occurred
-    occurred_at = Column(DateTime(timezone=True), nullable=False, index=True)
-
-    # Relationships
-    project = relationship("Project", foreign_keys=[project_id])
-    agent_instance = relationship("AgentInstance", foreign_keys=[agent_instance_id])
-    agent_type = relationship("AgentType", foreign_keys=[agent_type_id])
-
-    __table_args__ = (
-        # Primary query patterns
-        Index("ix_episodes_project_task", "project_id", "task_type"),
-        Index("ix_episodes_project_outcome", "project_id", "outcome"),
-        Index("ix_episodes_agent_task", "agent_instance_id", "task_type"),
-        Index("ix_episodes_project_time", "project_id", "occurred_at"),
-        # For importance-based pruning
-        Index("ix_episodes_importance_time", "importance_score", "occurred_at"),
-        # Data integrity constraints
-        CheckConstraint(
-            "importance_score >= 0.0 AND importance_score <= 1.0",
-            name="ck_episodes_importance_range",
-        ),
-        CheckConstraint(
-            "duration_seconds >= 0.0",
-            name="ck_episodes_duration_positive",
-        ),
-        CheckConstraint(
-            "tokens_used >= 0",
-            name="ck_episodes_tokens_positive",
-        ),
-    )
-
-    def __repr__(self) -> str:
-        return f"<Episode {self.id} task={self.task_type} outcome={self.outcome.value}>"

backend/app/models/memory/fact.py

@@ -1,120 +0,0 @@
-# app/models/memory/fact.py
-"""
-Fact database model.
-
-Stores semantic memories - learned facts in subject-predicate-object
-triple format with confidence scores and source tracking.
-"""
-
-from sqlalchemy import (
-    CheckConstraint,
-    Column,
-    DateTime,
-    Float,
-    ForeignKey,
-    Index,
-    Integer,
-    String,
-    Text,
-    text,
-)
-from sqlalchemy.dialects.postgresql import (
-    JSONB,
-    UUID as PGUUID,
-)
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-# Import pgvector type
-try:
-    from pgvector.sqlalchemy import Vector  # type: ignore[import-not-found]
-except ImportError:
-    Vector = None
-
-
-class Fact(Base, UUIDMixin, TimestampMixin):
-    """
-    Semantic memory model.
-
-    Stores learned facts as subject-predicate-object triples:
-    - "FastAPI" - "uses" - "Starlette framework"
-    - "Project Alpha" - "requires" - "OAuth authentication"
-
-    Facts have confidence scores that decay over time and can be
-    reinforced when the same fact is learned again.
-    """
-
-    __tablename__ = "facts"
-
-    # Scoping: project_id is NULL for global facts
-    project_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("projects.id", ondelete="CASCADE"),
-        nullable=True,
-        index=True,
-    )
-
-    # Triple format
-    subject = Column(String(500), nullable=False, index=True)
-    predicate = Column(String(255), nullable=False, index=True)
-    object = Column(Text, nullable=False)
-
-    # Confidence score (0.0 to 1.0)
-    confidence = Column(Float, nullable=False, default=0.8, index=True)
-
-    # Source tracking: which episodes contributed to this fact (stored as JSONB array of UUID strings)
-    source_episode_ids: Column[list] = Column(JSONB, default=list, nullable=False)
-
-    # Learning history
-    first_learned = Column(DateTime(timezone=True), nullable=False)
-    last_reinforced = Column(DateTime(timezone=True), nullable=False)
-    reinforcement_count = Column(Integer, nullable=False, default=1)
-
-    # Vector embedding for semantic search
-    embedding = Column(Vector(1536) if Vector else Text, nullable=True)
-
-    # Relationships
-    project = relationship("Project", foreign_keys=[project_id])
-
-    __table_args__ = (
-        # Unique constraint on triple within project scope
-        Index(
-            "ix_facts_unique_triple",
-            "project_id",
-            "subject",
-            "predicate",
-            "object",
-            unique=True,
-            postgresql_where=text("project_id IS NOT NULL"),
-        ),
-        # Unique constraint on triple for global facts (project_id IS NULL)
-        Index(
-            "ix_facts_unique_triple_global",
-            "subject",
-            "predicate",
-            "object",
-            unique=True,
-            postgresql_where=text("project_id IS NULL"),
-        ),
-        # Query patterns
-        Index("ix_facts_subject_predicate", "subject", "predicate"),
-        Index("ix_facts_project_subject", "project_id", "subject"),
-        Index("ix_facts_confidence_time", "confidence", "last_reinforced"),
-        # Note: subject already has index=True on Column definition, no need for explicit index
-        # Data integrity constraints
-        CheckConstraint(
-            "confidence >= 0.0 AND confidence <= 1.0",
-            name="ck_facts_confidence_range",
-        ),
-        CheckConstraint(
-            "reinforcement_count >= 1",
-            name="ck_facts_reinforcement_positive",
-        ),
-    )
-
-    def __repr__(self) -> str:
-        return (
-            f"<Fact {self.id} '{self.subject}' - '{self.predicate}' - "
-            f"'{self.object[:50]}...' conf={self.confidence:.2f}>"
-        )

backend/app/models/memory/procedure.py

@@ -1,129 +0,0 @@
-# app/models/memory/procedure.py
-"""
-Procedure database model.
-
-Stores procedural memories - learned skills and procedures
-derived from successful task execution patterns.
-"""
-
-from sqlalchemy import (
-    CheckConstraint,
-    Column,
-    DateTime,
-    ForeignKey,
-    Index,
-    Integer,
-    String,
-    Text,
-)
-from sqlalchemy.dialects.postgresql import (
-    JSONB,
-    UUID as PGUUID,
-)
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-# Import pgvector type
-try:
-    from pgvector.sqlalchemy import Vector  # type: ignore[import-not-found]
-except ImportError:
-    Vector = None
-
-
-class Procedure(Base, UUIDMixin, TimestampMixin):
-    """
-    Procedural memory model.
-
-    Stores learned procedures (skills) extracted from successful
-    task execution patterns:
-    - Name and trigger pattern for matching
-    - Step-by-step actions
-    - Success/failure tracking
-    """
-
-    __tablename__ = "procedures"
-
-    # Scoping
-    project_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("projects.id", ondelete="CASCADE"),
-        nullable=True,
-        index=True,
-    )
-
-    agent_type_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("agent_types.id", ondelete="SET NULL"),
-        nullable=True,
-        index=True,
-    )
-
-    # Procedure identification
-    name = Column(String(255), nullable=False, index=True)
-    trigger_pattern = Column(Text, nullable=False)
-
-    # Steps as JSON array of step objects
-    # Each step: {order, action, parameters, expected_outcome, fallback_action}
-    steps = Column(JSONB, default=list, nullable=False)
-
-    # Success tracking
-    success_count = Column(Integer, nullable=False, default=0)
-    failure_count = Column(Integer, nullable=False, default=0)
-
-    # Usage tracking
-    last_used = Column(DateTime(timezone=True), nullable=True, index=True)
-
-    # Vector embedding for semantic matching
-    embedding = Column(Vector(1536) if Vector else Text, nullable=True)
-
-    # Relationships
-    project = relationship("Project", foreign_keys=[project_id])
-    agent_type = relationship("AgentType", foreign_keys=[agent_type_id])
-
-    __table_args__ = (
-        # Unique procedure name within scope
-        Index(
-            "ix_procedures_unique_name",
-            "project_id",
-            "agent_type_id",
-            "name",
-            unique=True,
-        ),
-        # Query patterns
-        Index("ix_procedures_project_name", "project_id", "name"),
-        # Note: agent_type_id already has index=True on Column definition
-        # For finding best procedures
-        Index("ix_procedures_success_rate", "success_count", "failure_count"),
-        # Data integrity constraints
-        CheckConstraint(
-            "success_count >= 0",
-            name="ck_procedures_success_positive",
-        ),
-        CheckConstraint(
-            "failure_count >= 0",
-            name="ck_procedures_failure_positive",
-        ),
-    )
-
-    @property
-    def success_rate(self) -> float:
-        """Calculate the success rate of this procedure."""
-        # Snapshot values to avoid race conditions in concurrent access
-        success = self.success_count
-        failure = self.failure_count
-        total = success + failure
-        if total == 0:
-            return 0.0
-        return success / total
-
-    @property
-    def total_uses(self) -> int:
-        """Get total number of times this procedure was used."""
-        # Snapshot values for consistency
-        return self.success_count + self.failure_count
-
-    def __repr__(self) -> str:
-        return (
-            f"<Procedure {self.name} ({self.id}) success_rate={self.success_rate:.2%}>"
-        )

backend/app/models/memory/working_memory.py

@@ -1,58 +0,0 @@
-# app/models/memory/working_memory.py
-"""
-Working Memory database model.
-
-Stores ephemeral key-value data for active sessions with TTL support.
-Used as database backup when Redis is unavailable.
-"""
-
-from sqlalchemy import Column, DateTime, Enum, Index, String
-from sqlalchemy.dialects.postgresql import JSONB
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-from .enums import ScopeType
-
-
-class WorkingMemory(Base, UUIDMixin, TimestampMixin):
-    """
-    Working memory storage table.
-
-    Provides database-backed working memory as fallback when
-    Redis is unavailable. Supports TTL-based expiration.
-    """
-
-    __tablename__ = "working_memory"
-
-    # Scoping
-    scope_type: Column[ScopeType] = Column(
-        Enum(ScopeType),
-        nullable=False,
-        index=True,
-    )
-    scope_id = Column(String(255), nullable=False, index=True)
-
-    # Key-value storage
-    key = Column(String(255), nullable=False)
-    value = Column(JSONB, nullable=False)
-
-    # TTL support
-    expires_at = Column(DateTime(timezone=True), nullable=True, index=True)
-
-    __table_args__ = (
-        # Primary lookup: scope + key
-        Index(
-            "ix_working_memory_scope_key",
-            "scope_type",
-            "scope_id",
-            "key",
-            unique=True,
-        ),
-        # For cleanup of expired entries
-        Index("ix_working_memory_expires", "expires_at"),
-        # For listing all keys in a scope
-        Index("ix_working_memory_scope_list", "scope_type", "scope_id"),
-    )
-
-    def __repr__(self) -> str:
-        return f"<WorkingMemory {self.scope_type.value}:{self.scope_id}:{self.key}>"

backend/app/models/oauth_account.py

@@ -36,9 +36,9 @@ class OAuthAccount(Base, UUIDMixin, TimestampMixin):
     )  # Email from provider (for reference)
 
     # Optional: store provider tokens for API access
-    # These should be encrypted at rest in production
-    access_token_encrypted = Column(String(2048), nullable=True)
-    refresh_token_encrypted = Column(String(2048), nullable=True)
+    # 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

backend/app/models/oauth_authorization_code.py

@@ -92,7 +92,7 @@ class OAuthAuthorizationCode(Base, UUIDMixin, TimestampMixin):
         # Handle both timezone-aware and naive datetimes from DB
         if expires_at.tzinfo is None:
             expires_at = expires_at.replace(tzinfo=UTC)
-        return now > expires_at
+        return bool(now > expires_at)
 
     @property
     def is_valid(self) -> bool:

backend/app/models/oauth_provider_token.py

@@ -99,7 +99,7 @@ class OAuthProviderRefreshToken(Base, UUIDMixin, TimestampMixin):
         # Handle both timezone-aware and naive datetimes from DB
         if expires_at.tzinfo is None:
             expires_at = expires_at.replace(tzinfo=UTC)
-        return now > expires_at
+        return bool(now > expires_at)
 
     @property
     def is_valid(self) -> bool:

backend/app/models/syndarix/__init__.py

@@ -1,47 +0,0 @@
-# app/models/syndarix/__init__.py
-"""
-Syndarix domain models.
-
-This package contains all the core entities for the Syndarix AI consulting platform:
-- Project: Client engagements with autonomy settings
-- AgentType: Templates for AI agent capabilities
-- AgentInstance: Spawned agents working on projects
-- Issue: Units of work with external tracker sync
-- Sprint: Time-boxed iterations for organizing work
-"""
-
-from .agent_instance import AgentInstance
-from .agent_type import AgentType
-from .enums import (
-    AgentStatus,
-    AutonomyLevel,
-    ClientMode,
-    IssuePriority,
-    IssueStatus,
-    IssueType,
-    ProjectComplexity,
-    ProjectStatus,
-    SprintStatus,
-    SyncStatus,
-)
-from .issue import Issue
-from .project import Project
-from .sprint import Sprint
-
-__all__ = [
-    "AgentInstance",
-    "AgentStatus",
-    "AgentType",
-    "AutonomyLevel",
-    "ClientMode",
-    "Issue",
-    "IssuePriority",
-    "IssueStatus",
-    "IssueType",
-    "Project",
-    "ProjectComplexity",
-    "ProjectStatus",
-    "Sprint",
-    "SprintStatus",
-    "SyncStatus",
-]

backend/app/models/syndarix/agent_instance.py

@@ -1,115 +0,0 @@
-# app/models/syndarix/agent_instance.py
-"""
-AgentInstance model for Syndarix AI consulting platform.
-
-An AgentInstance is a spawned instance of an AgentType, assigned to a
-specific project to perform work.
-"""
-
-from sqlalchemy import (
-    BigInteger,
-    Column,
-    DateTime,
-    Enum,
-    ForeignKey,
-    Index,
-    Integer,
-    Numeric,
-    String,
-    Text,
-)
-from sqlalchemy.dialects.postgresql import (
-    JSONB,
-    UUID as PGUUID,
-)
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-from .enums import AgentStatus
-
-
-class AgentInstance(Base, UUIDMixin, TimestampMixin):
-    """
-    AgentInstance model representing a spawned agent working on a project.
-
-    Tracks:
-    - Current status and task
-    - Memory (short-term in DB, long-term reference to vector store)
-    - Session information for MCP connections
-    - Usage metrics (tasks completed, tokens, cost)
-    """
-
-    __tablename__ = "agent_instances"
-
-    # Foreign keys
-    agent_type_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("agent_types.id", ondelete="RESTRICT"),
-        nullable=False,
-        index=True,
-    )
-
-    project_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("projects.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-
-    # Agent instance name (e.g., "Dave", "Eve") for personality
-    name = Column(String(100), nullable=False, index=True)
-
-    # Status tracking
-    status: Column[AgentStatus] = Column(
-        Enum(
-            AgentStatus,
-            name="agent_status",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=AgentStatus.IDLE,
-        nullable=False,
-        index=True,
-    )
-
-    # Current task description (brief summary of what agent is doing)
-    current_task = Column(Text, nullable=True)
-
-    # Short-term memory stored in database (conversation context, recent decisions)
-    short_term_memory = Column(JSONB, default=dict, nullable=False)
-
-    # Reference to long-term memory in vector store (e.g., "project-123/agent-456")
-    long_term_memory_ref = Column(String(500), nullable=True)
-
-    # Session ID for active MCP connections
-    session_id = Column(String(255), nullable=True, index=True)
-
-    # Activity tracking
-    last_activity_at = Column(DateTime(timezone=True), nullable=True, index=True)
-    terminated_at = Column(DateTime(timezone=True), nullable=True, index=True)
-
-    # Usage metrics
-    tasks_completed = Column(Integer, default=0, nullable=False)
-    tokens_used = Column(BigInteger, default=0, nullable=False)
-    cost_incurred = Column(Numeric(precision=10, scale=4), default=0, nullable=False)
-
-    # Relationships
-    agent_type = relationship("AgentType", back_populates="instances")
-    project = relationship("Project", back_populates="agent_instances")
-    assigned_issues = relationship(
-        "Issue",
-        back_populates="assigned_agent",
-        foreign_keys="Issue.assigned_agent_id",
-    )
-
-    __table_args__ = (
-        Index("ix_agent_instances_project_status", "project_id", "status"),
-        Index("ix_agent_instances_type_status", "agent_type_id", "status"),
-        Index("ix_agent_instances_project_type", "project_id", "agent_type_id"),
-    )
-
-    def __repr__(self) -> str:
-        return (
-            f"<AgentInstance {self.name} ({self.id}) type={self.agent_type_id} "
-            f"project={self.project_id} status={self.status.value}>"
-        )

backend/app/models/syndarix/agent_type.py

@@ -1,91 +0,0 @@
-# app/models/syndarix/agent_type.py
-"""
-AgentType model for Syndarix AI consulting platform.
-
-An AgentType is a template that defines the capabilities, personality,
-and model configuration for agent instances.
-"""
-
-from sqlalchemy import Boolean, Column, Index, Integer, String, Text
-from sqlalchemy.dialects.postgresql import JSONB
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-
-class AgentType(Base, UUIDMixin, TimestampMixin):
-    """
-    AgentType model representing a template for agent instances.
-
-    Each agent type defines:
-    - Expertise areas and personality prompt
-    - Model configuration (primary, fallback, parameters)
-    - MCP server access and tool permissions
-
-    Examples: ProductOwner, Architect, BackendEngineer, QAEngineer
-    """
-
-    __tablename__ = "agent_types"
-
-    name = Column(String(255), nullable=False, index=True)
-    slug = Column(String(255), unique=True, nullable=False, index=True)
-    description = Column(Text, nullable=True)
-
-    # Areas of expertise for this agent type (e.g., ["python", "fastapi", "databases"])
-    expertise = Column(JSONB, default=list, nullable=False)
-
-    # System prompt defining the agent's personality and behavior
-    personality_prompt = Column(Text, nullable=False)
-
-    # Primary LLM model to use (e.g., "claude-opus-4-5-20251101")
-    primary_model = Column(String(100), nullable=False)
-
-    # Fallback models in order of preference
-    fallback_models = Column(JSONB, default=list, nullable=False)
-
-    # Model parameters (temperature, max_tokens, etc.)
-    model_params = Column(JSONB, default=dict, nullable=False)
-
-    # List of MCP servers this agent can connect to
-    mcp_servers = Column(JSONB, default=list, nullable=False)
-
-    # Tool permissions configuration
-    # Structure: {"allowed": ["*"], "denied": [], "require_approval": ["gitea:create_pr"]}
-    tool_permissions = Column(JSONB, default=dict, nullable=False)
-
-    # Whether this agent type is available for new instances
-    is_active = Column(Boolean, default=True, nullable=False, index=True)
-
-    # Category for grouping agents (development, design, quality, etc.)
-    category = Column(String(50), nullable=True, index=True)
-
-    # Lucide icon identifier for UI display (e.g., "code", "palette", "shield")
-    icon = Column(String(50), nullable=True, default="bot")
-
-    # Hex color code for visual distinction (e.g., "#3B82F6")
-    color = Column(String(7), nullable=True, default="#3B82F6")
-
-    # Display ordering within category (lower = first)
-    sort_order = Column(Integer, nullable=False, default=0, index=True)
-
-    # List of typical tasks this agent excels at
-    typical_tasks = Column(JSONB, default=list, nullable=False)
-
-    # List of agent slugs that collaborate well with this type
-    collaboration_hints = Column(JSONB, default=list, nullable=False)
-
-    # Relationships
-    instances = relationship(
-        "AgentInstance",
-        back_populates="agent_type",
-        cascade="all, delete-orphan",
-    )
-
-    __table_args__ = (
-        Index("ix_agent_types_slug_active", "slug", "is_active"),
-        Index("ix_agent_types_name_active", "name", "is_active"),
-        Index("ix_agent_types_category_sort", "category", "sort_order"),
-    )
-
-    def __repr__(self) -> str:
-        return f"<AgentType {self.name} ({self.slug}) active={self.is_active}>"

backend/app/models/syndarix/enums.py

@@ -1,195 +0,0 @@
-# app/models/syndarix/enums.py
-"""
-Enums for Syndarix domain models.
-
-These enums represent the core state machines and categorizations
-used throughout the Syndarix AI consulting platform.
-"""
-
-from enum import Enum as PyEnum
-
-
-class AutonomyLevel(str, PyEnum):
-    """
-    Defines how much control the human has over agent actions.
-
-    FULL_CONTROL: Human must approve every agent action
-    MILESTONE: Human approves at sprint boundaries and major decisions
-    AUTONOMOUS: Agents work independently, only escalating critical issues
-    """
-
-    FULL_CONTROL = "full_control"
-    MILESTONE = "milestone"
-    AUTONOMOUS = "autonomous"
-
-
-class ProjectComplexity(str, PyEnum):
-    """
-    Project complexity level for estimation and planning.
-
-    SCRIPT: Simple automation or script-level work
-    SIMPLE: Straightforward feature or fix
-    MEDIUM: Standard complexity with some architectural considerations
-    COMPLEX: Large-scale feature requiring significant design work
-    """
-
-    SCRIPT = "script"
-    SIMPLE = "simple"
-    MEDIUM = "medium"
-    COMPLEX = "complex"
-
-
-class ClientMode(str, PyEnum):
-    """
-    How the client prefers to interact with agents.
-
-    TECHNICAL: Client is technical and prefers detailed updates
-    AUTO: Agents automatically determine communication level
-    """
-
-    TECHNICAL = "technical"
-    AUTO = "auto"
-
-
-class ProjectStatus(str, PyEnum):
-    """
-    Project lifecycle status.
-
-    ACTIVE: Project is actively being worked on
-    PAUSED: Project is temporarily on hold
-    COMPLETED: Project has been delivered successfully
-    ARCHIVED: Project is no longer accessible for work
-    """
-
-    ACTIVE = "active"
-    PAUSED = "paused"
-    COMPLETED = "completed"
-    ARCHIVED = "archived"
-
-
-class AgentStatus(str, PyEnum):
-    """
-    Current operational status of an agent instance.
-
-    IDLE: Agent is available but not currently working
-    WORKING: Agent is actively processing a task
-    WAITING: Agent is waiting for external input or approval
-    PAUSED: Agent has been manually paused
-    TERMINATED: Agent instance has been shut down
-    """
-
-    IDLE = "idle"
-    WORKING = "working"
-    WAITING = "waiting"
-    PAUSED = "paused"
-    TERMINATED = "terminated"
-
-
-class IssueType(str, PyEnum):
-    """
-    Issue type for categorization and hierarchy.
-
-    EPIC: Large feature or body of work containing stories
-    STORY: User-facing feature or requirement
-    TASK: Technical work item
-    BUG: Defect or issue to be fixed
-    """
-
-    EPIC = "epic"
-    STORY = "story"
-    TASK = "task"
-    BUG = "bug"
-
-
-class IssueStatus(str, PyEnum):
-    """
-    Issue workflow status.
-
-    OPEN: Issue is ready to be worked on
-    IN_PROGRESS: Agent or human is actively working on the issue
-    IN_REVIEW: Work is complete, awaiting review
-    BLOCKED: Issue cannot proceed due to dependencies or blockers
-    CLOSED: Issue has been completed or cancelled
-    """
-
-    OPEN = "open"
-    IN_PROGRESS = "in_progress"
-    IN_REVIEW = "in_review"
-    BLOCKED = "blocked"
-    CLOSED = "closed"
-
-
-class IssuePriority(str, PyEnum):
-    """
-    Issue priority levels.
-
-    LOW: Nice to have, can be deferred
-    MEDIUM: Standard priority, should be done
-    HIGH: Important, should be prioritized
-    CRITICAL: Must be done immediately, blocking other work
-    """
-
-    LOW = "low"
-    MEDIUM = "medium"
-    HIGH = "high"
-    CRITICAL = "critical"
-
-
-class SyncStatus(str, PyEnum):
-    """
-    External issue tracker synchronization status.
-
-    SYNCED: Local and remote are in sync
-    PENDING: Local changes waiting to be pushed
-    CONFLICT: Merge conflict between local and remote
-    ERROR: Synchronization failed due to an error
-    """
-
-    SYNCED = "synced"
-    PENDING = "pending"
-    CONFLICT = "conflict"
-    ERROR = "error"
-
-
-class SprintStatus(str, PyEnum):
-    """
-    Sprint lifecycle status.
-
-    PLANNED: Sprint has been created but not started
-    ACTIVE: Sprint is currently in progress
-    IN_REVIEW: Sprint work is done, demo/review pending
-    COMPLETED: Sprint has been finished successfully
-    CANCELLED: Sprint was cancelled before completion
-    """
-
-    PLANNED = "planned"
-    ACTIVE = "active"
-    IN_REVIEW = "in_review"
-    COMPLETED = "completed"
-    CANCELLED = "cancelled"
-
-
-class AgentTypeCategory(str, PyEnum):
-    """
-    Category classification for agent types.
-
-    Used for grouping and filtering agents in the UI.
-
-    DEVELOPMENT: Product, project, and engineering roles
-    DESIGN: UI/UX and design research roles
-    QUALITY: QA and security engineering
-    OPERATIONS: DevOps and MLOps
-    AI_ML: Machine learning and AI specialists
-    DATA: Data science and engineering
-    LEADERSHIP: Technical leadership roles
-    DOMAIN_EXPERT: Industry and domain specialists
-    """
-
-    DEVELOPMENT = "development"
-    DESIGN = "design"
-    QUALITY = "quality"
-    OPERATIONS = "operations"
-    AI_ML = "ai_ml"
-    DATA = "data"
-    LEADERSHIP = "leadership"
-    DOMAIN_EXPERT = "domain_expert"

backend/app/models/syndarix/issue.py

@@ -1,190 +0,0 @@
-# app/models/syndarix/issue.py
-"""
-Issue model for Syndarix AI consulting platform.
-
-An Issue represents a unit of work that can be assigned to agents or humans,
-with optional synchronization to external issue trackers (Gitea, GitHub, GitLab).
-"""
-
-from sqlalchemy import (
-    Column,
-    Date,
-    DateTime,
-    Enum,
-    ForeignKey,
-    Index,
-    Integer,
-    String,
-    Text,
-)
-from sqlalchemy.dialects.postgresql import (
-    JSONB,
-    UUID as PGUUID,
-)
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-from .enums import IssuePriority, IssueStatus, IssueType, SyncStatus
-
-
-class Issue(Base, UUIDMixin, TimestampMixin):
-    """
-    Issue model representing a unit of work in a project.
-
-    Features:
-    - Standard issue fields (title, body, status, priority)
-    - Assignment to agent instances or human assignees
-    - Sprint association for backlog management
-    - External tracker synchronization (Gitea, GitHub, GitLab)
-    """
-
-    __tablename__ = "issues"
-
-    # Foreign key to project
-    project_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("projects.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-
-    # Parent issue for hierarchy (Epic -> Story -> Task)
-    parent_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("issues.id", ondelete="CASCADE"),
-        nullable=True,
-        index=True,
-    )
-
-    # Issue type (Epic, Story, Task, Bug)
-    type: Column[IssueType] = Column(
-        Enum(
-            IssueType, name="issue_type", values_callable=lambda x: [e.value for e in x]
-        ),
-        default=IssueType.TASK,
-        nullable=False,
-        index=True,
-    )
-
-    # Reporter (who created this issue - can be user or agent)
-    reporter_id = Column(
-        PGUUID(as_uuid=True),
-        nullable=True,  # System-generated issues may have no reporter
-        index=True,
-    )
-
-    # Issue content
-    title = Column(String(500), nullable=False)
-    body = Column(Text, nullable=False, default="")
-
-    # Status and priority
-    status: Column[IssueStatus] = Column(
-        Enum(
-            IssueStatus,
-            name="issue_status",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=IssueStatus.OPEN,
-        nullable=False,
-        index=True,
-    )
-
-    priority: Column[IssuePriority] = Column(
-        Enum(
-            IssuePriority,
-            name="issue_priority",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=IssuePriority.MEDIUM,
-        nullable=False,
-        index=True,
-    )
-
-    # Labels for categorization (e.g., ["bug", "frontend", "urgent"])
-    labels = Column(JSONB, default=list, nullable=False)
-
-    # Assignment - either to an agent or a human (mutually exclusive)
-    assigned_agent_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("agent_instances.id", ondelete="SET NULL"),
-        nullable=True,
-        index=True,
-    )
-
-    # Human assignee (username or email, not a FK to allow external users)
-    human_assignee = Column(String(255), nullable=True, index=True)
-
-    # Sprint association
-    sprint_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("sprints.id", ondelete="SET NULL"),
-        nullable=True,
-        index=True,
-    )
-
-    # Story points for estimation
-    story_points = Column(Integer, nullable=True)
-
-    # Due date for the issue
-    due_date = Column(Date, nullable=True, index=True)
-
-    # External tracker integration
-    external_tracker_type = Column(
-        String(50),
-        nullable=True,
-        index=True,
-    )  # 'gitea', 'github', 'gitlab'
-
-    external_issue_id = Column(String(255), nullable=True)  # External system's ID
-    remote_url = Column(String(1000), nullable=True)  # Link to external issue
-    external_issue_number = Column(Integer, nullable=True)  # Issue number (e.g., #123)
-
-    # Sync status with external tracker
-    sync_status: Column[SyncStatus] = Column(
-        Enum(
-            SyncStatus,
-            name="sync_status",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=SyncStatus.SYNCED,
-        nullable=False,
-        # Note: Index defined in __table_args__ as ix_issues_sync_status
-    )
-
-    last_synced_at = Column(DateTime(timezone=True), nullable=True)
-    external_updated_at = Column(DateTime(timezone=True), nullable=True)
-
-    # Lifecycle timestamp
-    closed_at = Column(DateTime(timezone=True), nullable=True, index=True)
-
-    # Relationships
-    project = relationship("Project", back_populates="issues")
-    assigned_agent = relationship(
-        "AgentInstance",
-        back_populates="assigned_issues",
-        foreign_keys=[assigned_agent_id],
-    )
-    sprint = relationship("Sprint", back_populates="issues")
-    parent = relationship("Issue", remote_side="Issue.id", backref="children")
-
-    __table_args__ = (
-        Index("ix_issues_project_status", "project_id", "status"),
-        Index("ix_issues_project_priority", "project_id", "priority"),
-        Index("ix_issues_project_sprint", "project_id", "sprint_id"),
-        Index(
-            "ix_issues_external_tracker_id",
-            "external_tracker_type",
-            "external_issue_id",
-        ),
-        Index("ix_issues_sync_status", "sync_status"),
-        Index("ix_issues_project_agent", "project_id", "assigned_agent_id"),
-        Index("ix_issues_project_type", "project_id", "type"),
-        Index("ix_issues_project_status_priority", "project_id", "status", "priority"),
-    )
-
-    def __repr__(self) -> str:
-        return (
-            f"<Issue {self.id} title='{self.title[:30]}...' "
-            f"status={self.status.value} priority={self.priority.value}>"
-        )

backend/app/models/syndarix/project.py

@@ -1,119 +0,0 @@
-# app/models/syndarix/project.py
-"""
-Project model for Syndarix AI consulting platform.
-
-A Project represents a client engagement where AI agents collaborate
-to deliver software solutions.
-"""
-
-from sqlalchemy import Column, Enum, ForeignKey, Index, String, Text
-from sqlalchemy.dialects.postgresql import (
-    JSONB,
-    UUID as PGUUID,
-)
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-from .enums import AutonomyLevel, ClientMode, ProjectComplexity, ProjectStatus
-
-
-class Project(Base, UUIDMixin, TimestampMixin):
-    """
-    Project model representing a client engagement.
-
-    A project contains:
-    - Configuration for how autonomous agents should operate
-    - Settings for MCP server integrations
-    - Relationship to assigned agents, issues, and sprints
-    """
-
-    __tablename__ = "projects"
-
-    name = Column(String(255), nullable=False, index=True)
-    slug = Column(String(255), unique=True, nullable=False, index=True)
-    description = Column(Text, nullable=True)
-
-    autonomy_level: Column[AutonomyLevel] = Column(
-        Enum(
-            AutonomyLevel,
-            name="autonomy_level",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=AutonomyLevel.MILESTONE,
-        nullable=False,
-        index=True,
-    )
-
-    status: Column[ProjectStatus] = Column(
-        Enum(
-            ProjectStatus,
-            name="project_status",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=ProjectStatus.ACTIVE,
-        nullable=False,
-        index=True,
-    )
-
-    complexity: Column[ProjectComplexity] = Column(
-        Enum(
-            ProjectComplexity,
-            name="project_complexity",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=ProjectComplexity.MEDIUM,
-        nullable=False,
-        index=True,
-    )
-
-    client_mode: Column[ClientMode] = Column(
-        Enum(
-            ClientMode,
-            name="client_mode",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=ClientMode.AUTO,
-        nullable=False,
-        index=True,
-    )
-
-    # JSON field for flexible project configuration
-    # Can include: mcp_servers, webhook_urls, notification_settings, etc.
-    settings = Column(JSONB, default=dict, nullable=False)
-
-    # Foreign key to the User who owns this project
-    owner_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("users.id", ondelete="SET NULL"),
-        nullable=True,
-        index=True,
-    )
-
-    # Relationships
-    owner = relationship("User", foreign_keys=[owner_id])
-    agent_instances = relationship(
-        "AgentInstance",
-        back_populates="project",
-        cascade="all, delete-orphan",
-    )
-    issues = relationship(
-        "Issue",
-        back_populates="project",
-        cascade="all, delete-orphan",
-    )
-    sprints = relationship(
-        "Sprint",
-        back_populates="project",
-        cascade="all, delete-orphan",
-    )
-
-    __table_args__ = (
-        Index("ix_projects_slug_status", "slug", "status"),
-        Index("ix_projects_owner_status", "owner_id", "status"),
-        Index("ix_projects_autonomy_status", "autonomy_level", "status"),
-        Index("ix_projects_complexity_status", "complexity", "status"),
-    )
-
-    def __repr__(self) -> str:
-        return f"<Project {self.name} ({self.slug}) status={self.status.value}>"

backend/app/models/syndarix/sprint.py

@@ -1,90 +0,0 @@
-# app/models/syndarix/sprint.py
-"""
-Sprint model for Syndarix AI consulting platform.
-
-A Sprint represents a time-boxed iteration for organizing and delivering work.
-"""
-
-from sqlalchemy import (
-    Column,
-    Date,
-    Enum,
-    ForeignKey,
-    Index,
-    Integer,
-    String,
-    Text,
-    UniqueConstraint,
-)
-from sqlalchemy.dialects.postgresql import UUID as PGUUID
-from sqlalchemy.orm import relationship
-
-from app.models.base import Base, TimestampMixin, UUIDMixin
-
-from .enums import SprintStatus
-
-
-class Sprint(Base, UUIDMixin, TimestampMixin):
-    """
-    Sprint model representing a time-boxed iteration.
-
-    Tracks:
-    - Sprint metadata (name, number, goal)
-    - Date range (start/end)
-    - Progress metrics (planned vs completed points)
-    """
-
-    __tablename__ = "sprints"
-
-    # Foreign key to project
-    project_id = Column(
-        PGUUID(as_uuid=True),
-        ForeignKey("projects.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-
-    # Sprint identification
-    name = Column(String(255), nullable=False)
-    number = Column(Integer, nullable=False)  # Sprint number within project
-
-    # Sprint goal (what we aim to achieve)
-    goal = Column(Text, nullable=True)
-
-    # Date range
-    start_date = Column(Date, nullable=False, index=True)
-    end_date = Column(Date, nullable=False, index=True)
-
-    # Status
-    status: Column[SprintStatus] = Column(
-        Enum(
-            SprintStatus,
-            name="sprint_status",
-            values_callable=lambda x: [e.value for e in x],
-        ),
-        default=SprintStatus.PLANNED,
-        nullable=False,
-        index=True,
-    )
-
-    # Progress metrics
-    planned_points = Column(Integer, nullable=True)  # Sum of story points at start
-    velocity = Column(Integer, nullable=True)  # Sum of completed story points
-
-    # Relationships
-    project = relationship("Project", back_populates="sprints")
-    issues = relationship("Issue", back_populates="sprint")
-
-    __table_args__ = (
-        Index("ix_sprints_project_status", "project_id", "status"),
-        Index("ix_sprints_project_number", "project_id", "number"),
-        Index("ix_sprints_date_range", "start_date", "end_date"),
-        # Ensure sprint numbers are unique within a project
-        UniqueConstraint("project_id", "number", name="uq_sprint_project_number"),
-    )
-
-    def __repr__(self) -> str:
-        return (
-            f"<Sprint {self.name} (#{self.number}) "
-            f"project={self.project_id} status={self.status.value}>"
-        )

backend/app/models/user_session.py

@@ -76,7 +76,11 @@ class UserSession(Base, UUIDMixin, TimestampMixin):
         """Check if session has expired."""
         from datetime import datetime
 
-        return self.expires_at < datetime.now(UTC)
+        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."""

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

@@ -1,6 +1,6 @@
-# app/crud/base_async.py
+# app/repositories/base.py
 """
-Async CRUD operations base class using SQLAlchemy 2.0 async patterns.
+Base repository class for async database operations using SQLAlchemy 2.0 async patterns.
 
 Provides reusable create, read, update, and delete operations for all models.
 """
@@ -18,6 +18,11 @@ 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__)
 
@@ -26,16 +31,16 @@ CreateSchemaType = TypeVar("CreateSchemaType", bound=BaseModel)
 UpdateSchemaType = TypeVar("UpdateSchemaType", bound=BaseModel)
 
 
-class CRUDBase[
+class BaseRepository[
     ModelType: Base,
     CreateSchemaType: BaseModel,
     UpdateSchemaType: BaseModel,
 ]:
-    """Async CRUD operations for a model."""
+    """Async repository operations for a model."""
 
     def __init__(self, model: type[ModelType]):
         """
-        CRUD object with default async methods to Create, Read, Update, Delete.
+        Repository object with default async methods to Create, Read, Update, Delete.
 
         Parameters:
             model: A SQLAlchemy model class
@@ -56,26 +61,19 @@ class CRUDBase[
 
         Returns:
             Model instance or None if not found
-
-        Example:
-            # Eager load user relationship
-            from sqlalchemy.orm import joinedload
-            session = await session_crud.get(db, id=session_id, options=[joinedload(UserSession.user)])
         """
-        # Validate UUID format and convert to UUID object if string
         try:
             if isinstance(id, uuid.UUID):
                 uuid_obj = id
             else:
                 uuid_obj = uuid.UUID(str(id))
         except (ValueError, AttributeError, TypeError) as e:
-            logger.warning(f"Invalid UUID format: {id} - {e!s}")
+            logger.warning("Invalid UUID format: %s - %s", id, e)
             return None
 
         try:
             query = select(self.model).where(self.model.id == uuid_obj)
 
-            # Apply eager loading options if provided
             if options:
                 for option in options:
                     query = query.options(option)
@@ -83,7 +81,9 @@ class CRUDBase[
             result = await db.execute(query)
             return result.scalar_one_or_none()
         except Exception as e:
-            logger.error(f"Error retrieving {self.model.__name__} with id {id}: {e!s}")
+            logger.error(
+                "Error retrieving %s with id %s: %s", self.model.__name__, id, e
+            )
             raise
 
     async def get_multi(
@@ -96,28 +96,17 @@ class CRUDBase[
     ) -> list[ModelType]:
         """
         Get multiple records with pagination validation and optional eager loading.
-
-        Args:
-            db: Database session
-            skip: Number of records to skip
-            limit: Maximum number of records to return
-            options: Optional list of SQLAlchemy load options for eager loading
-
-        Returns:
-            List of model instances
         """
-        # Validate pagination parameters
         if skip < 0:
-            raise ValueError("skip must be non-negative")
+            raise InvalidInputError("skip must be non-negative")
         if limit < 0:
-            raise ValueError("limit must be non-negative")
+            raise InvalidInputError("limit must be non-negative")
         if limit > 1000:
-            raise ValueError("Maximum limit is 1000")
+            raise InvalidInputError("Maximum limit is 1000")
 
         try:
-            query = select(self.model).offset(skip).limit(limit)
+            query = select(self.model).order_by(self.model.id).offset(skip).limit(limit)
 
-            # Apply eager loading options if provided
             if options:
                 for option in options:
                     query = query.options(option)
@@ -126,7 +115,7 @@ class CRUDBase[
             return list(result.scalars().all())
         except Exception as e:
             logger.error(
-                f"Error retrieving multiple {self.model.__name__} records: {e!s}"
+                "Error retrieving multiple %s records: %s", self.model.__name__, e
             )
             raise
 
@@ -136,9 +125,8 @@ class CRUDBase[
         """Create a new record with error handling.
 
         NOTE: This method is defensive code that's never called in practice.
-        All CRUD subclasses (CRUDUser, CRUDOrganization, CRUDSession) override this method
-        with their own implementations, so the base implementation and its exception handlers
-        are never executed. Marked as pragma: no cover to avoid false coverage gaps.
+        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)
@@ -152,22 +140,24 @@ class CRUDBase[
             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(
-                    f"Duplicate entry attempted for {self.model.__name__}: {error_msg}"
+                    "Duplicate entry attempted for %s: %s",
+                    self.model.__name__,
+                    error_msg,
                 )
-                raise ValueError(
+                raise DuplicateEntryError(
                     f"A {self.model.__name__} with this data already exists"
                 )
-            logger.error(f"Integrity error creating {self.model.__name__}: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
+            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(f"Database error creating {self.model.__name__}: {e!s}")
-            raise ValueError(f"Database operation failed: {e!s}")
+            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.error(
-                f"Unexpected error creating {self.model.__name__}: {e!s}", exc_info=True
-            )
+            logger.exception("Unexpected error creating %s: %s", self.model.__name__, e)
             raise
 
     async def update(
@@ -198,34 +188,35 @@ class CRUDBase[
             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(
-                    f"Duplicate entry attempted for {self.model.__name__}: {error_msg}"
+                    "Duplicate entry attempted for %s: %s",
+                    self.model.__name__,
+                    error_msg,
                 )
-                raise ValueError(
+                raise DuplicateEntryError(
                     f"A {self.model.__name__} with this data already exists"
                 )
-            logger.error(f"Integrity error updating {self.model.__name__}: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
+            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(f"Database error updating {self.model.__name__}: {e!s}")
-            raise ValueError(f"Database operation failed: {e!s}")
+            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.error(
-                f"Unexpected error updating {self.model.__name__}: {e!s}", exc_info=True
-            )
+            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."""
-        # Validate UUID format and convert to UUID object if string
         try:
             if isinstance(id, uuid.UUID):
                 uuid_obj = id
             else:
                 uuid_obj = uuid.UUID(str(id))
         except (ValueError, AttributeError, TypeError) as e:
-            logger.warning(f"Invalid UUID format for deletion: {id} - {e!s}")
+            logger.warning("Invalid UUID format for deletion: %s - %s", id, e)
             return None
 
         try:
@@ -236,7 +227,7 @@ class CRUDBase[
 
             if obj is None:
                 logger.warning(
-                    f"{self.model.__name__} with id {id} not found for deletion"
+                    "%s with id %s not found for deletion", self.model.__name__, id
                 )
                 return None
 
@@ -246,15 +237,16 @@ class CRUDBase[
         except IntegrityError as e:
             await db.rollback()
             error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
-            logger.error(f"Integrity error deleting {self.model.__name__}: {error_msg}")
-            raise ValueError(
+            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.error(
-                f"Error deleting {self.model.__name__} with id {id}: {e!s}",
-                exc_info=True,
+            logger.exception(
+                "Error deleting %s with id %s: %s", self.model.__name__, id, e
             )
             raise
 
@@ -272,57 +264,40 @@ class CRUDBase[
         Get multiple records with total count, filtering, and sorting.
 
         NOTE: This method is defensive code that's never called in practice.
-        All CRUD subclasses (CRUDUser, CRUDOrganization, CRUDSession) override this method
-        with their own implementations that include additional parameters like search.
+        All repository subclasses override this method with their own implementations.
         Marked as pragma: no cover to avoid false coverage gaps.
-
-        Args:
-            db: Database session
-            skip: Number of records to skip
-            limit: Maximum number of records to return
-            sort_by: Field name to sort by (must be a valid model attribute)
-            sort_order: Sort order ("asc" or "desc")
-            filters: Dictionary of filters (field_name: value)
-
-        Returns:
-            Tuple of (items, total_count)
         """
-        # Validate pagination parameters
         if skip < 0:
-            raise ValueError("skip must be non-negative")
+            raise InvalidInputError("skip must be non-negative")
         if limit < 0:
-            raise ValueError("limit must be non-negative")
+            raise InvalidInputError("limit must be non-negative")
         if limit > 1000:
-            raise ValueError("Maximum limit is 1000")
+            raise InvalidInputError("Maximum limit is 1000")
 
         try:
-            # Build base query
             query = select(self.model)
 
-            # Exclude soft-deleted records by default
             if hasattr(self.model, "deleted_at"):
                 query = query.where(self.model.deleted_at.is_(None))
 
-            # Apply filters
             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)
 
-            # Get total count (before pagination)
             count_query = select(func.count()).select_from(query.alias())
             count_result = await db.execute(count_query)
             total = count_result.scalar_one()
 
-            # Apply sorting
             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)
 
-            # Apply pagination
             query = query.offset(skip).limit(limit)
             items_result = await db.execute(query)
             items = list(items_result.scalars().all())
@@ -330,7 +305,7 @@ class CRUDBase[
             return items, total
         except Exception as e:  # pragma: no cover
             logger.error(
-                f"Error retrieving paginated {self.model.__name__} records: {e!s}"
+                "Error retrieving paginated %s records: %s", self.model.__name__, e
             )
             raise
 
@@ -340,7 +315,7 @@ class CRUDBase[
             result = await db.execute(select(func.count(self.model.id)))
             return result.scalar_one()
         except Exception as e:
-            logger.error(f"Error counting {self.model.__name__} records: {e!s}")
+            logger.error("Error counting %s records: %s", self.model.__name__, e)
             raise
 
     async def exists(self, db: AsyncSession, id: str) -> bool:
@@ -356,14 +331,13 @@ class CRUDBase[
         """
         from datetime import datetime
 
-        # Validate UUID format and convert to UUID object if string
         try:
             if isinstance(id, uuid.UUID):
                 uuid_obj = id
             else:
                 uuid_obj = uuid.UUID(str(id))
         except (ValueError, AttributeError, TypeError) as e:
-            logger.warning(f"Invalid UUID format for soft deletion: {id} - {e!s}")
+            logger.warning("Invalid UUID format for soft deletion: %s - %s", id, e)
             return None
 
         try:
@@ -374,18 +348,16 @@ class CRUDBase[
 
             if obj is None:
                 logger.warning(
-                    f"{self.model.__name__} with id {id} not found for soft deletion"
+                    "%s with id %s not found for soft deletion", self.model.__name__, id
                 )
                 return None
 
-            # Check if model supports soft deletes
             if not hasattr(self.model, "deleted_at"):
-                logger.error(f"{self.model.__name__} does not support soft deletes")
-                raise ValueError(
+                logger.error("%s does not support soft deletes", self.model.__name__)
+                raise InvalidInputError(
                     f"{self.model.__name__} does not have a deleted_at column"
                 )
 
-            # Set deleted_at timestamp
             obj.deleted_at = datetime.now(UTC)
             db.add(obj)
             await db.commit()
@@ -393,9 +365,8 @@ class CRUDBase[
             return obj
         except Exception as e:
             await db.rollback()
-            logger.error(
-                f"Error soft deleting {self.model.__name__} with id {id}: {e!s}",
-                exc_info=True,
+            logger.exception(
+                "Error soft deleting %s with id %s: %s", self.model.__name__, id, e
             )
             raise
 
@@ -405,18 +376,16 @@ class CRUDBase[
 
         Only works if the model has a 'deleted_at' column.
         """
-        # Validate UUID format
         try:
             if isinstance(id, uuid.UUID):
                 uuid_obj = id
             else:
                 uuid_obj = uuid.UUID(str(id))
         except (ValueError, AttributeError, TypeError) as e:
-            logger.warning(f"Invalid UUID format for restoration: {id} - {e!s}")
+            logger.warning("Invalid UUID format for restoration: %s - %s", id, e)
             return None
 
         try:
-            # Find the soft-deleted record
             if hasattr(self.model, "deleted_at"):
                 result = await db.execute(
                     select(self.model).where(
@@ -425,18 +394,19 @@ class CRUDBase[
                 )
                 obj = result.scalar_one_or_none()
             else:
-                logger.error(f"{self.model.__name__} does not support soft deletes")
-                raise ValueError(
+                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(
-                    f"Soft-deleted {self.model.__name__} with id {id} not found for restoration"
+                    "Soft-deleted %s with id %s not found for restoration",
+                    self.model.__name__,
+                    id,
                 )
                 return None
 
-            # Clear deleted_at timestamp
             obj.deleted_at = None
             db.add(obj)
             await db.commit()
@@ -444,8 +414,7 @@ class CRUDBase[
             return obj
         except Exception as e:
             await db.rollback()
-            logger.error(
-                f"Error restoring {self.model.__name__} with id {id}: {e!s}",
-                exc_info=True,
+            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

@@ -1,5 +1,5 @@
-# app/crud/organization_async.py
-"""Async CRUD operations for Organization model using SQLAlchemy 2.0 patterns."""
+# app/repositories/organization.py
+"""Repository for Organization model async database operations using SQLAlchemy 2.0 patterns."""
 
 import logging
 from typing import Any
@@ -9,10 +9,11 @@ from sqlalchemy import and_, case, func, or_, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
-from app.crud.base import CRUDBase
+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,
@@ -21,8 +22,10 @@ from app.schemas.organizations import (
 logger = logging.getLogger(__name__)
 
 
-class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUpdate]):
-    """Async CRUD operations for Organization model."""
+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."""
@@ -32,7 +35,7 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             )
             return result.scalar_one_or_none()
         except Exception as e:
-            logger.error(f"Error getting organization by slug {slug}: {e!s}")
+            logger.error("Error getting organization by slug %s: %s", slug, e)
             raise
 
     async def create(
@@ -54,18 +57,20 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
         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():
-                logger.warning(f"Duplicate slug attempted: {obj_in.slug}")
-                raise ValueError(
+            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(f"Integrity error creating organization: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
+            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.error(
-                f"Unexpected error creating organization: {e!s}", exc_info=True
-            )
+            logger.exception("Unexpected error creating organization: %s", e)
             raise
 
     async def get_multi_with_filters(
@@ -79,16 +84,10 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
         sort_by: str = "created_at",
         sort_order: str = "desc",
     ) -> tuple[list[Organization], int]:
-        """
-        Get multiple organizations with filtering, searching, and sorting.
-
-        Returns:
-            Tuple of (organizations list, total count)
-        """
+        """Get multiple organizations with filtering, searching, and sorting."""
         try:
             query = select(Organization)
 
-            # Apply filters
             if is_active is not None:
                 query = query.where(Organization.is_active == is_active)
 
@@ -100,26 +99,23 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
                 )
                 query = query.where(search_filter)
 
-            # Get total count before pagination
             count_query = select(func.count()).select_from(query.alias())
             count_result = await db.execute(count_query)
             total = count_result.scalar_one()
 
-            # Apply sorting
             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())
 
-            # Apply pagination
             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(f"Error getting organizations with filters: {e!s}")
+            logger.error("Error getting organizations with filters: %s", e)
             raise
 
     async def get_member_count(self, db: AsyncSession, *, organization_id: UUID) -> int:
@@ -136,7 +132,7 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             return result.scalar_one() or 0
         except Exception as e:
             logger.error(
-                f"Error getting member count for organization {organization_id}: {e!s}"
+                "Error getting member count for organization %s: %s", organization_id, e
             )
             raise
 
@@ -149,16 +145,8 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
         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.
-        This eliminates the N+1 query problem.
-
-        Returns:
-            Tuple of (list of dicts with org and member_count, total count)
-        """
+        """Get organizations with member counts in a SINGLE QUERY using JOIN and GROUP BY."""
         try:
-            # Build base query with LEFT JOIN and GROUP BY
-            # Use CASE statement to count only active members
             query = (
                 select(
                     Organization,
@@ -181,10 +169,10 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
                 .group_by(Organization.id)
             )
 
-            # Apply filters
             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}%"),
@@ -193,17 +181,15 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
                 )
                 query = query.where(search_filter)
 
-            # Get total count
             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:
+            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()
 
-            # Apply pagination and ordering
             query = (
                 query.order_by(Organization.created_at.desc()).offset(skip).limit(limit)
             )
@@ -211,7 +197,6 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             result = await db.execute(query)
             rows = result.all()
 
-            # Convert to list of dicts
             orgs_with_counts = [
                 {"organization": org, "member_count": member_count}
                 for org, member_count in rows
@@ -220,9 +205,7 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             return orgs_with_counts, total
 
         except Exception as e:
-            logger.error(
-                f"Error getting organizations with member counts: {e!s}", exc_info=True
-            )
+            logger.exception("Error getting organizations with member counts: %s", e)
             raise
 
     async def add_user(
@@ -236,7 +219,6 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
     ) -> UserOrganization:
         """Add a user to an organization with a specific role."""
         try:
-            # Check if relationship already exists
             result = await db.execute(
                 select(UserOrganization).where(
                     and_(
@@ -248,7 +230,6 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             existing = result.scalar_one_or_none()
 
             if existing:
-                # Reactivate if inactive, or raise error if already active
                 if not existing.is_active:
                     existing.is_active = True
                     existing.role = role
@@ -257,9 +238,10 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
                     await db.refresh(existing)
                     return existing
                 else:
-                    raise ValueError("User is already a member of this organization")
+                    raise DuplicateEntryError(
+                        "User is already a member of this organization"
+                    )
 
-            # Create new relationship
             user_org = UserOrganization(
                 user_id=user_id,
                 organization_id=organization_id,
@@ -273,11 +255,11 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             return user_org
         except IntegrityError as e:
             await db.rollback()
-            logger.error(f"Integrity error adding user to organization: {e!s}")
-            raise ValueError("Failed to add user to organization")
+            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.error(f"Error adding user to organization: {e!s}", exc_info=True)
+            logger.exception("Error adding user to organization: %s", e)
             raise
 
     async def remove_user(
@@ -303,7 +285,7 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             return True
         except Exception as e:
             await db.rollback()
-            logger.error(f"Error removing user from organization: {e!s}", exc_info=True)
+            logger.exception("Error removing user from organization: %s", e)
             raise
 
     async def update_user_role(
@@ -338,7 +320,7 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             return user_org
         except Exception as e:
             await db.rollback()
-            logger.error(f"Error updating user role: {e!s}", exc_info=True)
+            logger.exception("Error updating user role: %s", e)
             raise
 
     async def get_organization_members(
@@ -348,16 +330,10 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
         organization_id: UUID,
         skip: int = 0,
         limit: int = 100,
-        is_active: bool = True,
+        is_active: bool | None = True,
     ) -> tuple[list[dict[str, Any]], int]:
-        """
-        Get members of an organization with user details.
-
-        Returns:
-            Tuple of (members list with user details, total count)
-        """
+        """Get members of an organization with user details."""
         try:
-            # Build query with join
             query = (
                 select(UserOrganization, User)
                 .join(User, UserOrganization.user_id == User.id)
@@ -367,7 +343,6 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             if is_active is not None:
                 query = query.where(UserOrganization.is_active == is_active)
 
-            # Get total count
             count_query = select(func.count()).select_from(
                 select(UserOrganization)
                 .where(UserOrganization.organization_id == organization_id)
@@ -381,7 +356,6 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             count_result = await db.execute(count_query)
             total = count_result.scalar_one()
 
-            # Apply ordering and pagination
             query = (
                 query.order_by(UserOrganization.created_at.desc())
                 .offset(skip)
@@ -406,11 +380,11 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
 
             return members, total
         except Exception as e:
-            logger.error(f"Error getting organization members: {e!s}")
+            logger.error("Error getting organization members: %s", e)
             raise
 
     async def get_user_organizations(
-        self, db: AsyncSession, *, user_id: UUID, is_active: bool = True
+        self, db: AsyncSession, *, user_id: UUID, is_active: bool | None = True
     ) -> list[Organization]:
         """Get all organizations a user belongs to."""
         try:
@@ -429,21 +403,14 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             result = await db.execute(query)
             return list(result.scalars().all())
         except Exception as e:
-            logger.error(f"Error getting user organizations: {e!s}")
+            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 = True
+        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.
-        Eliminates N+1 problem by using subquery for member counts.
-
-        Returns:
-            List of dicts with organization, role, and member_count
-        """
+        """Get user's organizations with role and member count in SINGLE QUERY."""
         try:
-            # Subquery to get member counts for each organization
             member_count_subq = (
                 select(
                     UserOrganization.organization_id,
@@ -454,7 +421,6 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
                 .subquery()
             )
 
-            # Main query with JOIN to get org, role, and member count
             query = (
                 select(
                     Organization,
@@ -486,9 +452,7 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             ]
 
         except Exception as e:
-            logger.error(
-                f"Error getting user organizations with details: {e!s}", exc_info=True
-            )
+            logger.exception("Error getting user organizations with details: %s", e)
             raise
 
     async def get_user_role_in_org(
@@ -507,9 +471,9 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
             )
             user_org = result.scalar_one_or_none()
 
-            return user_org.role if user_org else None
+            return user_org.role if user_org else None  # pyright: ignore[reportReturnType]
         except Exception as e:
-            logger.error(f"Error getting user role in org: {e!s}")
+            logger.error("Error getting user role in org: %s", e)
             raise
 
     async def is_user_org_owner(
@@ -531,5 +495,5 @@ class CRUDOrganization(CRUDBase[Organization, OrganizationCreate, OrganizationUp
         return role in [OrganizationRole.OWNER, OrganizationRole.ADMIN]
 
 
-# Create a singleton instance for use across the application
-organization = CRUDOrganization(Organization)
+# Singleton instance
+organization_repo = OrganizationRepository(Organization)

backend/app/repositories/session.py

@@ -1,6 +1,5 @@
-"""
-Async CRUD operations for user sessions using SQLAlchemy 2.0 patterns.
-"""
+# app/repositories/session.py
+"""Repository for UserSession model async database operations using SQLAlchemy 2.0 patterns."""
 
 import logging
 import uuid
@@ -11,49 +10,32 @@ from sqlalchemy import and_, delete, func, select, update
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import joinedload
 
-from app.crud.base import CRUDBase
+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 CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
-    """Async CRUD operations for user sessions."""
+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.
-
-        Args:
-            db: Database session
-            jti: Refresh token JWT ID
-
-        Returns:
-            UserSession if found, None otherwise
-        """
+        """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(f"Error getting session by JTI {jti}: {e!s}")
+            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.
-
-        Args:
-            db: Database session
-            jti: Refresh token JWT ID
-
-        Returns:
-            Active UserSession if found, None otherwise
-        """
+        """Get active session by refresh token JTI."""
         try:
             result = await db.execute(
                 select(UserSession).where(
@@ -65,7 +47,7 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             )
             return result.scalar_one_or_none()
         except Exception as e:
-            logger.error(f"Error getting active session by JTI {jti}: {e!s}")
+            logger.error("Error getting active session by JTI %s: %s", jti, e)
             raise
 
     async def get_user_sessions(
@@ -76,25 +58,12 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
         active_only: bool = True,
         with_user: bool = False,
     ) -> list[UserSession]:
-        """
-        Get all sessions for a user with optional eager loading.
-
-        Args:
-            db: Database session
-            user_id: User ID
-            active_only: If True, return only active sessions
-            with_user: If True, eager load user relationship to prevent N+1
-
-        Returns:
-            List of UserSession objects
-        """
+        """Get all sessions for a user with optional eager loading."""
         try:
-            # Convert user_id string to UUID if needed
             user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
 
             query = select(UserSession).where(UserSession.user_id == user_uuid)
 
-            # Add eager loading if requested to prevent N+1 queries
             if with_user:
                 query = query.options(joinedload(UserSession.user))
 
@@ -105,25 +74,13 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             result = await db.execute(query)
             return list(result.scalars().all())
         except Exception as e:
-            logger.error(f"Error getting sessions for user {user_id}: {e!s}")
+            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.
-
-        Args:
-            db: Database session
-            obj_in: SessionCreate schema with session data
-
-        Returns:
-            Created UserSession
-
-        Raises:
-            ValueError: If session creation fails
-        """
+        """Create a new user session."""
         try:
             db_obj = UserSession(
                 user_id=obj_in.user_id,
@@ -143,33 +100,26 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             await db.refresh(db_obj)
 
             logger.info(
-                f"Session created for user {obj_in.user_id} from {obj_in.device_name} "
-                f"(IP: {obj_in.ip_address})"
+                "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.error(f"Error creating session: {e!s}", exc_info=True)
-            raise ValueError(f"Failed to create session: {e!s}")
+            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).
-
-        Args:
-            db: Database session
-            session_id: Session UUID
-
-        Returns:
-            Deactivated UserSession if found, None otherwise
-        """
+        """Deactivate a session (logout from device)."""
         try:
             session = await self.get(db, id=session_id)
             if not session:
-                logger.warning(f"Session {session_id} not found for deactivation")
+                logger.warning("Session %s not found for deactivation", session_id)
                 return None
 
             session.is_active = False
@@ -178,31 +128,23 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             await db.refresh(session)
 
             logger.info(
-                f"Session {session_id} deactivated for user {session.user_id} "
-                f"({session.device_name})"
+                "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(f"Error deactivating session {session_id}: {e!s}")
+            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).
-
-        Args:
-            db: Database session
-            user_id: User ID
-
-        Returns:
-            Number of sessions deactivated
-        """
+        """Deactivate all active sessions for a user (logout from all devices)."""
         try:
-            # Convert user_id string to UUID if needed
             user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
 
             stmt = (
@@ -216,27 +158,18 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
 
             count = result.rowcount
 
-            logger.info(f"Deactivated {count} sessions for user {user_id}")
+            logger.info("Deactivated %s sessions for user %s", count, user_id)
 
             return count
         except Exception as e:
             await db.rollback()
-            logger.error(f"Error deactivating all sessions for user {user_id}: {e!s}")
+            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.
-
-        Args:
-            db: Database session
-            session: UserSession object
-
-        Returns:
-            Updated UserSession
-        """
+        """Update the last_used_at timestamp for a session."""
         try:
             session.last_used_at = datetime.now(UTC)
             db.add(session)
@@ -245,7 +178,7 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             return session
         except Exception as e:
             await db.rollback()
-            logger.error(f"Error updating last_used for session {session.id}: {e!s}")
+            logger.error("Error updating last_used for session %s: %s", session.id, e)
             raise
 
     async def update_refresh_token(
@@ -256,20 +189,7 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
         new_jti: str,
         new_expires_at: datetime,
     ) -> UserSession:
-        """
-        Update session with new refresh token JTI and expiration.
-
-        Called during token refresh.
-
-        Args:
-            db: Database session
-            session: UserSession object
-            new_jti: New refresh token JTI
-            new_expires_at: New expiration datetime
-
-        Returns:
-            Updated UserSession
-        """
+        """Update session with new refresh token JTI and expiration."""
         try:
             session.refresh_token_jti = new_jti
             session.expires_at = new_expires_at
@@ -281,32 +201,16 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
         except Exception as e:
             await db.rollback()
             logger.error(
-                f"Error updating refresh token for session {session.id}: {e!s}"
+                "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.
-
-        Deletes sessions that are:
-        - Expired AND inactive
-        - Older than keep_days
-
-        Uses single DELETE query instead of N individual deletes for efficiency.
-
-        Args:
-            db: Database session
-            keep_days: Keep inactive sessions for this many days (for audit)
-
-        Returns:
-            Number of sessions deleted
-        """
+        """Clean up expired sessions using optimized bulk DELETE."""
         try:
             cutoff_date = datetime.now(UTC) - timedelta(days=keep_days)
             now = datetime.now(UTC)
 
-            # Use bulk DELETE with WHERE clause - single query
             stmt = delete(UserSession).where(
                 and_(
                     UserSession.is_active == False,  # noqa: E712
@@ -321,38 +225,25 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             count = result.rowcount
 
             if count > 0:
-                logger.info(f"Cleaned up {count} expired sessions using bulk DELETE")
+                logger.info("Cleaned up %s expired sessions using bulk DELETE", count)
 
             return count
         except Exception as e:
             await db.rollback()
-            logger.error(f"Error cleaning up expired sessions: {e!s}")
+            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.
-
-        Uses single bulk DELETE query for efficiency instead of N individual deletes.
-
-        Args:
-            db: Database session
-            user_id: User ID to cleanup sessions for
-
-        Returns:
-            Number of sessions deleted
-        """
+        """Clean up expired and inactive sessions for a specific user."""
         try:
-            # Validate UUID
             try:
                 uuid_obj = uuid.UUID(user_id)
             except (ValueError, AttributeError):
-                logger.error(f"Invalid UUID format: {user_id}")
-                raise ValueError(f"Invalid user ID format: {user_id}")
+                logger.error("Invalid UUID format: %s", user_id)
+                raise InvalidInputError(f"Invalid user ID format: {user_id}")
 
             now = datetime.now(UTC)
 
-            # Use bulk DELETE with WHERE clause - single query
             stmt = delete(UserSession).where(
                 and_(
                     UserSession.user_id == uuid_obj,
@@ -368,30 +259,22 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
 
             if count > 0:
                 logger.info(
-                    f"Cleaned up {count} expired sessions for user {user_id} using bulk DELETE"
+                    "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(
-                f"Error cleaning up expired sessions for user {user_id}: {e!s}"
+                "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.
-
-        Args:
-            db: Database session
-            user_id: User ID
-
-        Returns:
-            Number of active sessions
-        """
+        """Get count of active sessions for a user."""
         try:
-            # Convert user_id string to UUID if needed
             user_uuid = UUID(user_id) if isinstance(user_id, str) else user_id
 
             result = await db.execute(
@@ -401,7 +284,7 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             )
             return result.scalar_one()
         except Exception as e:
-            logger.error(f"Error counting sessions for user {user_id}: {e!s}")
+            logger.error("Error counting sessions for user %s: %s", user_id, e)
             raise
 
     async def get_all_sessions(
@@ -413,31 +296,16 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
         active_only: bool = True,
         with_user: bool = True,
     ) -> tuple[list[UserSession], int]:
-        """
-        Get all sessions across all users with pagination (admin only).
-
-        Args:
-            db: Database session
-            skip: Number of records to skip
-            limit: Maximum number of records to return
-            active_only: If True, return only active sessions
-            with_user: If True, eager load user relationship to prevent N+1
-
-        Returns:
-            Tuple of (list of UserSession objects, total count)
-        """
+        """Get all sessions across all users with pagination (admin only)."""
         try:
-            # Build query
             query = select(UserSession)
 
-            # Add eager loading if requested to prevent N+1 queries
             if with_user:
                 query = query.options(joinedload(UserSession.user))
 
             if active_only:
                 query = query.where(UserSession.is_active)
 
-            # Get total count
             count_query = select(func.count(UserSession.id))
             if active_only:
                 count_query = count_query.where(UserSession.is_active)
@@ -445,7 +313,6 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             count_result = await db.execute(count_query)
             total = count_result.scalar_one()
 
-            # Apply pagination and ordering
             query = (
                 query.order_by(UserSession.last_used_at.desc())
                 .offset(skip)
@@ -458,9 +325,9 @@ class CRUDSession(CRUDBase[UserSession, SessionCreate, SessionUpdate]):
             return sessions, total
 
         except Exception as e:
-            logger.error(f"Error getting all sessions: {e!s}", exc_info=True)
+            logger.exception("Error getting all sessions: %s", e)
             raise
 
 
-# Create singleton instance
-session = CRUDSession(UserSession)
+# Singleton instance
+session_repo = SessionRepository(UserSession)

backend/app/repositories/user.py

@@ -1,5 +1,5 @@
-# app/crud/user_async.py
-"""Async CRUD operations for User model using SQLAlchemy 2.0 patterns."""
+# app/repositories/user.py
+"""Repository for User model async database operations using SQLAlchemy 2.0 patterns."""
 
 import logging
 from datetime import UTC, datetime
@@ -11,15 +11,16 @@ from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.auth import get_password_hash_async
-from app.crud.base import CRUDBase
+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 CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
-    """Async CRUD operations for User model."""
+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."""
@@ -27,13 +28,12 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
             result = await db.execute(select(User).where(User.email == email))
             return result.scalar_one_or_none()
         except Exception as e:
-            logger.error(f"Error getting user by email {email}: {e!s}")
+            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:
-            # Hash password asynchronously to avoid blocking event loop
             password_hash = await get_password_hash_async(obj_in.password)
 
             db_obj = User(
@@ -57,13 +57,49 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
             await db.rollback()
             error_msg = str(e.orig) if hasattr(e, "orig") else str(e)
             if "email" in error_msg.lower():
-                logger.warning(f"Duplicate email attempted: {obj_in.email}")
-                raise ValueError(f"User with email {obj_in.email} already exists")
-            logger.error(f"Integrity error creating user: {error_msg}")
-            raise ValueError(f"Database integrity error: {error_msg}")
+                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.error(f"Unexpected error creating user: {e!s}", exc_info=True)
+            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(
@@ -75,8 +111,6 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
         else:
             update_data = obj_in.model_dump(exclude_unset=True)
 
-        # Handle password separately if it exists in update data
-        # Hash password asynchronously to avoid blocking event loop
         if "password" in update_data:
             update_data["password_hash"] = await get_password_hash_async(
                 update_data["password"]
@@ -85,6 +119,15 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
 
         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,
@@ -96,43 +139,23 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
         filters: dict[str, Any] | None = None,
         search: str | None = None,
     ) -> tuple[list[User], int]:
-        """
-        Get multiple users with total count, filtering, sorting, and search.
-
-        Args:
-            db: Database session
-            skip: Number of records to skip
-            limit: Maximum number of records to return
-            sort_by: Field name to sort by
-            sort_order: Sort order ("asc" or "desc")
-            filters: Dictionary of filters (field_name: value)
-            search: Search term to match against email, first_name, last_name
-
-        Returns:
-            Tuple of (users list, total count)
-        """
-        # Validate pagination
+        """Get multiple users with total count, filtering, sorting, and search."""
         if skip < 0:
-            raise ValueError("skip must be non-negative")
+            raise InvalidInputError("skip must be non-negative")
         if limit < 0:
-            raise ValueError("limit must be non-negative")
+            raise InvalidInputError("limit must be non-negative")
         if limit > 1000:
-            raise ValueError("Maximum limit is 1000")
+            raise InvalidInputError("Maximum limit is 1000")
 
         try:
-            # Build base query
             query = select(User)
-
-            # Exclude soft-deleted users
             query = query.where(User.deleted_at.is_(None))
 
-            # Apply filters
             if filters:
                 for field, value in filters.items():
                     if hasattr(User, field) and value is not None:
                         query = query.where(getattr(User, field) == value)
 
-            # Apply search
             if search:
                 search_filter = or_(
                     User.email.ilike(f"%{search}%"),
@@ -141,14 +164,12 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
                 )
                 query = query.where(search_filter)
 
-            # Get total count
             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()
 
-            # Apply sorting
             if sort_by and hasattr(User, sort_by):
                 sort_column = getattr(User, sort_by)
                 if sort_order.lower() == "desc":
@@ -156,7 +177,6 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
                 else:
                     query = query.order_by(sort_column.asc())
 
-            # Apply pagination
             query = query.offset(skip).limit(limit)
             result = await db.execute(query)
             users = list(result.scalars().all())
@@ -164,32 +184,21 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
             return users, total
 
         except Exception as e:
-            logger.error(f"Error retrieving paginated users: {e!s}")
+            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.
-
-        Args:
-            db: Database session
-            user_ids: List of user IDs to update
-            is_active: New active status
-
-        Returns:
-            Number of users updated
-        """
+        """Bulk update is_active status for multiple users."""
         try:
             if not user_ids:
                 return 0
 
-            # Use UPDATE with WHERE IN for efficiency
             stmt = (
                 update(User)
                 .where(User.id.in_(user_ids))
-                .where(User.deleted_at.is_(None))  # Don't update deleted users
+                .where(User.deleted_at.is_(None))
                 .values(is_active=is_active, updated_at=datetime.now(UTC))
             )
 
@@ -197,12 +206,14 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
             await db.commit()
 
             updated_count = result.rowcount
-            logger.info(f"Bulk updated {updated_count} users to is_active={is_active}")
+            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.error(f"Error bulk updating user status: {e!s}", exc_info=True)
+            logger.exception("Error bulk updating user status: %s", e)
             raise
 
     async def bulk_soft_delete(
@@ -212,34 +223,20 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
         user_ids: list[UUID],
         exclude_user_id: UUID | None = None,
     ) -> int:
-        """
-        Bulk soft delete multiple users.
-
-        Args:
-            db: Database session
-            user_ids: List of user IDs to delete
-            exclude_user_id: Optional user ID to exclude (e.g., the admin performing the action)
-
-        Returns:
-            Number of users deleted
-        """
+        """Bulk soft delete multiple users."""
         try:
             if not user_ids:
                 return 0
 
-            # Remove excluded user from list
             filtered_ids = [uid for uid in user_ids if uid != exclude_user_id]
 
             if not filtered_ids:
                 return 0
 
-            # Use UPDATE with WHERE IN for efficiency
             stmt = (
                 update(User)
                 .where(User.id.in_(filtered_ids))
-                .where(
-                    User.deleted_at.is_(None)
-                )  # Don't re-delete already deleted users
+                .where(User.deleted_at.is_(None))
                 .values(
                     deleted_at=datetime.now(UTC),
                     is_active=False,
@@ -251,22 +248,22 @@ class CRUDUser(CRUDBase[User, UserCreate, UserUpdate]):
             await db.commit()
 
             deleted_count = result.rowcount
-            logger.info(f"Bulk soft deleted {deleted_count} users")
+            logger.info("Bulk soft deleted %s users", deleted_count)
             return deleted_count
 
         except Exception as e:
             await db.rollback()
-            logger.error(f"Error bulk deleting users: {e!s}", exc_info=True)
+            logger.exception("Error bulk deleting users: %s", e)
             raise
 
     def is_active(self, user: User) -> bool:
         """Check if user is active."""
-        return user.is_active
+        return bool(user.is_active)
 
     def is_superuser(self, user: User) -> bool:
         """Check if user is a superuser."""
-        return user.is_superuser
+        return bool(user.is_superuser)
 
 
-# Create a singleton instance for use across the application
-user = CRUDUser(User)
+# Singleton instance
+user_repo = UserRepository(User)

backend/app/schemas/events.py

@@ -1,273 +0,0 @@
-"""
-Event schemas for the Syndarix EventBus (Redis Pub/Sub).
-
-This module defines event types and payload schemas for real-time communication
-between services, agents, and the frontend.
-"""
-
-from datetime import datetime
-from enum import Enum
-from typing import Literal
-from uuid import UUID
-
-from pydantic import BaseModel, Field
-
-
-class EventType(str, Enum):
-    """
-    Event types for the EventBus.
-
-    Naming convention: {domain}.{action}
-    """
-
-    # Agent Events
-    AGENT_SPAWNED = "agent.spawned"
-    AGENT_STATUS_CHANGED = "agent.status_changed"
-    AGENT_MESSAGE = "agent.message"
-    AGENT_TERMINATED = "agent.terminated"
-
-    # Issue Events
-    ISSUE_CREATED = "issue.created"
-    ISSUE_UPDATED = "issue.updated"
-    ISSUE_ASSIGNED = "issue.assigned"
-    ISSUE_CLOSED = "issue.closed"
-
-    # Sprint Events
-    SPRINT_STARTED = "sprint.started"
-    SPRINT_COMPLETED = "sprint.completed"
-
-    # Approval Events
-    APPROVAL_REQUESTED = "approval.requested"
-    APPROVAL_GRANTED = "approval.granted"
-    APPROVAL_DENIED = "approval.denied"
-
-    # Project Events
-    PROJECT_CREATED = "project.created"
-    PROJECT_UPDATED = "project.updated"
-    PROJECT_ARCHIVED = "project.archived"
-
-    # Workflow Events
-    WORKFLOW_STARTED = "workflow.started"
-    WORKFLOW_STEP_COMPLETED = "workflow.step_completed"
-    WORKFLOW_COMPLETED = "workflow.completed"
-    WORKFLOW_FAILED = "workflow.failed"
-
-
-ActorType = Literal["agent", "user", "system"]
-
-
-class Event(BaseModel):
-    """
-    Base event schema for the EventBus.
-
-    All events published to the EventBus must conform to this schema.
-    """
-
-    id: str = Field(
-        ...,
-        description="Unique event identifier (UUID string)",
-        examples=["550e8400-e29b-41d4-a716-446655440000"],
-    )
-    type: EventType = Field(
-        ...,
-        description="Event type enum value",
-        examples=[EventType.AGENT_MESSAGE],
-    )
-    timestamp: datetime = Field(
-        ...,
-        description="When the event occurred (UTC)",
-        examples=["2024-01-15T10:30:00Z"],
-    )
-    project_id: UUID = Field(
-        ...,
-        description="Project this event belongs to",
-        examples=["550e8400-e29b-41d4-a716-446655440001"],
-    )
-    actor_id: UUID | None = Field(
-        default=None,
-        description="ID of the agent or user who triggered the event",
-        examples=["550e8400-e29b-41d4-a716-446655440002"],
-    )
-    actor_type: ActorType = Field(
-        ...,
-        description="Type of actor: 'agent', 'user', or 'system'",
-        examples=["agent"],
-    )
-    payload: dict = Field(
-        default_factory=dict,
-        description="Event-specific payload data",
-    )
-
-    model_config = {
-        "json_schema_extra": {
-            "example": {
-                "id": "550e8400-e29b-41d4-a716-446655440000",
-                "type": "agent.message",
-                "timestamp": "2024-01-15T10:30:00Z",
-                "project_id": "550e8400-e29b-41d4-a716-446655440001",
-                "actor_id": "550e8400-e29b-41d4-a716-446655440002",
-                "actor_type": "agent",
-                "payload": {"message": "Processing task...", "progress": 50},
-            }
-        }
-    }
-
-
-# Specific payload schemas for type safety
-
-
-class AgentSpawnedPayload(BaseModel):
-    """Payload for AGENT_SPAWNED events."""
-
-    agent_instance_id: UUID = Field(..., description="ID of the spawned agent instance")
-    agent_type_id: UUID = Field(..., description="ID of the agent type")
-    agent_name: str = Field(..., description="Human-readable name of the agent")
-    role: str = Field(..., description="Agent role (e.g., 'product_owner', 'engineer')")
-
-
-class AgentStatusChangedPayload(BaseModel):
-    """Payload for AGENT_STATUS_CHANGED events."""
-
-    agent_instance_id: UUID = Field(..., description="ID of the agent instance")
-    previous_status: str = Field(..., description="Previous status")
-    new_status: str = Field(..., description="New status")
-    reason: str | None = Field(default=None, description="Reason for status change")
-
-
-class AgentMessagePayload(BaseModel):
-    """Payload for AGENT_MESSAGE events."""
-
-    agent_instance_id: UUID = Field(..., description="ID of the agent instance")
-    message: str = Field(..., description="Message content")
-    message_type: str = Field(
-        default="info",
-        description="Message type: 'info', 'warning', 'error', 'debug'",
-    )
-    metadata: dict = Field(
-        default_factory=dict,
-        description="Additional metadata (e.g., token usage, model info)",
-    )
-
-
-class AgentTerminatedPayload(BaseModel):
-    """Payload for AGENT_TERMINATED events."""
-
-    agent_instance_id: UUID = Field(..., description="ID of the agent instance")
-    termination_reason: str = Field(..., description="Reason for termination")
-    final_status: str = Field(..., description="Final status at termination")
-
-
-class IssueCreatedPayload(BaseModel):
-    """Payload for ISSUE_CREATED events."""
-
-    issue_id: str = Field(..., description="Issue ID (from external tracker)")
-    title: str = Field(..., description="Issue title")
-    priority: str | None = Field(default=None, description="Issue priority")
-    labels: list[str] = Field(default_factory=list, description="Issue labels")
-
-
-class IssueUpdatedPayload(BaseModel):
-    """Payload for ISSUE_UPDATED events."""
-
-    issue_id: str = Field(..., description="Issue ID (from external tracker)")
-    changes: dict = Field(..., description="Dictionary of field changes")
-
-
-class IssueAssignedPayload(BaseModel):
-    """Payload for ISSUE_ASSIGNED events."""
-
-    issue_id: str = Field(..., description="Issue ID (from external tracker)")
-    assignee_id: UUID | None = Field(
-        default=None, description="Agent or user assigned to"
-    )
-    assignee_name: str | None = Field(default=None, description="Assignee name")
-
-
-class IssueClosedPayload(BaseModel):
-    """Payload for ISSUE_CLOSED events."""
-
-    issue_id: str = Field(..., description="Issue ID (from external tracker)")
-    resolution: str = Field(..., description="Resolution status")
-
-
-class SprintStartedPayload(BaseModel):
-    """Payload for SPRINT_STARTED events."""
-
-    sprint_id: UUID = Field(..., description="Sprint ID")
-    sprint_name: str = Field(..., description="Sprint name")
-    goal: str | None = Field(default=None, description="Sprint goal")
-    issue_count: int = Field(default=0, description="Number of issues in sprint")
-
-
-class SprintCompletedPayload(BaseModel):
-    """Payload for SPRINT_COMPLETED events."""
-
-    sprint_id: UUID = Field(..., description="Sprint ID")
-    sprint_name: str = Field(..., description="Sprint name")
-    completed_issues: int = Field(default=0, description="Number of completed issues")
-    incomplete_issues: int = Field(default=0, description="Number of incomplete issues")
-
-
-class ApprovalRequestedPayload(BaseModel):
-    """Payload for APPROVAL_REQUESTED events."""
-
-    approval_id: UUID = Field(..., description="Approval request ID")
-    approval_type: str = Field(..., description="Type of approval needed")
-    description: str = Field(..., description="Description of what needs approval")
-    requested_by: UUID | None = Field(
-        default=None, description="Agent/user requesting approval"
-    )
-    timeout_minutes: int | None = Field(
-        default=None, description="Minutes before auto-escalation"
-    )
-
-
-class ApprovalGrantedPayload(BaseModel):
-    """Payload for APPROVAL_GRANTED events."""
-
-    approval_id: UUID = Field(..., description="Approval request ID")
-    approved_by: UUID = Field(..., description="User who granted approval")
-    comments: str | None = Field(default=None, description="Approval comments")
-
-
-class ApprovalDeniedPayload(BaseModel):
-    """Payload for APPROVAL_DENIED events."""
-
-    approval_id: UUID = Field(..., description="Approval request ID")
-    denied_by: UUID = Field(..., description="User who denied approval")
-    reason: str = Field(..., description="Reason for denial")
-
-
-class WorkflowStartedPayload(BaseModel):
-    """Payload for WORKFLOW_STARTED events."""
-
-    workflow_id: UUID = Field(..., description="Workflow execution ID")
-    workflow_type: str = Field(..., description="Type of workflow")
-    total_steps: int = Field(default=0, description="Total number of steps")
-
-
-class WorkflowStepCompletedPayload(BaseModel):
-    """Payload for WORKFLOW_STEP_COMPLETED events."""
-
-    workflow_id: UUID = Field(..., description="Workflow execution ID")
-    step_name: str = Field(..., description="Name of completed step")
-    step_number: int = Field(..., description="Step number (1-indexed)")
-    total_steps: int = Field(..., description="Total number of steps")
-    result: dict = Field(default_factory=dict, description="Step result data")
-
-
-class WorkflowCompletedPayload(BaseModel):
-    """Payload for WORKFLOW_COMPLETED events."""
-
-    workflow_id: UUID = Field(..., description="Workflow execution ID")
-    duration_seconds: float = Field(..., description="Total execution duration")
-    result: dict = Field(default_factory=dict, description="Workflow result data")
-
-
-class WorkflowFailedPayload(BaseModel):
-    """Payload for WORKFLOW_FAILED events."""
-
-    workflow_id: UUID = Field(..., description="Workflow execution ID")
-    error_message: str = Field(..., description="Error message")
-    failed_step: str | None = Field(default=None, description="Step that failed")
-    recoverable: bool = Field(default=False, description="Whether error is recoverable")

backend/app/schemas/oauth.py

@@ -60,8 +60,8 @@ class OAuthAccountCreate(OAuthAccountBase):
 
     user_id: UUID
     provider_user_id: str = Field(..., max_length=255)
-    access_token_encrypted: str | None = None
-    refresh_token_encrypted: str | None = None
+    access_token: str | None = None
+    refresh_token: str | None = None
     token_expires_at: datetime | None = None
 
 

backend/app/schemas/organizations.py

@@ -48,7 +48,7 @@ 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)
+    slug: str = Field(..., min_length=1, max_length=255)  # pyright: ignore[reportIncompatibleVariableOverride]
 
 
 class OrganizationUpdate(BaseModel):

backend/app/schemas/syndarix/__init__.py

@@ -1,113 +0,0 @@
-# app/schemas/syndarix/__init__.py
-"""
-Syndarix domain schemas.
-
-This package contains Pydantic schemas for validating and serializing
-Syndarix domain entities.
-"""
-
-from .agent_instance import (
-    AgentInstanceCreate,
-    AgentInstanceInDB,
-    AgentInstanceListResponse,
-    AgentInstanceMetrics,
-    AgentInstanceResponse,
-    AgentInstanceTerminate,
-    AgentInstanceUpdate,
-)
-from .agent_type import (
-    AgentTypeCreate,
-    AgentTypeInDB,
-    AgentTypeListResponse,
-    AgentTypeResponse,
-    AgentTypeUpdate,
-)
-from .enums import (
-    AgentStatus,
-    AutonomyLevel,
-    IssuePriority,
-    IssueStatus,
-    ProjectStatus,
-    SprintStatus,
-    SyncStatus,
-)
-from .issue import (
-    IssueAssign,
-    IssueClose,
-    IssueCreate,
-    IssueInDB,
-    IssueListResponse,
-    IssueResponse,
-    IssueStats,
-    IssueSyncUpdate,
-    IssueUpdate,
-)
-from .project import (
-    ProjectCreate,
-    ProjectInDB,
-    ProjectListResponse,
-    ProjectResponse,
-    ProjectUpdate,
-)
-from .sprint import (
-    SprintBurndown,
-    SprintComplete,
-    SprintCreate,
-    SprintInDB,
-    SprintListResponse,
-    SprintResponse,
-    SprintStart,
-    SprintUpdate,
-    SprintVelocity,
-)
-
-__all__ = [
-    # AgentInstance schemas
-    "AgentInstanceCreate",
-    "AgentInstanceInDB",
-    "AgentInstanceListResponse",
-    "AgentInstanceMetrics",
-    "AgentInstanceResponse",
-    "AgentInstanceTerminate",
-    "AgentInstanceUpdate",
-    # Enums
-    "AgentStatus",
-    # AgentType schemas
-    "AgentTypeCreate",
-    "AgentTypeInDB",
-    "AgentTypeListResponse",
-    "AgentTypeResponse",
-    "AgentTypeUpdate",
-    "AutonomyLevel",
-    # Issue schemas
-    "IssueAssign",
-    "IssueClose",
-    "IssueCreate",
-    "IssueInDB",
-    "IssueListResponse",
-    "IssuePriority",
-    "IssueResponse",
-    "IssueStats",
-    "IssueStatus",
-    "IssueSyncUpdate",
-    "IssueUpdate",
-    # Project schemas
-    "ProjectCreate",
-    "ProjectInDB",
-    "ProjectListResponse",
-    "ProjectResponse",
-    "ProjectStatus",
-    "ProjectUpdate",
-    # Sprint schemas
-    "SprintBurndown",
-    "SprintComplete",
-    "SprintCreate",
-    "SprintInDB",
-    "SprintListResponse",
-    "SprintResponse",
-    "SprintStart",
-    "SprintStatus",
-    "SprintUpdate",
-    "SprintVelocity",
-    "SyncStatus",
-]

backend/app/schemas/syndarix/agent_instance.py

@@ -1,124 +0,0 @@
-# app/schemas/syndarix/agent_instance.py
-"""
-Pydantic schemas for AgentInstance entity.
-"""
-
-from datetime import datetime
-from decimal import Decimal
-from typing import Any
-from uuid import UUID
-
-from pydantic import BaseModel, ConfigDict, Field
-
-from .enums import AgentStatus
-
-
-class AgentInstanceBase(BaseModel):
-    """Base agent instance schema with common fields."""
-
-    agent_type_id: UUID
-    project_id: UUID
-    status: AgentStatus = AgentStatus.IDLE
-    current_task: str | None = None
-    short_term_memory: dict[str, Any] = Field(default_factory=dict)
-    long_term_memory_ref: str | None = Field(None, max_length=500)
-    session_id: str | None = Field(None, max_length=255)
-
-
-class AgentInstanceCreate(BaseModel):
-    """Schema for creating a new agent instance."""
-
-    agent_type_id: UUID
-    project_id: UUID
-    name: str = Field(..., min_length=1, max_length=100)
-    status: AgentStatus = AgentStatus.IDLE
-    current_task: str | None = None
-    short_term_memory: dict[str, Any] = Field(default_factory=dict)
-    long_term_memory_ref: str | None = Field(None, max_length=500)
-    session_id: str | None = Field(None, max_length=255)
-
-
-class AgentInstanceUpdate(BaseModel):
-    """Schema for updating an agent instance."""
-
-    status: AgentStatus | None = None
-    current_task: str | None = None
-    short_term_memory: dict[str, Any] | None = None
-    long_term_memory_ref: str | None = None
-    session_id: str | None = None
-    last_activity_at: datetime | None = None
-    tasks_completed: int | None = Field(None, ge=0)
-    tokens_used: int | None = Field(None, ge=0)
-    cost_incurred: Decimal | None = Field(None, ge=0)
-
-
-class AgentInstanceTerminate(BaseModel):
-    """Schema for terminating an agent instance."""
-
-    reason: str | None = None
-
-
-class AgentInstanceInDB(AgentInstanceBase):
-    """Schema for agent instance in database."""
-
-    id: UUID
-    last_activity_at: datetime | None = None
-    terminated_at: datetime | None = None
-    tasks_completed: int = 0
-    tokens_used: int = 0
-    cost_incurred: Decimal = Decimal("0.0000")
-    created_at: datetime
-    updated_at: datetime
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class AgentInstanceResponse(BaseModel):
-    """Schema for agent instance API responses."""
-
-    id: UUID
-    agent_type_id: UUID
-    project_id: UUID
-    name: str
-    status: AgentStatus
-    current_task: str | None = None
-    short_term_memory: dict[str, Any] = Field(default_factory=dict)
-    long_term_memory_ref: str | None = None
-    session_id: str | None = None
-    last_activity_at: datetime | None = None
-    terminated_at: datetime | None = None
-    tasks_completed: int = 0
-    tokens_used: int = 0
-    cost_incurred: Decimal = Decimal("0.0000")
-    created_at: datetime
-    updated_at: datetime
-
-    # Expanded fields from relationships
-    agent_type_name: str | None = None
-    agent_type_slug: str | None = None
-    project_name: str | None = None
-    project_slug: str | None = None
-    assigned_issues_count: int | None = 0
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class AgentInstanceListResponse(BaseModel):
-    """Schema for paginated agent instance list responses."""
-
-    agent_instances: list[AgentInstanceResponse]
-    total: int
-    page: int
-    page_size: int
-    pages: int
-
-
-class AgentInstanceMetrics(BaseModel):
-    """Schema for agent instance metrics summary."""
-
-    total_instances: int
-    active_instances: int
-    idle_instances: int
-    total_tasks_completed: int
-    total_tokens_used: int
-    total_cost_incurred: Decimal

backend/app/schemas/syndarix/agent_type.py

@@ -1,197 +0,0 @@
-# app/schemas/syndarix/agent_type.py
-"""
-Pydantic schemas for AgentType entity.
-"""
-
-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.syndarix.enums import AgentTypeCategory
-
-
-class AgentTypeBase(BaseModel):
-    """Base agent type 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
-    expertise: list[str] = Field(default_factory=list)
-    personality_prompt: str = Field(..., min_length=1)
-    primary_model: str = Field(..., min_length=1, max_length=100)
-    fallback_models: list[str] = Field(default_factory=list)
-    model_params: dict[str, Any] = Field(default_factory=dict)
-    mcp_servers: list[str] = Field(default_factory=list)
-    tool_permissions: dict[str, Any] = Field(default_factory=dict)
-    is_active: bool = True
-
-    # Category and display fields
-    category: AgentTypeCategory | None = None
-    icon: str | None = Field(None, max_length=50)
-    color: str | None = Field(None, pattern=r"^#[0-9A-Fa-f]{6}$")
-    sort_order: int = Field(default=0, ge=0, le=1000)
-    typical_tasks: list[str] = Field(default_factory=list)
-    collaboration_hints: list[str] = Field(default_factory=list)
-
-    @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 agent type name."""
-        if not v or v.strip() == "":
-            raise ValueError("Agent type name cannot be empty")
-        return v.strip()
-
-    @field_validator("expertise")
-    @classmethod
-    def validate_expertise(cls, v: list[str]) -> list[str]:
-        """Validate and normalize expertise list."""
-        return [e.strip().lower() for e in v if e.strip()]
-
-    @field_validator("mcp_servers")
-    @classmethod
-    def validate_mcp_servers(cls, v: list[str]) -> list[str]:
-        """Validate MCP server list."""
-        return [s.strip() for s in v if s.strip()]
-
-    @field_validator("typical_tasks")
-    @classmethod
-    def validate_typical_tasks(cls, v: list[str]) -> list[str]:
-        """Validate and normalize typical tasks list."""
-        return [t.strip() for t in v if t.strip()]
-
-    @field_validator("collaboration_hints")
-    @classmethod
-    def validate_collaboration_hints(cls, v: list[str]) -> list[str]:
-        """Validate and normalize collaboration hints (agent slugs)."""
-        return [h.strip().lower() for h in v if h.strip()]
-
-
-class AgentTypeCreate(AgentTypeBase):
-    """Schema for creating a new agent type."""
-
-    name: str = Field(..., min_length=1, max_length=255)
-    slug: str = Field(..., min_length=1, max_length=255)
-    personality_prompt: str = Field(..., min_length=1)
-    primary_model: str = Field(..., min_length=1, max_length=100)
-
-
-class AgentTypeUpdate(BaseModel):
-    """Schema for updating an agent type."""
-
-    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
-    expertise: list[str] | None = None
-    personality_prompt: str | None = None
-    primary_model: str | None = Field(None, min_length=1, max_length=100)
-    fallback_models: list[str] | None = None
-    model_params: dict[str, Any] | None = None
-    mcp_servers: list[str] | None = None
-    tool_permissions: dict[str, Any] | None = None
-    is_active: bool | None = None
-
-    # Category and display fields (all optional for updates)
-    category: AgentTypeCategory | None = None
-    icon: str | None = Field(None, max_length=50)
-    color: str | None = Field(None, pattern=r"^#[0-9A-Fa-f]{6}$")
-    sort_order: int | None = Field(None, ge=0, le=1000)
-    typical_tasks: list[str] | None = None
-    collaboration_hints: list[str] | 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 agent type name."""
-        if v is not None and (not v or v.strip() == ""):
-            raise ValueError("Agent type name cannot be empty")
-        return v.strip() if v else v
-
-    @field_validator("expertise")
-    @classmethod
-    def validate_expertise(cls, v: list[str] | None) -> list[str] | None:
-        """Validate and normalize expertise list."""
-        if v is None:
-            return v
-        return [e.strip().lower() for e in v if e.strip()]
-
-    @field_validator("typical_tasks")
-    @classmethod
-    def validate_typical_tasks(cls, v: list[str] | None) -> list[str] | None:
-        """Validate and normalize typical tasks list."""
-        if v is None:
-            return v
-        return [t.strip() for t in v if t.strip()]
-
-    @field_validator("collaboration_hints")
-    @classmethod
-    def validate_collaboration_hints(cls, v: list[str] | None) -> list[str] | None:
-        """Validate and normalize collaboration hints (agent slugs)."""
-        if v is None:
-            return v
-        return [h.strip().lower() for h in v if h.strip()]
-
-
-class AgentTypeInDB(AgentTypeBase):
-    """Schema for agent type in database."""
-
-    id: UUID
-    created_at: datetime
-    updated_at: datetime
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class AgentTypeResponse(AgentTypeBase):
-    """Schema for agent type API responses."""
-
-    id: UUID
-    created_at: datetime
-    updated_at: datetime
-    instance_count: int | None = 0
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class AgentTypeListResponse(BaseModel):
-    """Schema for paginated agent type list responses."""
-
-    agent_types: list[AgentTypeResponse]
-    total: int
-    page: int
-    page_size: int
-    pages: int

backend/app/schemas/syndarix/enums.py

@@ -1,26 +0,0 @@
-# app/schemas/syndarix/enums.py
-"""
-Re-export enums from models for use in schemas.
-
-This allows schemas to import enums without depending on SQLAlchemy models directly.
-"""
-
-from app.models.syndarix.enums import (
-    AgentStatus,
-    AutonomyLevel,
-    IssuePriority,
-    IssueStatus,
-    ProjectStatus,
-    SprintStatus,
-    SyncStatus,
-)
-
-__all__ = [
-    "AgentStatus",
-    "AutonomyLevel",
-    "IssuePriority",
-    "IssueStatus",
-    "ProjectStatus",
-    "SprintStatus",
-    "SyncStatus",
-]

backend/app/schemas/syndarix/issue.py

@@ -1,191 +0,0 @@
-# app/schemas/syndarix/issue.py
-"""
-Pydantic schemas for Issue entity.
-"""
-
-from datetime import datetime
-from typing import Literal
-from uuid import UUID
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-
-from .enums import IssuePriority, IssueStatus, SyncStatus
-
-
-class IssueBase(BaseModel):
-    """Base issue schema with common fields."""
-
-    title: str = Field(..., min_length=1, max_length=500)
-    body: str = ""
-    status: IssueStatus = IssueStatus.OPEN
-    priority: IssuePriority = IssuePriority.MEDIUM
-    labels: list[str] = Field(default_factory=list)
-    story_points: int | None = Field(None, ge=0, le=100)
-
-    @field_validator("title")
-    @classmethod
-    def validate_title(cls, v: str) -> str:
-        """Validate issue title."""
-        if not v or v.strip() == "":
-            raise ValueError("Issue title cannot be empty")
-        return v.strip()
-
-    @field_validator("labels")
-    @classmethod
-    def validate_labels(cls, v: list[str]) -> list[str]:
-        """Validate and normalize labels."""
-        return [label.strip().lower() for label in v if label.strip()]
-
-
-class IssueCreate(IssueBase):
-    """Schema for creating a new issue."""
-
-    project_id: UUID
-    assigned_agent_id: UUID | None = None
-    human_assignee: str | None = Field(None, max_length=255)
-    sprint_id: UUID | None = None
-
-    # External tracker fields (optional, for importing from external systems)
-    external_tracker_type: Literal["gitea", "github", "gitlab"] | None = None
-    external_issue_id: str | None = Field(None, max_length=255)
-    remote_url: str | None = Field(None, max_length=1000)
-    external_issue_number: int | None = None
-
-
-class IssueUpdate(BaseModel):
-    """Schema for updating an issue."""
-
-    title: str | None = Field(None, min_length=1, max_length=500)
-    body: str | None = None
-    status: IssueStatus | None = None
-    priority: IssuePriority | None = None
-    labels: list[str] | None = None
-    assigned_agent_id: UUID | None = None
-    human_assignee: str | None = Field(None, max_length=255)
-    sprint_id: UUID | None = None
-    story_points: int | None = Field(None, ge=0, le=100)
-    sync_status: SyncStatus | None = None
-
-    @field_validator("title")
-    @classmethod
-    def validate_title(cls, v: str | None) -> str | None:
-        """Validate issue title."""
-        if v is not None and (not v or v.strip() == ""):
-            raise ValueError("Issue title cannot be empty")
-        return v.strip() if v else v
-
-    @field_validator("labels")
-    @classmethod
-    def validate_labels(cls, v: list[str] | None) -> list[str] | None:
-        """Validate and normalize labels."""
-        if v is None:
-            return v
-        return [label.strip().lower() for label in v if label.strip()]
-
-
-class IssueClose(BaseModel):
-    """Schema for closing an issue."""
-
-    resolution: str | None = None  # Optional resolution note
-
-
-class IssueAssign(BaseModel):
-    """Schema for assigning an issue."""
-
-    assigned_agent_id: UUID | None = None
-    human_assignee: str | None = Field(None, max_length=255)
-
-    @model_validator(mode="after")
-    def validate_assignment(self) -> "IssueAssign":
-        """Ensure only one type of assignee is set."""
-        if self.assigned_agent_id and self.human_assignee:
-            raise ValueError("Cannot assign to both an agent and a human. Choose one.")
-        return self
-
-
-class IssueSyncUpdate(BaseModel):
-    """Schema for updating sync-related fields."""
-
-    sync_status: SyncStatus
-    last_synced_at: datetime | None = None
-    external_updated_at: datetime | None = None
-
-
-class IssueInDB(IssueBase):
-    """Schema for issue in database."""
-
-    id: UUID
-    project_id: UUID
-    assigned_agent_id: UUID | None = None
-    human_assignee: str | None = None
-    sprint_id: UUID | None = None
-    external_tracker_type: str | None = None
-    external_issue_id: str | None = None
-    remote_url: str | None = None
-    external_issue_number: int | None = None
-    sync_status: SyncStatus = SyncStatus.SYNCED
-    last_synced_at: datetime | None = None
-    external_updated_at: datetime | None = None
-    closed_at: datetime | None = None
-    created_at: datetime
-    updated_at: datetime
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class IssueResponse(BaseModel):
-    """Schema for issue API responses."""
-
-    id: UUID
-    project_id: UUID
-    title: str
-    body: str
-    status: IssueStatus
-    priority: IssuePriority
-    labels: list[str] = Field(default_factory=list)
-    assigned_agent_id: UUID | None = None
-    human_assignee: str | None = None
-    sprint_id: UUID | None = None
-    story_points: int | None = None
-    external_tracker_type: str | None = None
-    external_issue_id: str | None = None
-    remote_url: str | None = None
-    external_issue_number: int | None = None
-    sync_status: SyncStatus = SyncStatus.SYNCED
-    last_synced_at: datetime | None = None
-    external_updated_at: datetime | None = None
-    closed_at: datetime | None = None
-    created_at: datetime
-    updated_at: datetime
-
-    # Expanded fields from relationships
-    project_name: str | None = None
-    project_slug: str | None = None
-    sprint_name: str | None = None
-    assigned_agent_type_name: str | None = None
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class IssueListResponse(BaseModel):
-    """Schema for paginated issue list responses."""
-
-    issues: list[IssueResponse]
-    total: int
-    page: int
-    page_size: int
-    pages: int
-
-
-class IssueStats(BaseModel):
-    """Schema for issue statistics."""
-
-    total: int
-    open: int
-    in_progress: int
-    in_review: int
-    blocked: int
-    closed: int
-    by_priority: dict[str, int]
-    total_story_points: int | None = None
-    completed_story_points: int | None = None

backend/app/schemas/syndarix/project.py

@@ -1,131 +0,0 @@
-# app/schemas/syndarix/project.py
-"""
-Pydantic schemas for Project entity.
-"""
-
-import re
-from datetime import datetime
-from typing import Any
-from uuid import UUID
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator
-
-from .enums import AutonomyLevel, ProjectStatus
-
-
-class ProjectBase(BaseModel):
-    """Base project 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
-    autonomy_level: AutonomyLevel = AutonomyLevel.MILESTONE
-    status: ProjectStatus = ProjectStatus.ACTIVE
-    settings: dict[str, Any] = Field(default_factory=dict)
-
-    @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 project name."""
-        if not v or v.strip() == "":
-            raise ValueError("Project name cannot be empty")
-        return v.strip()
-
-
-class ProjectCreate(ProjectBase):
-    """Schema for creating a new project."""
-
-    name: str = Field(..., min_length=1, max_length=255)
-    slug: str = Field(..., min_length=1, max_length=255)
-    owner_id: UUID | None = None
-
-
-class ProjectUpdate(BaseModel):
-    """Schema for updating a project.
-
-    Note: owner_id is intentionally excluded to prevent IDOR vulnerabilities.
-    Project ownership transfer should be done via a dedicated endpoint with
-    proper authorization checks.
-    """
-
-    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
-    autonomy_level: AutonomyLevel | None = None
-    status: ProjectStatus | 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 project name."""
-        if v is not None and (not v or v.strip() == ""):
-            raise ValueError("Project name cannot be empty")
-        return v.strip() if v else v
-
-
-class ProjectInDB(ProjectBase):
-    """Schema for project in database."""
-
-    id: UUID
-    owner_id: UUID | None = None
-    created_at: datetime
-    updated_at: datetime
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class ProjectResponse(ProjectBase):
-    """Schema for project API responses."""
-
-    id: UUID
-    owner_id: UUID | None = None
-    created_at: datetime
-    updated_at: datetime
-    agent_count: int | None = 0
-    issue_count: int | None = 0
-    active_sprint_name: str | None = None
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class ProjectListResponse(BaseModel):
-    """Schema for paginated project list responses."""
-
-    projects: list[ProjectResponse]
-    total: int
-    page: int
-    page_size: int
-    pages: int

backend/app/schemas/syndarix/sprint.py

@@ -1,135 +0,0 @@
-# app/schemas/syndarix/sprint.py
-"""
-Pydantic schemas for Sprint entity.
-"""
-
-from datetime import date, datetime
-from uuid import UUID
-
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
-
-from .enums import SprintStatus
-
-
-class SprintBase(BaseModel):
-    """Base sprint schema with common fields."""
-
-    name: str = Field(..., min_length=1, max_length=255)
-    number: int = Field(..., ge=1)
-    goal: str | None = None
-    start_date: date
-    end_date: date
-    status: SprintStatus = SprintStatus.PLANNED
-    planned_points: int | None = Field(None, ge=0)
-    velocity: int | None = Field(None, ge=0)
-
-    @field_validator("name")
-    @classmethod
-    def validate_name(cls, v: str) -> str:
-        """Validate sprint name."""
-        if not v or v.strip() == "":
-            raise ValueError("Sprint name cannot be empty")
-        return v.strip()
-
-    @model_validator(mode="after")
-    def validate_dates(self) -> "SprintBase":
-        """Validate that end_date is after start_date."""
-        if self.end_date < self.start_date:
-            raise ValueError("End date must be after or equal to start date")
-        return self
-
-
-class SprintCreate(SprintBase):
-    """Schema for creating a new sprint."""
-
-    project_id: UUID
-
-
-class SprintUpdate(BaseModel):
-    """Schema for updating a sprint."""
-
-    name: str | None = Field(None, min_length=1, max_length=255)
-    goal: str | None = None
-    start_date: date | None = None
-    end_date: date | None = None
-    status: SprintStatus | None = None
-    planned_points: int | None = Field(None, ge=0)
-    velocity: int | None = Field(None, ge=0)
-
-    @field_validator("name")
-    @classmethod
-    def validate_name(cls, v: str | None) -> str | None:
-        """Validate sprint name."""
-        if v is not None and (not v or v.strip() == ""):
-            raise ValueError("Sprint name cannot be empty")
-        return v.strip() if v else v
-
-
-class SprintStart(BaseModel):
-    """Schema for starting a sprint."""
-
-    start_date: date | None = None  # Optionally override start date
-
-
-class SprintComplete(BaseModel):
-    """Schema for completing a sprint."""
-
-    velocity: int | None = Field(None, ge=0)
-    notes: str | None = None
-
-
-class SprintInDB(SprintBase):
-    """Schema for sprint in database."""
-
-    id: UUID
-    project_id: UUID
-    created_at: datetime
-    updated_at: datetime
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class SprintResponse(SprintBase):
-    """Schema for sprint API responses."""
-
-    id: UUID
-    project_id: UUID
-    created_at: datetime
-    updated_at: datetime
-
-    # Expanded fields from relationships
-    project_name: str | None = None
-    project_slug: str | None = None
-    issue_count: int | None = 0
-    open_issues: int | None = 0
-    completed_issues: int | None = 0
-
-    model_config = ConfigDict(from_attributes=True)
-
-
-class SprintListResponse(BaseModel):
-    """Schema for paginated sprint list responses."""
-
-    sprints: list[SprintResponse]
-    total: int
-    page: int
-    page_size: int
-    pages: int
-
-
-class SprintVelocity(BaseModel):
-    """Schema for sprint velocity metrics."""
-
-    sprint_number: int
-    sprint_name: str
-    planned_points: int | None
-    velocity: int | None  # Sum of completed story points
-    velocity_ratio: float | None  # velocity/planned ratio
-
-
-class SprintBurndown(BaseModel):
-    """Schema for sprint burndown data point."""
-
-    date: date
-    remaining_points: int
-    ideal_remaining: float