.cursorrules

# Evo AI - Project Rules and Structure

## Main Technologies
- FastAPI: Web framework for building the API
- SQLAlchemy: ORM for database interaction
- Alembic: Database migration system
- PostgreSQL: Main database
- Pydantic: Data validation and serialization
- Uvicorn: ASGI server for application execution
- Redis: Cache and session management
- JWT: Secure token authentication
- Bcrypt: Secure password hashing
- SendGrid: Email service for notifications
- Jinja2: Template engine for email rendering

## Project Structure
```
src/
├── api/
│   ├── __init__.py        # Package initialization
│   ├── admin_routes.py    # Admin routes for management interface
│   ├── agent_routes.py    # Routes to manage agents
│   ├── auth_routes.py     # Authentication routes (login, registration)
│   ├── chat_routes.py     # Routes for chat interactions with agents
│   ├── client_routes.py   # Routes to manage clients
│   ├── mcp_server_routes.py # Routes to manage MCP servers
│   ├── session_routes.py  # Routes to manage chat sessions
│   └── tool_routes.py     # Routes to manage tools for agents
├── config/
│   ├── database.py        # Database configuration
│   └── settings.py        # General settings
├── core/
│   ├── middleware.py      # API Key middleware (legacy)
│   └── jwt_middleware.py  # JWT authentication middleware
├── models/
│   └── models.py          # SQLAlchemy models
├── schemas/
│   ├── schemas.py         # Main Pydantic schemas
│   ├── chat.py            # Chat schemas
│   ├── user.py            # User and authentication schemas
│   └── audit.py           # Audit logs schemas
├── services/
│   ├── agent_service.py   # Business logic for agents
│   ├── agent_runner.py    # Agent execution logic
│   ├── auth_service.py    # JWT authentication logic
│   ├── audit_service.py   # Audit logs logic
│   ├── client_service.py  # Business logic for clients
│   ├── email_service.py   # Email sending service
│   ├── mcp_server_service.py # Business logic for MCP servers
│   ├── session_service.py # Business logic for chat sessions
│   ├── tool_service.py    # Business logic for tools
│   └── user_service.py    # User management logic
├── templates/
│   ├── emails/
│   │   ├── base_email.html           # Base template with common structure and styles
│   │   ├── verification_email.html   # Email verification template
│   │   ├── password_reset.html       # Password reset template  
│   │   ├── welcome_email.html        # Welcome email after verification
│   │   └── account_locked.html       # Security alert for locked accounts
├── tests/
│   ├── __init__.py        # Package initialization
│   ├── api/
│   │   ├── __init__.py        # Package initialization
│   │   ├── test_auth_routes.py # Test for authentication routes
│   │   └── test_root.py       # Test for root endpoint
│   ├── models/
│   │   ├── __init__.py        # Package initialization
│   │   ├── test_models.py     # Test for models
│   ├── services/
│   │   ├── __init__.py        # Package initialization
│   │   ├── test_auth_service.py # Test for authentication service
│   │   └── test_user_service.py # Test for user service
└── utils/
    ├── logger.py          # Logger configuration
    └── security.py        # Security utilities (JWT, hash)
```

## Code Standards

### Language Requirements
- **ALL code comments, docstrings, and logging messages MUST be written in English**
- Variable names, function names, and class names must be in English
- API error messages must be in English
- Documentation (including inline comments) must be in English
- Code examples in documentation must be in English
- Commit messages must be in English

### Project Configuration
- Dependencies managed in `pyproject.toml` using modern Python packaging standards
- Development dependencies specified as optional dependencies in `pyproject.toml`
- Single source of truth for project metadata in `pyproject.toml`
- Build system configured to use setuptools
- Pytest configuration in `pyproject.toml` under `[tool.pytest.ini_options]`
- Code formatting with Black configured in `pyproject.toml`
- Linting with Flake8 configured in `.flake8`

### Schemas (Pydantic)
- Use `BaseModel` as base for all schemas
- Define fields with explicit types
- Use `Optional` for optional fields
- Use `Field` for validations and default values
- Implement `Config` with `from_attributes = True` for models
- Use `EmailStr` for email validation

