evoai-backend-template

The project is built using the following technologies:

Backend Framework

• FastAPI: High-performance web framework.
• Tortoise ORM: Asynchronous ORM.
• Pydantic: Data validation and settings management.
• JWT: JSON Web Token authentication.

Database

• PostgreSQL: Recommended for production environments.
• SQLite: Default for development environments.
• Redis: Used for caching and session storage.
• Aerich: Database migration tool.

Development & DevOps

• UV: Fast Python package manager.
• Black / Ruff / MyPy: Code formatting, linting, and type checking.
• Pytest: Testing framework (supports async testing).
• Docker / Uvicorn / Nginx: Deployment and containerization.

The template includes enterprise-grade security features out of the box:

• JWT Authentication: Uses a dual-token system with an Access Token (4-hour lifespan) and a Refresh Token (7-day lifespan).
• RBAC (Role-Based Access Control): Provides fine-grained permission management by assigning roles to users.
• Password Security: Uses the Argon2 hashing algorithm for secure password storage.
• Rate Limiting: Includes protection against brute-force attacks via login frequency limits.

The template follows a clean 3-layer design to ensure separation of concerns:

1. API Layer: Handles FastAPI routes, input validation, and response formatting.
2. Service Layer: Contains business logic, permissions, validation, and cross-cutting concerns.
3. Repository Layer: Manages data access, including CRUD operations and query building.
4. Model Layer: Uses Tortoise ORM to define database models and relations.

The project follows a layered architecture:

• src/api/v1/: API routing layer (versioned)
• src/services/: Business logic layer
• src/repositories/: Data access layer
• src/models/: Database models
• src/schemas/: Data validation schemas (Pydantic)
• src/core/: Core functionality and configuration
• src/utils/: Utility functions
• src/main.py: Application entry point
• tests/: Test files
• migrations/: Database migration files (managed by aerich)
• pyproject.toml: Project configuration and dependencies

The project follows a strict separation of concerns to ensure maintainability and scalability. The data flows through these layers:

1. API Layer (src/api/v1): Routes are kept "thin". They only handle parameter parsing, dependency injection, and response formatting.
2. Service Layer (src/services): Contains all business logic, including permission checks, validation, and orchestration.
3. Repository Layer (src/repositories): Handles all data access logic. This prevents ORM queries from leaking into the Service layer.
4. Model Layer (src/models): Defines the data structures using Tortoise ORM. Tortoise models are kept separate from Pydantic schemas.

Key Principle: All I/O (database, cache, task queue) is async-first.

When adding new functionality, follow the project's architectural pattern by implementing these four layers:

1. Model: Define data structures in src/models/.
2. Repository: Implement data access logic in src/repositories/.
3. Service: Implement business logic in src/services/.
4. Router: Define API endpoints in src/api/v1/.

All API responses follow a unified JSON structure. Success responses include a code, a msg (usually "success"), and the payload in the data field. Error responses include a code, an error msg, and set data to null.

### Success Response
```json
{
  "code": 200,
  "msg": "success",
  "data": {...}
}

Error Response

{
  "code": 400,
  "msg": "error message",
  "data": null
}

To ensure high performance in an enterprise-grade application, follow these patterns:

Database Optimization

• Use .select_related() to pre-load related data (one-to-one/many-to-one).
• Use .prefetch_related() to optimize many-to-many or one-to-many queries.
• Ensure appropriate database indexes are defined in your models.

Caching Strategy

• Use Redis to cache frequently accessed data.
• Implement query result caching.
• Set reasonable TTL (Time To Live) for cache expiration.

Asynchronous Processing

• Always use asynchronous I/O operations.
• Utilize connection pooling.
• Avoid blocking operations in the event loop.

Once the server is running at http://localhost:8000, you can access the following endpoints:

• Interactive API Docs (Swagger UI): http://localhost:8000/docs
• Alternative Docs (ReDoc): http://localhost:8000/redoc
• Health Check Endpoint: http://localhost:8000/api/v1/base/health

Default Credentials

Use these to log in for the first time (change them immediately in production!):

• Username: admin
• Password: abcd1234

To deploy to production, build a Docker image and run the container. It is recommended to use environment variables for secrets in production instead of a .env file.

# Build image
docker build -t fastapi-template .

# Run container
docker run -d -p 8000:8000 --name fastapi-app fastapi-template

# Production environment variables
export SECRET_KEY="your-secret-key"
export DB_HOST="your-db-host"
export DB_PASSWORD="your-db-password"