CLAUDE.md

Claude Code Instructions: Backend - Task Management API

Project Context

This is the backend component of "The Evolution of Todo" - Phase II, a full-stack web application for managing personal tasks with user authentication. Built with FastAPI, SQLModel, Python 3.13+, and PostgreSQL, following RESTful API design principles with automatic OpenAPI documentation.

Project Constitution (MANDATORY - Read Carefully)

You MUST follow the constitutional requirements defined in the root .specify/memory/constitution.md:

Core Principles (MANDATORY)

1. Spec-Driven Development Only: All features must be implemented from approved specifications in specs/
2. AI as Primary Developer: Humans write specs, Claude Code implements all code
3. Mandatory Traceability: Complete audit trail (ADR → Spec → Plan → Tasks → Implementation → Tests)
4. Test-First Mandate: Minimum 80% coverage target (pytest backend, Jest frontend, Playwright E2E)
5. Evolutionary Consistency: Phase II extends Phase I without breaking changes

Phase II Backend Technology Stack Requirements (MANDATORY)

FastAPI Framework + SQLModel ORM (NOT raw SQLAlchemy)

• Python 3.13+ with UV package manager
• SQLModel ORM for type-safe database operations (NOT raw SQLAlchemy)
• Pydantic v2 for request/response validation and serialization
• Automatic OpenAPI/Swagger documentation generation
• Async/await patterns for non-blocking I/O
• Dependency injection for testability

Security Requirements (NON-NEGOTIABLE)

• User Data Isolation: ALL database queries MUST filter by user_id
• Authorization: verify user_id in URL matches authenticated user
• Return 404 (NOT 403) for unauthorized access attempts
• SQL injection prevention via SQLModel parameterized queries
• JWT validation on all protected endpoints
• Password hashing with bcrypt (NEVER plaintext passwords)

API Design Standards

• RESTful resource naming (/api/tasks, not /api/getTasks)
• Standard HTTP methods (GET, POST, PUT, PATCH, DELETE)
• Consistent error response format (JSON with status, message, details)
• Proper HTTP status codes (200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error)
• Type-safe request/response schemas using Pydantic

Current Feature Context

Feature: Task CRUD Operations with Authentication (001-task-crud-auth) Spec: ../specs/001-task-crud-auth/spec.md Plan: ../specs/001-task-crud-auth/plan.md Tasks: ../specs/001-task-crud-auth/tasks.md

User Stories (Priority Order):

1. US1 (P1): User Registration - New users can create accounts
2. US2 (P1): User Login - Registered users can authenticate
3. US3 (P2): View All My Tasks - Display user's tasks with data isolation
4. US4 (P2): Create New Task - Add tasks with title/description
5. US5 (P3): Mark Task Complete/Incomplete - Toggle completion status
6. US6 (P3): Update Task - Edit task title/description
7. US7 (P4): Delete Task - Remove tasks permanently

Key Entities

• User: id (UUID), email (unique, indexed), password_hash (bcrypt), account timestamps
• Task: id (int), user_id (FK, indexed), title (1-200 chars), description (0-1000 chars), completed (bool, indexed), task timestamps

Implementation Guidelines

Database Layer (SQLModel)

• Use SQLModel models with proper relationships and constraints
• Add indexes on critical fields (user_id for performance, completed for filtering)
• Implement proper foreign key relationships
• Use automatic timestamp fields (created_at, updated_at)
• Follow SQLModel best practices for type safety

Authentication Layer

• Implement JWT-based authentication with 7-day expiration
• Store secrets in environment variables (BETTER_AUTH_SECRET)
• Validate JWT tokens on all protected endpoints
• Return httpOnly cookies for secure token storage
• Hash passwords with bcrypt before storing

Authorization Layer (CRITICAL - Security)

• ALL database queries must filter by user_id (100% data isolation)
• Verify user_id in URL paths matches authenticated user (return 404 if mismatch)
• Use dependency injection for authentication (get_current_user)
• Return 404 (not 403) for unauthorized access to prevent information leakage
• Implement proper role-based access if needed (though user isolation is primary)

