Python3 API Boilerplate

Features

• Clean Architecture: Separated layers (Controller, Service, Repository, Model, Adapters)
• Strict Model Validation: Models enforce required parameters and throw errors for missing fields
• Database Integration: PostgreSQL with SQLAlchemy ORM
• Observability: Structured logging with Prometheus metrics
• Error Handling: Centralized error handling middleware
• Health Checks: Database connectivity and application health monitoring
• API Documentation: Automatic OpenAPI/Swagger documentation

Architecture

┌─────────────────┐
│   Controllers   │  ← HTTP layer (FastAPI)
└─────────────────┘
         │
┌─────────────────┐
│    Services     │  ← Business logic
└─────────────────┘
         │
┌─────────────────┐
│  Repositories   │  ← Data access layer
└─────────────────┘
         │
┌─────────────────┐
│    Adapters     │  ← Infrastructure (DB, Logging)
└─────────────────┘
         │
┌─────────────────┐
│     Models      │  ← Domain entities with validation
└─────────────────┘

Quick Start

1. Clone and setup:

git clone https://github.com/BotecoDaFerramenta/pythoncrudbp.git
cd pythoncrudbp
cp .env.example .env

2. Run with Docker Compose:

docker-compose up --build

3. Access the application:

• API: http://localhost:8000
• API Docs: http://localhost:8000/docs
• Health Check: http://localhost:8000/health
• Metrics: http://localhost:8000/metrics
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin)

API Endpoints

Users

• POST /api/v1/users/ - Create user
• GET /api/v1/users/{id} - Get user by ID
• GET /api/v1/users/ - Get all users
• PUT /api/v1/users/{id} - Update user
• DELETE /api/v1/users/{id} - Delete user

System

• GET /health - Health check
• GET /metrics - Prometheus metrics
• GET / - Root endpoint

Model Validation

The application enforces strict model validation. Models will raise ValidationError if:

• Required fields are missing from constructor arguments
• Required fields are set to None
• Field values don't meet validation criteria

Example:

# This will raise ValidationError
user = User(name="John")  # Missing required 'email' field

# This will also raise ValidationError
user = User(name="John", email=None)  # Required field cannot be None

# This works correctly
user = User(name="John", email="[email protected]")

Testing

# Run tests
pytest tests/

# Run with coverage
pytest tests/ --cov=app --cov-report=html

Development

1. Install dependencies:

pip install -r requirements.txt

2. Run database migrations:

# Using docker-compose
docker-compose exec app alembic upgrade head

3. Run application locally:

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Monitoring

The application includes comprehensive observability:

• Structured Logging: JSON formatted logs with correlation IDs
• Metrics: Prometheus metrics for requests, errors, and performance
• Health Checks: Database connectivity and application status
• Error Tracking: Centralized error handling with detailed context

Environment Variables

Variable	Description	Default
DATABASE_URL	PostgreSQL connection string	postgresql://user:password@localhost:5432/myapp
LOG_LEVEL	Logging level	INFO
ENVIRONMENT	Environment name	development
APP_NAME	Application name	MyPythonApp
DEBUG	Debug mode	false

Contributing

1. Follow the established architecture patterns
2. Ensure all models have proper validation
3. Add tests for new functionality
4. Update documentation as needed
5. Use structured logging for observability

License

MIT License