# Windsurf Rules

You are working on a Python Flask REST API for internal task management.
The codebase uses Python 3.11+, Flask, SQLAlchemy, and Marshmallow.

## General Approach
- Read existing code before making changes. Match local conventions.
- Prefer small, focused edits over large refactors.
- Run tests after every change to catch regressions early.
- If unsure about a pattern, check the closest existing file first.

## Code Style
- Type hints on all function signatures. Use str | None over Optional[str].
- Google-style docstrings on every public function and class.
- Functions under 40 lines. Extract helpers for complex branches.
- Guard clauses over deeply nested conditionals.
- Descriptive variable names: is_active, has_permission, item_count.
- Use pathlib.Path for file operations, not os.path.

# cxp:section:dependencies
## Dependencies and Configuration
- Flask for routing. SQLAlchemy is the ORM through Flask-SQLAlchemy.
- Marshmallow for request/response validation and serialization.
- python-dotenv loads environment variables in development.
- Pin all dependency versions in requirements.txt.
- App config in src/app/config.py with environment-specific classes.

# cxp:section:error-handling
## Error Handling
- Use @app.errorhandler for mapping HTTP exceptions to JSON responses.
- Error responses include status, message, and error_code fields.
- Log errors as structured JSON using the standard logging module.
- Always catch specific exceptions. No bare except clauses.
- Validate incoming request data at the route boundary before services.
- Use abort() with the correct HTTP status for known failure conditions.
- Never expose tracebacks, internal paths, or server state in responses.
- Let unexpected errors propagate to the centralized error handler.

# cxp:section:api-routes
## API Routes
- Organize routes in Flask Blueprints, one per domain (users, tasks, auth).
- Authentication via before_request hooks at the blueprint level.
- Validate all payloads with Marshmallow schemas before processing.
- Prefix routes with /api/v1/.
- Return 201 for creation, 204 for deletion, 409 for conflicts.
- Rate-limit public-facing endpoints with Flask-Limiter.
- CORS configured with explicit allowed origins. No wildcard.

## Database
- Flask-Migrate manages all schema changes. Never modify tables by hand.
- Models in src/app/models/, one file per domain entity.
- Required columns specify nullable=False.
- Index columns used in filters and foreign key columns.
- Use relationship() for associations between models.

## Testing
- pytest is the test runner. Fixtures in conftest.py.
- Test client fixture with an isolated Flask app context.
- factory_boy for model instance creation in tests.
- Test files mirror source layout: tests/blueprints/test_users.py.

## Key Conventions
- Application factory pattern: create_app() in src/app/__init__.py.
- Business logic in services/, never in route handlers.
- Environment variables for all secrets and environment-specific config.
- Follow RESTful naming for all endpoints.
