cursorrules

SerpentStack — Cursor Rules

You are working on SerpentStack, a fullstack template: FastAPI + React + PostgreSQL + Terraform.

Architecture

• Backend: FastAPI, Python 3.12+, async SQLAlchemy 2.0 (asyncpg), Alembic, pydantic-settings, structlog, SlowAPI, Sentry SDK, ARQ
• Frontend: React 18, Vite, TypeScript (strict), Tailwind CSS v4, React Router, React Query, shadcn/ui
• Cache/Queue: Redis 7 (rate limiting, background tasks)
• Database: PostgreSQL 16 (Docker locally, RDS in production)
• Testing: pytest + testcontainers (real Postgres), httpx AsyncClient, Vitest
• Infrastructure: Terraform, AWS (App Runner, ECR, RDS, S3)

Key Conventions

Python / Backend

• All route handlers and service methods MUST be async def
• Use AsyncSession from sqlalchemy.ext.asyncio — never sync Session
• Services return None or domain values — NEVER raise HTTPException in services
• Services flush() but do NOT commit() — routes own the transaction boundary
• Routes translate service results to HTTP responses (None → 404, etc.) and call await db.commit() after mutations
• New models MUST be imported in backend/app/models/__init__.py for Alembic to detect them
• Use get_logger(__name__) with structured event-style logging: logger.info("event_name", key=value)
• UUID primary keys on all models — never integer IDs
• Pydantic schemas in schemas/ — never expose ORM models directly
• API routes prefixed with /api/v1/
• Protect routes with Depends(get_current_user) from routes/auth.py — returns UserInfo
• Database engine is lazily initialized (not at import time)
• Line length: 100 characters
• Formatter/linter: ruff

TypeScript / Frontend

• Strict mode — no any without justifying comment
• Named exports for hooks and utilities (components may use default exports)
• Types auto-generated from OpenAPI spec via make types — prefer generated types over hand-written
• Use React Query for data fetching, React Router for routing
• Tailwind CSS v4 for styling