Skip to content

architecture.md

Latest commit

 

History

History
259 lines (196 loc) · 11.4 KB

architecture.md

File metadata and controls

259 lines (196 loc) · 11.4 KB
Raw

Architecture Overview

This document provides an overview of the fastapi-base project architecture, including the technology stack, project structure, and key design decisions.

🏗️ System Architecture

The fastapi-base project follows a modern, microservices-oriented architecture with the following components:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Load Balancer │    │     FastAPI     │    │   PostgreSQL    │
│    (Optional)   │────│   Application   │────│    Database     │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                               │
                       ┌─────────────────┐    ┌─────────────────┐
                       │      Redis      │    │     Celery      │
                       │    (Cache)      │    │   Workers       │
                       └─────────────────┘    └─────────────────┘

High-Level Request Flow

User Request → Load Balancer → FastAPI App → Business Logic → Database
                                    ↓
                              Cache Check (Redis) → Background Tasks (Celery)

🛠️ Technology Stack

Core Framework

  • FastAPI - Modern, fast web framework for building APIs with Python
  • Pydantic - Data validation and settings management using Python type annotations
  • SQLModel - SQL databases in Python, designed for simplicity, compatibility, and robustness

Database & Storage

  • PostgreSQL - Advanced open-source relational database
  • Alembic - Database migration tool for SQLAlchemy
  • Redis - In-memory data structure store for caching and sessions

Background Processing

  • Celery - Distributed task queue for background job processing
  • Celery Beat - Scheduler for periodic tasks

Development & Deployment

  • Docker - Containerization for consistent development and deployment
  • uv - Fast Python package manager and resolver
  • Gunicorn + Uvicorn - ASGI server for production deployment

Code Quality & Testing

  • pytest - Testing framework with fixtures and plugins
  • ruff - Fast Python linter and code formatter
  • black - Code formatter for consistent style
  • mypy - Static type checker
  • pre-commit - Git hooks for code quality

📁 Project Structure

fastapi-base/
├── fastapi-base/                   # Main application directory
│   ├── src/                        # Source code
│   │   ├── api/                    # API layer
│   │   │   ├── v1/                 # API version 1
│   │   │   │   ├── endpoints/      # API endpoints
│   │   │   │   └── deps.py         # Dependencies
│   │   │   └── __init__.py
│   │   ├── core/                   # Core configuration
│   │   │   ├── config.py           # Settings and configuration
│   │   │   ├── security.py         # Security utilities
│   │   │   └── __init__.py
│   │   ├── db/                     # Database layer
│   │   │   ├── base.py             # Database base classes
│   │   │   ├── init_db.py          # Database initialization
│   │   │   └── session.py          # Database session management
│   │   ├── models/                 # Data models
│   │   │   ├── user.py             # User model
│   │   │   └── __init__.py
│   │   ├── schemas/                # Pydantic schemas
│   │   │   ├── user.py             # User schemas
│   │   │   └── __init__.py
│   │   ├── services/               # Business logic layer
│   │   │   ├── user_service.py     # User business logic
│   │   │   └── __init__.py
│   │   ├── utils/                  # Utility functions
│   │   │   ├── cache.py            # Caching utilities
│   │   │   └── __init__.py
│   │   ├── migrations/             # Alembic migrations
│   │   │   ├── versions/           # Migration files
│   │   │   ├── env.py              # Alembic configuration
│   │   │   └── script.py.mako      # Migration template
│   │   ├── tasks/                  # Celery tasks
│   │   │   ├── __init__.py
│   │   │   └── example_tasks.py    # Example background tasks
│   │   └── main.py                 # Application entry point
│   ├── tests/                      # Test suite
│   │   ├── api/                    # API tests
│   │   ├── models/                 # Model tests
│   │   ├── services/               # Service tests
│   │   ├── conftest.py             # Pytest configuration
│   │   └── __init__.py
│   ├── pyproject.toml              # Project dependencies & config
│   ├── Dockerfile                  # Development Docker image
│   ├── alembic.ini                 # Alembic configuration
│   └── logconfig.yml               # Logging configuration
├── ops/                            # Operations & deployment
│   └── production.Dockerfile       # Production Docker image
├── docs/                           # Documentation
│   ├── architecture.md             # This file
│   ├── developing.md               # Development guide
│   ├── README-pt.md                # Portuguese README
│   ├── README-fr.md                # French README
│   └── README-es.md                # Spanish README
├── docker-compose.yml              # Development environment
├── Makefile                        # Development commands
├── .env.example                    # Environment variables template
├── CONTRIBUTING.md                 # Contribution guidelines
└── README.md                       # Main documentation

