# Project Rules

You are an expert in Python, Flask, and scalable API development.

## Key Principles
- Write concise, technical responses with accurate Python examples.
- Use functional, declarative programming. Avoid unnecessary classes.
- Prefer iteration and modularization over code duplication.
- Use descriptive variable names with auxiliary verbs (e.g., is_active, has_permission).
- Use lowercase with underscores for directories and files (e.g., blueprints/user_routes.py).
- Favor named exports for utility functions and constants.
- Follow the Receive an Object, Return an Object (RORO) pattern where applicable.

## Python/Flask
- Use def for pure functions and standard route handlers.
- Use type hints for all function signatures. Prefer Python 3.11+ syntax.
- Keep file structure flat: blueprints/, models/, services/, utils/.
- Use guard clauses to avoid deeply nested conditionals.
- Docstrings on every public function following Google style.
- Keep functions short, single-responsibility, under 40 lines.

# cxp:section:dependencies
## Dependencies and Configuration
- Flask for HTTP routing. SQLAlchemy as ORM with Flask-SQLAlchemy extension.
- Use Marshmallow for request/response serialization and schema validation.
- Use python-dotenv for environment variable management in development.
- Pin all dependencies in requirements.txt with exact versions.

# cxp:section:error-handling
## Error Handling
- Use Flask's @app.errorhandler for HTTP exception mapping.
- Return consistent JSON error responses with status, message, and error code.
- Log errors to structured JSON using the standard logging module.
- Never expose internal state in production error responses.
- Catch specific exceptions rather than using bare except clauses.
- Use abort() with appropriate HTTP status codes for expected failures.
- Always validate request data at the boundary before passing to services.
- Use try/except in service layers; let unexpected exceptions bubble to the handler.

# cxp:section:api-routes
## API Routes and Middleware
- Use Flask Blueprints to organize routes by domain.
- Apply authentication middleware at the blueprint level, not per-route.
- Validate request payloads with Marshmallow schemas before processing.
- Use before_request hooks for cross-cutting concerns like request logging.
- Return appropriate HTTP status codes: 201 for creation, 204 for deletion.
- Version API routes with a /api/v1/ prefix.
- Rate-limit public endpoints using Flask-Limiter.
- Use CORS middleware for cross-origin requests with explicit allowed origins.

## Database
- Use Flask-Migrate (Alembic) for schema migrations. Never modify tables by hand.
- Define models in a dedicated models/ package, one file per domain.
- Use SQLAlchemy relationship() for foreign key associations.
- Always set nullable=False on columns that require values.
- Index columns used in WHERE clauses and foreign keys.

## Testing
- Use pytest as the test runner with a conftest.py for shared fixtures.
- Create a test client fixture that provides an isolated Flask app context.
- Test each blueprint independently using the test client.
- Use factories (factory_boy) for creating test model instances.

## Key Conventions
- Follow RESTful naming conventions for endpoints.
- Use environment variables for all secrets and environment-specific config.
- Structure the project as an application factory using create_app().
- Keep business logic in services/, not in route handlers.
