# 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/
│   ├── routes.py          # API routes definition
│   ├── auth_routes.py     # Authentication routes (login, registration, etc.)
│   └── admin_routes.py    # Protected admin routes
├── 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
│   ├── user.py            # User and authentication schemas
│   └── audit.py           # Audit logs schemas
├── services/
│   ├── agent_service.py   # Business logic for agents
│   ├── client_service.py  # Business logic for clients
│   ├── contact_service.py # Business logic for contacts
│   ├── mcp_server_service.py # Business logic for MCP servers
│   ├── tool_service.py    # Business logic for tools
│   ├── user_service.py    # User and authentication logic
│   ├── auth_service.py    # JWT authentication logic
│   ├── email_service.py   # Email sending service
│   └── audit_service.py   # Audit logs 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
└── utils/
    └── security.py        # Security utilities (JWT, hash)
```

## Code Standards

### 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

## 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 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