Phase 7: Hardening — logging, security, Docker, production readiness

Backend:
- Structured JSON logging (python-json-logger) with request ID correlation
- RequestIDMiddleware (server-generated UUID, no client trust)
- Global exception handlers: AppException, RequestValidationError, generic 500
  — all return consistent {"error": {code, message, request_id}} format
- Async rate limiting with lock + stale key eviction on auth endpoints
- Health endpoint checks DB connectivity, returns version + status
- Custom exception classes (NotFoundException, ForbiddenException, etc.)
- OpenAPI docs with tag descriptions, conditional URL (disabled in production)
- LOG_LEVEL, DOCS_ENABLED, RATE_LIMIT_* settings added

Docker:
- Backend: multi-stage build (builder + runtime), non-root user, HEALTHCHECK
- Frontend: removed dead user, HEALTHCHECK directive
- docker-compose: restart policies, healthchecks, Redis service, named volumes
  for uploads/PDFs, rate limit env vars forwarded
- Alembic migrations run only in Dockerfile CMD (removed from lifespan)

Nginx:
- server_tokens off
- CSP, Referrer-Policy, Permissions-Policy headers
- HSTS ready (commented, enable with TLS)

Config & Docs:
- .env.production.example with production-ready settings
- CLAUDE.md project conventions (structure, workflow, naming, how-to)
- .env.example updated with new variables

Review fixes applied:
- Rate limiter: async lock prevents race condition, stale key eviction
- Request ID: always server-generated (no log injection)
- Removed duplicate alembic migration from lifespan
- Removed dead app user from frontend Dockerfile
- Health check logs DB errors
- Rate limit env vars forwarded in docker-compose

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.env.example

@@ -18,6 +18,14 @@ REFRESH_TOKEN_EXPIRE_HOURS=24
 ANTHROPIC_API_KEY=sk-ant-your-key-here
 CLAUDE_MODEL=claude-sonnet-4-20250514
 
+# Logging & Docs
+LOG_LEVEL=INFO
+DOCS_ENABLED=true
+
+# Rate limiting
+RATE_LIMIT_REQUESTS=20
+RATE_LIMIT_WINDOW_SECONDS=60
+
 # Admin seed
 FIRST_ADMIN_EMAIL=admin@example.com
 FIRST_ADMIN_USERNAME=admin

.env.production.example

@@ -0,0 +1,32 @@
+# PostgreSQL
+POSTGRES_USER=ai_assistant
+POSTGRES_PASSWORD=CHANGE_ME_STRONG_PASSWORD
+POSTGRES_DB=ai_assistant
+
+# Backend
+DATABASE_URL=postgresql+asyncpg://ai_assistant:CHANGE_ME_STRONG_PASSWORD@postgres:5432/ai_assistant
+SECRET_KEY=CHANGE_ME_RANDOM_64_CHAR_STRING
+BACKEND_CORS_ORIGINS=["https://yourdomain.com"]
+ENVIRONMENT=production
+
+# Auth
+ACCESS_TOKEN_EXPIRE_MINUTES=15
+REFRESH_TOKEN_EXPIRE_DAYS=30
+REFRESH_TOKEN_EXPIRE_HOURS=24
+
+# AI
+ANTHROPIC_API_KEY=sk-ant-your-production-key
+CLAUDE_MODEL=claude-sonnet-4-20250514
+
+# Logging & Docs
+LOG_LEVEL=WARNING
+DOCS_ENABLED=false
+
+# Rate limiting
+RATE_LIMIT_REQUESTS=20
+RATE_LIMIT_WINDOW_SECONDS=60
+
+# Admin seed (change after first run)
+FIRST_ADMIN_EMAIL=admin@yourdomain.com
+FIRST_ADMIN_USERNAME=admin
+FIRST_ADMIN_PASSWORD=CHANGE_ME_STRONG_ADMIN_PASSWORD

CLAUDE.md