🔄 Application Flow

Request Lifecycle

  1. Request Reception: HTTP requests are received by the FastAPI application
  2. Middleware Processing: Security, CORS, and logging middleware process the request
  3. Route Resolution: FastAPI routes the request to the appropriate endpoint
  4. Dependency Injection: FastAPI resolves dependencies (database session, authentication, etc.)
  5. Business Logic: Service layer handles the business logic
  6. Data Access: Models interact with the PostgreSQL database through SQLModel
  7. Response Serialization: Pydantic schemas serialize the response data
  8. Response Return: JSON response is returned to the client

Database Operations

  1. Connection Management: Database connections are managed through SQLModel/SQLAlchemy
  2. Query Execution: Async queries are executed against PostgreSQL
  3. Transaction Handling: Database transactions ensure data consistency
  4. Migration Management: Alembic handles database schema changes

Background Tasks

  1. Task Queuing: Tasks are queued in Redis through Celery
  2. Worker Processing: Celery workers process tasks asynchronously
  3. Result Storage: Task results are stored in Redis for retrieval
  4. Scheduling: Celery Beat handles periodic task scheduling

🔐 Security Architecture

Database Security

  • Connection Encryption: SSL/TLS encryption for database connections
  • Parameter Binding: Parameterized queries to prevent SQL injection
  • Input Validation: Pydantic schemas validate all input data

Environment Configuration

  • Secret Management: Sensitive data stored in environment variables
  • Configuration Validation: Pydantic settings for configuration validation
  • Environment Isolation: Separate configurations for development, testing, and production

📊 Monitoring & Observability

Logging

  • Structured Logging: JSON-formatted logs for better parsing
  • Log Levels: Configurable log levels for different environments
  • Request Tracing: Correlation IDs for request tracking

Error Handling

  • Sentry Integration: Error tracking and performance monitoring
  • Exception Handling: Comprehensive exception handling with proper HTTP status codes
  • Health Checks: API endpoints for service health monitoring

Performance

  • Database Connection Pooling: Efficient database connection management
  • Redis Caching: In-memory caching for frequently accessed data
  • Async Operations: Non-blocking I/O for better performance

🚀 Deployment Architecture

Development Environment

  • Docker Compose: Multi-container development setup
  • Hot Reloading: Automatic code reloading for development
  • Volume Mounting: Source code mounted for real-time changes

Production Environment

  • Multi-stage Docker Build: Optimized production Docker images
  • Gunicorn + Uvicorn: Production ASGI server configuration
  • Environment Variables: Configuration through environment variables
  • Health Checks: Container health monitoring

Scalability Considerations

  • Horizontal Scaling: Stateless design allows for easy horizontal scaling
  • Database Connection Pooling: Efficient resource utilization
  • Caching Strategy: Redis caching reduces database load
  • Background Processing: Celery workers can be scaled independently

🔧 Configuration Management

Environment-based Configuration

  • Development: Debug mode enabled, verbose logging
  • Testing: Isolated test database, mocked external services
  • Production: Optimized for performance, error monitoring enabled

Feature Flags

  • Environment Variables: Feature toggles through environment configuration
  • Runtime Configuration: Dynamic configuration changes without deployment

📈 Performance Optimization

Database Optimization

  • Connection Pooling: Reuse database connections for efficiency
  • Query Optimization: Efficient queries with proper indexing
  • Migration Strategy: Zero-downtime database migrations

Caching Strategy

  • Redis Integration: In-memory caching for frequent data
  • Cache Invalidation: Proper cache invalidation strategies
  • Session Management: Redis-based session storage

API Optimization

  • Response Compression: Gzip compression for API responses
  • Pagination: Efficient data pagination for large datasets
  • Rate Limiting: API rate limiting to prevent abuse

🔄 Development Workflow

Code Quality Pipeline

  1. Pre-commit Hooks: Automated checks before commits
  2. Linting & Formatting: Code quality enforcement
  3. Type Checking: Static type analysis with mypy
  4. Testing: Comprehensive test suite execution
  5. Code Review: Peer review process for all changes

Continuous Integration

  • GitHub Actions: Automated CI/CD pipeline
  • Test Execution: Automated test running on pull requests
  • Code Coverage: Coverage reporting and enforcement
  • Security Scanning: Automated security vulnerability scanning

This architecture ensures a scalable, maintainable, and production-ready FastAPI application with modern development practices and comprehensive tooling.