### Services
- Error handling with `SQLAlchemyError`
- Consistent logging with messages in English
- Strong typing with `Optional` for null returns
- Documentation with docstrings
- Rollback in case of error
- Standardized returns
- Use transactions for multiple operations

### Email Templates
- All email templates extend a base template
- Templates written in English
- Use Jinja2 templating system
- Consistent styling using a common base template
- Responsive design for mobile compatibility
- Clear call-to-action buttons
- Fallback mechanisms for failed template rendering

### Routes
- Appropriate status codes (201 for creation, 204 for deletion)
- Error handling with `HTTPException`
- Error messages in English
- Pagination for list endpoints
- Input validation with schemas
- JWT authentication for all protected routes
- Use of asynchronous functions with `async def`

### Migrations
- Use Alembic for migration management
- Descriptive names for migrations
- Maintain change history
- Use CASCADE when necessary to remove dependencies

### Authentication
- Use JWT for authentication with OAuth2PasswordBearer
- JWT tokens with expiration time defined in settings
- Access token containing essential user data (is_admin, client_id, etc.)
- Resource ownership verification based on client_id
- Protection of administrative routes with permission verification
- Email verification system via tokens
- Secure password recovery with one-time tokens
- Account locking after multiple failed login attempts

### Audit
- Record important administrative actions
- Automatic collection of contextual data (IP, user-agent)
- Relationship with user who performed the action
- Filtering and querying by different criteria

### Environment Variables
- Use .env file for sensitive settings
- Keep .env.example updated
- Document all environment variables
- Use safe default values
- Validate required variables
- Clear separation between development and production configurations

## Conventions
- Variable and function names in English
- Log and error messages in English
- Documentation in English
- User-facing content (emails, responses) in English
- Indentation with 4 spaces
- Maximum of 79 characters per line

## Commit Rules
- Use Conventional Commits format for all commit messages
- Format: `<type>(<scope>): <description>`
- Types:
  - `feat`: A new feature
  - `fix`: A bug fix
  - `docs`: Documentation changes
  - `style`: Changes that do not affect code meaning (formatting, etc.)
  - `refactor`: Code changes that neither fix a bug nor add a feature
  - `perf`: Performance improvements
  - `test`: Adding or modifying tests
  - `chore`: Changes to build process or auxiliary tools
- Scope is optional and should be the module or component affected
- Description should be concise, in the imperative mood, and not capitalized
- Use body for more detailed explanations if needed
- Reference issues in the footer with `Fixes #123` or `Relates to #123`
- Examples:
  - `feat(auth): add password reset functionality`
  - `fix(api): correct validation error in client registration`
  - `docs: update API documentation for new endpoints`
  - `refactor(services): improve error handling in authentication`

## Best Practices
- Always validate input data
- Implement appropriate logging
- Handle all possible errors
- Maintain consistency in returns
- Document functions and classes
- Follow SOLID principles
- Keep tests updated
- Protect routes with JWT authentication
- Use environment variables for sensitive configurations
- Implement resource ownership verification
- Store passwords only with secure hash (bcrypt)
- Implement appropriate expiration for tokens
- Use template inheritance for consistent email layouts

## Security
- JWT tokens with limited lifetime
- Email verification with one-time tokens
- Secure password hashing with bcrypt and random salt
- Audit system for administrative actions
- Resource-based access control
- Clear separation between regular users and administrators
- Strict input validation with Pydantic
- Account lockout after multiple failed login attempts

## Useful Commands
- `make run`: Start the server
- `make run-prod`: Start the server in production mode
- `make alembic-revision message="description"`: Create new migration
- `make alembic-upgrade`: Apply pending migrations
- `make alembic-downgrade`: Revert last migration
- `make alembic-migrate`: Create and apply new migration
- `make alembic-reset`: Reset database to initial state
- `make alembic-upgrade-cascade`: Force upgrade removing dependencies
- `make clear-cache`: Clean project cache
- `make seed-all`: Run all database seeders
- `make lint`: Run linting checks with flake8
- `make format`: Format code with black
- `make install`: Install project for development
- `make install-dev`: Install project with development dependencies