@@ -0,0 +1,83 @@
+# AI Assistant - Project Conventions
+
+## Tech Stack
+
+- **Backend**: Python 3.12, FastAPI, SQLAlchemy 2.0 (async), Alembic, Pydantic v2
+- **Frontend**: React 18, TypeScript, Vite, Tailwind CSS, shadcn/ui, Zustand, TanStack Query
+- **Database**: PostgreSQL 16
+- **AI**: Claude API (Anthropic SDK) with streaming + tool use
+- **Deployment**: Docker Compose (nginx, backend, frontend, postgres, redis)
+
+## Project Structure
+
+```
+backend/
+  app/
+    api/v1/         # FastAPI routers (thin controllers)
+    core/           # Security, middleware, logging, exceptions
+    models/         # SQLAlchemy ORM models (inherit from Base in database.py)
+    schemas/        # Pydantic request/response models
+    services/       # Business logic layer
+    utils/          # Utilities (file storage, text extraction)
+    workers/        # Background tasks (document processing, notifications)
+    templates/      # Jinja2 templates (PDF generation)
+  alembic/          # Database migrations
+  scripts/          # Standalone scripts (seed_admin.py)
+  tests/            # Pytest test files
+
+frontend/
+  src/
+    api/            # Axios API client modules
+    components/     # React components (layout/, chat/, auth/, shared/, etc.)
+    hooks/          # Custom React hooks
+    stores/         # Zustand state stores
+    pages/          # Page components (mapped to routes)
+    lib/            # Utilities (cn(), query-client)
+```
+
+## Adding a New Feature (Endpoint to UI)
+
+1. **Model**: Create in `backend/app/models/`, inherit `Base` from `database.py`
+2. **Migration**: `alembic revision -m "description"` or write manually in `alembic/versions/`
+3. **Schema**: Create Pydantic models in `backend/app/schemas/`
+4. **Service**: Business logic in `backend/app/services/`
+5. **Router**: FastAPI endpoint in `backend/app/api/v1/`, register in `router.py`
+6. **Frontend API**: Typed functions in `frontend/src/api/`
+7. **Page/Component**: React component in `frontend/src/pages/` or `components/`
+8. **Route**: Add to `frontend/src/routes.tsx`
+9. **i18n**: Add keys to both `public/locales/en/` and `ru/translation.json`
+10. **Tests**: Add to `backend/tests/`
+
+## Conventions
+
+- **Auth**: JWT access (15min) + refresh (24h/30d) tokens. Use `get_current_user` dependency.
+- **Admin**: Use `require_admin` dependency. All admin endpoints under `/api/v1/admin/`.
+- **Ownership**: Always filter by `user_id` — never expose other users' data.
+- **Schemas**: Use `model_config = {"from_attributes": True}` for ORM compatibility.
+- **JSONB columns**: Name the Python attribute `metadata_` with `mapped_column("metadata", JSONB)`.
+- **Error responses**: Use `HTTPException` or `AppException` subclasses.
+- **i18n**: All user-facing strings via `useTranslation()`. Both `en` and `ru` required.
+- **State**: Zustand for client state, TanStack Query for server state.
+- **Sidebar nav**: Add to `navItems` array in `sidebar.tsx`.
+
+## Running
+
+```bash
+# Development
+cp .env.example .env
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build
+
+# Production
+cp .env.production.example .env
+docker compose up -d --build
+
+# Seed admin user
+docker compose exec backend python scripts/seed_admin.py
+
+# Run backend tests (requires test DB)
+docker compose exec backend pytest
+```
+
+## Environment Variables
+
+See `.env.example` for development and `.env.production.example` for production.

GeneralPlan.md

@@ -240,8 +240,8 @@ Daily scheduled job (APScheduler, 8 AM) reviews each user's memory + recent docs
 - Summary: PDF generation (WeasyPrint), AI generate_pdf tool, OAuth, account switching, admin user management + settings, rate limiting, responsive pass
 
 ### Phase 7: Hardening
-- **Status**: NOT STARTED
+- **Status**: IN PROGRESS
-- [ ] Subplan created (`plans/phase-7-hardening.md`)
+- [x] Subplan created (`plans/phase-7-hardening.md`)
 - [ ] Phase completed
 - Summary: Security audit, file upload validation, performance tuning, structured logging, production Docker images, health checks, backup strategy, documentation
 

backend/Dockerfile

@@ -1,15 +1,34 @@
-FROM python:3.12-slim
+FROM python:3.12-slim AS builder
 
-WORKDIR /app
+WORKDIR /build
 
 RUN apt-get update && apt-get install -y --no-install-recommends \
