FastAPI RealWorld Demo

A comprehensive FastAPI reference implementation demonstrating modern development practices with the RealWorld API specification using Domain-Driven Design principles.

🚀 Quick Start

# Clone and setup
git clone <repository-url>
cd fastapi-realworld-demo
poetry install

# Start databases and apply migrations
make setup-dev
make migrate

# Run the application
make run

🌐 Visit: http://localhost:8000/docs for interactive API documentation

📚 New here? → Development Quickstart (5-minute setup)

📖 Documentation Hub

📊 Visual Architecture

• Architecture Diagrams - Complete C4 model visualization with PlantUML diagrams
• System Overview - Technology stack with architectural diagrams

🏃‍♂️ Getting Started

• Development Quickstart - 5-minute setup
• Getting Started Guide - Detailed setup with troubleshooting
• API Usage Guide - Complete API reference with examples

🏗️ Architecture & Design

• Domain-Driven Design - DDD architecture patterns with domain model
• Event-Driven Architecture - Event system design with request flow diagrams
• Exception Handling - Standardized error handling
• Transaction Management - Database transaction patterns

🛠️ Development & Testing

• Development Workflow - Complete development process
• Testing Guide - Comprehensive testing strategies with test pyramid architecture
• Commit Guidelines - Git commit conventions

🚀 Deployment & Production

• Production Deployment - Complete deployment guide

📋 Browse All Documentation

⚡ What You Get

🌍 RealWorld API Implementation

• ✅ User Management: Registration, authentication, profile management
• ✅ Article System: CRUD operations with slug-based URLs
• ✅ Social Features: Following users, favoriting articles
• ✅ Content Features: Comments, tags, personalized feeds
• ✅ Pagination: Efficient list pagination across endpoints

🏗️ Development-Ready Architecture

• ✅ Domain-Driven Design: Clean separation of concerns with clear layer boundaries
• ✅ Event-Driven Architecture: Loose coupling via domain events with extensible framework
• ✅ Type Safety: Full MyPy validation for compile-time error detection
• ✅ Comprehensive Testing: Unit, integration, and E2E tests with optimized fixtures
• ✅ Transaction Management: Automatic UoW pattern with @transactional() decorator

🛠️ Modern Development Stack

• FastAPI 0.115+ with Pydantic v2
• PostgreSQL with async SQLAlchemy 2.0
• JWT Authentication with bcrypt
• Docker for development databases
• Poetry for dependency management
• pytest with async support

🧪 Testing

# Run all tests  
make test

# Run specific test types
poetry run pytest tests/unit/         # Unit tests
poetry run pytest tests/integration/  # Integration tests  
poetry run pytest tests/e2e/         # End-to-end tests

# Run with coverage
make test-cov

🎯 Development Focus: This project prioritizes development experience, code quality, and architectural patterns. While it includes deployment-ready code, additional configuration is needed for full production deployment (monitoring, security hardening, performance optimization, etc.).

🚀 Development Commands

# Essential commands
make run            # Start with auto-reload
make test           # Run all tests
make lint           # Format and lint code
make type-check     # MyPy type checking

# Database management
make migrate                    # Apply migrations
make migration msg="Add field"  # Create migration
make db-check                  # Test connection

# Quality assurance
make format         # Auto-format code
make health-all     # Check all systems

🎯 Key Features

🎯 Development Focus: This project prioritizes development experience, code quality, and architectural patterns. While it includes deployment-ready code and solid architectural foundations, additional configuration is needed for full production deployment (monitoring, security hardening, etc.).

Automatic Transaction Management

@transactional()
async def create_article(uow: AsyncUnitOfWork, article_data: ArticleCreate, user: User) -> Article:
    # Business logic - automatic commit/rollback

Standardized Exception Handling

# Domain layer raises business exceptions
raise ArticleNotFoundError(slug)

# API layer automatically converts to HTTP responses
# → 404 {"errors": {"body": ["Article not found"]}}

Event-Driven Architecture

# Publish domain events from service layer
shared_event_bus.publish(ArticleCreated(
    article_id=article.id,
    title=article.title,
    slug=article.slug
))

🏗️ Project Structure

The codebase follows a clean, layered architecture:

app/
├── api/           # 🌐 HTTP endpoints (FastAPI routers)
├── service_layer/ # ⚙️ Use cases and orchestration
├── domain/        # 🏛️ Business logic and entities
├── adapters/      # 🔌 Infrastructure (repositories, ORM)
├── events/        # 📡 Event-driven architecture
└── shared/        # 🛠️ Common utilities

tests/
├── unit/          # Pure business logic tests
├── integration/   # Database and API tests
└── e2e/          # Complete workflow tests

📊 Visual Architecture: See the Component Diagram for detailed layer relationships and Architecture Diagrams for the complete system visualization.

🔗 API Documentation

• Interactive Docs: http://localhost:8000/docs (Swagger UI)
• ReDoc: http://localhost:8000/redoc (Alternative documentation)
• Health Check: http://localhost:8000/healthcheck (Basic status endpoint)
• OpenAPI Spec: http://localhost:8000/openapi.json (Machine-readable specification)

📊 RealWorld Spec: Fully implements the RealWorld API specification

🤝 Contributing

1. Setup: Follow the Development Quickstart
2. Standards: Review Development Workflow
3. Commits: Use Conventional Commits
4. Testing: Ensure comprehensive test coverage
5. Type Safety: All code must pass MyPy validation

📚 Learn More

• 📖 Project Overview - Complete technology overview
• 🏗️ Architecture Guides - Detailed design patterns
• 🛠️ Development Guides - Complete development workflow
• 📋 All Documentation - Browse complete documentation

---

💡 Questions? Check the documentation or open an issue!