API Design

• Use FastAPI routers for endpoint organization
• Implement proper request/response validation with Pydantic schemas
• Follow RESTful conventions for resource naming and HTTP methods
• Include comprehensive API documentation via FastAPI auto-generation
• Handle errors consistently with proper HTTP status codes

Error Handling

• Use HTTPException for API errors with appropriate status codes
• Implement custom exception handlers for consistent error responses
• Log errors for debugging while protecting sensitive information from users
• Provide user-friendly error messages without exposing system details

Quality Standards

Code Quality

• Clean, readable, well-documented code
• Follow Python PEP 8 standards
• Use type hints for all public interfaces
• Implement separation of concerns (models, schemas, routers, middleware, utils)
• No circular dependencies between modules

Security

• Parameterized queries via SQLModel to prevent SQL injection
• Input validation and sanitization to prevent XSS
• Proper authentication and authorization on all endpoints
• Secure password handling with bcrypt
• Environment variable configuration for secrets

Performance

• Proper indexing on database queries (especially user_id)
• Efficient database queries with proper joins when needed
• Async/await patterns for non-blocking operations
• Connection pooling for database operations

Testing Requirements

• Unit tests for models and utility functions
• API integration tests for all endpoints
• Authentication and authorization tests (especially user isolation)
• Database transaction tests
• Error handling tests

Documentation

• Type hints for all public interfaces
• Docstrings for complex functions
• API documentation via FastAPI auto-generation
• Inline comments for complex business logic only

File Structure

backend/
├── src/
│   ├── main.py                    # FastAPI app entry point and configuration
│   ├── config.py                  # Configuration management (env vars, settings)
│   ├── database.py                # Database connection and session management
│   ├── models/                    # SQLModel database models
│   │   ├── __init__.py
│   │   ├── user.py                # User model with authentication fields
│   │   └── task.py                # Task model with user relationship
│   ├── schemas/                   # Pydantic request/response schemas
│   │   ├── __init__.py
│   │   ├── auth.py                # Auth request/response schemas
│   │   └── task.py                # Task request/response schemas
│   ├── routers/                   # API route handlers
│   │   ├── __init__.py
│   │   ├── auth.py                # Authentication endpoints (register, login)
│   │   └── tasks.py               # Task CRUD endpoints
│   ├── middleware/                # FastAPI middleware
│   │   ├── __init__.py
│   │   └── auth.py                # JWT validation middleware
│   └── utils/                     # Utility functions
│       ├── __init__.py
│       ├── security.py            # Password hashing, JWT utilities
│       └── deps.py                # Dependency injection functions
├── tests/                         # Backend tests
│   ├── conftest.py                # pytest fixtures (test database, client)
│   ├── unit/                      # Unit tests
│   │   ├── test_models.py         # Model validation tests
│   │   └── test_security.py       # Security utility tests
│   └── integration/               # API integration tests
│       ├── test_auth.py           # Authentication flow tests
│       ├── test_tasks.py          # Task CRUD operation tests
│       └── test_user_isolation.py # User data isolation tests (CRITICAL)
├── alembic/                       # Database migrations
│   ├── versions/                  # Migration files
│   ├── env.py                     # Alembic environment
│   └── alembic.ini                # Alembic configuration
├── .env                           # Backend environment variables
├── pyproject.toml                 # UV project configuration
├── uv.lock                        # UV lock file
└── CLAUDE.md                      # Backend-specific agent instructions

Working with Claude Code

1. Follow Specifications: Implement exactly what's in the spec, nothing more/less
2. Maintain Security: Never compromise user data isolation requirements
3. Keep User Focus: Remember this is for individual task management
4. Test Thoroughly: Implement tests for all acceptance scenarios, especially security
5. Stay Organized: Follow the defined project structure

Success Metrics

• API endpoints respond in under 200ms (p95)
• 100% user data isolation (no cross-user data access)
• 95%+ of API requests succeed
• 80%+ test coverage across all layers
• Proper error handling with appropriate HTTP status codes