173 lines
6.5 KiB
Plaintext
173 lines
6.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/
|
|
│ ├── 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
|
|
|
|
### 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
|
|
|
|
### 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
|