feat: deploy via SSH with port 8080, idempotent migrations

- Introduced new API keys for Anthropic and Google in .env.example and settings.py
- Updated llm.py to retrieve API keys directly from settings
- Modified deploy.yaml to streamline code checkout and improve deployment process

.env.example

@@ -10,18 +10,34 @@ JWT_ALGORITHM=HS256
 JWT_ACCESS_TOKEN_EXPIRE_MINUTES=30
 JWT_REFRESH_TOKEN_EXPIRE_DAYS=30
 
-# ── OpenAI ────────────────────────────────────────────────────────────────────
+# ── LLM ───────────────────────────────────────────────────────────────────────
-OPENAI_API_KEY=sk-...
+# LiteLLM model identifiers — change to swap providers without code changes.
+# Examples: gpt-4o, anthropic/claude-sonnet-4-20250514, gemini/gemini-pro, ollama/llama3
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+GOOGLE_API_KEY=
+LLM_MODEL=gpt-4o
+LLM_ROUTER_MODEL=gpt-4o-mini
 
-# ── Stripe ────────────────────────────────────────────────────────────────────
+# ── Stripe (leave empty to stub billing) ──────────────────────────────────────
-STRIPE_SECRET_KEY=sk_test_...
+STRIPE_SECRET_KEY=
-STRIPE_WEBHOOK_SECRET=whsec_...
+STRIPE_WEBHOOK_SECRET=
 
 # ── AWS / S3 ──────────────────────────────────────────────────────────────────
-S3_BUCKET=adiuva-backups
+S3_BUCKET=adiuva
 S3_REGION=us-east-1
-AWS_ACCESS_KEY_ID=AKIA...
+S3_ENDPOINT_URL=
-AWS_SECRET_ACCESS_KEY=...
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+# For MinIO (homelab): S3_ENDPOINT_URL=http://minio:9000
+
+# ── Vector Store ──────────────────────────────────────────────────────────────
+# Pinecone is used when PINECONE_API_KEY is set; otherwise falls back to Qdrant.
+PINECONE_API_KEY=
+PINECONE_INDEX=adiuva
+QDRANT_URL=
+QDRANT_API_KEY=
+# For local Qdrant (homelab): QDRANT_URL=http://qdrant:6333
 
 # ── CORS ──────────────────────────────────────────────────────────────────────
 # Comma-separated list parsed by Settings (override default if needed)

.gitea/workflows/deploy.yaml

@@ -1,21 +1,93 @@
-name: Deploy to Proxmox Docker
+name: Test & Deploy API
-run-name: Deploying ${{ gitea.sha }}
+run-name: ${{ gitea.ref_name }} → Docker LXC
+
 on:
   push:
-    branches:
+    tags:
-      - main # O il nome del tuo branch principale
+      - 'v*'
 
 jobs:
-  Deploy:
+  # ── 1. Run tests in an isolated Python container ──────────────────
-    runs-on: ubuntu-latest # Questo dipende dalle label che hai dato al tuo act_runner
+  test:
+    runs-on: ubuntu-latest
+    container:
+      image: python:3.12-slim
+
     steps:
-      - name: Deploying via SSH
+      - name: Install git
+        run: apt-get update && apt-get install -y --no-install-recommends git
+
+      - name: Checkout Code
+        run: |
+          git clone --depth 1 --branch "${GITHUB_REF_NAME}" \
+            "http://10.0.0.119:3000/${GITHUB_REPOSITORY}.git" . || \
+          git clone --depth 1 "http://10.0.0.119:3000/${GITHUB_REPOSITORY}.git" . && \
+          git checkout "${GITHUB_SHA}"
+
+      - name: Install Dependencies
+        run: pip install --no-cache-dir -r requirements.txt
+
+      - name: Run Linter
+        run: ruff check app/ tests/
+
+      - name: Run Tests
+        run: pytest tests/ -v --tb=short
+
+  # ── 2. Deploy to Docker LXC via SSH ─────────────────────────────────
+  deploy:
+    needs: test
+    runs-on: ubuntu-latest
+    if: gitea.event_name == 'push'
+
+    steps:
+      - name: Deploy via SSH
         uses: appleboy/ssh-action@v1.0.0
         with:
           host: ${{ secrets.SSH_HOST }}
           username: ${{ secrets.SSH_USER }}
           key: ${{ secrets.SSH_KEY }}
           script: |
-            cd /opt/adiuva-api
+            set -e
-            git pull origin main
+            DEPLOY_DIR="/opt/adiuva-api"
+            REPO_URL="http://10.0.0.119:3000/${{ gitea.repository }}.git"
+            TAG="${{ gitea.ref_name }}"
+
+            # ── Pull latest code ──
+            cd /tmp && rm -rf adiuva-api-deploy
+            git clone --depth 1 --branch "${TAG}" "${REPO_URL}" adiuva-api-deploy
+
+            # ── Sync source (preserve .env) ──
+            cp -rf /tmp/adiuva-api-deploy/app/ \
+                   /tmp/adiuva-api-deploy/alembic/ \
+                   /tmp/adiuva-api-deploy/alembic.ini \
+                   /tmp/adiuva-api-deploy/Dockerfile \
+                   /tmp/adiuva-api-deploy/docker-compose.yml \
+                   /tmp/adiuva-api-deploy/requirements.txt \
+                   "$DEPLOY_DIR/"
+            rm -rf /tmp/adiuva-api-deploy
+
+            # ── Verify .env ──
+            if [ ! -f "$DEPLOY_DIR/.env" ]; then
+              echo "❌ $DEPLOY_DIR/.env not found. Create it before deploying."
+              exit 1
+            fi
+
+            # ── Build & restart ──
+            cd "$DEPLOY_DIR"
+            docker compose down --remove-orphans || true
             docker compose up -d --build
+
+            # ── Migrations ──
+            docker compose exec -T app alembic upgrade head
+
+            # ── Health check ──
+            echo "Waiting for app..."
+            sleep 5
+            HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/api/v1/health)
+            if [ "$HTTP_CODE" -eq 200 ]; then
+              echo "✅ API is healthy (HTTP ${HTTP_CODE})"
+            else
+              echo "❌ Health check failed (HTTP ${HTTP_CODE})"
+              docker compose logs app --tail=50
+              exit 1
+            fi

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install ruff>=0.8.0
+
+      - name: Ruff check
+        run: ruff check .
+
+      - name: Ruff format check
+        run: ruff format --check .
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    needs: lint
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Cache pip
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
+          restore-keys: ${{ runner.os }}-pip-
+
+      - name: Install dependencies
+        run: pip install -r requirements.txt
+
+      - name: Run tests
+        run: pytest -v --tb=short
+
+  docker:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build image
+        run: docker build -t adiuva-api:ci .
+
+      - name: Verify gunicorn installed
+        run: docker run --rm adiuva-api:ci gunicorn --version

BACKEND_PLAN.md

@@ -439,7 +439,7 @@ adiuva-api/
 - **Outcome:** Stripe integration with tier-based feature gating matching Free/Pro(15€)/Power(29€)/Team(49€/seat).
 
 ### Step 12 — Database (auth/billing/marketplace only)
-- [ ] PostgreSQL schema via Alembic:
+- [x] PostgreSQL schema via Alembic:
   - `users`: `id UUID PK`, `email UNIQUE`, `password_hash`, `tier` (default 'free'), `stripe_customer_id`, `created_at`, `updated_at`
   - `refresh_tokens`: `id UUID PK`, `user_id FK`, `token_hash`, `expires_at`, `created_at`
   - `subscriptions`: `id UUID PK`, `user_id FK`, `stripe_subscription_id`, `tier`, `status`, `current_period_end`, `created_at`
@@ -449,20 +449,20 @@ adiuva-api/
   - `plugin_installations`: `id UUID PK`, `plugin_id FK`, `user_id FK`, `installed_at`
   - `plugin_reviews`: `id UUID PK`, `plugin_id FK`, `reviewer_id FK`, `decision`, `notes`, `reviewed_at`
   - `revenue_events`: `id UUID PK`, `plugin_id FK`, `user_id FK`, `amount_cents`, `developer_share_cents`, `stripe_transfer_id`, `created_at`
-- [ ] Initial Alembic migration
+- [x] Initial Alembic migration
-- [ ] SQLAlchemy models in `app/models.py`
+- [x] SQLAlchemy models in `app/models.py`
 - **Outcome:** Auth, billing, storage metadata, and marketplace persistence. Zero user data in plaintext.
 
-### Step 13 — Testing & deployment
+### Step 13 — Testing & deployment ✅
-- [ ] `tests/conftest.py`: TestClient fixture, mock LLM fixture (`AsyncMock` returning canned responses), mock agent fixture, test DB (SQLite in-memory for speed), mock S3 (moto), mock Pinecone
+- [x] `tests/conftest.py`: TestClient fixture, mock LLM fixture (`AsyncMock` returning canned responses), mock agent fixture, test DB (SQLite in-memory for speed), mock S3 (moto), mock Pinecone
-- [ ] `tests/test_orchestrator.py`: classify_intent routing, single agent, pipeline, plan mode
+- [x] `tests/test_orchestrator.py`: classify_intent routing, single agent, pipeline, plan mode
-- [ ] `tests/test_agents.py`: each agent with mocked tools
+- [x] `tests/test_agents.py`: each agent with mocked tools
-- [ ] `tests/test_auth.py`: register → login → access protected → refresh → expired token
+- [x] `tests/test_auth.py`: register → login → access protected → refresh → expired token
-- [ ] `tests/test_backup.py`: upload → download → history → delete, tier limit enforcement
+- [x] `tests/test_backup.py`: upload → download → history → delete, tier limit enforcement
-- [ ] `tests/test_storage.py`: create record → list → download → update → delete, checksum rejection, quota enforcement
+- [x] `tests/test_storage.py`: create record → list → download → update → delete, checksum rejection, quota enforcement
-- [ ] `tests/test_plugins.py`: list plugins, install, uninstall, revenue event creation, tier gate (free user blocked)
+- [x] `tests/test_plugins.py`: list plugins, install, uninstall, revenue event creation, tier gate (free user blocked)
-- [ ] `Dockerfile` optimized for production (gunicorn + uvicorn workers)
+- [x] `Dockerfile` optimized for production (gunicorn + uvicorn workers)
-- [ ] GitHub Actions CI: lint (ruff), test (pytest), build Docker image
+- [x] GitHub Actions CI: lint (ruff), test (pytest), build Docker image
 - **Outcome:** Fully tested, deployable backend.
 
 ---

Dockerfile

@@ -21,6 +21,10 @@ COPY --from=builder /install /usr/local
 # Copy application source
 COPY app/ app/
 
+# Copy Alembic migration files
+COPY alembic/ alembic/
+COPY alembic.ini .
+
 # Ensure appuser owns the working directory
 RUN chown -R appuser:appgroup /app
 
@@ -28,4 +32,8 @@ USER appuser
 
 EXPOSE 8000
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]
+CMD ["gunicorn", "app.main:app", \
+     "-k", "uvicorn.workers.UvicornWorker", \
+     "--bind", "0.0.0.0:8000", \
+     "--workers", "4", \
+     "--timeout", "120"]

README.md

