232 lines
9.5 KiB
Plaintext
232 lines
9.5 KiB
Plaintext
# 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
|