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>

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"},
+    )