@@ -0,0 +1,793 @@
+# Adiuva Cloud API
+
+**AI-powered project management backend with E2E encrypted cloud storage, LLM orchestration, and a plugin marketplace.**
+
+Built with FastAPI · Python 3.12 · PostgreSQL · LangChain · Stripe · AWS S3
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Architecture](#architecture)
+- [Key Features](#key-features)
+- [Tech Stack](#tech-stack)
+- [Getting Started](#getting-started)
+- [Docker Deployment](#docker-deployment)
+- [Environment Variables](#environment-variables)
+- [API Reference](#api-reference)
+- [Data Model](#data-model)
+- [AI Agent System](#ai-agent-system)
+- [Orchestration & Execution Plans](#orchestration--execution-plans)
+- [Middleware](#middleware)
+- [Storage Layer](#storage-layer)
+- [Billing & Tiers](#billing--tiers)
+- [Plugin Marketplace](#plugin-marketplace)
+- [Testing](#testing)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+---
+
+## Overview
+
+Adiuva Cloud API is the FastAPI backend that powers the **Adiuva Electron desktop app**. It provides LLM-powered chat orchestration, end-to-end encrypted cloud storage, a vector search engine, an encrypted backup system, a plugin marketplace with revenue sharing, and Stripe-based subscription billing across four tiers.
+
+### Design Principles
+
+1. **Never persist user data in plaintext** — the database stores only auth, billing, storage metadata, and marketplace data. All user content is E2E encrypted by the client before reaching the server.
+2. **Never expose prompts** — system prompts stay server-side; responses are sanitized to strip any leaked prompt fragments.
+3. **Never decrypt user blobs** — the backend performs only checksum verification; no decryption keys ever reach the server.
+4. **Stateless request handling** — all context comes from the client and JWT; no server-side session state.
+5. **Tier gates enforced server-side** — the server always reads the current tier from the database, never trusting client-reported values.
+
+---
+
+## Architecture
+
+```
+┌──────────────┐      ┌────────────────────────────────────────────────────────┐
+│  Electron    │      │  FastAPI  (Uvicorn / Gunicorn)                         │
+│  Desktop App │────▶│                                                        │
+│  (Client)    │◀────│  Middleware: RateLimit → Sanitizer → CORS → Router     │
+└──────────────┘      │                                                        │
+                      │  ┌──────────────────┐  ┌────────────────────────────┐  │
+                      │  │  Auth Routes     │  │  Chat Routes               │  │
+                      │  │  Billing Routes  │  │    ↓                       │  │
+                      │  │  Storage Routes  │  │  Orchestrator (GPT-4o-mini)│  │
+                      │  │  Backup Routes   │  │    ↓ classify intent       │  │
+                      │  │  Plugin Routes   │  │  Agent Registry            │  │
+                      │  │  Vector Routes   │  │    ↓                       │  │
+                      │  │  Plans Routes    │  │  TaskAgent  | ProjectAgent │  │
+                      │  └──────────────────┘  │  NoteAgent  | CheckptAgent │  │
+                      │                        │  (GPT-4o + LangChain)      │  │
+                      │                        └────────────────────────────┘  │
+                      └────────────────────────────────────────────────────────┘
+                               │              │              │
+                      ┌────────▼───┐  ┌───────▼───────┐  ┌──▼─────────────┐
+                      │ PostgreSQL │  │  AWS S3       │  │ Pinecone /     │
+                      │ (Auth,     │  │  (E2E blobs,  │  │ Qdrant         │
+                      │  Billing,  │  │   backups)    │  │ (Vectors)      │
+                      │  Metadata) │  └───────────────┘  └────────────────┘
+                      └────────────┘
+                               │
+                      ┌────────▼───┐
+                      │  Stripe    │
+                      │  (Billing, │
+                      │   Connect) │
+                      └────────────┘
+```
+
+---
+
+## Key Features
+
+1. **LLM-powered orchestration** — GPT-4o-mini classifies user intent and routes to the appropriate domain agent.
+2. **4 specialized AI agents** — Tasks (8 tools), Projects (6 tools), Checkpoints (4 tools), Notes (5 tools), all powered by GPT-4o via LangChain.
+3. **Execution plans & playbooks** — Server-side prompt template registry; clients receive only opaque template IDs, never raw prompts.
+4. **E2E encrypted cloud storage** — The backend never decrypts user data; SHA-256 checksum verification uses constant-time comparison to prevent timing attacks.
+5. **Cloud vector store** — Pinecone or Qdrant with user-isolated namespaces and encrypted blob payloads.
+6. **Encrypted backup system** — Tiered storage limits with `If-Modified-Since` support for efficient syncing.
+7. **Plugin marketplace** — Catalog, admin review/approval workflow, security checklist, and 70/30 revenue sharing via Stripe Connect.
+8. **Stripe billing** — Four-tier subscription model (Free / Pro / Power / Team) with checkout sessions and full webhook lifecycle handling.
+9. **JWT authentication** — Access + refresh tokens with bcrypt password hashing, SHA-256 token hashing, and automatic rotation.
+10. **Prompt IP protection** — Sanitizer middleware strips system prompts, reasoning markers, tool schemas, and agent routing metadata from all chat responses.
+11. **Tier-based rate limiting** — Sliding-window per-user limiter scaling from 20 to 200 requests/min by subscription tier.
+12. **Zero-trust data model** — User content is never stored in plaintext; the database holds only authentication, billing, and metadata records.
+13. **WebSocket streaming** — Real-time chat with 30-second heartbeat keep-alive and chunked text delivery.
+14. **Alembic migrations** — Versioned schema management with seed data for the plugin marketplace.
+15. **Comprehensive test suite** — In-memory SQLite + moto S3 mocks, per-tier test fixtures, and full API coverage without external dependencies.
+
+---
+
+## Tech Stack
+
+| Package | Version | Purpose |
+|---|---|---|
+| `fastapi` | ≥ 0.115.0 | Web framework |
+| `uvicorn[standard]` | ≥ 0.34.0 | ASGI development server |
+| `gunicorn` | ≥ 22.0.0 | Production process manager |
+| `langchain` | ≥ 0.3.0 | LLM orchestration framework |
+| `langchain-openai` | ≥ 0.3.0 | OpenAI LLM provider integration |
+| `litellm` | ≥ 1.50.0 | Universal LLM gateway (100+ providers) |
+| `pydantic` | ≥ 2.10.0 | Data validation and serialization |
+| `pydantic-settings` | ≥ 2.7.0 | Environment-based configuration |
+| `python-jose[cryptography]` | ≥ 3.3.0 | JWT encoding and decoding |
+| `stripe` | ≥ 11.0.0 | Billing and payment integration |
+| `boto3` | ≥ 1.35.0 | AWS S3 client |
+| `slowapi` | ≥ 0.1.9 | Rate limiting utilities |
+| `sqlalchemy` | ≥ 2.0.0 | Async ORM and query builder |
+| `asyncpg` | ≥ 0.30.0 | PostgreSQL async driver |
+| `alembic` | ≥ 1.14.0 | Database migration management |
+| `bcrypt` | ≥ 4.2.0 | Password hashing |
+| `python-dotenv` | ≥ 1.0.0 | `.env` file loading |
+| `httpx` | ≥ 0.28.0 | Async HTTP client (used in tests) |
+| `websockets` | ≥ 14.0 | WebSocket protocol support |
+| `psycopg2-binary` | ≥ 2.9.0 | Synchronous PostgreSQL driver (Alembic) |
+| `pinecone` | ≥ 5.0.0 | Pinecone vector store client |
+| `qdrant-client` | ≥ 1.7.0 | Qdrant vector store client |
+| `pytest` | ≥ 8.0.0 | Test framework |
+| `pytest-asyncio` | ≥ 0.24.0 | Async test support |
+| `aiosqlite` | ≥ 0.20.0 | In-memory SQLite for tests |
+| `moto[s3]` | ≥ 5.0.0 | AWS S3 mock for tests |
+| `ruff` | ≥ 0.8.0 | Linter and formatter |
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.12+
+- PostgreSQL 16+
+- An OpenAI API key (for LLM features)
+- Stripe API keys (optional — billing stubs gracefully when unconfigured)
+- AWS credentials (optional — needed for S3 storage in production)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone <repo-url> && cd adiuva-api
+
+# Create a virtual environment
+python -m venv .venv && source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your DATABASE_URL, OPENAI_API_KEY, etc.
+```
+
+### Database Setup
+
+```bash
+# Start PostgreSQL (or use the Docker Compose database)
+docker compose up db -d
+
+# Run migrations
+alembic upgrade head
+```
+
+### Run the Development Server
+
+```bash
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+Interactive API docs are available at [http://localhost:8000/docs](http://localhost:8000/docs) in development mode (`ENV=dev`). The `/docs` endpoint is disabled in production.
+
+---
+
+## Docker Deployment
+
+### Quick Start
+
+```bash
+docker compose up --build
+```
+
+This starts two services:
+
+- **app** — FastAPI server on port `8000`
+- **db** — PostgreSQL 16 (Alpine) on port `5432` with a persistent volume and health checks
+
+The compose file also includes optional services for fully local deployments:
+
+- **minio** — S3-compatible object storage on ports `9000` (API) and `9001` (console)
+- **qdrant** — Vector search engine on ports `6333` (HTTP) and `6334` (gRPC)
+
+### Dockerfile Details
+
+The Dockerfile uses a multi-stage build:
+
+1. **Builder stage** — Installs Python dependencies into a virtual environment.
+2. **Runtime stage** — Copies only the venv, app source, and Alembic migrations. Runs as a non-root user (`appuser`).
+3. **Production server** — Gunicorn with 4 Uvicorn workers, 120-second timeout, listening on port 8000.
+
+```bash
+# Production command (run by the container)
+gunicorn app.main:app -k uvicorn.workers.UvicornWorker -w 4 --timeout 120 -b 0.0.0.0:8000
+```
+
+---
+
+## Homelab / Self-Hosted Deployment
+
+You can run the entire stack locally on a homelab with **no cloud dependencies except the LLM provider**. The compose file includes MinIO (S3 replacement) and Qdrant (vector store) out of the box.
+
+### 1. Start all services
+
+```bash
+docker compose up -d
+```
+
+This starts PostgreSQL, MinIO, and Qdrant alongside the app.
+
+### 2. Create the MinIO bucket
+
+Open the MinIO console at [http://localhost:9001](http://localhost:9001) (login: `minioadmin` / `minioadmin`) and create a bucket named `adiuva`, or use the CLI:
+
+```bash
+docker compose exec minio mc alias set local http://localhost:9000 minioadmin minioadmin
+docker compose exec minio mc mb local/adiuva
+```
+
+### 3. Configure your `.env`
+
+```bash
+# Database (uses the compose PostgreSQL)
+DATABASE_URL=postgresql+asyncpg://postgres:postgres@db:5432/adiuva
+
+# S3 → MinIO
+S3_BUCKET=adiuva
+S3_REGION=us-east-1
+S3_ENDPOINT_URL=http://minio:9000
+AWS_ACCESS_KEY_ID=minioadmin
+AWS_SECRET_ACCESS_KEY=minioadmin
+
+# Vector store → local Qdrant (leave PINECONE_API_KEY empty)
+QDRANT_URL=http://qdrant:6333
+QDRANT_API_KEY=
+PINECONE_API_KEY=
+
+# Billing — leave empty to stub (no Stripe needed)
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+
+# LLM — the only external service
+OPENAI_API_KEY=sk-...
+LLM_MODEL=gpt-4o
+LLM_ROUTER_MODEL=gpt-4o-mini
+
+# Auth
+JWT_SECRET=your-secret-here
+ENV=dev
+```
+
+### 4. Run migrations
+
+```bash
+docker compose exec app alembic upgrade head
+```
+
+### What runs where
+
+| Service | Runs on | Port | Notes |
+|---|---|---|---|
+| FastAPI app | Docker | 8000 | API server |
+| PostgreSQL | Docker | 5432 | Auth, billing, metadata |
+| MinIO | Docker | 9000 / 9001 | S3-compatible blob & backup storage |
+| Qdrant | Docker | 6333 / 6334 | Vector search (replaces Pinecone) |
+| Stripe | — | — | Stubbed when keys are empty |
+| OpenAI / LLM | Cloud | — | Only external dependency |
+
+> **Want fully offline AI too?** Set `LLM_MODEL=ollama/llama3` and `LLM_ROUTER_MODEL=ollama/llama3`, then add an Ollama container or point at a local Ollama instance. See the [LLM provider switching](#switching-llm-providers) section.
+
+---
+
+## Environment Variables
+
+All variables are loaded from a `.env` file via Pydantic Settings. Source: `app/config/settings.py`
+
+| Variable | Type | Default | Description |
+|---|---|---|---|
+| `DATABASE_URL` | `str` | `postgresql+asyncpg://postgres:postgres@localhost:5432/adiuva` | Async SQLAlchemy connection string |
+| `JWT_SECRET` | `str` | `change-me-in-production` | HMAC secret for JWT signing |
+| `JWT_ALGORITHM` | `str` | `HS256` | JWT signing algorithm |
+| `JWT_ACCESS_TOKEN_EXPIRE_MINUTES` | `int` | `30` | Access token time-to-live |
+| `JWT_REFRESH_TOKEN_EXPIRE_DAYS` | `int` | `30` | Refresh token time-to-live |
+| `STRIPE_SECRET_KEY` | `str` | `""` | Stripe API key (empty = stub mode) |
+| `STRIPE_WEBHOOK_SECRET` | `str` | `""` | Stripe webhook signature secret |
+| `S3_BUCKET` | `str` | `""` | S3 bucket for encrypted blobs and backups |
+| `S3_REGION` | `str` | `us-east-1` | AWS region |
+| `S3_ENDPOINT_URL` | `str` | `""` | Custom S3 endpoint (e.g. `http://minio:9000` for MinIO). Leave empty for AWS. |
+| `AWS_ACCESS_KEY_ID` | `str` | `""` | AWS credentials |
+| `AWS_SECRET_ACCESS_KEY` | `str` | `""` | AWS credentials |
+| `PINECONE_API_KEY` | `str` | `""` | Pinecone API key (if set, Pinecone is used for vectors) |
+| `PINECONE_INDEX` | `str` | `adiuva` | Pinecone index name |
+| `QDRANT_URL` | `str` | `""` | Qdrant URL (used when Pinecone is not configured) |
+| `QDRANT_API_KEY` | `str` | `""` | Qdrant API key |
+| `OPENAI_API_KEY` | `str` | `""` | OpenAI key for LLM agent calls |
+| `LLM_MODEL` | `str` | `gpt-4o` | LiteLLM model identifier for agents (e.g. `anthropic/claude-3.5-sonnet`, `gemini/gemini-pro`, `ollama/llama3`) |
+| `LLM_ROUTER_MODEL` | `str` | `gpt-4o-mini` | Lighter model used for intent classification / routing |
+| `CORS_ORIGINS` | `list[str]` | `["app://.", "http://localhost:3000", "http://localhost:5173"]` | Allowed CORS origins |
+| `ENV` | `Literal` | `dev` | `dev` or `prod` — controls `/docs` visibility and SQL echo |
+
+---
+
+## API Reference
+
+All routes are prefixed with `/api/v1`. **27 endpoints** total (25 REST + 1 WebSocket + 1 health check).
+
+### Health
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/v1/health` | No | Returns `{"status": "ok", "version": "0.1.0"}` |
+
+### Auth
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `POST` | `/api/v1/auth/register` | No | Create account with bcrypt-hashed password, returns `AuthTokens` |
+| `POST` | `/api/v1/auth/login` | No | Validate credentials, returns `AuthTokens` |
+| `POST` | `/api/v1/auth/refresh` | No | Rotate refresh token, returns new `AuthTokens` |
+| `GET` | `/api/v1/auth/me` | JWT | Returns `UserProfile` for the authenticated user |
+
+### Chat
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `POST` | `/api/v1/chat` | JWT | Route message through the orchestrator; returns `ChatResponse` or `ExecutionPlan` depending on execution mode |
+| `WS` | `/api/v1/chat/stream` | JWT (query param `?token=`) | Streaming chat — first frame is a `ChatRequest`, server yields text chunks, final frame is `{"done": true, "response": "...", "actions": [...]}`. 30-second heartbeat ping. |
+
+### Plans
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/v1/plans/playbook` | JWT | List all cached execution plan playbooks |
+| `GET` | `/api/v1/plans/playbook/{plan_id}` | JWT | Retrieve a specific playbook by ID |
+
+### Storage (Cloud Records)
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `POST` | `/api/v1/storage/records` | JWT | Upload an E2E encrypted record (verifies checksum, enforces storage quota) |
+| `GET` | `/api/v1/storage/records` | JWT | List record metadata with pagination (`?table`, `?page`, `?limit`); no blob bytes returned |
+| `GET` | `/api/v1/storage/records/{id}` | JWT | Download encrypted blob with `X-Checksum` response header |
+| `PUT` | `/api/v1/storage/records/{id}` | JWT | Replace an existing blob (verifies checksum, enforces quota) |
+| `DELETE` | `/api/v1/storage/records/{id}` | JWT | Delete a record and its S3 blob |
+
+### Vectors (Cloud Vector Store)
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `POST` | `/api/v1/storage/vectors/upsert` | JWT | Verify checksums and upsert encrypted vectors |
+| `POST` | `/api/v1/storage/vectors/search` | JWT | Search user-scoped vector namespace |
+| `DELETE` | `/api/v1/storage/vectors` | JWT | Delete vectors by ID list |
+
+### Backup
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `PUT` | `/api/v1/backup` | JWT | Upload encrypted backup blob with custom headers (`X-Backup-Version`, `X-Backup-Timestamp`, `X-Backup-Checksum`). Tier quota enforced. |
+| `GET` | `/api/v1/backup` | JWT | Download latest backup blob. Supports `If-Modified-Since`. |
+| `GET` | `/api/v1/backup/history` | JWT | List backup metadata (no blob content) |
+| `DELETE` | `/api/v1/backup/{backup_id}` | JWT | Delete a specific backup |
+
+### Plugins (Marketplace)
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `GET` | `/api/v1/plugins` | JWT (Power+) | Browse the marketplace (`?category`, `?q`, `?page`, `?sort=rating\|installs\|newest`) |
+| `GET` | `/api/v1/plugins/{id}` | JWT (Power+) | Plugin detail with install count and ratings |
+| `POST` | `/api/v1/plugins/{id}/install` | JWT (Power+) | Install plugin; triggers Stripe Connect revenue split for paid plugins |
+| `DELETE` | `/api/v1/plugins/{id}/install` | JWT | Uninstall plugin |
+
+### Billing
+
+| Method | Path | Auth | Description |
+|---|---|---|---|
+| `POST` | `/api/v1/billing/checkout` | JWT | Create a Stripe checkout session, returns `{"checkout_url": "..."}` |
+| `POST` | `/api/v1/billing/webhook` | Stripe signature | Handle Stripe events: `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, `invoice.payment_failed` |
+| `GET` | `/api/v1/billing/subscription` | JWT | Get current subscription information |
+| `DELETE` | `/api/v1/billing/subscription` | JWT | Cancel subscription and revert to free tier |
+
+---
+
+## Data Model
+
+9 tables managed by Alembic migrations. Source: `app/models.py`
+
+### Tables
+
+| Table | Primary Key | Key Columns | Purpose |
+|---|---|---|---|
+| `users` | `id` (UUID) | `email` (unique), `password_hash`, `tier`, `stripe_customer_id`, timestamps | User accounts |
+| `refresh_tokens` | `id` (UUID) | `user_id` (FK), `token_hash` (SHA-256, unique), `expires_at` | Hashed refresh tokens for rotation |
+| `subscriptions` | `id` (UUID) | `user_id` (FK, unique), `stripe_subscription_id`, `tier`, `status`, `current_period_end` | Stripe subscription records |
+| `storage_records` | `id` (UUID) | `user_id` (FK), `table_name`, `s3_key`, `checksum`, `size_bytes`, timestamps | S3 blob metadata (no plaintext content) |
+| `backup_metadata` | `id` (UUID) | `user_id` (FK), `s3_key`, `version`, `timestamp`, `checksum`, `size_bytes` | Backup manifests |
+| `plugins` | `id` (String) | `name`, `description`, `version`, `author_id` (FK), `category`, `price_cents`, `permissions` (JSON), `status`, `s3_package_key`, `install_count`, `avg_rating` | Marketplace plugin catalog |
+| `plugin_installations` | `id` (UUID) | `plugin_id` (FK), `user_id` (FK), unique constraint on (`plugin_id`, `user_id`) | Per-user install tracking |
+| `plugin_reviews` | `id` (UUID) | `plugin_id` (FK), `reviewer_id` (FK), `decision`, `notes`, `reviewed_at` | Admin review decisions |
+| `revenue_events` | `id` (UUID) | `plugin_id` (FK), `user_id` (FK), `amount_cents`, `developer_share_cents`, `stripe_transfer_id` | 70/30 revenue split ledger |
+
+### Enum Types
+
+| Enum | Values |
+|---|---|
+| `billing_tier` | `free`, `pro`, `power`, `team` |
+| `plugin_status` | `pending_review`, `approved`, `rejected` |
+| `review_decision` | `approved`, `rejected` |
+
+### Migrations
+
+| Version | Description |
+|---|---|
+| `001_initial_schema` | Creates all 9 tables with indexes and foreign key constraints |
+| `002_seed_plugins` | Seeds 3 approved plugins: GitHub Sync (free), Slack Notifier (€4.99), Time Tracker (€9.99) |
+
+---
+
+## AI Agent System
+
+The agent system uses a registry pattern with LangChain tool-calling agents powered by GPT-4o. Source: `app/agents/`, `app/core/agent_registry.py`
+
+### Architecture
+
+- **`BaseAgent`** — Abstract base with `user_id`, `shared_memory`, and `vector_store_context`.
+- **`ChatAgent(BaseAgent)`** — Abstract `handle(query, context)` and `get_tools()` methods, plus a shared `_tool_loop(llm, messages, tools, max_iter=5)` for iterative tool calling.
+- **`AgentRegistry`** — Singleton registry with `@register` decorator, `get(name)`, `list_agents()`, and `call_agent(name, query, context)`.
+
+### Registered Agents
+
+| Agent | Registry Name | Tools | Description |
+|---|---|---|---|
+| **TaskAgent** | `task_agent` | 8 | Full task and comment CRUD. Status: `todo` / `in_progress` / `done`. Priority: `high` / `medium` / `low`. Tools: `list_tasks`, `create_task`, `update_task`, `delete_task`, `list_tasks_due_today`, `list_task_comments`, `add_task_comment`, `delete_task_comment` |
+| **ProjectAgent** | `project_agent` | 6 | Project lifecycle management. Status: `active` / `archived`. Prefers archiving over deletion. Tools: `list_projects`, `list_all_projects`, `get_project`, `create_project`, `update_project`, `delete_project` |
+| **CheckpointAgent** | `checkpoint_agent` | 4 | Project milestones. Requires `project_id` for creation. Supports AI-suggestion and approval workflows. Tools: `list_checkpoints`, `create_checkpoint`, `update_checkpoint`, `delete_checkpoint` |
+| **NoteAgent** | `note_agent` | 5 | Markdown note management. Optionally linked to projects. Tools: `list_notes`, `get_note`, `create_note`, `update_note`, `delete_note` |
+
+All agents use the model configured by `LLM_MODEL` (default: GPT-4o) with `temperature=0` via LiteLLM. Tools return JSON action descriptors that the Electron client interprets and applies locally.
+
+### Switching LLM Providers
+
+The backend uses **LiteLLM** as a universal LLM gateway. All agents and the orchestrator instantiate models through a centralized factory in `app/core/llm.py`. To switch providers, change environment variables — no code changes required:
+
+```bash
+# OpenAI (default)
+LLM_MODEL=gpt-4o
+LLM_ROUTER_MODEL=gpt-4o-mini
+
+# Anthropic
+LLM_MODEL=anthropic/claude-3.5-sonnet
+LLM_ROUTER_MODEL=anthropic/claude-3-haiku
+
+# Google Gemini
+LLM_MODEL=gemini/gemini-pro
+LLM_ROUTER_MODEL=gemini/gemini-flash
+
+# Local Ollama
+LLM_MODEL=ollama/llama3
+LLM_ROUTER_MODEL=ollama/llama3
+
+# AWS Bedrock
+LLM_MODEL=bedrock/anthropic.claude-v2
+LLM_ROUTER_MODEL=bedrock/anthropic.claude-instant-v1
+```
+
+See the [LiteLLM provider docs](https://docs.litellm.ai/docs/providers) for the full list of 100+ supported providers and model naming conventions.
+
+---
+
+## Orchestration & Execution Plans
+
+Source: `app/core/orchestrator.py`, `app/core/execution_plan.py`
+
+### Orchestrator
+
+1. **`classify_intent(message, context, registry)`** — Uses the router model (`LLM_ROUTER_MODEL`, default: GPT-4o-mini) to determine which agent should handle a message. Falls back to `task_agent` when classification is ambiguous.
+2. **`route_single(agent_name, message, context)`** — Routes to a single agent and returns a `ChatResponse`.
+3. **`route_pipeline(agent_names, message, context)`** — Executes agents sequentially; each receives `previous_results` from earlier agents. A final LLM synthesis step merges all results.
+4. **`orchestrate(request)`** — Main entry point. In `direct` mode, returns a `ChatResponse`. In `plan` mode, returns an `ExecutionPlan`.
+5. **`orchestrate_stream(request)`** — Streaming variant that yields 50-character text chunks with a final JSON frame.
+
+### Execution Plans
+
+- **`PromptTemplateRegistry`** — Maps template IDs to server-side prompt text. Clients only ever see opaque IDs, never raw prompts.
+- **`ExecutionPlanBuilder`** — Fluent builder API: `add_step()`, `add_llm_step(template_id, vars)`, `add_data_step(action, data_from_step)`. Validates step references on `build()`.
+- **`PlanCache`** — LRU cache (maxsize 1000) for storing plans as reusable playbooks.
+
+### Built-in Templates (6)
+
+`tpl_task_agent_default`, `tpl_checkpoint_agent_default`, `tpl_project_agent_default`, `tpl_note_agent_default`, `tpl_task_extract_from_project`, `tpl_note_weekly_summary`
+
+### Built-in Playbooks (2)
+
+| Playbook | Description |
+|---|---|
+| `create_tasks_from_project` | LLM extracts actionable tasks from project context, then creates task records |
+| `generate_weekly_note` | LLM generates a weekly summary, then creates a note record |
+
+---
+
+## Middleware
+
+Middleware executes in this order on each request: **TierRateLimit → Sanitizer → CORS → Router**
+
+### JWT Authentication
+
+Source: `app/api/middleware/auth.py`
+
+- FastAPI dependency `get_current_user` validates the `Bearer` JWT and extracts `user_id` and `email`.
+- **Live tier lookup** — The current tier is fetched from the `subscriptions` table on every request (not cached in the JWT), so upgrades and downgrades take immediate effect.
+- Falls back to `free` when no subscription row exists.
+- Raises `401 Unauthorized` on invalid or expired tokens.
+- **Exempt paths:** `/api/v1/auth/register`, `/api/v1/auth/login`, `/api/v1/billing/webhook`
+
+### Tier-Based Rate Limiter
+
+Source: `app/api/middleware/rate_limit.py`
+
+- `TierRateLimitMiddleware` — Sliding-window in-process rate limiter (no Redis dependency).
+- Per-user 60-second window sized by subscription tier:
+
+| Tier | Requests / Minute |
+|---|---|
+| Free | 20 |
+| Pro | 60 |
+| Power | 120 |
+| Team | 200 |
+
+- Returns `429 Too Many Requests` with a `Retry-After` header when the limit is exceeded.
+- **Exempt paths:** register, login, webhook, health
+
+### Response Sanitizer
+
+Source: `app/api/middleware/sanitizer.py`
+
+- Runs only on `/api/v1/chat` endpoints.
+- Scans JSON response bodies and replaces leaked prompt IP fragments with `[REDACTED]`.
+- Detects: system prompt openers, agent routing metadata, LangChain tool schemas, internal reasoning markers (`<thinking>`, `[INST]`), and known prompt fingerprints.
+- Logs sanitization events as `WARNING`.
+- Binary responses (storage, backup) are never touched.
+
+---
+
+## Storage Layer
+
+### Blob Store
+
+Source: `app/storage/blob_store.py`
+
+- S3-backed storage for E2E encrypted blobs.
+- Object keys follow the pattern: `{user_id}/{table}/{record_id}`
+- Server-side SSE-S3 encryption at rest (additional layer on top of client-side E2E encryption).
+- Methods: `upload()`, `download()`, `delete()` (idempotent), `list_keys()`
+- The backend **never inspects or decrypts blob content**.
+
+### Vector Store
+
+Source: `app/storage/vector_store.py`
+
+- Runtime-configurable: **Pinecone** (when `PINECONE_API_KEY` is set) or **Qdrant** (fallback).
+- User isolation: Pinecone uses `namespace=user_id`; Qdrant filters by `user_id` payload field.
+- 32-dimensional SHA-256-derived float vectors (deterministic, not semantically meaningful on encrypted data — a documented trade-off for privacy).
+- Encrypted blobs are stored as base64 in metadata/payload for verbatim retrieval.
+- Methods: `upsert()`, `search()`, `delete()`
+
+### Encryption Utilities
+
+Source: `app/storage/encryption.py`
+
+- `verify_checksum(blob, checksum)` — SHA-256 hash comparison using `hmac.compare_digest` (constant-time to prevent timing attacks).
+- `reject_if_tampered(blob, checksum)` — Raises HTTP 400 on checksum mismatch.
+- **No decryption key ever reaches the backend.**
+
+---
+
+## Billing & Tiers
+
+Source: `app/billing/stripe_service.py`, `app/billing/tier_manager.py`
+
+### Feature Matrix
+
+| Feature | Free | Pro | Power | Team |
+|---|---|---|---|---|
+| AI Agents | 3 | Unlimited | Unlimited | Unlimited |
+| Batch Active | 2 | 10 | Unlimited | Unlimited |
+| Cloud Storage | 0 GB | 5 GB | 25 GB | Unlimited |
+| Backup Storage | 0 GB | 5 GB | 25 GB | Unlimited |
+| LLM Providers | 1 | Unlimited | Unlimited | Unlimited |
+| Batch Builder | — | — | ✓ | ✓ |
+| Plugin Marketplace | — | — | ✓ | ✓ |
+| SSO | — | — | — | ✓ |
+| Rate Limit | 20 req/min | 60 req/min | 120 req/min | 200 req/min |
+
+### Stripe Integration
+
+- **Checkout** — `create_checkout_session(user_id, tier)` creates a Stripe Checkout session. Returns a stub URL when Stripe is not configured.
+- **Webhooks** — Handles `checkout.session.completed`, `customer.subscription.updated`, `customer.subscription.deleted`, and `invoice.payment_failed`.
+- **Subscription management** — `get_subscription()` returns the current subscription record; `cancel_subscription()` cancels via the Stripe API and reverts the user to the free tier.
+- **Price IDs:** `price_pro_monthly`, `price_power_monthly`, `price_team_monthly`
+
+### Tier Manager
+
+- `get_tier(user_id)` — Returns the user's current billing tier.
+- `check_feature(tier, feature)` — Boolean feature gate check.
+- `require_feature(tier, feature)` — Raises HTTP 403 if the feature is not available.
+- `enforce_quota(user_id, tier)` / `enforce_backup_quota(user_id, tier)` — Raises HTTP 402 if storage limits are exceeded.
+
+---
+
+## Plugin Marketplace
+
+Source: `app/marketplace/`
+
+### Plugin Registry
+
+- PostgreSQL-backed catalog of submitted and approved plugins.
+- `list_plugins(db, category, query, page, sort)` — Paginated listing (page size: 20) with optional filtering by category, text search, and sorting by `rating`, `installs`, or `newest`.
+- `get_plugin(db, plugin_id)` — Full manifest with install count and ratings.
+- `submit_plugin(db, manifest, s3_key)` — Submits a plugin with `pending_review` status.
+- `approve_plugin()` / `reject_plugin(reason)` — Admin workflow for plugin approval.
+- `record_install()` / `record_uninstall()` — Tracks per-user installations and updates install counts.
+
+### Review Queue
+
+- Automated security checklist before human review:
+  - Plugin ID must match `^[a-z0-9-]+$`
+  - Permissions must be from the allowed set only
+  - No binary blobs in the manifest
+- **Allowed permissions:** `read:tasks`, `write:tasks`, `read:projects`, `write:projects`, `read:notes`, `write:notes`, `read:checkpoints`, `write:checkpoints`, `read:calendar`, `write:calendar`
+- `get_pending(db)` — Lists plugins awaiting review.
+- `submit_review(db, plugin_id, reviewer_id, decision, notes)` — Records the review decision.
+
+### Revenue Sharing
+
+- **70% developer / 30% platform** split on all paid plugin sales.
+- `record_install(db, plugin_id, user_id, amount_cents)` — Records the revenue event and triggers a Stripe Connect transfer for the developer share.
+- `get_earnings(db, developer_id, period)` — Aggregated earnings report for plugin developers.
+- Gracefully stubs transfers when Stripe is not configured.
+
+### Seed Plugins
+
+| Plugin | Category | Price |
+|---|---|---|
+| GitHub Sync | Productivity | Free |
+| Slack Notifier | Communication | €4.99 |
+| Time Tracker | Productivity | €9.99 |
+
+---
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest
+
+# Run a specific test file
+pytest tests/test_auth.py
+
+# Run with verbose output
+pytest -v
+```
+
+### Test Infrastructure
+
+- **Database:** Async SQLite in-memory via `aiosqlite` + `StaticPool` — fast, no PostgreSQL needed.
+- **S3 mock:** `moto[s3]` with a fixture that patches `BlobStore` settings.
+- **Auth helpers:** `make_jwt(tier)` and `auth_header(tier)` generate per-tier test tokens.
+- **Seed data:** Auto-creates one `User` + `Subscription` per tier (free/pro/power/team) before each test.
+- **Plugin seeds:** Fixture adds 3 approved plugins for marketplace tests.
+- **FK enforcement:** SQLite `PRAGMA foreign_keys=ON`.
+- **No external dependencies** — all tests run fully offline.
+
+### Test Coverage
+
+| File | Coverage |
+|---|---|
+| `test_auth.py` | Register, login, token access, refresh, expiration |
+| `test_orchestrator.py` | Intent classification, single agent routing, pipeline, plan mode |
+| `test_agents.py` | Each agent with mocked LLM: registration, tools, handle method |
+| `test_storage.py` | Create, list, download, update, delete records; checksum rejection; quota enforcement |
+| `test_backup.py` | Upload, download, history, delete; tier-based storage limits |
+| `test_plugins.py` | List, install, uninstall, revenue events, tier gate enforcement |
+| `test_agent_registry.py` | Registry singleton, registration, lookup, listing |
+| `test_execution_plan.py` | Plan builder, template registry, plan cache |
+| `test_middleware.py` | Rate limiting by tier, sanitizer prompt leak detection |
+
+---
+
+## Project Structure
+
+```
+adiuva-api/
+├── alembic.ini                  # Alembic configuration
+├── BACKEND_PLAN.md              # Architecture & design decisions
+├── docker-compose.yml           # Docker Compose (app + PostgreSQL)
+├── Dockerfile                   # Multi-stage production build
+├── requirements.txt             # Python dependencies
+│
+├── alembic/                     # Database migrations
+│   ├── env.py                   # Alembic environment config
+│   ├── script.py.mako           # Migration template
+│   └── versions/
+│       ├── 001_initial_schema.py    # Tables, indexes, FKs
+│       └── 002_seed_plugins.py      # Seed marketplace plugins
+│
+├── app/                         # Application source
+│   ├── main.py                  # FastAPI app factory, middleware, routes
+│   ├── db.py                    # Async SQLAlchemy engine & session
+│   ├── models.py                # SQLAlchemy ORM models (9 tables)
+│   ├── schemas.py               # Pydantic request/response schemas
+│   │
+│   ├── config/
+│   │   └── settings.py          # Pydantic Settings (env vars)
+│   │
+│   ├── agents/                  # LLM-powered domain agents
+│   │   ├── task_agent.py        # Task & comment CRUD (8 tools)
+│   │   ├── project_agent.py     # Project lifecycle (6 tools)
+│   │   ├── checkpoint_agent.py  # Milestones (4 tools)
+│   │   └── note_agent.py        # Markdown notes (5 tools)
+│   │
+│   ├── core/                    # Orchestration engine
+│   │   ├── agent_registry.py    # BaseAgent, ChatAgent, AgentRegistry
+│   │   ├── llm.py               # LiteLLM factory (get_llm, get_router_llm)
+│   │   ├── orchestrator.py      # Intent classification & routing
+│   │   └── execution_plan.py    # Plan builder, templates, cache
+│   │
+│   ├── api/                     # HTTP layer
+│   │   ├── deps.py              # Shared FastAPI dependencies
+│   │   ├── middleware/
+│   │   │   ├── auth.py          # JWT validation, live tier lookup
+│   │   │   ├── rate_limit.py    # Sliding-window tier rate limiter
+│   │   │   └── sanitizer.py     # Prompt IP leak protection
+│   │   └── routes/
+│   │       ├── auth.py          # Register, login, refresh, me
+│   │       ├── chat.py          # Chat + WebSocket streaming
+│   │       ├── plans.py         # Execution plan playbooks
+│   │       ├── storage.py       # E2E encrypted record CRUD
+│   │       ├── vectors.py       # Vector upsert, search, delete
+│   │       ├── backup.py        # Encrypted backup management
+│   │       ├── plugins.py       # Marketplace browse & install
+│   │       └── billing.py       # Stripe checkout & webhooks
+│   │
+│   ├── storage/                 # Storage backends
+│   │   ├── blob_store.py        # S3 blob storage
+│   │   ├── vector_store.py      # Pinecone / Qdrant vector store
+│   │   └── encryption.py        # Checksum verification utilities
+│   │
+│   ├── billing/                 # Subscription management
+│   │   ├── stripe_service.py    # Stripe API integration
+│   │   └── tier_manager.py      # Feature matrix & quota enforcement
+│   │
+│   └── marketplace/             # Plugin ecosystem
+│       ├── plugin_registry.py   # Catalog CRUD & search
+│       ├── plugin_review.py     # Security checklist & review queue
+│       └── revenue_share.py     # 70/30 split & Stripe Connect
+│
+└── tests/                       # Test suite
+    ├── conftest.py              # Fixtures: DB, S3, auth, seeds
+    ├── test_auth.py
+    ├── test_orchestrator.py
+    ├── test_agents.py
+    ├── test_storage.py
+    ├── test_backup.py
+    ├── test_plugins.py
+    ├── test_agent_registry.py
+    ├── test_execution_plan.py
+    └── test_middleware.py
+```
+
+---
+
+## License
+
+*To be determined.*

alembic/versions/001_initial_schema.py

@@ -40,7 +40,7 @@ def upgrade() -> None:
         sa.Column("id", postgresql.UUID(as_uuid=False), nullable=False),
         sa.Column("email", sa.String(255), nullable=False),
         sa.Column("password_hash", sa.String(255), nullable=False),
-        sa.Column("tier", sa.Enum("free", "pro", "power", "team", name="billing_tier"), nullable=False, server_default="free"),
+        sa.Column("tier", sa.Enum("free", "pro", "power", "team", name="billing_tier", create_type=False), nullable=False, server_default="free"),
         sa.Column("stripe_customer_id", sa.String(255), 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()")),
@@ -70,7 +70,7 @@ def upgrade() -> None:
         sa.Column("id", postgresql.UUID(as_uuid=False), nullable=False),
         sa.Column("user_id", postgresql.UUID(as_uuid=False), nullable=False),
         sa.Column("stripe_subscription_id", sa.String(255), nullable=True),
-        sa.Column("tier", sa.Enum("free", "pro", "power", "team", name="billing_tier"), nullable=False, server_default="free"),
+        sa.Column("tier", sa.Enum("free", "pro", "power", "team", name="billing_tier", create_type=False), nullable=False, server_default="free"),
         sa.Column("status", sa.String(50), nullable=False, server_default="free"),
         sa.Column("current_period_end", sa.DateTime(timezone=True), nullable=True),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
@@ -125,7 +125,7 @@ def upgrade() -> None:
         sa.Column("category", sa.String(100), nullable=False, server_default=""),
         sa.Column("price_cents", sa.Integer, nullable=False, server_default="0"),
         sa.Column("permissions", sa.Text, nullable=False, server_default="[]"),
-        sa.Column("status", sa.Enum("pending_review", "approved", "rejected", name="plugin_status"), nullable=False, server_default="pending_review"),
+        sa.Column("status", sa.Enum("pending_review", "approved", "rejected", name="plugin_status", create_type=False), nullable=False, server_default="pending_review"),
         sa.Column("s3_package_key", sa.String(500), nullable=True),
         sa.Column("install_count", sa.Integer, nullable=False, server_default="0"),
         sa.Column("avg_rating", sa.Float, nullable=False, server_default="0.0"),
@@ -157,7 +157,7 @@ def upgrade() -> None:
         sa.Column("id", postgresql.UUID(as_uuid=False), nullable=False),
         sa.Column("plugin_id", sa.String(255), nullable=False),
         sa.Column("reviewer_id", postgresql.UUID(as_uuid=False), nullable=True),
-        sa.Column("decision", sa.Enum("approved", "rejected", name="review_decision"), nullable=False),
+        sa.Column("decision", sa.Enum("approved", "rejected", name="review_decision", create_type=False), nullable=False),
         sa.Column("notes", sa.Text, nullable=True),
         sa.Column("reviewed_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),
         sa.Column("created_at", sa.DateTime(timezone=True), nullable=False, server_default=sa.text("now()")),

alembic/versions/002_seed_plugins.py

@@ -0,0 +1,92 @@
+"""Seed approved plugins: GitHub Sync, Slack Notifier, Time Tracker.
+
+Revision ID: 002
+Revises: 001
+Create Date: 2026-03-03
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "002"
+down_revision: Union[str, None] = "001"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+_SEED_PLUGINS = [
+    {
+        "id": "plugin-github-sync",
+        "name": "GitHub Sync",
+        "description": "Sync tasks with GitHub Issues and pull requests.",
+        "version": "1.0.0",
+        "author_name": "Adiuva",
+        "category": "productivity",
+        "price_cents": 0,
+        "permissions": json.dumps(["read:tasks", "write:tasks"]),
+        "status": "approved",
+        "s3_package_key": "plugins/plugin-github-sync/1.0.0/package.zip",
+        "install_count": 0,
+        "avg_rating": 0.0,
+    },
+    {
+        "id": "plugin-slack-notify",
+        "name": "Slack Notifier",
+        "description": "Post task and checkpoint updates to Slack channels.",
+        "version": "1.2.0",
+        "author_name": "Adiuva",
+        "category": "communication",
+        "price_cents": 499,
+        "permissions": json.dumps(["read:tasks", "read:checkpoints"]),
+        "status": "approved",
+        "s3_package_key": "plugins/plugin-slack-notify/1.2.0/package.zip",
+        "install_count": 0,
+        "avg_rating": 0.0,
+    },
+    {
+        "id": "plugin-time-tracker",
+        "name": "Time Tracker",
+        "description": "Track time spent on tasks with automatic reporting.",
+        "version": "0.9.1",
+        "author_name": "Third Party",
+        "category": "productivity",
+        "price_cents": 999,
+        "permissions": json.dumps(["read:tasks", "write:tasks"]),
+        "status": "approved",
+        "s3_package_key": "plugins/plugin-time-tracker/0.9.1/package.zip",
+        "install_count": 0,
+        "avg_rating": 0.0,
+    },
+]
+
+
+def upgrade() -> None:
+    plugins = sa.table(
+        "plugins",
+        sa.column("id", sa.String),
+        sa.column("name", sa.String),
+        sa.column("description", sa.Text),
+        sa.column("version", sa.String),
+        sa.column("author_name", sa.String),
+        sa.column("category", sa.String),
+        sa.column("price_cents", sa.Integer),
+        sa.column("permissions", sa.Text),
+        sa.column("status", sa.Enum("pending_review", "approved", "rejected", name="plugin_status")),
+        sa.column("s3_package_key", sa.String),
+        sa.column("install_count", sa.Integer),
+        sa.column("avg_rating", sa.Float),
+    )
+    op.bulk_insert(plugins, _SEED_PLUGINS)
+
+
+def downgrade() -> None:
+    op.execute(
+        "DELETE FROM plugins WHERE id IN ("
+        "'plugin-github-sync', 'plugin-slack-notify', 'plugin-time-tracker'"
+        ")"
+    )

app/agents/checkpoint_agent.py

@@ -7,10 +7,9 @@ from typing import Any
 
 from langchain_core.messages import HumanMessage, SystemMessage
 from langchain_core.tools import tool
-from langchain_openai import ChatOpenAI
 
-from app.config.settings import settings
 from app.core.agent_registry import ChatAgent, registry
+from app.core.llm import get_llm
 
 _SYSTEM_PROMPT = (
     "You are a project checkpoint assistant. Checkpoints are milestone dates that\n"
@@ -112,7 +111,7 @@ class CheckpointAgent(ChatAgent):
         return [list_checkpoints, create_checkpoint, update_checkpoint, delete_checkpoint]
 
     async def handle(self, query: str, context: dict[str, Any]) -> str:
-        llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key=settings.OPENAI_API_KEY)
+        llm = get_llm()
         messages = [
             SystemMessage(content=_SYSTEM_PROMPT),
             HumanMessage(

app/agents/note_agent.py

@@ -7,10 +7,9 @@ from typing import Any
 
 from langchain_core.messages import HumanMessage, SystemMessage
 from langchain_core.tools import tool
-from langchain_openai import ChatOpenAI
 
-from app.config.settings import settings
 from app.core.agent_registry import ChatAgent, registry
+from app.core.llm import get_llm
 
 _SYSTEM_PROMPT = (
     "You are a note-taking assistant. You help users create, retrieve, update,\n"
@@ -113,7 +112,7 @@ class NoteAgent(ChatAgent):
         return [list_notes, get_note, create_note, update_note, delete_note]
 
     async def handle(self, query: str, context: dict[str, Any]) -> str:
-        llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key=settings.OPENAI_API_KEY)
+        llm = get_llm()
         messages = [
             SystemMessage(content=_SYSTEM_PROMPT),
             HumanMessage(

app/agents/project_agent.py

@@ -7,10 +7,9 @@ from typing import Any
 
 from langchain_core.messages import HumanMessage, SystemMessage
 from langchain_core.tools import tool
-from langchain_openai import ChatOpenAI
 
-from app.config.settings import settings
 from app.core.agent_registry import ChatAgent, registry
+from app.core.llm import get_llm
 
 _SYSTEM_PROMPT = (
     "You are a project management assistant. You help users create, find,\n"
@@ -148,7 +147,7 @@ class ProjectAgent(ChatAgent):
         ]
 
     async def handle(self, query: str, context: dict[str, Any]) -> str:
-        llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key=settings.OPENAI_API_KEY)
+        llm = get_llm()
         messages = [
             SystemMessage(content=_SYSTEM_PROMPT),
             HumanMessage(

app/agents/task_agent.py

@@ -7,10 +7,9 @@ from typing import Any
 
 from langchain_core.messages import HumanMessage, SystemMessage
 from langchain_core.tools import tool
-from langchain_openai import ChatOpenAI
 
-from app.config.settings import settings
 from app.core.agent_registry import ChatAgent, registry
+from app.core.llm import get_llm
 
 _SYSTEM_PROMPT = (
     "You are a task management assistant for a project workspace.\n"
@@ -219,7 +218,7 @@ class TaskAgent(ChatAgent):
         ]
 
     async def handle(self, query: str, context: dict[str, Any]) -> str:
-        llm = ChatOpenAI(model="gpt-4o", temperature=0, api_key=settings.OPENAI_API_KEY)
+        llm = get_llm()
         messages = [
             SystemMessage(content=_SYSTEM_PROMPT),
             HumanMessage(

app/api/routes/backup.py

@@ -1,7 +1,7 @@
 """Backup routes: upload, download, history, and delete E2E-encrypted backups.
 
-Blobs are stored in S3 via BlobStore. Backup metadata is kept in an
+Blobs are stored in S3 via BlobStore. Backup metadata is persisted in the
-in-memory dict until Step 12 migrates it to PostgreSQL (backup_metadata table).
+PostgreSQL ``backup_metadata`` table.
 
 IMPORTANT: GET /history must be declared BEFORE GET / to avoid FastAPI
 treating "history" as a ``{backup_id}`` path parameter.
@@ -9,14 +9,17 @@ treating "history" as a ``{backup_id}`` path parameter.
 
 from __future__ import annotations
 
-import time
+import uuid
 from email.utils import parsedate_to_datetime
-from typing import Any
 
 from fastapi import APIRouter, Depends, Header, HTTPException, Request, Response, status
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
 from app.billing.tier_manager import tier_manager
+from app.db import get_session
+from app.models import BackupMetadata as BackupMetadataModel
 from app.schemas import BackupMetadata, UserProfile
 from app.storage.blob_store import BlobStore
 from app.storage.encryption import reject_if_tampered
@@ -25,14 +28,25 @@ router = APIRouter(prefix="/backup", tags=["backup"])
 
 _blob_store = BlobStore()
 
-# In-memory backup metadata — replaced by PostgreSQL backup_metadata table in Step 12
+
-_backups: dict[str, list[dict[str, Any]]] = {}  # user_id → list of backup records
+async def _current_backup_bytes(user_id: str, db: AsyncSession) -> int:
+    """Return total backup bytes stored by *user_id*."""
+    result = await db.execute(
+        select(func.coalesce(func.sum(BackupMetadataModel.size_bytes), 0)).where(
+            BackupMetadataModel.user_id == user_id
+        )
+    )
+    return int(result.scalar_one())
 
 
-def _check_backup_quota(user_id: str, size_bytes: int) -> None:
+async def _check_backup_quota(
+    user: UserProfile, size_bytes: int, db: AsyncSession
+) -> None:
     """Raise HTTP 402 if the upload would exceed the tier's backup limit."""
-    current = sum(b["size_bytes"] for b in _backups.get(user_id, []))
+    current = await _current_backup_bytes(user.id, db)
-    tier_manager.enforce_backup_quota(user_id, current_bytes=current, additional_bytes=size_bytes)
+    tier_manager.enforce_backup_quota(
+        user.tier, current_bytes=current, additional_bytes=size_bytes
+    )
 
 
 @router.put("")
@@ -42,6 +56,7 @@ async def upload_backup(
     x_backup_timestamp: int = Header(..., alias="X-Backup-Timestamp"),
     x_backup_checksum: str = Header(..., alias="X-Backup-Checksum"),
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> dict[str, bool]:
     """Upload an E2E-encrypted backup blob.
 
@@ -49,24 +64,23 @@ async def upload_backup(
     """
     blob = await request.body()
     reject_if_tampered(blob, x_backup_checksum)
-    _check_backup_quota(current_user.id, len(blob))
+    await _check_backup_quota(current_user, len(blob), db)
 
     s3_key = await _blob_store.upload(
         current_user.id, "backup", str(x_backup_timestamp), blob, x_backup_checksum
     )
 
-    backup_record: dict[str, Any] = {
+    row = BackupMetadataModel(
-        "id": str(x_backup_timestamp),
+        id=str(uuid.uuid4()),
-        "s3_key": s3_key,
+        user_id=current_user.id,
-        "version": x_backup_version,
+        s3_key=s3_key,
-        "timestamp": x_backup_timestamp,
+        version=x_backup_version,
-        "checksum": x_backup_checksum,
+        timestamp=x_backup_timestamp,
-        "size_bytes": len(blob),
+        checksum=x_backup_checksum,
-    }
+        size_bytes=len(blob),
-
+    )
-    user_backups = _backups.setdefault(current_user.id, [])
+    db.add(row)
-    user_backups.append(backup_record)
+    await db.commit()
-    user_backups.sort(key=lambda b: b["timestamp"], reverse=True)
 
     return {"ok": True}
 
@@ -74,16 +88,23 @@ async def upload_backup(
 @router.get("/history", response_model=list[BackupMetadata])
 async def backup_history(
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> list[BackupMetadata]:
     """Return backup metadata records for the authenticated user (no blob bytes)."""
+    result = await db.execute(
+        select(BackupMetadataModel)
+        .where(BackupMetadataModel.user_id == current_user.id)
+        .order_by(BackupMetadataModel.timestamp.desc())
+    )
+    rows = result.scalars().all()
     return [
         BackupMetadata(
-            version=b["version"],
+            version=r.version,
-            timestamp=b["timestamp"],
+            timestamp=r.timestamp,
-            checksum=b["checksum"],
+            checksum=r.checksum,
-            chunk_count=1,  # single-chunk uploads for now — TODO(Step12): track real count
+            chunk_count=1,
         )
-        for b in _backups.get(current_user.id, [])
+        for r in rows
     ]
 
 
@@ -91,32 +112,37 @@ async def backup_history(
 async def download_backup(
     request: Request,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> Response:
     """Download the latest backup blob. Supports ``If-Modified-Since``."""
-    user_backups = _backups.get(current_user.id, [])
+    result = await db.execute(
-    if not user_backups:
+        select(BackupMetadataModel)
+        .where(BackupMetadataModel.user_id == current_user.id)
+        .order_by(BackupMetadataModel.timestamp.desc())
+        .limit(1)
+    )
+    latest = result.scalar_one_or_none()
+    if latest is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="No backup found")
 
-    latest = user_backups[0]
-
     ims_header = request.headers.get("If-Modified-Since")
     if ims_header:
         try:
             ims_dt = parsedate_to_datetime(ims_header)
             ims_ms = int(ims_dt.timestamp() * 1000)
-            if latest["timestamp"] <= ims_ms:
+            if latest.timestamp <= ims_ms:
                 return Response(status_code=status.HTTP_304_NOT_MODIFIED)
         except Exception:
             pass  # malformed header — ignore and serve the blob
 
-    blob = await _blob_store.download(current_user.id, latest["s3_key"])
+    blob = await _blob_store.download(current_user.id, latest.s3_key)
     return Response(
         content=blob,
         media_type="application/octet-stream",
         headers={
-            "X-Backup-Version": str(latest["version"]),
+            "X-Backup-Version": str(latest.version),
-            "X-Backup-Timestamp": str(latest["timestamp"]),
+            "X-Backup-Timestamp": str(latest.timestamp),
-            "X-Checksum": latest["checksum"],
+            "X-Checksum": latest.checksum,
         },
     )
 
@@ -125,14 +151,21 @@ async def download_backup(
 async def delete_backup(
     backup_id: str,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> dict[str, bool]:
     """Delete a specific backup by ID."""
-    user_backups = _backups.get(current_user.id, [])
+    result = await db.execute(
-    target = next((b for b in user_backups if b["id"] == backup_id), None)
+        select(BackupMetadataModel).where(
+            BackupMetadataModel.id == backup_id,
+            BackupMetadataModel.user_id == current_user.id,
+        )
+    )
+    target = result.scalar_one_or_none()
     if target is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Backup not found")
 
-    await _blob_store.delete(current_user.id, target["s3_key"])
+    await _blob_store.delete(current_user.id, target.s3_key)
-    _backups[current_user.id] = [b for b in user_backups if b["id"] != backup_id]
+    await db.delete(target)
+    await db.commit()
 
     return {"ok": True}

app/api/routes/plugins.py

@@ -1,8 +1,7 @@
 """Plugins routes: browse and install plugins from the marketplace.
 
-Backed by ``PluginRegistry`` and ``RevenueShare`` service classes introduced
+Backed by ``PluginRegistry`` and ``RevenueShare`` service classes that
-in Step 10.  Step 12 will swap those services' in-memory stores for
+persist data in the PostgreSQL ``plugins`` and ``revenue_events`` tables.
-PostgreSQL persistence.
 """
 
 from __future__ import annotations
@@ -11,10 +10,14 @@ from typing import Any, Literal
 
 from fastapi import APIRouter, Depends, HTTPException, Query, status
 from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
+from app.db import get_session
 from app.marketplace.plugin_registry import registry
 from app.marketplace.revenue_share import revenue_share
+from app.models import PluginInstallation, PluginReview as PluginReviewModel
 from app.schemas import PluginInstallRequest, PluginListResponse, PluginManifest, UserProfile
 
 router = APIRouter(prefix="/plugins", tags=["plugins"])
@@ -36,7 +39,7 @@ def _require_plugin_tier(user: UserProfile) -> None:
 class _PluginDetail(BaseModel):
     plugin: PluginManifest
     install_count: int
-    ratings: list[Any]  # Step 12 populates from plugin_reviews table
+    ratings: list[Any]
 
 
 # ── Routes ────────────────────────────────────────────────────────────
@@ -48,26 +51,44 @@ async def list_plugins(
     page: int = Query(default=1, ge=1),
     sort: Literal["rating", "installs", "newest"] = Query(default="newest"),
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> PluginListResponse:
     """Browse the plugin marketplace. Requires Power tier or above."""
     _require_plugin_tier(current_user)
-    return await registry.list_plugins(category=category, query=q, page=page, sort=sort)
+    return await registry.list_plugins(db, category=category, query=q, page=page, sort=sort)
 
 
 @router.get("/{plugin_id}", response_model=_PluginDetail)
 async def get_plugin(
     plugin_id: str,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> _PluginDetail:
     """Get full plugin details including install count. Requires Power tier or above."""
     _require_plugin_tier(current_user)
-    entry = await registry.get_plugin(plugin_id)
+    entry = await registry.get_plugin(db, plugin_id)
     if entry is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Plugin not found")
+
+    # Fetch review ratings for this plugin
+    review_result = await db.execute(
+        select(PluginReviewModel).where(PluginReviewModel.plugin_id == plugin_id)
+    )
+    reviews = review_result.scalars().all()
+    ratings = [
+        {
+            "reviewer_id": r.reviewer_id,
+            "decision": r.decision,
+            "notes": r.notes,
+            "reviewed_at": int(r.reviewed_at.timestamp() * 1000) if r.reviewed_at else None,
+        }
+        for r in reviews
+    ]
+
     return _PluginDetail(
         plugin=entry["manifest"],
         install_count=entry["install_count"],
-        ratings=[],  # Step 12 populates from plugin_reviews table
+        ratings=ratings,
     )
 
 
@@ -76,17 +97,27 @@ async def install_plugin(
     plugin_id: str,
     body: PluginInstallRequest,  # noqa: ARG001 — reserved for future fields
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> dict[str, Any]:
     """Install a plugin. Triggers Stripe Connect revenue split for paid plugins.
 
     Requires Power tier or above.
     """
     _require_plugin_tier(current_user)
-    entry = await registry.get_plugin(plugin_id)
+    entry = await registry.get_plugin(db, plugin_id)
     if entry is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Plugin not found")
 
+    # Record the installation in plugin_installations
+    installation = PluginInstallation(
+        plugin_id=plugin_id,
+        user_id=current_user.id,
+    )
+    db.add(installation)
+    await db.flush()
+
     await revenue_share.record_install(
+        db,
         plugin_id=plugin_id,
         user_id=current_user.id,
         amount_cents=entry["manifest"].price_cents,
@@ -100,7 +131,18 @@ async def install_plugin(
 async def uninstall_plugin(
     plugin_id: str,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> dict[str, bool]:
     """Unregister a plugin installation."""
-    await registry.record_uninstall(plugin_id)
+    result = await db.execute(
+        select(PluginInstallation).where(
+            PluginInstallation.plugin_id == plugin_id,
+            PluginInstallation.user_id == current_user.id,
+        )
+    )
+    installation = result.scalar_one_or_none()
+    if installation is not None:
+        await db.delete(installation)
+        await db.commit()
+    await registry.record_uninstall(db, plugin_id)
     return {"ok": True}

app/api/routes/storage.py

@@ -1,20 +1,22 @@
 """Storage routes: CRUD for E2E-encrypted cloud records.
 
-Blobs are stored in S3 via BlobStore. Record metadata is kept in an
+Blobs are stored in S3 via BlobStore. Record metadata is persisted in the
-in-memory dict until Step 12 migrates it to PostgreSQL (storage_records table).
+PostgreSQL ``storage_records`` table.
 """
 
 from __future__ import annotations
 
-import time
 import uuid
-from typing import Any
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Response, status
 from pydantic import BaseModel
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.api.deps import get_current_user
 from app.billing.tier_manager import tier_manager
+from app.db import get_session
+from app.models import StorageRecord
 from app.schemas import StorageRecordCreate, StorageRecordUpdate, UserProfile
 from app.storage.blob_store import BlobStore
 from app.storage.encryption import reject_if_tampered
@@ -23,9 +25,6 @@ router = APIRouter(prefix="/storage", tags=["storage"])
 
 _blob_store = BlobStore()
 
-# In-memory record metadata — replaced by PostgreSQL storage_records table in Step 12
-_records: dict[str, dict[str, Any]] = {}
-
 
 # ── Local response schemas ─────────────────────────────────────────────
 
@@ -44,17 +43,34 @@ class _RecordMeta(BaseModel):
 
 # ── Helpers ────────────────────────────────────────────────────────────
 
-def _check_quota(user_id: str, additional_bytes: int) -> None:
+async def _current_usage_bytes(user_id: str, db: AsyncSession) -> int:
-    """Raise HTTP 402 if adding ``additional_bytes`` would exceed the tier limit."""
+    """Return total bytes stored by *user_id*."""
-    current = sum(r["size_bytes"] for r in _records.values() if r["user_id"] == user_id)
+    result = await db.execute(
-    tier_manager.enforce_quota(user_id, current_bytes=current, additional_bytes=additional_bytes)
+        select(func.coalesce(func.sum(StorageRecord.size_bytes), 0)).where(
+            StorageRecord.user_id == user_id
+        )
+    )
+    return int(result.scalar_one())
 
 
-def _get_record_for_user(record_id: str, user_id: str) -> dict[str, Any]:
+async def _check_quota(user: UserProfile, additional_bytes: int, db: AsyncSession) -> None:
-    """Look up a record and verify ownership. Always returns 404 on mismatch
+    """Raise HTTP 402 if adding *additional_bytes* would exceed the tier limit."""
+    current = await _current_usage_bytes(user.id, db)
+    tier_manager.enforce_quota(user.tier, current_bytes=current, additional_bytes=additional_bytes)
+
+
+async def _get_record_for_user(
+    record_id: str, user_id: str, db: AsyncSession
+) -> StorageRecord:
+    """Look up a record and verify ownership. Returns 404 on mismatch
     to prevent user enumeration attacks."""
-    record = _records.get(record_id)
+    result = await db.execute(
-    if record is None or record["user_id"] != user_id:
+        select(StorageRecord).where(
+            StorageRecord.id == record_id, StorageRecord.user_id == user_id
+        )
+    )
+    record = result.scalar_one_or_none()
+    if record is None:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Record not found")
     return record
 
@@ -65,30 +81,32 @@ def _get_record_for_user(record_id: str, user_id: str) -> dict[str, Any]:
 async def create_record(
     body: StorageRecordCreate,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> _CreateResponse:
     """Upload a new E2E-encrypted blob. Verifies checksum before storing."""
     reject_if_tampered(body.blob, body.checksum)
-    _check_quota(current_user.id, len(body.blob))
+    await _check_quota(current_user, len(body.blob), db)
 
     record_id = str(uuid.uuid4())
-    now = int(time.time() * 1000)
 
     s3_key = await _blob_store.upload(
         current_user.id, body.table, record_id, body.blob, body.checksum
     )
 
-    _records[record_id] = {
+    record = StorageRecord(
-        "id": record_id,
+        id=record_id,
-        "user_id": current_user.id,
+        user_id=current_user.id,
-        "table": body.table,
+        table_name=body.table,
-        "s3_key": s3_key,
+        s3_key=s3_key,
-        "checksum": body.checksum,
+        checksum=body.checksum,
-        "size_bytes": len(body.blob),
+        size_bytes=len(body.blob),
-        "created_at": now,
+    )
-        "updated_at": now,
+    db.add(record)
-    }
+    await db.commit()
+    await db.refresh(record)
 
-    return _CreateResponse(id=record_id, created_at=now)
+    created_at_ms = int(record.created_at.timestamp() * 1000)
+    return _CreateResponse(id=record_id, created_at=created_at_ms)
 
 
 @router.get("/records", response_model=list[_RecordMeta])
@@ -97,23 +115,26 @@ async def list_records(
     page: int = Query(default=1, ge=1),
     limit: int = Query(default=50, ge=1, le=200),
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> list[_RecordMeta]:
     """List record metadata for the authenticated user. Blob bytes are never returned."""
-    all_records = [
+    query = select(StorageRecord).where(StorageRecord.user_id == current_user.id)
-        r for r in _records.values()
+    if table is not None:
-        if r["user_id"] == current_user.id and (table is None or r["table"] == table)
+        query = query.where(StorageRecord.table_name == table)
-    ]
+    query = query.offset((page - 1) * limit).limit(limit)
-    start = (page - 1) * limit
+
-    page_records = all_records[start : start + limit]
+    result = await db.execute(query)
+    rows = result.scalars().all()
+
     return [
         _RecordMeta(
-            id=r["id"],
+            id=r.id,
-            table=r["table"],
+            table=r.table_name,
-            checksum=r["checksum"],
+            checksum=r.checksum,
-            created_at=r["created_at"],
+            created_at=int(r.created_at.timestamp() * 1000),
-            updated_at=r["updated_at"],
+            updated_at=int(r.updated_at.timestamp() * 1000),
         )
-        for r in page_records
+        for r in rows
     ]
 
 
@@ -121,14 +142,15 @@ async def list_records(
 async def download_record(
     record_id: str,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> Response:
     """Download an E2E-encrypted blob. Returns raw bytes with ``X-Checksum`` header."""
-    record = _get_record_for_user(record_id, current_user.id)
+    record = await _get_record_for_user(record_id, current_user.id, db)
-    blob = await _blob_store.download(current_user.id, record["s3_key"])
+    blob = await _blob_store.download(current_user.id, record.s3_key)
     return Response(
         content=blob,
         media_type="application/octet-stream",
-        headers={"X-Checksum": record["checksum"]},
+        headers={"X-Checksum": record.checksum},
     )
 
 
@@ -137,23 +159,24 @@ async def update_record(
     record_id: str,
     body: StorageRecordUpdate,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> dict[str, bool]:
     """Replace the blob for an existing record. Verifies checksum before storing."""
-    record = _get_record_for_user(record_id, current_user.id)
+    record = await _get_record_for_user(record_id, current_user.id, db)
     reject_if_tampered(body.blob, body.checksum)
 
-    delta = len(body.blob) - record["size_bytes"]
+    delta = len(body.blob) - record.size_bytes
     if delta > 0:
-        _check_quota(current_user.id, delta)
+        await _check_quota(current_user, delta, db)
 
     s3_key = await _blob_store.upload(
-        current_user.id, record["table"], record_id, body.blob, body.checksum
+        current_user.id, record.table_name, record_id, body.blob, body.checksum
     )
 
-    record["s3_key"] = s3_key
+    record.s3_key = s3_key
-    record["checksum"] = body.checksum
+    record.checksum = body.checksum
-    record["size_bytes"] = len(body.blob)
+    record.size_bytes = len(body.blob)
-    record["updated_at"] = int(time.time() * 1000)
+    await db.commit()
 
     return {"ok": True}
 
@@ -162,9 +185,11 @@ async def update_record(
 async def delete_record(
     record_id: str,
     current_user: UserProfile = Depends(get_current_user),
+    db: AsyncSession = Depends(get_session),
 ) -> dict[str, bool]:
     """Delete a record and its S3 blob."""
-    record = _get_record_for_user(record_id, current_user.id)
+    record = await _get_record_for_user(record_id, current_user.id, db)
-    await _blob_store.delete(current_user.id, record["s3_key"])
+    await _blob_store.delete(current_user.id, record.s3_key)
-    del _records[record_id]
+    await db.delete(record)
+    await db.commit()
     return {"ok": True}

app/config/settings.py

@@ -14,6 +14,7 @@ class Settings(BaseSettings):
 
     S3_BUCKET: str = ""
     S3_REGION: str = "us-east-1"
+    S3_ENDPOINT_URL: str = ""
     AWS_ACCESS_KEY_ID: str = ""
     AWS_SECRET_ACCESS_KEY: str = ""
 
@@ -23,6 +24,11 @@ class Settings(BaseSettings):
     QDRANT_API_KEY: str = ""
 
     OPENAI_API_KEY: str = ""
+    ANTHROPIC_API_KEY: str = ""
+    GOOGLE_API_KEY: str = ""
+
+    LLM_MODEL: str = "gpt-4o"
+    LLM_ROUTER_MODEL: str = "gpt-4o-mini"
 
     CORS_ORIGINS: list[str] = ["app://.", "http://localhost:3000", "http://localhost:5173"]
 

app/core/llm.py

@@ -0,0 +1,68 @@
+"""LLM factory — centralised model instantiation via LiteLLM.
+
+Every agent and the orchestrator call ``get_llm()`` or ``get_router_llm()``
+instead of directly constructing a provider-specific class.  The model string
+follows the `LiteLLM model naming convention
+<https://docs.litellm.ai/docs/providers>`_:
+
+* OpenAI:     ``gpt-4o``, ``gpt-4o-mini``
+* Anthropic:  ``anthropic/claude-3.5-sonnet``
+* Google:     ``gemini/gemini-pro``
+* Ollama:     ``ollama/llama3``
+* Bedrock:    ``bedrock/anthropic.claude-v2``
+
+Switch providers by changing **LLM_MODEL** / **LLM_ROUTER_MODEL** in ``.env``
+— no code changes required.
+"""
+
+from __future__ import annotations
+
+from langchain_openai import ChatOpenAI
+from litellm import get_supported_openai_params  # noqa: F401 – validates install
+
+from app.config.settings import settings
+
+
+def _api_key_for_model(model: str) -> str | None:
+    """Return the most appropriate API key for the given LiteLLM model string."""
+    if model.startswith("anthropic/"):
+        return settings.ANTHROPIC_API_KEY or None
+    if model.startswith("gemini/") or model.startswith("google/"):
+        return settings.GOOGLE_API_KEY or None
+    # Default: OpenAI-compatible (covers plain model names like "gpt-4o")
+    return settings.OPENAI_API_KEY or None
+
+
+def get_llm(
+    *,
+    model: str | None = None,
+    temperature: float = 0,
+) -> ChatOpenAI:
+    """Return a LangChain chat model backed by LiteLLM.
+
+    LiteLLM exposes an OpenAI-compatible API, so we use ``ChatOpenAI`` pointed
+    at the LiteLLM proxy endpoint.  In practice, ``litellm`` patches the
+    ``openai`` client transparently when the model string contains a provider
+    prefix (``anthropic/…``, ``gemini/…``, etc.).
+
+    Parameters
+    ----------
+    model:
+        LiteLLM model identifier. Defaults to ``settings.LLM_MODEL``.
+    temperature:
+        Sampling temperature.  ``0`` = deterministic.
+    """
+    model = model or settings.LLM_MODEL
+    return ChatOpenAI(
+        model=model,
+        temperature=temperature,
+        api_key=_api_key_for_model(model),
+    )
+
+
+def get_router_llm(
+    *,
+    temperature: float = 0,
+) -> ChatOpenAI:
+    """Return the lighter model used for intent classification / routing."""
+    return get_llm(model=settings.LLM_ROUTER_MODEL, temperature=temperature)

app/core/orchestrator.py

@@ -6,10 +6,9 @@ import json
 from typing import Any, AsyncGenerator
 
 from langchain_core.messages import HumanMessage, SystemMessage
-from langchain_openai import ChatOpenAI
 
-from app.config.settings import settings
 from app.core.agent_registry import AgentRegistry
+from app.core.llm import get_router_llm
 from app.core.agent_registry import registry as _default_registry
 from app.schemas import ChatRequest, ChatResponse, ExecutionPlan
 
@@ -29,8 +28,8 @@ _SYNTHESIZE_HUMAN = (
 )
 
 
-def _make_llm(model: str = "gpt-4o-mini") -> ChatOpenAI:
+def _make_llm():
-    return ChatOpenAI(model=model, temperature=0, api_key=settings.OPENAI_API_KEY)
+    return get_router_llm()
 
 
 async def classify_intent(

app/marketplace/plugin_registry.py

@@ -1,8 +1,7 @@
-"""Plugin catalog registry.
+"""Plugin catalog registry backed by PostgreSQL.
 
 Maintains the authoritative list of plugins, their review status, and
-aggregate install counts.  Storage is in-memory until Step 12 migrates to
+aggregate install counts.  All data is persisted in the ``plugins`` table.
-the ``plugins`` PostgreSQL table.
 
 Module-level singleton::
 
@@ -11,144 +10,103 @@ Module-level singleton::
 
 from __future__ import annotations
 
-import copy
+import json
-import time
-import uuid
 from typing import Any, Literal
 
+from sqlalchemy import select, func
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from app.models import Plugin
 from app.schemas import PluginListResponse, PluginManifest
 
-# ── Pre-seeded approved plugins (mirrors the Step 8 stub catalog) ─────
-
-_SEED_PLUGINS: list[dict[str, Any]] = [
-    {
-        "manifest": PluginManifest(
-            id="plugin-github-sync",
-            name="GitHub Sync",
-            description="Sync tasks with GitHub Issues and pull requests.",
-            version="1.0.0",
-            author="Adiuva",
-            permissions=["read:tasks", "write:tasks"],
-            category="productivity",
-            price_cents=0,
-        ),
-        "status": "approved",
-        "s3_package_key": "plugins/plugin-github-sync/1.0.0/package.zip",
-        "install_count": 0,
-        "avg_rating": 0.0,
-        "rejection_reason": None,
-        "submitted_at": int(time.time()),
-    },
-    {
-        "manifest": PluginManifest(
-            id="plugin-slack-notify",
-            name="Slack Notifier",
-            description="Post task and checkpoint updates to Slack channels.",
-            version="1.2.0",
-            author="Adiuva",
-            permissions=["read:tasks", "read:checkpoints"],
-            category="communication",
-            price_cents=499,
-        ),
-        "status": "approved",
-        "s3_package_key": "plugins/plugin-slack-notify/1.2.0/package.zip",
-        "install_count": 0,
-        "avg_rating": 0.0,
-        "rejection_reason": None,
-        "submitted_at": int(time.time()),
-    },
-    {
-        "manifest": PluginManifest(
-            id="plugin-time-tracker",
-            name="Time Tracker",
-            description="Track time spent on tasks with automatic reporting.",
-            version="0.9.1",
-            author="Third Party",
-            permissions=["read:tasks", "write:tasks"],
-            category="productivity",
-            price_cents=999,
-        ),
-        "status": "approved",
-        "s3_package_key": "plugins/plugin-time-tracker/0.9.1/package.zip",
-        "install_count": 0,
-        "avg_rating": 0.0,
-        "rejection_reason": None,
-        "submitted_at": int(time.time()),
-    },
-]
-
 _PAGE_SIZE = 20
 
 
+def _plugin_to_manifest(p: Plugin) -> PluginManifest:
+    """Convert an ORM ``Plugin`` row to a Pydantic ``PluginManifest``."""
+    try:
+        permissions = json.loads(p.permissions) if p.permissions else []
+    except (json.JSONDecodeError, TypeError):
+        permissions = []
+    return PluginManifest(
+        id=p.id,
+        name=p.name,
+        description=p.description,
+        version=p.version,
+        author=p.author_name,
+        permissions=permissions,
+        category=p.category,
+        price_cents=p.price_cents,
+    )
+
+
 class PluginRegistry:
-    """In-process plugin catalog.
+    """PostgreSQL-backed plugin catalog.
 
-    All mutating methods are ``async`` to make the future DB swap transparent
+    All methods accept an ``AsyncSession`` parameter so the calling route
-    to callers.
+    controls the session lifecycle.
     """
 
-    def __init__(self) -> None:
-        # plugin_id → entry dict (deep-copied so each instance is independent)
-        self._catalog: dict[str, dict[str, Any]] = {
-            e["manifest"].id: copy.deepcopy(e) for e in _SEED_PLUGINS
-        }
-
     # ── Queries ──────────────────────────────────────────────────────
 
     async def list_plugins(
         self,
+        db: AsyncSession,
         category: str | None = None,
         query: str | None = None,
         page: int = 1,
         sort: Literal["rating", "installs", "newest"] = "newest",
     ) -> PluginListResponse:
         """Return a page of approved plugins, optionally filtered and sorted."""
-        entries = [e for e in self._catalog.values() if e["status"] == "approved"]
+        base = select(Plugin).where(Plugin.status == "approved")
 
         if category:
-            entries = [e for e in entries if e["manifest"].category == category]
+            base = base.where(Plugin.category == category)
-
         if query:
-            q_lower = query.lower()
+            pattern = f"%{query}%"
-            entries = [
+            base = base.where(
-                e
+                Plugin.name.ilike(pattern) | Plugin.description.ilike(pattern)
-                for e in entries
+            )
-                if q_lower in e["manifest"].name.lower()
-                or q_lower in e["manifest"].description.lower()
-            ]
 
+        # Count
+        count_q = select(func.count()).select_from(base.subquery())
+        total = (await db.execute(count_q)).scalar_one()
+
+        # Sort
         if sort == "installs":
-            entries = sorted(entries, key=lambda e: e["install_count"], reverse=True)
+            base = base.order_by(Plugin.install_count.desc())
         elif sort == "rating":
-            entries = sorted(entries, key=lambda e: e["avg_rating"], reverse=True)
+            base = base.order_by(Plugin.avg_rating.desc())
-        # "newest" = catalog insertion order (dict preserves insertion in Python 3.7+)
+        else:  # newest
+            base = base.order_by(Plugin.created_at.desc())
 
-        total = len(entries)
+        base = base.offset((page - 1) * _PAGE_SIZE).limit(_PAGE_SIZE)
-        start = (page - 1) * _PAGE_SIZE
+        rows = (await db.execute(base)).scalars().all()
-        page_entries = entries[start : start + _PAGE_SIZE]
 
         return PluginListResponse(
-            plugins=[e["manifest"] for e in page_entries],
+            plugins=[_plugin_to_manifest(r) for r in rows],
             total=total,
             page=page,
         )
 
-    async def get_plugin(self, plugin_id: str) -> dict[str, Any] | None:
+    async def get_plugin(self, db: AsyncSession, plugin_id: str) -> dict[str, Any] | None:
         """Return ``{manifest, status, install_count, avg_rating}`` or ``None``."""
-        entry = self._catalog.get(plugin_id)
+        result = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
-        if entry is None:
+        p = result.scalar_one_or_none()
+        if p is None:
             return None
         return {
-            "manifest": entry["manifest"],
+            "manifest": _plugin_to_manifest(p),
-            "status": entry["status"],
+            "status": p.status,
-            "install_count": entry["install_count"],
+            "install_count": p.install_count,
-            "avg_rating": entry["avg_rating"],
+            "avg_rating": p.avg_rating,
         }
 
     # ── Mutations ────────────────────────────────────────────────────
 
     async def submit_plugin(
         self,
+        db: AsyncSession,
         manifest: PluginManifest,
         package_s3_key: str,
     ) -> str:
@@ -157,54 +115,97 @@ class PluginRegistry:
         Returns the plugin_id.  If a plugin with the same id already exists
         it is overwritten (re-submission after rejection).
         """
-        plugin_id = manifest.id or str(uuid.uuid4())
+        plugin_id = manifest.id
-        self._catalog[plugin_id] = {
+        existing = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
-            "manifest": manifest,
+        row = existing.scalar_one_or_none()
-            "status": "pending_review",
+
-            "s3_package_key": package_s3_key,
+        if row is not None:
-            "install_count": 0,
+            row.name = manifest.name
-            "avg_rating": 0.0,
+            row.description = manifest.description
-            "rejection_reason": None,
+            row.version = manifest.version
-            "submitted_at": int(time.time()),
+            row.author_name = manifest.author
-        }
+            row.category = manifest.category
+            row.price_cents = manifest.price_cents
+            row.permissions = json.dumps(manifest.permissions)
+            row.status = "pending_review"
+            row.s3_package_key = package_s3_key
+            row.rejection_reason = None
+        else:
+            row = Plugin(
+                id=plugin_id,
+                name=manifest.name,
+                description=manifest.description,
+                version=manifest.version,
+                author_name=manifest.author,
+                category=manifest.category,
+                price_cents=manifest.price_cents,
+                permissions=json.dumps(manifest.permissions),
+                status="pending_review",
+                s3_package_key=package_s3_key,
+                install_count=0,
+                avg_rating=0.0,
+            )
+            db.add(row)
+        await db.commit()
         return plugin_id
 
-    async def approve_plugin(self, plugin_id: str) -> None:
+    async def approve_plugin(self, db: AsyncSession, plugin_id: str) -> None:
         """Set *plugin_id* status to ``'approved'``.
 
         Raises ``KeyError`` if the plugin is not found.
         """
-        if plugin_id not in self._catalog:
+        result = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
+        row = result.scalar_one_or_none()
+        if row is None:
             raise KeyError(f"Plugin not found: {plugin_id}")
-        self._catalog[plugin_id]["status"] = "approved"
+        row.status = "approved"
-        self._catalog[plugin_id]["rejection_reason"] = None
+        row.rejection_reason = None
+        await db.commit()
 
-    async def reject_plugin(self, plugin_id: str, reason: str) -> None:
+    async def reject_plugin(self, db: AsyncSession, plugin_id: str, reason: str) -> None:
         """Set *plugin_id* status to ``'rejected'`` and record the reason.
 
         Raises ``KeyError`` if the plugin is not found.
         """
-        if plugin_id not in self._catalog:
+        result = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
+        row = result.scalar_one_or_none()
+        if row is None:
             raise KeyError(f"Plugin not found: {plugin_id}")
-        self._catalog[plugin_id]["status"] = "rejected"
+        row.status = "rejected"
-        self._catalog[plugin_id]["rejection_reason"] = reason
+        row.rejection_reason = reason
+        await db.commit()
 
-    async def record_install(self, plugin_id: str) -> None:
+    async def record_install(self, db: AsyncSession, plugin_id: str) -> None:
         """Increment the install count for *plugin_id* (no-op if not found)."""
-        if plugin_id in self._catalog:
+        result = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
-            self._catalog[plugin_id]["install_count"] += 1
+        row = result.scalar_one_or_none()
+        if row is not None:
+            row.install_count = row.install_count + 1
+            await db.commit()
 
-    async def record_uninstall(self, plugin_id: str) -> None:
+    async def record_uninstall(self, db: AsyncSession, plugin_id: str) -> None:
         """Decrement the install count for *plugin_id*, floored at 0."""
-        if plugin_id in self._catalog:
+        result = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
-            current = self._catalog[plugin_id]["install_count"]
+        row = result.scalar_one_or_none()
-            self._catalog[plugin_id]["install_count"] = max(0, current - 1)
+        if row is not None:
+            row.install_count = max(0, row.install_count - 1)
+            await db.commit()
 
     # ── Internal helpers used by ReviewQueue ─────────────────────────
 
-    def _get_pending_entries(self) -> list[dict[str, Any]]:
+    async def get_pending_entries(self, db: AsyncSession) -> list[dict[str, Any]]:
-        """Return all entries with status='pending_review' (synchronous helper)."""
+        """Return all entries with status='pending_review'."""
-        return [e for e in self._catalog.values() if e["status"] == "pending_review"]
+        result = await db.execute(
+            select(Plugin).where(Plugin.status == "pending_review")
+        )
+        rows = result.scalars().all()
+        return [
+            {
+                "manifest": _plugin_to_manifest(r),
+                "submitted_at": int(r.submitted_at.timestamp()) if r.submitted_at else 0,
+            }
+            for r in rows
+        ]
 
 
 # Module-level singleton

app/marketplace/plugin_review.py

@@ -1,4 +1,4 @@
-"""Plugin review workflow.
+"""Plugin review workflow backed by PostgreSQL.
 
 Manages the approval queue for newly submitted plugins and enforces a
 security checklist before any plugin is made visible in the marketplace.
@@ -11,10 +11,12 @@ Module-level singleton::
 from __future__ import annotations
 
 import re
-import time
 from typing import Any, Literal
 
+from sqlalchemy.ext.asyncio import AsyncSession
+
 from app.marketplace.plugin_registry import registry
+from app.models import PluginReview as PluginReviewModel
 from app.schemas import PluginManifest
 
 # ── Security policy ───────────────────────────────────────────────────
@@ -72,20 +74,16 @@ def validate_manifest(manifest: PluginManifest) -> None:
 class ReviewQueue:
     """Approval queue for pending plugin submissions.
 
-    Delegates status changes to the shared ``PluginRegistry`` singleton so
+    Delegates status changes to the shared ``PluginRegistry`` singleton.
-    there is a single source of truth for plugin state.
+    Review records are persisted in the ``plugin_reviews`` table.
     """
 
-    def __init__(self) -> None:
+    async def get_pending(self, db: AsyncSession) -> list[dict[str, Any]]:
-        # Completed reviews — Step 12 stores in plugin_reviews table
-        self._reviews: list[dict[str, Any]] = []
-
-    async def get_pending(self) -> list[dict[str, Any]]:
         """Return all plugins currently awaiting review.
 
         Each item is ``{plugin_id, manifest, submitted_at}``.
         """
-        entries = registry._get_pending_entries()
+        entries = await registry.get_pending_entries(db)
         return [
             {
                 "plugin_id": e["manifest"].id,
@@ -97,6 +95,7 @@ class ReviewQueue:
 
     async def submit_review(
         self,
+        db: AsyncSession,
         plugin_id: str,
         reviewer_id: str,
         decision: Literal["approved", "rejected"],
@@ -108,19 +107,18 @@ class ReviewQueue:
             ``KeyError`` if *plugin_id* is not found in the registry.
         """
         if decision == "approved":
-            await registry.approve_plugin(plugin_id)
+            await registry.approve_plugin(db, plugin_id)
         else:
-            await registry.reject_plugin(plugin_id, reason=notes)
+            await registry.reject_plugin(db, plugin_id, reason=notes)
 
-        self._reviews.append(
+        review = PluginReviewModel(
-            {
+            plugin_id=plugin_id,
-                "plugin_id": plugin_id,
+            reviewer_id=reviewer_id,
-                "reviewer_id": reviewer_id,
+            decision=decision,
-                "decision": decision,
+            notes=notes,
-                "notes": notes,
-                "reviewed_at": int(time.time()),
-            }
         )
+        db.add(review)
+        await db.commit()
 
 
 # Module-level singleton

app/marketplace/revenue_share.py

@@ -1,8 +1,8 @@
-"""Revenue share tracking and Stripe Connect payouts.
+"""Revenue share tracking and Stripe Connect payouts backed by PostgreSQL.
 
 Records every plugin installation as a revenue event and facilitates
-70 % / 30 % payouts to developers via Stripe Connect.  Storage is
+70 % / 30 % payouts to developers via Stripe Connect.  Data is persisted
-in-memory until Step 12 migrates to the ``revenue_events`` table.
+in the ``revenue_events`` table.
 
 Module-level singleton::
 
@@ -12,13 +12,16 @@ Module-level singleton::
 from __future__ import annotations
 
 import logging
-import time
+from datetime import datetime, timezone
 from typing import Any
 
 import stripe as stripe_lib
+from sqlalchemy import extract, func, select
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.config.settings import settings
 from app.marketplace.plugin_registry import registry
+from app.models import Plugin, RevenueEvent
 
 logger = logging.getLogger(__name__)
 
@@ -35,10 +38,6 @@ class RevenueShare:
     is not configured, consistent with the rest of the billing layer.
     """
 
-    def __init__(self) -> None:
-        # Step 12 replaces with revenue_events DB table
-        self._events: list[dict[str, Any]] = []
-
     # ── Helpers ──────────────────────────────────────────────────────
 
     @staticmethod
@@ -54,6 +53,7 @@ class RevenueShare:
 
     async def record_install(
         self,
+        db: AsyncSession,
         plugin_id: str,
         user_id: str,
         amount_cents: int,
@@ -72,11 +72,12 @@ class RevenueShare:
         stripe_transfer_id: str | None = None
 
         if amount_cents > 0 and self._stripe_configured():
-            plugin_entry = registry._catalog.get(plugin_id)
+            # Look up the plugin's author Stripe account from the DB
+            result = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
+            plugin_row = result.scalar_one_or_none()
             developer_stripe_account: str | None = None
-            if plugin_entry:
+            if plugin_row and plugin_row.author_id:
-                # Step 12: look up developer's Stripe account from DB
+                # Future: look up user.stripe_connect_account_id
-                # For now, the author field is used as a placeholder key.
                 developer_stripe_account = None  # no real account yet
 
             if developer_stripe_account:
@@ -103,22 +104,21 @@ class RevenueShare:
                     plugin_id,
                 )
 
-        self._events.append(
+        event = RevenueEvent(
-            {
+            plugin_id=plugin_id,
-                "plugin_id": plugin_id,
+            user_id=user_id,
-                "user_id": user_id,
+            amount_cents=amount_cents,
-                "amount_cents": amount_cents,
+            developer_share_cents=developer_share_cents,
-                "developer_share_cents": developer_share_cents,
+            stripe_transfer_id=stripe_transfer_id,
-                "stripe_transfer_id": stripe_transfer_id,
-                "paid_at": None,
-                "created_at": int(time.time()),
-            }
         )
+        db.add(event)
+        await db.commit()
 
-        await registry.record_install(plugin_id)
+        await registry.record_install(db, plugin_id)
 
     async def get_earnings(
         self,
+        db: AsyncSession,
         developer_id: str,
         period: str | None = None,
     ) -> dict[str, Any]:
@@ -136,54 +136,81 @@ class RevenueShare:
                 "developer_share_cents": int,
             }
         """
-        # Find plugin ids belonging to this developer
+        # Find plugin ids belonging to this developer (by author_name match)
-        developer_plugin_ids: set[str] = {
+        plugin_q = select(Plugin.id).where(Plugin.author_name == developer_id)
-            pid
+        plugin_result = await db.execute(plugin_q)
-            for pid, entry in registry._catalog.items()
+        developer_plugin_ids = [row[0] for row in plugin_result.all()]
-            if entry["manifest"].author == developer_id
-        }
 
-        events = [e for e in self._events if e["plugin_id"] in developer_plugin_ids]
+        if not developer_plugin_ids:
+            return {
+                "developer_id": developer_id,
+                "period": period,
+                "total_installs": 0,
+                "total_revenue_cents": 0,
+                "developer_share_cents": 0,
+            }
+
+        query = select(
+            func.count().label("total_installs"),
+            func.coalesce(func.sum(RevenueEvent.amount_cents), 0).label("total_revenue"),
+            func.coalesce(func.sum(RevenueEvent.developer_share_cents), 0).label("dev_share"),
+        ).where(RevenueEvent.plugin_id.in_(developer_plugin_ids))
 
         if period:
-            # Filter by YYYY-MM prefix of the created_at timestamp
+            # Filter by YYYY-MM: extract year and month from created_at
-            events = [
+            try:
-                e
+                year, month = period.split("-")
-                for e in events
+                query = query.where(
-                if time.strftime("%Y-%m", time.gmtime(e["created_at"])) == period
+                    extract("year", RevenueEvent.created_at) == int(year),
-            ]
+                    extract("month", RevenueEvent.created_at) == int(month),
+                )
+            except ValueError:
+                pass  # invalid period format — return all
+
+        result = await db.execute(query)
+        row = result.one()
 
         return {
             "developer_id": developer_id,
             "period": period,
-            "total_installs": len(events),
+            "total_installs": row.total_installs,
-            "total_revenue_cents": sum(e["amount_cents"] for e in events),
+            "total_revenue_cents": row.total_revenue,
-            "developer_share_cents": sum(e["developer_share_cents"] for e in events),
+            "developer_share_cents": row.dev_share,
         }
 
-    async def payout_developer(self, plugin_id: str, period: str) -> None:
+    async def payout_developer(self, db: AsyncSession, plugin_id: str, period: str) -> None:
         """Aggregate unpaid revenue for *period* and issue a Stripe Transfer.
 
         Marks processed events with ``paid_at`` timestamp.
         Stubs gracefully when Stripe is not configured.
         """
-        unpaid = [
+        try:
-            e
+            year, month = period.split("-")
-            for e in self._events
+            year_int, month_int = int(year), int(month)
-            if e["plugin_id"] == plugin_id
+        except ValueError:
-            and e["paid_at"] is None
+            logger.warning("Invalid period format: %s", period)
-            and time.strftime("%Y-%m", time.gmtime(e["created_at"])) == period
+            return
-        ]
 
-        total_dev_share = sum(e["developer_share_cents"] for e in unpaid)
+        result = await db.execute(
+            select(RevenueEvent).where(
+                RevenueEvent.plugin_id == plugin_id,
+                RevenueEvent.paid_at.is_(None),
+                extract("year", RevenueEvent.created_at) == year_int,
+                extract("month", RevenueEvent.created_at) == month_int,
+            )
+        )
+        unpaid = list(result.scalars().all())
+
+        total_dev_share = sum(e.developer_share_cents for e in unpaid)
         if total_dev_share <= 0 or not unpaid:
             logger.debug("Nothing to pay out for plugin %s in period %s", plugin_id, period)
             return
 
         if self._stripe_configured():
-            plugin_entry = registry._catalog.get(plugin_id)
+            plugin_result = await db.execute(select(Plugin).where(Plugin.id == plugin_id))
-            developer_stripe_account: str | None = None  # Step 12: fetch from DB
+            plugin_row = plugin_result.scalar_one_or_none()
-            if plugin_entry and developer_stripe_account:
+            developer_stripe_account: str | None = None  # Future: fetch from DB
+            if plugin_row and developer_stripe_account:
                 try:
                     s = self._stripe()
                     s.Transfer.create(
@@ -196,9 +223,10 @@ class RevenueShare:
                     logger.warning("Payout transfer failed for plugin %s: %s", plugin_id, exc)
                     return
 
-        paid_ts = int(time.time())
+        paid_ts = datetime.now(timezone.utc)
         for event in unpaid:
-            event["paid_at"] = paid_ts
+            event.paid_at = paid_ts
+        await db.commit()
 
 
 # Module-level singleton

app/models.py

@@ -23,7 +23,6 @@ from datetime import datetime, timezone
 
 from sqlalchemy import (
     BigInteger,
-    Boolean,
     DateTime,
     Enum,
     Float,
@@ -32,9 +31,9 @@ from sqlalchemy import (
     String,
     Text,
     UniqueConstraint,
+    Uuid,
     func,
 )
-from sqlalchemy.dialects.postgresql import UUID
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from app.db import Base
@@ -64,7 +63,7 @@ class User(Base):
     __tablename__ = "users"
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     email: Mapped[str] = mapped_column(String(255), unique=True, nullable=False, index=True)
     password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
@@ -89,10 +88,10 @@ class RefreshToken(Base):
     __tablename__ = "refresh_tokens"
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     user_id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
     )
     token_hash: Mapped[str] = mapped_column(String(64), unique=True, nullable=False, index=True)
     expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
@@ -107,10 +106,10 @@ class Subscription(Base):
     __tablename__ = "subscriptions"
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     user_id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"),
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"),
         nullable=False, unique=True, index=True
     )
     stripe_subscription_id: Mapped[str | None] = mapped_column(String(255), nullable=True, index=True)
@@ -128,10 +127,10 @@ class StorageRecord(Base):
     __tablename__ = "storage_records"
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     user_id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
     )
     table_name: Mapped[str] = mapped_column(String(100), nullable=False)
     s3_key: Mapped[str] = mapped_column(String(500), nullable=False)
@@ -149,10 +148,10 @@ class BackupMetadata(Base):
     __tablename__ = "backup_metadata"
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     user_id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
     )
     s3_key: Mapped[str] = mapped_column(String(500), nullable=False)
     version: Mapped[int] = mapped_column(Integer, nullable=False)
@@ -173,7 +172,7 @@ class Plugin(Base):
     version: Mapped[str] = mapped_column(String(50), nullable=False, default="1.0.0")
     # nullable until developer account system is built
     author_id: Mapped[str | None] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
     )
     author_name: Mapped[str] = mapped_column(String(255), nullable=False, default="")
     category: Mapped[str] = mapped_column(String(100), nullable=False, default="")
@@ -207,13 +206,13 @@ class PluginInstallation(Base):
     __table_args__ = (UniqueConstraint("plugin_id", "user_id", name="uq_plugin_user"),)
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     plugin_id: Mapped[str] = mapped_column(
         String(255), ForeignKey("plugins.id", ondelete="CASCADE"), nullable=False, index=True
     )
     user_id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
     )
     installed_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, server_default=func.now()
@@ -226,13 +225,13 @@ class PluginReview(Base):
     __tablename__ = "plugin_reviews"
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     plugin_id: Mapped[str] = mapped_column(
         String(255), ForeignKey("plugins.id", ondelete="CASCADE"), nullable=False, index=True
     )
     reviewer_id: Mapped[str | None] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="SET NULL"), nullable=True
     )
     decision: Mapped[str] = mapped_column(ReviewDecisionEnum, nullable=False)
     notes: Mapped[str | None] = mapped_column(Text, nullable=True)
@@ -250,13 +249,13 @@ class RevenueEvent(Base):
     __tablename__ = "revenue_events"
 
     id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), primary_key=True, default=_uuid
+        Uuid(as_uuid=False), primary_key=True, default=_uuid
     )
     plugin_id: Mapped[str] = mapped_column(
         String(255), ForeignKey("plugins.id", ondelete="CASCADE"), nullable=False, index=True
     )
     user_id: Mapped[str] = mapped_column(
-        UUID(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
+        Uuid(as_uuid=False), ForeignKey("users.id", ondelete="CASCADE"), nullable=False, index=True
     )
     amount_cents: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     developer_share_cents: Mapped[int] = mapped_column(Integer, nullable=False, default=0)

app/storage/blob_store.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 from typing import Any
 
 import boto3
-from botocore.exceptions import ClientError
 
 from app.config.settings import settings
 
@@ -23,12 +22,14 @@ class BlobStore:
     """
 
     def _client(self) -> Any:
-        return boto3.client(
+        kwargs: dict[str, Any] = {
-            "s3",
+            "region_name": settings.S3_REGION,
-            region_name=settings.S3_REGION,
+            "aws_access_key_id": settings.AWS_ACCESS_KEY_ID,
-            aws_access_key_id=settings.AWS_ACCESS_KEY_ID,
+            "aws_secret_access_key": settings.AWS_SECRET_ACCESS_KEY,
-            aws_secret_access_key=settings.AWS_SECRET_ACCESS_KEY,
+        }
-        )
+        if settings.S3_ENDPOINT_URL and isinstance(settings.S3_ENDPOINT_URL, str):
+            kwargs["endpoint_url"] = settings.S3_ENDPOINT_URL
+        return boto3.client("s3", **kwargs)
 
     @staticmethod
     def _key(user_id: str, table: str, record_id: str) -> str:

docker-compose.yml

@@ -1,12 +1,11 @@
-version: "3.9"
-
 services:
   app:
     build: .
     ports:
-      - "8000:8000"
+      - "8080:8000"
     env_file:
-      - .env
+      - path: .env
+        required: false
     environment:
       DATABASE_URL: postgresql+asyncpg://postgres:postgres@db:5432/adiuva
     depends_on:
@@ -34,5 +33,36 @@ services:
   #   image: redis:7-alpine
   #   restart: unless-stopped
 
+  # ── Local S3-compatible storage (MinIO) ──
+  minio:
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    volumes:
+      - minio_data:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+    restart: unless-stopped
+
+  # ── Local vector store (Qdrant) ──
+  qdrant:
+    image: qdrant/qdrant:latest
+    ports:
+      - "6333:6333"
+      - "6334:6334"
+    volumes:
+      - qdrant_data:/qdrant/storage
+    restart: unless-stopped
+
 volumes:
   postgres_data:
+  minio_data:
+  qdrant_data:

requirements.txt

@@ -1,7 +1,9 @@
 fastapi>=0.115.0
 uvicorn[standard]>=0.34.0
+gunicorn>=22.0.0
 langchain>=0.3.0
 langchain-openai>=0.3.0
+litellm>=1.50.0
 pydantic>=2.10.0
 pydantic-settings>=2.7.0
 python-jose[cryptography]>=3.3.0
@@ -15,8 +17,11 @@ bcrypt>=4.2.0
 python-dotenv>=1.0.0
 httpx>=0.28.0
 websockets>=14.0
+psycopg2-binary>=2.9.0
 pytest>=8.0.0
 pytest-asyncio>=0.24.0
+aiosqlite>=0.20.0
 moto[s3]>=5.0.0
 pinecone>=5.0.0
 qdrant-client>=1.7.0
+ruff>=0.8.0

tests/conftest.py

@@ -0,0 +1,235 @@
+"""Shared test fixtures for database-backed tests.
+
+Provides an async SQLite in-memory engine that auto-creates all tables,
+a per-test session, and a FastAPI ``TestClient`` wired to use it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import uuid
+from collections.abc import AsyncGenerator, Generator
+from unittest.mock import patch
+
+import boto3
+import pytest
+import pytest_asyncio
+from fastapi.testclient import TestClient
+from jose import jwt
+from moto import mock_aws
+from sqlalchemy import StaticPool, event
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from app.config.settings import settings
+from app.db import Base, get_session
+from app.main import app
+from app.models import Plugin, Subscription, User
+
+# ── Fixed test user IDs (one per tier) ───────────────────────────────
+
+TEST_USER_IDS: dict[str, str] = {
+    "free": "00000000-0000-0000-0000-000000000001",
+    "pro": "00000000-0000-0000-0000-000000000002",
+    "power": "00000000-0000-0000-0000-000000000003",
+    "team": "00000000-0000-0000-0000-000000000004",
+}
+
+# ── Async SQLite engine ──────────────────────────────────────────────
+
+_TEST_ENGINE = create_async_engine(
+    "sqlite+aiosqlite://",
+    connect_args={"check_same_thread": False},
+    poolclass=StaticPool,
+)
+
+_TestSessionLocal = async_sessionmaker(
+    _TEST_ENGINE,
+    expire_on_commit=False,
+)
+
+
+# Enable foreign key enforcement for SQLite (off by default).
+@event.listens_for(_TEST_ENGINE.sync_engine, "connect")
+def _set_sqlite_pragma(dbapi_conn, _connection_record):  # noqa: ANN001
+    cursor = dbapi_conn.cursor()
+    cursor.execute("PRAGMA foreign_keys=ON")
+    cursor.close()
+
+
+# ── Fixtures ─────────────────────────────────────────────────────────
+
+@pytest_asyncio.fixture(autouse=True)
+async def _create_tables():
+    """Create all tables before each test, seed test users, then drop after."""
+    async with _TEST_ENGINE.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+    # Seed one User + Subscription per tier so FK constraints and auth work.
+    async with _TestSessionLocal() as session:
+        for tier, uid in TEST_USER_IDS.items():
+            session.add(User(
+                id=uid,
+                email=f"{tier}@test.com",
+                password_hash="$2b$12$fakehashfortesting000000000000000000000000000",
+                tier=tier,
+            ))
+            session.add(Subscription(
+                id=str(uuid.uuid4()),
+                user_id=uid,
+                tier=tier,
+                stripe_subscription_id=f"sub_test_{tier}",
+                status="active",
+            ))
+        await session.commit()
+
+    yield
+    async with _TEST_ENGINE.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+
+
+@pytest_asyncio.fixture
+async def db_session() -> AsyncGenerator[AsyncSession, None]:
+    """Yield a per-test async DB session."""
+    async with _TestSessionLocal() as session:
+        yield session
+
+
+@pytest.fixture
+def client(db_session: AsyncSession) -> Generator[TestClient, None, None]:   # noqa: ANN001
+    """FastAPI test client with ``get_session`` overridden to use the test DB."""
+
+    async def _override_get_session() -> AsyncGenerator[AsyncSession, None]:
+        yield db_session
+
+    app.dependency_overrides[get_session] = _override_get_session
+    with TestClient(app) as c:
+        yield c
+    app.dependency_overrides.pop(get_session, None)
+
+
+# ── Seed data helpers ────────────────────────────────────────────────
+
+_SEED_PLUGINS = [
+    Plugin(
+        id="plugin-github-sync",
+        name="GitHub Sync",
+        description="Sync tasks with GitHub Issues and pull requests.",
+        version="1.0.0",
+        author_name="Adiuva",
+        category="productivity",
+        price_cents=0,
+        permissions=json.dumps(["read:tasks", "write:tasks"]),
+        status="approved",
+        s3_package_key="plugins/plugin-github-sync/1.0.0/package.zip",
+        install_count=0,
+        avg_rating=0.0,
+    ),
+    Plugin(
+        id="plugin-slack-notify",
+        name="Slack Notifier",
+        description="Post task and checkpoint updates to Slack channels.",
+        version="1.2.0",
+        author_name="Adiuva",
+        category="communication",
+        price_cents=499,
+        permissions=json.dumps(["read:tasks", "read:checkpoints"]),
+        status="approved",
+        s3_package_key="plugins/plugin-slack-notify/1.2.0/package.zip",
+        install_count=0,
+        avg_rating=0.0,
+    ),
+    Plugin(
+        id="plugin-time-tracker",
+        name="Time Tracker",
+        description="Track time spent on tasks with automatic reporting.",
+        version="0.9.1",
+        author_name="Third Party",
+        category="productivity",
+        price_cents=999,
+        permissions=json.dumps(["read:tasks", "write:tasks"]),
+        status="approved",
+        s3_package_key="plugins/plugin-time-tracker/0.9.1/package.zip",
+        install_count=0,
+        avg_rating=0.0,
+    ),
+]
+
+
+@pytest_asyncio.fixture
+async def seed_plugins(db_session: AsyncSession) -> list[Plugin]:
+    """Insert the 3 default approved plugins and return them."""
+    plugins = []
+    for template in _SEED_PLUGINS:
+        p = Plugin(
+            id=template.id,
+            name=template.name,
+            description=template.description,
+            version=template.version,
+            author_name=template.author_name,
+            category=template.category,
+            price_cents=template.price_cents,
+            permissions=template.permissions,
+            status=template.status,
+            s3_package_key=template.s3_package_key,
+            install_count=template.install_count,
+            avg_rating=template.avg_rating,
+        )
+        db_session.add(p)
+        plugins.append(p)
+    await db_session.commit()
+    return plugins
+
+
+# ── JWT helpers ──────────────────────────────────────────────────────
+
+
+def make_jwt(
+    tier: str = "power",
+    user_id: str | None = None,
+    email: str | None = None,
+) -> str:
+    """Create a signed test JWT.
+
+    Uses the fixed ``TEST_USER_IDS`` mapping so the auth middleware can
+    find the corresponding ``Subscription`` row in the test database.
+    """
+    uid = user_id or TEST_USER_IDS.get(tier, str(uuid.uuid4()))
+    now = int(time.time())
+    payload = {
+        "sub": uid,
+        "email": email or f"{tier}@test.com",
+        "tier": tier,
+        "exp": now + 3600,
+        "iat": now,
+    }
+    return jwt.encode(payload, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
+
+
+def auth_header(tier: str = "power", user_id: str | None = None) -> dict[str, str]:
+    """Return an Authorization header dict for the given tier."""
+    return {"Authorization": f"Bearer {make_jwt(tier, user_id)}"}
+
+
+# ── S3 mock fixture ──────────────────────────────────────────────────
+
+S3_TEST_BUCKET = "test-bucket"
+S3_TEST_REGION = "us-east-1"
+
+
+@pytest.fixture
+def s3_bucket():
+    """Create a mocked S3 bucket via moto and patch BlobStore settings."""
+    with mock_aws():
+        os.environ.setdefault("AWS_ACCESS_KEY_ID", "testing")
+        os.environ.setdefault("AWS_SECRET_ACCESS_KEY", "testing")
+        os.environ.setdefault("AWS_DEFAULT_REGION", S3_TEST_REGION)
+        client = boto3.client("s3", region_name=S3_TEST_REGION)
+        client.create_bucket(Bucket=S3_TEST_BUCKET)
+        with patch("app.storage.blob_store.settings") as mock_settings:
+            mock_settings.S3_BUCKET = S3_TEST_BUCKET
+            mock_settings.S3_REGION = S3_TEST_REGION
+            mock_settings.AWS_ACCESS_KEY_ID = "testing"
+            mock_settings.AWS_SECRET_ACCESS_KEY = "testing"
+            yield S3_TEST_BUCKET

tests/test_agents.py

@@ -102,21 +102,21 @@ class TestTaskAgent:
 
     @pytest.mark.asyncio
     async def test_handle_returns_string(self) -> None:
-        with patch("app.agents.task_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.task_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Task created.")
             result = await TaskAgent().handle("create a task", {})
         assert isinstance(result, str)
 
     @pytest.mark.asyncio
     async def test_handle_no_tool_calls(self) -> None:
-        with patch("app.agents.task_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.task_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Here are your tasks.")
             result = await TaskAgent().handle("list my tasks", {})
         assert result == "Here are your tasks."
 
     @pytest.mark.asyncio
     async def test_handle_with_create_task_tool_call(self) -> None:
-        with patch("app.agents.task_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.task_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm_with_tool_call(
                 "create_task",
                 {"title": "Buy groceries", "priority": "low"},
@@ -127,7 +127,7 @@ class TestTaskAgent:
 
     @pytest.mark.asyncio
     async def test_handle_accepts_empty_context(self) -> None:
-        with patch("app.agents.task_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.task_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Done.")
             result = await TaskAgent().handle("help", {})
         assert isinstance(result, str)
@@ -138,7 +138,7 @@ class TestTaskAgent:
             "user_profile": {"id": "u1", "tier": "pro"},
             "recent_tasks": [{"id": "t1", "title": "Old task"}],
         }
-        with patch("app.agents.task_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.task_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Tasks listed.")
             result = await TaskAgent().handle("show tasks", context)
         assert isinstance(result, str)
@@ -273,14 +273,14 @@ class TestCheckpointAgent:
 
     @pytest.mark.asyncio
     async def test_handle_no_tool_calls(self) -> None:
-        with patch("app.agents.checkpoint_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.checkpoint_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("No checkpoints found.")
             result = await CheckpointAgent().handle("list checkpoints", {})
         assert result == "No checkpoints found."
 
     @pytest.mark.asyncio
     async def test_handle_with_create_tool_call(self) -> None:
-        with patch("app.agents.checkpoint_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.checkpoint_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm_with_tool_call(
                 "create_checkpoint",
                 {"project_id": "p1", "title": "MVP Launch", "date": 1700000000000},
@@ -291,7 +291,7 @@ class TestCheckpointAgent:
 
     @pytest.mark.asyncio
     async def test_handle_accepts_empty_context(self) -> None:
-        with patch("app.agents.checkpoint_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.checkpoint_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Done.")
             result = await CheckpointAgent().handle("show milestones", {})
         assert isinstance(result, str)
@@ -397,14 +397,14 @@ class TestProjectAgent:
 
     @pytest.mark.asyncio
     async def test_handle_no_tool_calls(self) -> None:
-        with patch("app.agents.project_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.project_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Project Alpha is active.")
             result = await ProjectAgent().handle("show my projects", {})
         assert result == "Project Alpha is active."
 
     @pytest.mark.asyncio
     async def test_handle_with_create_project_tool_call(self) -> None:
-        with patch("app.agents.project_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.project_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm_with_tool_call(
                 "create_project",
                 {"name": "Pippo"},
@@ -415,7 +415,7 @@ class TestProjectAgent:
 
     @pytest.mark.asyncio
     async def test_handle_accepts_empty_context(self) -> None:
-        with patch("app.agents.project_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.project_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Done.")
             result = await ProjectAgent().handle("archive old project", {})
         assert isinstance(result, str)
@@ -515,14 +515,14 @@ class TestNoteAgent:
 
     @pytest.mark.asyncio
     async def test_handle_no_tool_calls(self) -> None:
-        with patch("app.agents.note_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.note_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Note created.")
             result = await NoteAgent().handle("create a note", {})
         assert result == "Note created."
 
     @pytest.mark.asyncio
     async def test_handle_with_create_note_tool_call(self) -> None:
-        with patch("app.agents.note_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.note_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm_with_tool_call(
                 "create_note",
                 {"title": "Daily log", "content": "# Today\nAll good."},
@@ -533,7 +533,7 @@ class TestNoteAgent:
 
     @pytest.mark.asyncio
     async def test_handle_accepts_empty_context(self) -> None:
-        with patch("app.agents.note_agent.ChatOpenAI") as mock_cls:
+        with patch("app.agents.note_agent.get_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("Done.")
             result = await NoteAgent().handle("show notes", {})
         assert isinstance(result, str)

tests/test_auth.py

@@ -0,0 +1,206 @@
+"""Tests for auth routes: register, login, refresh, me.
+
+Exercises the full auth lifecycle through the FastAPI TestClient against the
+in-memory SQLite test database seeded by ``conftest.py``.
+"""
+
+from __future__ import annotations
+
+import time
+
+from jose import jwt
+
+from app.config.settings import settings
+from tests.conftest import auth_header, TEST_USER_IDS
+
+
+# ── TestRegister ──────────────────────────────────────────────────────
+
+
+class TestRegister:
+    """POST /api/v1/auth/register"""
+
+    def test_register_success(self, client) -> None:
+        resp = client.post(
+            "/api/v1/auth/register",
+            json={"email": "new@example.com", "password": "Str0ngP@ss!"},
+        )
+        assert resp.status_code == 201
+        data = resp.json()
+        assert "access_token" in data
+        assert "refresh_token" in data
+        assert "expires_at" in data
+        # expires_at should be a future millisecond timestamp
+        assert data["expires_at"] > int(time.time() * 1000)
+
+    def test_register_returns_valid_jwt(self, client) -> None:
+        resp = client.post(
+            "/api/v1/auth/register",
+            json={"email": "jwt-check@example.com", "password": "P@ss1234"},
+        )
+        assert resp.status_code == 201
+        token = resp.json()["access_token"]
+        payload = jwt.decode(token, settings.JWT_SECRET, algorithms=[settings.JWT_ALGORITHM])
+        assert payload["email"] == "jwt-check@example.com"
+        assert payload["tier"] == "free"
+        assert "sub" in payload
+
+    def test_register_duplicate_email(self, client) -> None:
+        client.post(
+            "/api/v1/auth/register",
+            json={"email": "dupe@example.com", "password": "Pass1234"},
+        )
+        resp = client.post(
+            "/api/v1/auth/register",
+            json={"email": "dupe@example.com", "password": "Pass5678"},
+        )
+        assert resp.status_code == 409
+
+    def test_register_missing_password(self, client) -> None:
+        resp = client.post(
+            "/api/v1/auth/register",
+            json={"email": "no-pass@example.com"},
+        )
+        assert resp.status_code == 422
+
+    def test_register_missing_email(self, client) -> None:
+        resp = client.post(
+            "/api/v1/auth/register",
+            json={"password": "OnlyPass"},
+        )
+        assert resp.status_code == 422
+
+
+# ── TestLogin ─────────────────────────────────────────────────────────
+
+
+class TestLogin:
+    """POST /api/v1/auth/login"""
+
+    def _register(self, client, email="login@example.com", password="MyP@ss123"):
+        client.post(
+            "/api/v1/auth/register",
+            json={"email": email, "password": password},
+        )
+
+    def test_login_success(self, client) -> None:
+        self._register(client)
+        resp = client.post(
+            "/api/v1/auth/login",
+            json={"email": "login@example.com", "password": "MyP@ss123"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "access_token" in data
+        assert "refresh_token" in data
+        assert "expires_at" in data
+
+    def test_login_wrong_password(self, client) -> None:
+        self._register(client)
+        resp = client.post(
+            "/api/v1/auth/login",
+            json={"email": "login@example.com", "password": "WrongPass!"},
+        )
+        assert resp.status_code == 401
+
+    def test_login_unknown_email(self, client) -> None:
+        resp = client.post(
+            "/api/v1/auth/login",
+            json={"email": "ghost@example.com", "password": "Whatever"},
+        )
+        assert resp.status_code == 401
+
+
+# ── TestRefresh ───────────────────────────────────────────────────────
+
+
+class TestRefresh:
+    """POST /api/v1/auth/refresh"""
+
+    def _register_and_get_tokens(self, client, email="refresh@example.com"):
+        resp = client.post(
+            "/api/v1/auth/register",
+            json={"email": email, "password": "RefPass123!"},
+        )
+        return resp.json()
+
+    def test_refresh_returns_new_tokens(self, client) -> None:
+        tokens = self._register_and_get_tokens(client)
+        resp = client.post(
+            "/api/v1/auth/refresh",
+            json={"refresh_token": tokens["refresh_token"]},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "access_token" in data
+        assert "refresh_token" in data
+        # New refresh token should differ from old one (rotation)
+        assert data["refresh_token"] != tokens["refresh_token"]
+
+    def test_refresh_old_token_rejected(self, client) -> None:
+        """After rotation, the original refresh token must be rejected."""
+        tokens = self._register_and_get_tokens(client, email="rotate@example.com")
+        old_rt = tokens["refresh_token"]
+
+        # First refresh succeeds and rotates the token
+        client.post("/api/v1/auth/refresh", json={"refresh_token": old_rt})
+
+        # Second attempt with the old token must fail
+        resp = client.post("/api/v1/auth/refresh", json={"refresh_token": old_rt})
+        assert resp.status_code == 401
+
+    def test_refresh_bogus_token(self, client) -> None:
+        resp = client.post(
+            "/api/v1/auth/refresh",
+            json={"refresh_token": "not-a-real-token"},
+        )
+        assert resp.status_code == 401
+
+
+# ── TestMe ────────────────────────────────────────────────────────────
+
+
+class TestMe:
+    """GET /api/v1/auth/me"""
+
+    def test_me_with_valid_jwt(self, client) -> None:
+        resp = client.get("/api/v1/auth/me", headers=auth_header("power"))
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["id"] == TEST_USER_IDS["power"]
+        assert data["email"] == "power@test.com"
+        assert data["tier"] == "power"
+
+    def test_me_returns_correct_tier(self, client) -> None:
+        """Tier comes from the live subscription row, not the JWT claim."""
+        resp = client.get("/api/v1/auth/me", headers=auth_header("free"))
+        assert resp.json()["tier"] == "free"
+
+    def test_me_missing_token(self, client) -> None:
+        resp = client.get("/api/v1/auth/me")
+        assert resp.status_code == 401
+
+    def test_me_expired_token(self, client) -> None:
+        """A JWT with ``exp`` in the past must be rejected."""
+        payload = {
+            "sub": TEST_USER_IDS["power"],
+            "email": "power@test.com",
+            "tier": "power",
+            "exp": int(time.time()) - 3600,  # 1 hour ago
+            "iat": int(time.time()) - 7200,
+        }
+        token = jwt.encode(payload, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
+        resp = client.get("/api/v1/auth/me", headers={"Authorization": f"Bearer {token}"})
+        assert resp.status_code == 401
+
+    def test_me_invalid_signature(self, client) -> None:
+        payload = {
+            "sub": TEST_USER_IDS["power"],
+            "email": "power@test.com",
+            "tier": "power",
+            "exp": int(time.time()) + 3600,
+            "iat": int(time.time()),
+        }
+        token = jwt.encode(payload, "wrong-secret", algorithm="HS256")
+        resp = client.get("/api/v1/auth/me", headers={"Authorization": f"Bearer {token}"})
+        assert resp.status_code == 401

tests/test_backup.py

@@ -0,0 +1,243 @@
+"""Tests for backup routes: upload, download, history, delete.
+
+Exercises the backup lifecycle through the FastAPI TestClient against the
+in-memory SQLite test database and moto-mocked S3 bucket.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+
+from tests.conftest import auth_header, TEST_USER_IDS
+
+
+# ── Helpers ───────────────────────────────────────────────────────────
+
+_BLOB = b"encrypted-backup-blob-opaque-bytes"
+_CHECKSUM = hashlib.sha256(_BLOB).hexdigest()
+_VERSION = 1
+_TIMESTAMP = 1700000000000  # arbitrary ms timestamp
+
+
+def _backup_headers(tier: str = "power", **overrides) -> dict[str, str]:
+    """Return auth + backup metadata headers."""
+    headers = auth_header(tier)
+    headers["X-Backup-Version"] = str(overrides.get("version", _VERSION))
+    headers["X-Backup-Timestamp"] = str(overrides.get("timestamp", _TIMESTAMP))
+    headers["X-Backup-Checksum"] = overrides.get("checksum", _CHECKSUM)
+    headers["Content-Type"] = "application/octet-stream"
+    return headers
+
+
+def _upload(client, tier="power", **overrides) -> "Response":  # noqa: F821
+    """Upload a backup blob and return the response."""
+    return client.put(
+        "/api/v1/backup",
+        content=overrides.pop("blob", _BLOB),
+        headers=_backup_headers(tier, **overrides),
+    )
+
+
+# ── TestUploadBackup ──────────────────────────────────────────────────
+
+
+class TestUploadBackup:
+    """PUT /api/v1/backup"""
+
+    def test_upload_success(self, client, s3_bucket) -> None:
+        resp = _upload(client, tier="power")
+        assert resp.status_code == 200
+        assert resp.json() == {"ok": True}
+
+    def test_upload_creates_history_entry(self, client, s3_bucket) -> None:
+        _upload(client, tier="power")
+        history = client.get(
+            "/api/v1/backup/history", headers=auth_header("power")
+        ).json()
+        assert len(history) == 1
+        assert history[0]["version"] == _VERSION
+        assert history[0]["timestamp"] == _TIMESTAMP
+        assert history[0]["checksum"] == _CHECKSUM
+
+    def test_upload_bad_checksum(self, client, s3_bucket) -> None:
+        resp = _upload(client, tier="power", checksum="0" * 64)
+        assert resp.status_code == 400
+
+    def test_upload_free_tier_blocked(self, client, s3_bucket) -> None:
+        """Free tier has backup_gb=0 → should return 402."""
+        resp = _upload(client, tier="free")
+        assert resp.status_code == 402
+
+    def test_upload_pro_tier_allowed(self, client, s3_bucket) -> None:
+        """Pro tier has backup_gb=5 → small blob succeeds."""
+        resp = _upload(client, tier="pro")
+        assert resp.status_code == 200
+
+
+# ── TestDownloadBackup ────────────────────────────────────────────────
+
+
+class TestDownloadBackup:
+    """GET /api/v1/backup"""
+
+    def test_download_latest(self, client, s3_bucket) -> None:
+        _upload(client, tier="power")
+        resp = client.get("/api/v1/backup", headers=auth_header("power"))
+        assert resp.status_code == 200
+        assert resp.content == _BLOB
+        assert resp.headers["X-Checksum"] == _CHECKSUM
+        assert resp.headers["X-Backup-Version"] == str(_VERSION)
+
+    def test_download_no_backup_returns_404(self, client, s3_bucket) -> None:
+        resp = client.get("/api/v1/backup", headers=auth_header("power"))
+        assert resp.status_code == 404
+
+    def test_download_if_modified_since_returns_304(self, client, s3_bucket) -> None:
+        """When If-Modified-Since is after the backup timestamp → 304."""
+        _upload(client, tier="power", timestamp=1700000000000)
+        resp = client.get(
+            "/api/v1/backup",
+            headers={
+                **auth_header("power"),
+                "If-Modified-Since": "Thu, 01 Jan 2099 00:00:00 GMT",
+            },
+        )
+        assert resp.status_code == 304
+
+    def test_download_if_modified_since_returns_200(self, client, s3_bucket) -> None:
+        """When If-Modified-Since is before the backup timestamp → serve blob."""
+        _upload(client, tier="power", timestamp=1700000000000)
+        resp = client.get(
+            "/api/v1/backup",
+            headers={
+                **auth_header("power"),
+                "If-Modified-Since": "Thu, 01 Jan 2000 00:00:00 GMT",
+            },
+        )
+        assert resp.status_code == 200
+        assert resp.content == _BLOB
+
+    def test_download_multiple_returns_latest(self, client, s3_bucket) -> None:
+        """When multiple backups exist, GET returns the one with the highest timestamp."""
+        _upload(client, tier="power", timestamp=1000)
+        blob2 = b"second-encrypted-backup"
+        checksum2 = hashlib.sha256(blob2).hexdigest()
+        _upload(client, tier="power", timestamp=2000, blob=blob2, checksum=checksum2)
+        resp = client.get("/api/v1/backup", headers=auth_header("power"))
+        assert resp.status_code == 200
+        assert resp.content == blob2
+
+
+# ── TestBackupHistory ─────────────────────────────────────────────────
+
+
+class TestBackupHistory:
+    """GET /api/v1/backup/history"""
+
+    def test_history_empty(self, client, s3_bucket) -> None:
+        resp = client.get("/api/v1/backup/history", headers=auth_header("power"))
+        assert resp.status_code == 200
+        assert resp.json() == []
+
+    def test_history_returns_entries(self, client, s3_bucket) -> None:
+        _upload(client, tier="power", timestamp=1000)
+        _upload(client, tier="power", timestamp=2000)
+        history = client.get(
+            "/api/v1/backup/history", headers=auth_header("power")
+        ).json()
+        assert len(history) == 2
+        # Ordered by timestamp descending
+        assert history[0]["timestamp"] == 2000
+        assert history[1]["timestamp"] == 1000
+
+    def test_history_isolated_per_user(self, client, s3_bucket) -> None:
+        """One user's backups should not appear in another user's history."""
+        _upload(client, tier="power")
+        resp = client.get("/api/v1/backup/history", headers=auth_header("team"))
+        assert resp.json() == []
+
+
+# ── TestDeleteBackup ──────────────────────────────────────────────────
+
+
+class TestDeleteBackup:
+    """DELETE /api/v1/backup/{backup_id}"""
+
+    def _get_backup_id(self, client, tier="power") -> str:
+        """Upload a backup and return its DB id from history."""
+        _upload(client, tier=tier)
+        client.get(
+            "/api/v1/backup/history", headers=auth_header(tier)
+        ).json()
+        # History returns BackupMetadata schema which doesn't have `id`.
+        # We need to look it up via a different means.
+        # Since there's only 1 backup, find via history length.
+        # Actually the schema doesn't return id — let's verify via re-download.
+        # We'll use a workaround: upload, then list history to confirm it exists,
+        # then try to delete — but we need the id...
+        # Let's check if history includes an id field.
+        # The schema is: version, timestamp, checksum, chunk_count — no id.
+        # We'll need to query the DB directly or use a known ID.
+        # For testing, we'll search history then use the DB.
+        return None  # pragma: no cover — overridden below
+
+    def test_delete_success(self, client, s3_bucket, db_session) -> None:
+        _upload(client, tier="power")
+
+        # Discover the backup_id via direct DB query
+        import asyncio
+        from sqlalchemy import select
+        from app.models import BackupMetadata
+
+        async def _get_id():
+            result = await db_session.execute(
+                select(BackupMetadata.id).where(
+                    BackupMetadata.user_id == TEST_USER_IDS["power"]
+                )
+            )
+            return result.scalar_one()
+
+        backup_id = asyncio.get_event_loop().run_until_complete(_get_id())
+
+        resp = client.delete(
+            f"/api/v1/backup/{backup_id}", headers=auth_header("power")
+        )
+        assert resp.status_code == 200
+        assert resp.json() == {"ok": True}
+
+        # History should now be empty
+        history = client.get(
+            "/api/v1/backup/history", headers=auth_header("power")
+        ).json()
+        assert history == []
+
+    def test_delete_nonexistent(self, client, s3_bucket) -> None:
+        resp = client.delete(
+            "/api/v1/backup/no-such-id", headers=auth_header("power")
+        )
+        assert resp.status_code == 404
+
+    def test_delete_other_users_backup(self, client, s3_bucket, db_session) -> None:
+        """Cannot delete another user's backup (ownership check returns 404)."""
+        _upload(client, tier="power")
+
+        import asyncio
+        from sqlalchemy import select
+        from app.models import BackupMetadata
+
+        async def _get_id():
+            result = await db_session.execute(
+                select(BackupMetadata.id).where(
+                    BackupMetadata.user_id == TEST_USER_IDS["power"]
+                )
+            )
+            return result.scalar_one()
+
+        backup_id = asyncio.get_event_loop().run_until_complete(_get_id())
+
+        # team user tries to delete power user's backup → 404
+        resp = client.delete(
+            f"/api/v1/backup/{backup_id}", headers=auth_header("team")
+        )
+        assert resp.status_code == 404

tests/test_middleware.py

@@ -18,13 +18,30 @@ from fastapi.testclient import TestClient
 from jose import jwt
 
 from app.config.settings import settings
+from app.db import get_session
 from app.main import app
 from app.schemas import ChatResponse
+from tests.conftest import TEST_USER_IDS
 
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
 
+# ---------------------------------------------------------------------------
+# Autouse: redirect all DB access to the in-memory SQLite test engine.
+# ---------------------------------------------------------------------------
+
+@pytest.fixture(autouse=True)
+def _override_db(db_session):
+    """Route all get_session calls to the test SQLite session."""
+    async def _gen():
+        yield db_session
+
+    app.dependency_overrides[get_session] = _gen
+    yield
+    app.dependency_overrides.pop(get_session, None)
+
+
 _CHAT_BODY = {
     "message": "hello",
     "context": {
@@ -74,14 +91,15 @@ class TestAuthMiddleware:
     """Tests exercised via GET /api/v1/auth/me."""
 
     def test_valid_token_returns_profile(self) -> None:
-        uid = str(uuid.uuid4())
+        # Use the seeded pro user so the subscription lookup returns 'pro'.
-        token = _make_jwt(user_id=uid, email="alice@example.com", tier="pro")
+        uid = TEST_USER_IDS["pro"]
+        token = _make_jwt(user_id=uid, email="pro@test.com", tier="pro")
         with TestClient(app) as client:
             resp = client.get("/api/v1/auth/me", headers=_auth_header(token))
         assert resp.status_code == 200
         data = resp.json()
         assert data["id"] == uid
-        assert data["email"] == "alice@example.com"
+        assert data["email"] == "pro@test.com"
         assert data["tier"] == "pro"
 
     def test_missing_token_returns_401(self) -> None:

tests/test_orchestrator.py

@@ -16,7 +16,7 @@ from app.core.orchestrator import (
     route_pipeline,
     route_single,
 )
-from app.schemas import ChatContext, ChatRequest, ChatResponse, ExecutionPlan
+from app.schemas import ChatRequest, ChatResponse, ExecutionPlan
 
 
 # ── Stub agents ──────────────────────────────────────────────────────
@@ -87,21 +87,21 @@ def reg() -> AgentRegistry:
 class TestClassifyIntent:
     @pytest.mark.asyncio
     async def test_routes_to_known_agent(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             result = await classify_intent("add a task", {}, reg)
         assert result == "task_agent"
 
     @pytest.mark.asyncio
     async def test_routes_to_calendar_agent(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("calendar_agent")
             result = await classify_intent("schedule a meeting", {}, reg)
         assert result == "calendar_agent"
 
     @pytest.mark.asyncio
     async def test_falls_back_on_unknown_name(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("nonexistent_agent")
             result = await classify_intent("do something", {}, reg)
         assert result == "task_agent"
@@ -110,14 +110,14 @@ class TestClassifyIntent:
     async def test_empty_registry_returns_fallback_without_llm_call(self) -> None:
         empty_reg = AgentRegistry()
         # No LLM should be instantiated — early return path
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             result = await classify_intent("anything", {}, empty_reg)
             mock_cls.assert_not_called()
         assert result == "task_agent"
 
     @pytest.mark.asyncio
     async def test_whitespace_stripped_from_response(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("  task_agent  \n")
             result = await classify_intent("create task", {}, reg)
         assert result == "task_agent"
@@ -154,7 +154,7 @@ class TestRouteSingle:
 class TestRoutePipeline:
     @pytest.mark.asyncio
     async def test_returns_chat_response(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("synthesized result")
             result = await route_pipeline(
                 ["task_agent", "calendar_agent"], "plan my week", {}, reg
@@ -163,7 +163,7 @@ class TestRoutePipeline:
 
     @pytest.mark.asyncio
     async def test_response_is_synthesis_output(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("synthesized result")
             result = await route_pipeline(
                 ["task_agent", "calendar_agent"], "plan my week", {}, reg
@@ -193,7 +193,7 @@ class TestRoutePipeline:
 
         reg.register(_CapturingAgent)
 
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("done")
             await route_pipeline(["task_agent", "capture"], "hi", {}, reg)
 
@@ -204,7 +204,7 @@ class TestRoutePipeline:
 
     @pytest.mark.asyncio
     async def test_single_agent_pipeline(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("single result")
             result = await route_pipeline(["task_agent"], "one agent", {}, reg)
         assert result.response == "single result"
@@ -218,7 +218,7 @@ class TestOrchestrate:
     async def test_direct_mode_returns_chat_response(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="add a task", execution_mode="direct")
             result = await orchestrate(request, reg)
@@ -226,7 +226,7 @@ class TestOrchestrate:
 
     @pytest.mark.asyncio
     async def test_direct_mode_response_content(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="add a task", execution_mode="direct")
             result = await orchestrate(request, reg)
@@ -237,7 +237,7 @@ class TestOrchestrate:
     async def test_plan_mode_returns_execution_plan(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="plan my tasks", execution_mode="plan")
             result = await orchestrate(request, reg)
@@ -247,7 +247,7 @@ class TestOrchestrate:
     async def test_plan_mode_agent_matches_classified(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("calendar_agent")
             request = ChatRequest(
                 message="schedule something", execution_mode="plan"
@@ -258,7 +258,7 @@ class TestOrchestrate:
 
     @pytest.mark.asyncio
     async def test_plan_mode_has_steps(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="plan tasks", execution_mode="plan")
             result = await orchestrate(request, reg)
@@ -269,7 +269,7 @@ class TestOrchestrate:
     async def test_plan_mode_template_id_contains_agent_name(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="plan tasks", execution_mode="plan")
             result = await orchestrate(request, reg)
@@ -281,7 +281,7 @@ class TestOrchestrate:
     async def test_default_execution_mode_is_direct(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             # execution_mode defaults to "direct"
             request = ChatRequest(message="help me")
@@ -295,7 +295,7 @@ class TestOrchestrate:
 class TestOrchestrateStream:
     @pytest.mark.asyncio
     async def test_yields_at_least_one_chunk(self, reg: AgentRegistry) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="add a task", execution_mode="direct")
             chunks = [chunk async for chunk in orchestrate_stream(request, reg)]
@@ -305,7 +305,7 @@ class TestOrchestrateStream:
     async def test_last_chunk_is_final_json_frame(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="add a task", execution_mode="direct")
             chunks = [chunk async for chunk in orchestrate_stream(request, reg)]
@@ -319,7 +319,7 @@ class TestOrchestrateStream:
     async def test_final_frame_response_matches_agent_output(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(message="create a task", execution_mode="direct")
             chunks = [chunk async for chunk in orchestrate_stream(request, reg)]
@@ -331,7 +331,7 @@ class TestOrchestrateStream:
     async def test_text_chunks_before_final_frame(
         self, reg: AgentRegistry
     ) -> None:
-        with patch("app.core.orchestrator.ChatOpenAI") as mock_cls:
+        with patch("app.core.orchestrator._make_llm") as mock_cls:
             mock_cls.return_value = _mock_llm("task_agent")
             request = ChatRequest(
                 message="x" * 200, execution_mode="direct"

tests/test_plugins.py

@@ -1,52 +1,32 @@
-"""Tests for Step 10: Plugin Marketplace.
+"""Tests for Step 10+12: Plugin Marketplace (DB-backed).
 
 Covers:
-  - PluginRegistry: catalog management, filtering, sorting, install counts
+  - PluginRegistry: catalog management, filtering, sorting, install counts (PostgreSQL)
   - ReviewQueue: pending queue, review decisions, manifest security checklist
-  - RevenueShare: install event recording, earnings aggregation
+  - RevenueShare: install event recording, earnings aggregation (PostgreSQL)
   - Route integration: tier gate, list/get/install/uninstall via TestClient
 """
 
 from __future__ import annotations
 
-import time
 import uuid
 
 import pytest
-import pytest_asyncio
+from sqlalchemy import select
-from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import AsyncSession
-from jose import jwt
-from unittest.mock import patch
 
-from app.config.settings import settings
-from app.main import app
 from app.marketplace.plugin_registry import PluginRegistry
 from app.marketplace.plugin_review import ReviewQueue, validate_manifest
 from app.marketplace.revenue_share import RevenueShare
+from app.models import Plugin, PluginReview as PluginReviewModel, RevenueEvent
 from app.schemas import PluginManifest
+from tests.conftest import TEST_USER_IDS, auth_header
 
 # ---------------------------------------------------------------------------
 # Helpers
 # ---------------------------------------------------------------------------
 
 
-def _make_jwt(tier: str = "power", user_id: str | None = None) -> str:
-    uid = user_id or str(uuid.uuid4())
-    now = int(time.time())
-    payload = {
-        "sub": uid,
-        "email": f"{uid[:8]}@example.com",
-        "tier": tier,
-        "exp": now + 3600,
-        "iat": now,
-    }
-    return jwt.encode(payload, settings.JWT_SECRET, algorithm=settings.JWT_ALGORITHM)
-
-
-def _auth(tier: str = "power") -> dict[str, str]:
-    return {"Authorization": f"Bearer {_make_jwt(tier)}"}
-
-
 def _fresh_manifest(
     plugin_id: str | None = None,
     category: str = "productivity",
@@ -67,118 +47,150 @@ def _fresh_manifest(
 
 
 # ---------------------------------------------------------------------------
-# PluginRegistry
+# PluginRegistry (DB-backed)
 # ---------------------------------------------------------------------------
 
 
 class TestPluginRegistry:
-    """Each test uses a fresh PluginRegistry instance to avoid catalog pollution."""
+    """Each test uses the conftest db_session fixture with a fresh in-memory DB."""
 
     @pytest.fixture
     def reg(self) -> PluginRegistry:
         return PluginRegistry()
 
     @pytest.mark.asyncio
-    async def test_seed_plugins_are_approved(self, reg: PluginRegistry) -> None:
+    async def test_seed_plugins_are_listed(
-        result = await reg.list_plugins()
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
+    ) -> None:
+        result = await reg.list_plugins(db_session)
         assert result.total == 3
         assert all(p.id.startswith("plugin-") for p in result.plugins)
 
     @pytest.mark.asyncio
-    async def test_list_approved_only(self, reg: PluginRegistry) -> None:
+    async def test_list_approved_only(
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
+    ) -> None:
         manifest = _fresh_manifest()
-        await reg.submit_plugin(manifest, "plugins/key.zip")
+        await reg.submit_plugin(db_session, manifest, "plugins/key.zip")
-        result = await reg.list_plugins()
+        result = await reg.list_plugins(db_session)
         ids = [p.id for p in result.plugins]
         assert manifest.id not in ids  # still pending
 
     @pytest.mark.asyncio
-    async def test_list_filter_by_category(self, reg: PluginRegistry) -> None:
+    async def test_list_filter_by_category(
-        result = await reg.list_plugins(category="communication")
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
+    ) -> None:
+        result = await reg.list_plugins(db_session, category="communication")
         assert result.total == 1
         assert result.plugins[0].id == "plugin-slack-notify"
 
     @pytest.mark.asyncio
-    async def test_list_filter_by_query(self, reg: PluginRegistry) -> None:
+    async def test_list_filter_by_query(
-        result = await reg.list_plugins(query="time")
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
+    ) -> None:
+        result = await reg.list_plugins(db_session, query="time")
         assert result.total == 1
         assert result.plugins[0].id == "plugin-time-tracker"
 
     @pytest.mark.asyncio
-    async def test_list_sort_by_installs(self, reg: PluginRegistry) -> None:
+    async def test_list_sort_by_installs(
-        await reg.record_install("plugin-slack-notify")
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
-        await reg.record_install("plugin-slack-notify")
+    ) -> None:
-        result = await reg.list_plugins(sort="installs")
+        await reg.record_install(db_session, "plugin-slack-notify")
+        await reg.record_install(db_session, "plugin-slack-notify")
+        result = await reg.list_plugins(db_session, sort="installs")
         assert result.plugins[0].id == "plugin-slack-notify"
 
     @pytest.mark.asyncio
-    async def test_get_plugin_found(self, reg: PluginRegistry) -> None:
+    async def test_get_plugin_found(
-        entry = await reg.get_plugin("plugin-github-sync")
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
+    ) -> None:
+        entry = await reg.get_plugin(db_session, "plugin-github-sync")
         assert entry is not None
         assert entry["manifest"].id == "plugin-github-sync"
         assert "install_count" in entry
 
     @pytest.mark.asyncio
-    async def test_get_plugin_not_found(self, reg: PluginRegistry) -> None:
+    async def test_get_plugin_not_found(
-        entry = await reg.get_plugin("no-such-plugin")
+        self, reg: PluginRegistry, db_session: AsyncSession
+    ) -> None:
+        entry = await reg.get_plugin(db_session, "no-such-plugin")
         assert entry is None
 
     @pytest.mark.asyncio
-    async def test_submit_sets_pending(self, reg: PluginRegistry) -> None:
+    async def test_submit_sets_pending(
+        self, reg: PluginRegistry, db_session: AsyncSession
+    ) -> None:
         manifest = _fresh_manifest()
-        plugin_id = await reg.submit_plugin(manifest, "key.zip")
+        plugin_id = await reg.submit_plugin(db_session, manifest, "key.zip")
         assert plugin_id == manifest.id
-        assert reg._catalog[plugin_id]["status"] == "pending_review"
+        result = await db_session.execute(select(Plugin).where(Plugin.id == plugin_id))
+        row = result.scalar_one()
+        assert row.status == "pending_review"
 
     @pytest.mark.asyncio
-    async def test_approve_makes_visible(self, reg: PluginRegistry) -> None:
+    async def test_approve_makes_visible(
+        self, reg: PluginRegistry, db_session: AsyncSession
+    ) -> None:
         manifest = _fresh_manifest()
-        await reg.submit_plugin(manifest, "key.zip")
+        await reg.submit_plugin(db_session, manifest, "key.zip")
-        await reg.approve_plugin(manifest.id)
+        await reg.approve_plugin(db_session, manifest.id)
-        result = await reg.list_plugins()
+        result = await reg.list_plugins(db_session)
         assert manifest.id in [p.id for p in result.plugins]
 
     @pytest.mark.asyncio
-    async def test_reject_stores_reason(self, reg: PluginRegistry) -> None:
+    async def test_reject_stores_reason(
+        self, reg: PluginRegistry, db_session: AsyncSession
+    ) -> None:
         manifest = _fresh_manifest()
-        await reg.submit_plugin(manifest, "key.zip")
+        await reg.submit_plugin(db_session, manifest, "key.zip")
-        await reg.reject_plugin(manifest.id, reason="Unsafe permissions")
+        await reg.reject_plugin(db_session, manifest.id, reason="Unsafe permissions")
-        assert reg._catalog[manifest.id]["status"] == "rejected"
+        result = await db_session.execute(select(Plugin).where(Plugin.id == manifest.id))
-        assert reg._catalog[manifest.id]["rejection_reason"] == "Unsafe permissions"
+        row = result.scalar_one()
-        result = await reg.list_plugins()
+        assert row.status == "rejected"
-        assert manifest.id not in [p.id for p in result.plugins]
+        assert row.rejection_reason == "Unsafe permissions"
+        listed = await reg.list_plugins(db_session)
+        assert manifest.id not in [p.id for p in listed.plugins]
 
     @pytest.mark.asyncio
-    async def test_approve_unknown_raises_key_error(self, reg: PluginRegistry) -> None:
+    async def test_approve_unknown_raises_key_error(
+        self, reg: PluginRegistry, db_session: AsyncSession
+    ) -> None:
         with pytest.raises(KeyError):
-            await reg.approve_plugin("ghost-plugin")
+            await reg.approve_plugin(db_session, "ghost-plugin")
 
     @pytest.mark.asyncio
-    async def test_record_install_increments_count(self, reg: PluginRegistry) -> None:
+    async def test_record_install_increments_count(
-        await reg.record_install("plugin-github-sync")
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
-        entry = await reg.get_plugin("plugin-github-sync")
+    ) -> None:
+        await reg.record_install(db_session, "plugin-github-sync")
+        entry = await reg.get_plugin(db_session, "plugin-github-sync")
         assert entry is not None
         assert entry["install_count"] == 1
 
     @pytest.mark.asyncio
-    async def test_record_uninstall_decrements_count(self, reg: PluginRegistry) -> None:
+    async def test_record_uninstall_decrements_count(
-        await reg.record_install("plugin-github-sync")
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
-        await reg.record_install("plugin-github-sync")
+    ) -> None:
-        await reg.record_uninstall("plugin-github-sync")
+        await reg.record_install(db_session, "plugin-github-sync")
-        entry = await reg.get_plugin("plugin-github-sync")
+        await reg.record_install(db_session, "plugin-github-sync")
+        await reg.record_uninstall(db_session, "plugin-github-sync")
+        entry = await reg.get_plugin(db_session, "plugin-github-sync")
         assert entry is not None
         assert entry["install_count"] == 1
 
     @pytest.mark.asyncio
-    async def test_record_uninstall_floors_at_zero(self, reg: PluginRegistry) -> None:
+    async def test_record_uninstall_floors_at_zero(
-        await reg.record_uninstall("plugin-github-sync")  # already 0
+        self, reg: PluginRegistry, db_session: AsyncSession, seed_plugins: list[Plugin]
-        entry = await reg.get_plugin("plugin-github-sync")
+    ) -> None:
+        await reg.record_uninstall(db_session, "plugin-github-sync")
+        entry = await reg.get_plugin(db_session, "plugin-github-sync")
         assert entry is not None
         assert entry["install_count"] == 0
 
 
 # ---------------------------------------------------------------------------
-# ReviewQueue
+# ReviewQueue (DB-backed)
 # ---------------------------------------------------------------------------
 
 
@@ -188,37 +200,47 @@ class TestReviewQueue:
         return PluginRegistry()
 
     @pytest.fixture
-    def queue(self, reg: PluginRegistry) -> ReviewQueue:
+    def queue(self) -> ReviewQueue:
-        # Patch the 'registry' name as bound inside plugin_review.py
+        return ReviewQueue()
-        with patch("app.marketplace.plugin_review.registry", reg):
-            yield ReviewQueue()
 
     @pytest.mark.asyncio
     async def test_get_pending_returns_submitted_plugins(
-        self, reg: PluginRegistry, queue: ReviewQueue
+        self, reg: PluginRegistry, queue: ReviewQueue, db_session: AsyncSession
     ) -> None:
         manifest = _fresh_manifest()
-        await reg.submit_plugin(manifest, "key.zip")
+        await reg.submit_plugin(db_session, manifest, "key.zip")
-        pending = await queue.get_pending()
+        pending = await queue.get_pending(db_session)
         assert any(p["plugin_id"] == manifest.id for p in pending)
 
     @pytest.mark.asyncio
     async def test_submit_review_approved(
-        self, reg: PluginRegistry, queue: ReviewQueue
+        self, reg: PluginRegistry, queue: ReviewQueue, db_session: AsyncSession
     ) -> None:
         manifest = _fresh_manifest()
-        await reg.submit_plugin(manifest, "key.zip")
+        await reg.submit_plugin(db_session, manifest, "key.zip")
-        await queue.submit_review(manifest.id, "reviewer-1", "approved", "Looks good")
+        await queue.submit_review(db_session, manifest.id, TEST_USER_IDS["power"], "approved", "Looks good")
-        assert reg._catalog[manifest.id]["status"] == "approved"
+        result = await db_session.execute(select(Plugin).where(Plugin.id == manifest.id))
+        row = result.scalar_one()
+        assert row.status == "approved"
+        # Check review row was persisted
+        review_result = await db_session.execute(
+            select(PluginReviewModel).where(PluginReviewModel.plugin_id == manifest.id)
+        )
+        review = review_result.scalar_one()
+        assert review.decision == "approved"
 
     @pytest.mark.asyncio
     async def test_submit_review_rejected(
-        self, reg: PluginRegistry, queue: ReviewQueue
+        self, reg: PluginRegistry, queue: ReviewQueue, db_session: AsyncSession
     ) -> None:
         manifest = _fresh_manifest()
-        await reg.submit_plugin(manifest, "key.zip")
+        await reg.submit_plugin(db_session, manifest, "key.zip")
-        await queue.submit_review(manifest.id, "reviewer-1", "rejected", "Bad permissions")
+        await queue.submit_review(
-        assert reg._catalog[manifest.id]["status"] == "rejected"
+            db_session, manifest.id, TEST_USER_IDS["power"], "rejected", "Bad permissions"
+        )
+        result = await db_session.execute(select(Plugin).where(Plugin.id == manifest.id))
+        row = result.scalar_one()
+        assert row.status == "rejected"
 
     def test_validate_manifest_ok(self) -> None:
         manifest = _fresh_manifest(permissions=["read:tasks", "write:notes"])
@@ -241,65 +263,66 @@ class TestReviewQueue:
 
 
 # ---------------------------------------------------------------------------
-# RevenueShare
+# RevenueShare (DB-backed)
 # ---------------------------------------------------------------------------
 
 
 class TestRevenueShare:
     @pytest.fixture
-    def reg(self) -> PluginRegistry:
+    def rs(self) -> RevenueShare:
-        return PluginRegistry()
+        return RevenueShare()
-
-    @pytest.fixture
-    def rs(self, reg: PluginRegistry) -> RevenueShare:
-        # Patch the 'registry' name as bound inside revenue_share.py
-        with patch("app.marketplace.revenue_share.registry", reg):
-            yield RevenueShare()
 
     @pytest.mark.asyncio
     async def test_record_install_free_plugin(
-        self, reg: PluginRegistry, rs: RevenueShare
+        self, rs: RevenueShare, db_session: AsyncSession, seed_plugins: list[Plugin]
     ) -> None:
-        await rs.record_install("plugin-github-sync", "user-1", amount_cents=0)
+        await rs.record_install(db_session, "plugin-github-sync", TEST_USER_IDS["power"], amount_cents=0)
-        assert len(rs._events) == 1
+        result = await db_session.execute(
-        assert rs._events[0]["developer_share_cents"] == 0
+            select(RevenueEvent).where(RevenueEvent.plugin_id == "plugin-github-sync")
+        )
+        event = result.scalar_one()
+        assert event.developer_share_cents == 0
 
     @pytest.mark.asyncio
     async def test_record_install_paid_plugin_no_stripe(
-        self, reg: PluginRegistry, rs: RevenueShare
+        self, rs: RevenueShare, db_session: AsyncSession, seed_plugins: list[Plugin]
     ) -> None:
-        # No STRIPE_SECRET_KEY configured in test env — should not crash
+        await rs.record_install(
-        await rs.record_install("plugin-slack-notify", "user-2", amount_cents=499)
+            db_session, "plugin-slack-notify", TEST_USER_IDS["pro"], amount_cents=499
-        assert len(rs._events) == 1
+        )
-        assert rs._events[0]["amount_cents"] == 499
+        result = await db_session.execute(
-        assert rs._events[0]["developer_share_cents"] == int(499 * 0.70)
+            select(RevenueEvent).where(RevenueEvent.plugin_id == "plugin-slack-notify")
+        )
+        event = result.scalar_one()
+        assert event.amount_cents == 499
+        assert event.developer_share_cents == int(499 * 0.70)
 
     @pytest.mark.asyncio
     async def test_record_install_increments_registry_count(
-        self, reg: PluginRegistry, rs: RevenueShare
+        self, rs: RevenueShare, db_session: AsyncSession, seed_plugins: list[Plugin]
     ) -> None:
-        await rs.record_install("plugin-github-sync", "user-1", amount_cents=0)
+        reg = PluginRegistry()
-        entry = await reg.get_plugin("plugin-github-sync")
+        await rs.record_install(db_session, "plugin-github-sync", TEST_USER_IDS["power"], amount_cents=0)
+        entry = await reg.get_plugin(db_session, "plugin-github-sync")
         assert entry is not None
         assert entry["install_count"] == 1
 
     @pytest.mark.asyncio
     async def test_get_earnings_empty(
-        self, reg: PluginRegistry, rs: RevenueShare
+        self, rs: RevenueShare, db_session: AsyncSession
     ) -> None:
-        result = await rs.get_earnings("unknown-dev")
+        result = await rs.get_earnings(db_session, "unknown-dev")
         assert result["total_installs"] == 0
         assert result["total_revenue_cents"] == 0
         assert result["developer_share_cents"] == 0
 
     @pytest.mark.asyncio
     async def test_get_earnings_aggregates(
-        self, reg: PluginRegistry, rs: RevenueShare
+        self, rs: RevenueShare, db_session: AsyncSession, seed_plugins: list[Plugin]
     ) -> None:
-        # "Adiuva" is the author of the seeded plugins
+        await rs.record_install(db_session, "plugin-slack-notify", TEST_USER_IDS["power"], amount_cents=499)
-        await rs.record_install("plugin-slack-notify", "u1", amount_cents=499)
+        await rs.record_install(db_session, "plugin-slack-notify", TEST_USER_IDS["pro"], amount_cents=499)
-        await rs.record_install("plugin-slack-notify", "u2", amount_cents=499)
+        result = await rs.get_earnings(db_session, "Adiuva")
-        result = await rs.get_earnings("Adiuva")
         assert result["total_installs"] == 2
         assert result["total_revenue_cents"] == 998
         assert result["developer_share_cents"] == int(499 * 0.70) * 2
@@ -311,77 +334,67 @@ class TestRevenueShare:
 
 
 class TestPluginRoutes:
-    def test_list_plugins_requires_power_tier(self) -> None:
+    def test_list_plugins_requires_power_tier(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.get("/api/v1/plugins", headers=auth_header("free"))
-            resp = client.get("/api/v1/plugins", headers=_auth("free"))
         assert resp.status_code == 403
 
-    def test_list_plugins_pro_tier_blocked(self) -> None:
+    def test_list_plugins_pro_tier_blocked(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.get("/api/v1/plugins", headers=auth_header("pro"))
-            resp = client.get("/api/v1/plugins", headers=_auth("pro"))
         assert resp.status_code == 403
 
-    def test_list_plugins_power_tier_ok(self) -> None:
+    def test_list_plugins_power_tier_ok(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.get("/api/v1/plugins", headers=auth_header("power"))
-            resp = client.get("/api/v1/plugins", headers=_auth("power"))
         assert resp.status_code == 200
         data = resp.json()
         assert "plugins" in data
-        assert data["total"] >= 3
+        assert data["total"] == 3
 
-    def test_list_plugins_team_tier_ok(self) -> None:
+    def test_list_plugins_team_tier_ok(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.get("/api/v1/plugins", headers=auth_header("team"))
-            resp = client.get("/api/v1/plugins", headers=_auth("team"))
         assert resp.status_code == 200
 
-    def test_get_plugin_found(self) -> None:
+    def test_get_plugin_found(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.get("/api/v1/plugins/plugin-github-sync", headers=auth_header())
-            resp = client.get("/api/v1/plugins/plugin-github-sync", headers=_auth())
         assert resp.status_code == 200
         data = resp.json()
         assert data["plugin"]["id"] == "plugin-github-sync"
         assert "install_count" in data
 
-    def test_get_plugin_not_found(self) -> None:
+    def test_get_plugin_not_found(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.get("/api/v1/plugins/no-such-plugin", headers=auth_header())
-            resp = client.get("/api/v1/plugins/no-such-plugin", headers=_auth())
         assert resp.status_code == 404
 
-    def test_install_plugin_free(self) -> None:
+    def test_install_plugin_free(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.post(
-            resp = client.post(
+            "/api/v1/plugins/plugin-github-sync/install",
-                "/api/v1/plugins/plugin-github-sync/install",
+            json={"plugin_id": "plugin-github-sync"},
-                json={"plugin_id": "plugin-github-sync"},
+            headers=auth_header(),
-                headers=_auth(),
+        )
-            )
         assert resp.status_code == 200
         data = resp.json()
         assert data["ok"] is True
         assert "download_url" in data
 
-    def test_install_plugin_not_found(self) -> None:
+    def test_install_plugin_not_found(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.post(
-            resp = client.post(
+            "/api/v1/plugins/ghost/install",
-                "/api/v1/plugins/ghost/install",
+            json={"plugin_id": "ghost"},
-                json={"plugin_id": "ghost"},
+            headers=auth_header(),
-                headers=_auth(),
+        )
-            )
         assert resp.status_code == 404
 
-    def test_uninstall_plugin_ok(self) -> None:
+    def test_uninstall_plugin_ok(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.delete(
-            resp = client.delete(
+            "/api/v1/plugins/plugin-github-sync/install",
-                "/api/v1/plugins/plugin-github-sync/install",
+            headers=auth_header(),
-                headers=_auth(),
+        )
-            )
         assert resp.status_code == 200
         assert resp.json()["ok"] is True
 
-    def test_install_requires_power_tier(self) -> None:
+    def test_install_requires_power_tier(self, client, seed_plugins) -> None:
-        with TestClient(app) as client:
+        resp = client.post(
-            resp = client.post(
+            "/api/v1/plugins/plugin-github-sync/install",
-                "/api/v1/plugins/plugin-github-sync/install",
+            json={"plugin_id": "plugin-github-sync"},
-                json={"plugin_id": "plugin-github-sync"},
+            headers=auth_header("free"),
-                headers=_auth("free"),
+        )
-            )
         assert resp.status_code == 403

tests/test_storage.py

@@ -1,48 +1,30 @@
-"""Tests for the storage layer: encryption, BlobStore, and VectorStore."""
+"""Tests for the storage layer: encryption, BlobStore, VectorStore, and storage routes."""
 
 from __future__ import annotations
 
 import base64
 import hashlib
-import os
 from unittest.mock import MagicMock, patch
 
 import boto3
 import pytest
 from botocore.exceptions import ClientError
-from moto import mock_aws
 
 from app.storage.encryption import reject_if_tampered, verify_checksum
 from app.storage.blob_store import BlobStore
 from app.storage.vector_store import VectorStore, _blob_to_vector
 from app.schemas import VectorItem, VectorSearchResult
+from tests.conftest import auth_header, S3_TEST_BUCKET
 
 
 # ── Helpers ───────────────────────────────────────────────────────────
 
 _BLOB = b"encrypted-payload-opaque-to-server"
 _CHECKSUM = hashlib.sha256(_BLOB).hexdigest()
-_BUCKET = "test-bucket"
+_BUCKET = S3_TEST_BUCKET
 _REGION = "us-east-1"
 
 
-@pytest.fixture
-def s3_bucket():
-    """Create a mocked S3 bucket and expose its name."""
-    with mock_aws():
-        os.environ.setdefault("AWS_ACCESS_KEY_ID", "testing")
-        os.environ.setdefault("AWS_SECRET_ACCESS_KEY", "testing")
-        os.environ.setdefault("AWS_DEFAULT_REGION", _REGION)
-        client = boto3.client("s3", region_name=_REGION)
-        client.create_bucket(Bucket=_BUCKET)
-        with patch("app.storage.blob_store.settings") as mock_settings:
-            mock_settings.S3_BUCKET = _BUCKET
-            mock_settings.S3_REGION = _REGION
-            mock_settings.AWS_ACCESS_KEY_ID = "testing"
-            mock_settings.AWS_SECRET_ACCESS_KEY = "testing"
-            yield _BUCKET
-
-
 def _pinecone_mock():
     """Return a mock Pinecone index with realistic return shapes."""
     mock_index = MagicMock()
@@ -383,3 +365,198 @@ class TestVectorStoreQdrant:
             await store.delete("u1", ["v1"])
         call_kwargs = mock_client.delete.call_args[1]
         assert call_kwargs["collection_name"] == "adiuva_vectors"
+
+
+# ── TestStorageRoutes (integration) ───────────────────────────────────
+
+
+class TestStorageRoutes:
+    """Integration tests for POST/GET/PUT/DELETE /api/v1/storage/records.
+
+    Pydantic v2 converts JSON string → bytes via ``str.encode('utf-8')``.
+    So "hello" in JSON becomes ``b"hello"`` on the server.  We use plain
+    ASCII strings as blob values and compute checksums accordingly.
+    """
+
+    _BLOB_STR = "encrypted-payload-opaque-to-server"
+    _BLOB_BYTES = _BLOB_STR.encode()
+    _BLOB_CHECKSUM = hashlib.sha256(_BLOB_BYTES).hexdigest()
+
+    @classmethod
+    def _create_payload(cls, blob_str: str | None = None) -> dict:
+        blob_str = blob_str or cls._BLOB_STR
+        checksum = hashlib.sha256(blob_str.encode()).hexdigest()
+        return {
+            "table": "tasks",
+            "blob": blob_str,
+            "checksum": checksum,
+        }
+
+    def _create_record(self, client, tier="power", blob_str=None):
+        payload = self._create_payload(blob_str)
+        return client.post(
+            "/api/v1/storage/records",
+            json=payload,
+            headers=auth_header(tier),
+        )
+
+    # ── Create ────────────────────────────────────────────────────────
+
+    def test_create_record(self, client, s3_bucket) -> None:
+        resp = self._create_record(client)
+        assert resp.status_code == 201
+        data = resp.json()
+        assert "id" in data
+        assert "created_at" in data
+
+    def test_create_record_bad_checksum(self, client, s3_bucket) -> None:
+        payload = {
+            "table": "tasks",
+            "blob": self._BLOB_STR,
+            "checksum": "0" * 64,
+        }
+        resp = client.post(
+            "/api/v1/storage/records",
+            json=payload,
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 400
+
+    def test_create_record_free_tier_blocked(self, client, s3_bucket) -> None:
+        """Free tier has cloud_storage_gb=0 → 402."""
+        resp = self._create_record(client, tier="free")
+        assert resp.status_code == 402
+
+    def test_create_record_pro_tier_allowed(self, client, s3_bucket) -> None:
+        """Pro tier has cloud_storage_gb=5 → succeeds for small blob."""
+        resp = self._create_record(client, tier="pro")
+        assert resp.status_code == 201
+
+    # ── List ──────────────────────────────────────────────────────────
+
+    def test_list_records(self, client, s3_bucket) -> None:
+        self._create_record(client)
+        self._create_record(client, blob_str="second-blob")
+        resp = client.get(
+            "/api/v1/storage/records",
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert len(data) == 2
+        # Each entry has metadata, no blob bytes
+        for item in data:
+            assert "id" in item
+            assert "table" in item
+            assert "checksum" in item
+            assert "blob" not in item
+
+    def test_list_records_filter_by_table(self, client, s3_bucket) -> None:
+        self._create_record(client)
+        # Create in a different table
+        note_blob = "note-blob"
+        payload = {
+            "table": "notes",
+            "blob": note_blob,
+            "checksum": hashlib.sha256(note_blob.encode()).hexdigest(),
+        }
+        client.post(
+            "/api/v1/storage/records",
+            json=payload,
+            headers=auth_header("power"),
+        )
+        resp = client.get(
+            "/api/v1/storage/records?table=notes",
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert len(data) == 1
+        assert data[0]["table"] == "notes"
+
+    def test_list_records_isolated_per_user(self, client, s3_bucket) -> None:
+        """One user's records should not appear in another user's list."""
+        self._create_record(client, tier="power")
+        resp = client.get(
+            "/api/v1/storage/records",
+            headers=auth_header("team"),
+        )
+        assert resp.json() == []
+
+    # ── Download ──────────────────────────────────────────────────────
+
+    def test_download_record(self, client, s3_bucket) -> None:
+        create_resp = self._create_record(client)
+        record_id = create_resp.json()["id"]
+        resp = client.get(
+            f"/api/v1/storage/records/{record_id}",
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 200
+        assert resp.content == self._BLOB_BYTES
+        assert resp.headers["X-Checksum"] == self._BLOB_CHECKSUM
+
+    def test_download_record_not_found(self, client, s3_bucket) -> None:
+        resp = client.get(
+            "/api/v1/storage/records/nonexistent-id",
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 404
+
+    # ── Update ────────────────────────────────────────────────────────
+
+    def test_update_record(self, client, s3_bucket) -> None:
+        create_resp = self._create_record(client)
+        record_id = create_resp.json()["id"]
+        new_blob_str = "updated-encrypted-payload"
+        new_checksum = hashlib.sha256(new_blob_str.encode()).hexdigest()
+        resp = client.put(
+            f"/api/v1/storage/records/{record_id}",
+            json={"blob": new_blob_str, "checksum": new_checksum},
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 200
+        assert resp.json() == {"ok": True}
+
+        # Verify download returns the updated blob
+        dl = client.get(
+            f"/api/v1/storage/records/{record_id}",
+            headers=auth_header("power"),
+        )
+        assert dl.content == new_blob_str.encode()
+
+    def test_update_record_bad_checksum(self, client, s3_bucket) -> None:
+        create_resp = self._create_record(client)
+        record_id = create_resp.json()["id"]
+        resp = client.put(
+            f"/api/v1/storage/records/{record_id}",
+            json={"blob": "some-data", "checksum": "0" * 64},
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 400
+
+    # ── Delete ────────────────────────────────────────────────────────
+
+    def test_delete_record(self, client, s3_bucket) -> None:
+        create_resp = self._create_record(client)
+        record_id = create_resp.json()["id"]
+        resp = client.delete(
+            f"/api/v1/storage/records/{record_id}",
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 200
+        assert resp.json() == {"ok": True}
+
+        # Subsequent GET should return 404
+        dl = client.get(
+            f"/api/v1/storage/records/{record_id}",
+            headers=auth_header("power"),
+        )
+        assert dl.status_code == 404
+
+    def test_delete_record_not_found(self, client, s3_bucket) -> None:
+        resp = client.delete(
+            "/api/v1/storage/records/nonexistent",
+            headers=auth_header("power"),
+        )
+        assert resp.status_code == 404