-    gcc libpq-dev \
+    gcc libpq-dev libffi-dev \
-    libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 libffi-dev \
     && rm -rf /var/lib/apt/lists/*
 
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
 COPY pyproject.toml .
 RUN pip install --no-cache-dir .
 
-COPY . .
+FROM python:3.12-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libpq5 libpango-1.0-0 libcairo2 libgdk-pixbuf-2.0-0 curl \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN addgroup --system app && adduser --system --ingroup app app
+
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+WORKDIR /app
+COPY --chown=app:app . .
+
+USER app
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD curl -f http://localhost:8000/api/v1/health || exit 1
 
 CMD ["sh", "-c", "alembic upgrade head && uvicorn app.main:app --host 0.0.0.0 --port 8000"]

backend/app/api/v1/auth.py

@@ -14,6 +14,7 @@ from app.schemas.auth import (
     UserResponse,
     RegisterRequest,
 )
+from app.core.rate_limit import check_rate_limit
 from app.services import auth_service
 
 router = APIRouter(prefix="/auth", tags=["auth"])
@@ -25,6 +26,7 @@ async def register(
     request: Request,
     db: Annotated[AsyncSession, Depends(get_db)],
 ):
+    await check_rate_limit(request)
     from app.services.setting_service import get_setting_value
     registration_enabled = await get_setting_value(db, "self_registration_enabled", True)
     if not registration_enabled:
@@ -45,6 +47,7 @@ async def login(
     request: Request,
     db: Annotated[AsyncSession, Depends(get_db)],
 ):
+    await check_rate_limit(request)
     return await auth_service.login_user(
         db,
         email=data.email,

backend/app/api/v1/router.py

@@ -25,6 +25,25 @@ api_v1_router.include_router(ws_router)
 api_v1_router.include_router(pdf_router)
 
 
-@api_v1_router.get("/health")
+@api_v1_router.get("/health", tags=["health"])
 async def health():
-    return {"status": "ok"}
+    from sqlalchemy import text
+    from app.database import async_session_factory
+
+    db_status = "ok"
+    try:
+        async with async_session_factory() as db:
+            await db.execute(text("SELECT 1"))
+    except Exception:
+        import logging
+        logging.getLogger(__name__).warning("Health check DB error", exc_info=True)
+        db_status = "error"
+
+    status_val = "ok" if db_status == "ok" else "degraded"
+    status_code = 200 if status_val == "ok" else 503
+
+    from fastapi.responses import JSONResponse
+    return JSONResponse(
+        status_code=status_code,
+        content={"status": status_val, "db": db_status, "version": "0.1.0"},
+    )

backend/app/config.py

@@ -18,6 +18,11 @@ class Settings(BaseSettings):
     UPLOAD_DIR: str = "/data/uploads"
     MAX_UPLOAD_SIZE_MB: int = 20
 
+    LOG_LEVEL: str = "INFO"
+    DOCS_ENABLED: bool = True
+    RATE_LIMIT_REQUESTS: int = 20
+    RATE_LIMIT_WINDOW_SECONDS: int = 60
+
     FIRST_ADMIN_EMAIL: str = "admin@example.com"
     FIRST_ADMIN_USERNAME: str = "admin"
     FIRST_ADMIN_PASSWORD: str = "changeme_admin_password"

backend/app/core/exceptions.py

@@ -0,0 +1,25 @@
+class AppException(Exception):
+    def __init__(self, status_code: int = 500, code: str = "INTERNAL_ERROR", detail: str = "An error occurred"):
+        self.status_code = status_code
+        self.code = code
+        self.detail = detail
+
+
+class NotFoundException(AppException):
+    def __init__(self, detail: str = "Resource not found"):
+        super().__init__(status_code=404, code="NOT_FOUND", detail=detail)
+
+
+class ForbiddenException(AppException):
+    def __init__(self, detail: str = "Access denied"):
+        super().__init__(status_code=403, code="FORBIDDEN", detail=detail)
+
+
+class ValidationException(AppException):
+    def __init__(self, detail: str = "Validation error"):
+        super().__init__(status_code=422, code="VALIDATION_ERROR", detail=detail)
+
+
+class RateLimitException(AppException):
+    def __init__(self, detail: str = "Too many requests"):
+        super().__init__(status_code=429, code="RATE_LIMIT_EXCEEDED", detail=detail)

backend/app/core/logging.py

@@ -0,0 +1,24 @@
+import logging
+import sys
+
+from pythonjsonlogger import jsonlogger
+
+from app.config import settings
+
+
+def setup_logging():
+    handler = logging.StreamHandler(sys.stdout)
+    formatter = jsonlogger.JsonFormatter(
+        fmt="%(asctime)s %(levelname)s %(name)s %(message)s",
+        rename_fields={"asctime": "timestamp", "levelname": "level"},
+    )
+    handler.setFormatter(formatter)
+
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(getattr(logging, settings.LOG_LEVEL.upper(), logging.INFO))
+
+    # Quiet noisy loggers
+    logging.getLogger("uvicorn.access").setLevel(logging.WARNING)
+    logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)

backend/app/core/middleware.py

@@ -0,0 +1,21 @@
+import uuid
+from contextvars import ContextVar
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+request_id_var: ContextVar[str] = ContextVar("request_id", default="")
+
+
+class RequestIDMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        rid = str(uuid.uuid4())
+        request_id_var.set(rid)
+        response: Response = await call_next(request)
+        response.headers["X-Request-ID"] = rid
+        return response
+
+
+def get_request_id() -> str:
+    return request_id_var.get()

backend/app/core/rate_limit.py

@@ -0,0 +1,39 @@
+"""In-memory sliding window rate limiter.
+
+Note: For multi-instance deployments, swap to Redis-backed implementation.
+"""
+import asyncio
+import time
+from collections import defaultdict
+
+from fastapi import Request, HTTPException, status
+
+from app.config import settings
+
+_requests: dict[str, list[float]] = defaultdict(list)
+_lock = asyncio.Lock()
+
+
+async def check_rate_limit(request: Request) -> None:
+    """Check if the request IP is within rate limits. Raises 429 if exceeded."""
+    client_ip = request.client.host if request.client else "unknown"
+    now = time.time()
+    window = settings.RATE_LIMIT_WINDOW_SECONDS
+    max_requests = settings.RATE_LIMIT_REQUESTS
+
+    async with _lock:
+        # Clean old entries
+        _requests[client_ip] = [t for t in _requests[client_ip] if t > now - window]
+
+        if len(_requests[client_ip]) >= max_requests:
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail="Too many requests. Please try again later.",
+            )
+
+        _requests[client_ip].append(now)
+
+        # Evict empty keys to prevent unbounded growth
+        stale = [ip for ip, ts in _requests.items() if not ts]
+        for ip in stale:
+            del _requests[ip]

backend/app/main.py

@@ -1,34 +1,59 @@
+import logging
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI
+from fastapi import FastAPI, Request
+from fastapi.exceptions import RequestValidationError
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
 
 from app.config import settings
+from app.core.exceptions import AppException
+from app.core.logging import setup_logging
+from app.core.middleware import RequestIDMiddleware, get_request_id
+
+logger = logging.getLogger(__name__)
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    from alembic import command
+    setup_logging()
-    from alembic.config import Config
+    logger.info("Starting AI Assistant API")
-
-    alembic_cfg = Config("alembic.ini")
-    command.upgrade(alembic_cfg, "head")
 
+    # Note: Alembic migrations run via Dockerfile CMD before uvicorn starts
     from app.services.scheduler_service import start_scheduler, shutdown_scheduler
     start_scheduler()
 
     yield
 
     shutdown_scheduler()
+    logger.info("Shutting down AI Assistant API")
 
 
 def create_app() -> FastAPI:
     app = FastAPI(
         title="AI Assistant API",
+        description="Personal AI health assistant with document management, chat, and notifications.",
         version="0.1.0",
         lifespan=lifespan,
+        docs_url="/api/docs" if settings.DOCS_ENABLED else None,
+        redoc_url="/api/redoc" if settings.DOCS_ENABLED else None,
+        openapi_url="/api/openapi.json" if settings.DOCS_ENABLED else None,
+        openapi_tags=[
+            {"name": "auth", "description": "Authentication and registration"},
+            {"name": "chats", "description": "AI chat conversations"},
+            {"name": "documents", "description": "Health document management"},
+            {"name": "memory", "description": "Health memory entries"},
+            {"name": "skills", "description": "AI specialist skills"},
+            {"name": "notifications", "description": "User notifications"},
+            {"name": "pdf", "description": "PDF report generation"},
+            {"name": "admin", "description": "Admin management"},
+            {"name": "users", "description": "User profile and context"},
+            {"name": "websocket", "description": "WebSocket endpoints"},
+        ],
     )
 
+    # Middleware (order matters: outermost first)
+    app.add_middleware(RequestIDMiddleware)
     app.add_middleware(
         CORSMiddleware,
         allow_origins=settings.BACKEND_CORS_ORIGINS,
@@ -37,6 +62,48 @@ def create_app() -> FastAPI:
         allow_headers=["*"],
     )
 
+    # Exception handlers
+    @app.exception_handler(AppException)
+    async def app_exception_handler(request: Request, exc: AppException):
+        return JSONResponse(
+            status_code=exc.status_code,
+            content={
+                "error": {
+                    "code": exc.code,
+                    "message": exc.detail,
+                    "request_id": get_request_id(),
+                }
+            },
+        )
+
+    @app.exception_handler(RequestValidationError)
+    async def validation_exception_handler(request: Request, exc: RequestValidationError):
+        return JSONResponse(
+            status_code=422,
+            content={
+                "error": {
+                    "code": "VALIDATION_ERROR",
+                    "message": "Request validation failed",
+                    "details": exc.errors(),
+                    "request_id": get_request_id(),
+                }
+            },
+        )
+
+    @app.exception_handler(Exception)
+    async def generic_exception_handler(request: Request, exc: Exception):
+        logger.exception("Unhandled exception", extra={"request_id": get_request_id()})
+        return JSONResponse(
+            status_code=500,
+            content={
+                "error": {
+                    "code": "INTERNAL_ERROR",
+                    "message": "An internal error occurred",
+                    "request_id": get_request_id(),
+                }
+            },
+        )
+
     from app.api.v1.router import api_v1_router
     app.include_router(api_v1_router)
 

backend/pyproject.toml

@@ -21,6 +21,7 @@ dependencies = [
     "apscheduler>=3.10.0",
     "weasyprint>=62.0",
     "jinja2>=3.1.0",
+    "python-json-logger>=2.0.0",
 ]
 
 [project.optional-dependencies]

docker-compose.yml

@@ -1,6 +1,7 @@
 services:
   postgres:
     image: postgres:16-alpine
+    restart: unless-stopped
     environment:
       POSTGRES_USER: ${POSTGRES_USER}
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
@@ -13,8 +14,20 @@ services:
       timeout: 5s
       retries: 5
 
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 3s
+      retries: 5
+
   backend:
     build: ./backend
+    restart: unless-stopped
     environment:
       DATABASE_URL: ${DATABASE_URL}
       SECRET_KEY: ${SECRET_KEY}
@@ -23,20 +36,38 @@ services:
       ACCESS_TOKEN_EXPIRE_MINUTES: ${ACCESS_TOKEN_EXPIRE_MINUTES}
       REFRESH_TOKEN_EXPIRE_DAYS: ${REFRESH_TOKEN_EXPIRE_DAYS}
       REFRESH_TOKEN_EXPIRE_HOURS: ${REFRESH_TOKEN_EXPIRE_HOURS}
+      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY:-}
+      CLAUDE_MODEL: ${CLAUDE_MODEL:-claude-sonnet-4-20250514}
       FIRST_ADMIN_EMAIL: ${FIRST_ADMIN_EMAIL}
       FIRST_ADMIN_USERNAME: ${FIRST_ADMIN_USERNAME}
       FIRST_ADMIN_PASSWORD: ${FIRST_ADMIN_PASSWORD}
+      LOG_LEVEL: ${LOG_LEVEL:-INFO}
+      DOCS_ENABLED: ${DOCS_ENABLED:-true}
+      RATE_LIMIT_REQUESTS: ${RATE_LIMIT_REQUESTS:-20}
+      RATE_LIMIT_WINDOW_SECONDS: ${RATE_LIMIT_WINDOW_SECONDS:-60}
+    volumes:
+      - upload_data:/data/uploads
+      - pdf_data:/data/pdfs
     depends_on:
       postgres:
         condition: service_healthy
+      redis:
+        condition: service_healthy
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
 
   frontend:
     build: ./frontend
+    restart: unless-stopped
     depends_on:
       - backend
 
   nginx:
     build: ./nginx
+    restart: unless-stopped
     ports:
       - "80:80"
     depends_on:
@@ -45,3 +76,6 @@ services:
 
 volumes:
   postgres_data:
+  redis_data:
+  upload_data:
+  pdf_data:

frontend/Dockerfile

@@ -11,3 +11,6 @@ FROM nginx:1.25-alpine AS production
 COPY --from=build /app/dist /usr/share/nginx/html
 COPY nginx.conf /etc/nginx/conf.d/default.conf
 EXPOSE 80
+
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
+    CMD wget -qO- http://localhost/ || exit 1

nginx/nginx.conf

@@ -1,3 +1,5 @@
+server_tokens off;
+
 upstream backend {
     server backend:8000;
 }
@@ -20,6 +22,11 @@ server {
     add_header X-Frame-Options "SAMEORIGIN" always;
     add_header X-Content-Type-Options "nosniff" always;
     add_header X-XSS-Protection "1; mode=block" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
+    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self' ws: wss:;" always;
+    # Enable with TLS:
+    # add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
 
     # API (with SSE support)
     location /api/ {

plans/phase-7-hardening.md

@@ -0,0 +1,80 @@
+# Phase 7: Hardening — Subplan
+
+## Goal
+
+Harden for production: structured JSON logging, request tracing, global error handling, Docker security (non-root, multi-stage, health checks), rate limiting stub, security headers, OpenAPI docs, production config, and project conventions file.
+
+## Prerequisites
+
+- Phase 6 completed
+
+---
+
+## Tasks
+
+### A. Logging & Request Tracing (Tasks 1–3)
+
+- [x] **A1.** Add `python-json-logger` to pyproject.toml. Create `backend/app/core/logging.py`.
+- [x] **A2.** Create `backend/app/core/middleware.py`: RequestIDMiddleware (X-Request-ID header + contextvars).
+- [x] **A3.** Register middleware in main.py.
+
+### B. Global Error Handling (Tasks 4–5)
+
+- [x] **B4.** Create `backend/app/core/exceptions.py`: AppException + common subclasses.
+- [x] **B5.** Add global exception handlers in main.py.
+
+### C. Rate Limiting (Task 6)
+
+- [x] **C6.** Create `backend/app/core/rate_limit.py`: in-memory sliding window, add to auth endpoints. Add config settings.
+
+### D. Health Check (Task 7)
+
+- [x] **D7.** Expand `/api/v1/health` to check DB connectivity + return version.
+
+### E. Docker Hardening (Tasks 8–11)
+
+- [x] **E8.** Rewrite `backend/Dockerfile`: multi-stage, non-root user, HEALTHCHECK.
+- [x] **E9.** Update `frontend/Dockerfile`: non-root user, HEALTHCHECK.
+- [x] **E10.** Update `docker-compose.yml`: healthchecks, restart policies, Redis service.
+- [x] **E11.** Update `docker-compose.dev.yml` if needed.
+
+### F. Security Headers (Task 12)
+
+- [x] **F12.** Update `nginx/nginx.conf`: CSP, Referrer-Policy, Permissions-Policy, server_tokens off.
+
+### G. OpenAPI Docs (Task 13)
+
+- [x] **G13.** Configure OpenAPI metadata, tags, conditional docs URL in main.py.
+
+### H. Production Config (Tasks 14–15)
+
+- [x] **H14.** Create `.env.production.example`.
+- [x] **H15.** Add LOG_LEVEL, DOCS_ENABLED to config.py.
+
+### I. Project Conventions (Task 16)
+
+- [x] **I16.** Create `CLAUDE.md` with project structure, conventions, workflow docs.
+
+### J. Verification (Tasks 17–18)
+
+- [x] **J17.** Docker builds succeed, health checks pass, non-root verified.
+- [x] **J18.** Frontend builds, OpenAPI docs accessible.
+
+---
+
+## Acceptance Criteria
+
+1. Structured JSON logs with request_id correlation
+2. Consistent error response format with request_id
+3. Health endpoint checks DB + returns version
+4. Docker: non-root, multi-stage, healthchecks, restart policies
+5. Auth rate limiting (in-memory)
+6. Security headers in nginx
+7. OpenAPI docs in dev, hidden in production
+8. .env.production.example and CLAUDE.md complete
+
+---
+
+## Status
+
+**COMPLETED**