Files

dolgolyov.alexei 4cbce89129 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>

2026-03-19 14:52:21 +03:00

3.3 KiB

Raw Permalink Blame History

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)

Model: Create in backend/app/models/, inherit Base from database.py
Migration: alembic revision -m "description" or write manually in alembic/versions/
Schema: Create Pydantic models in backend/app/schemas/
Service: Business logic in backend/app/services/
Router: FastAPI endpoint in backend/app/api/v1/, register in router.py
Frontend API: Typed functions in frontend/src/api/
Page/Component: React component in frontend/src/pages/ or components/
Route: Add to frontend/src/routes.tsx
i18n: Add keys to both public/locales/en/ and ru/translation.json
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

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

3.3 KiB Raw Permalink Blame History

AI Assistant - Project Conventions

Tech Stack

Project Structure

Adding a New Feature (Endpoint to UI)

Conventions

Running

Environment Variables

3.3 KiB

Raw Permalink Blame History