# 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**