🏗️ Mario's Pizzeria: Technical Architecture¶

System Design Document > Architecture: Clean Architecture + CQRS + Event Sourcing Technology Stack: FastAPI, Python, MongoDB, OAuth 2.0 Status: Production Ready

📋 Source Code: View Complete Implementation

💡 Pattern in Action: This document demonstrates Clean Architecture layer separation with the Repository Pattern for data access abstraction and Event-Driven Architecture for scalability.

📋 Architecture Overview¶

Mario's Pizzeria implements a modern, scalable architecture following clean architecture principles with CQRS (Command Query Responsibility Segregation) and event-driven patterns. This design ensures maintainability, testability, and scalability for a growing restaurant business.

Key Architectural Decisions:

• Clean Architecture: Clear separation of concerns across four distinct layers
• CQRS Pattern: Separate models for read and write operations
• Event-Driven Design: Asynchronous processing and loose coupling
• Repository Pattern: Abstracted data access with multiple storage options
• Dependency Injection: Testable and maintainable service management

⚠️ Architecture Principle: Dependencies point INWARD only (API → Application → Domain ← Integration). The domain layer has ZERO dependencies on outer layers! See Clean Architecture for why this matters.

🏛️ Clean Architecture Layers¶

Mario's Pizzeria demonstrates the four-layer clean architecture:

graph TB
    %% API Layer
    subgraph APILayer["🌐 API Layer"]
        OrdersController["📋 OrdersController<br/>FastAPI<br/>Order management endpoints"]
        MenuController["🍕 MenuController<br/>FastAPI<br/>Menu browsing endpoints"]
        KitchenController["👨‍🍳 KitchenController<br/>FastAPI<br/>Kitchen status endpoints"]
        DTOs["📄 DTOs<br/>Pydantic<br/>Request/Response models"]
    end

    %% Application Layer
    subgraph AppLayer["💼 Application Layer"]
        Mediator["🎯 Mediator<br/>CQRS<br/>Command/Query dispatcher"]
        PlaceOrderHandler["📝 PlaceOrderHandler<br/>Command Handler<br/>Order placement logic"]
        GetMenuHandler["📖 GetMenuHandler<br/>Query Handler<br/>Menu retrieval logic"]
        KitchenHandlers["⚡ KitchenHandlers<br/>Event Handlers<br/>Kitchen workflow"]
    end

    %% Domain Layer
    subgraph DomainLayer["🏛️ Domain Layer"]
        OrderEntity["📋 Order<br/>AggregateRoot<br/>Order business logic"]
        PizzaEntity["🍕 Pizza<br/>AggregateRoot<br/>Pizza with pricing"]
        CustomerEntity["👤 Customer<br/>AggregateRoot<br/>Customer information"]
        KitchenEntity["🏠 Kitchen<br/>Entity<br/>Kitchen capacity"]
        DomainEvents["⚡ Domain Events<br/>Events<br/>OrderPlaced, OrderReady"]
    end

    %% Integration Layer
    subgraph IntegrationLayer["🔌 Integration Layer"]
        OrderRepo["💾 OrderRepository<br/>File/Mongo<br/>Order persistence"]
        PaymentService["💳 PaymentService<br/>External API<br/>Payment processing"]
        SMSService["📱 SMSService<br/>External API<br/>Customer notifications"]
    end

    %% API to Application connections
    OrdersController -->|Sends commands/queries| Mediator
    MenuController -->|Sends queries| Mediator
    KitchenController -->|Sends queries| Mediator

    %% Application Layer connections
    Mediator -->|Routes PlaceOrderCommand| PlaceOrderHandler
    Mediator -->|Routes GetMenuQuery| GetMenuHandler
    Mediator -->|Routes events| KitchenHandlers

    %% Application to Domain connections
    PlaceOrderHandler -->|Creates/manipulates| OrderEntity
    GetMenuHandler -->|Reads menu data| PizzaEntity

    %% Application to Integration connections
    PlaceOrderHandler -->|Persists orders| OrderRepo
    PlaceOrderHandler -->|Processes payments| PaymentService
    KitchenHandlers -->|Sends notifications| SMSService

    %% Styling
    classDef apiLayer fill:#E3F2FD,stroke:#1976D2,stroke-width:2px
    classDef appLayer fill:#F3E5F5,stroke:#7B1FA2,stroke-width:2px
    classDef domainLayer fill:#E8F5E8,stroke:#388E3C,stroke-width:2px
    classDef integrationLayer fill:#FFF3E0,stroke:#F57C00,stroke-width:2px

    class OrdersController,MenuController,KitchenController,DTOs apiLayer
    class Mediator,PlaceOrderHandler,GetMenuHandler,KitchenHandlers appLayer
    class OrderEntity,PizzaEntity,CustomerEntity,KitchenEntity,DomainEvents domainLayer
    class OrderRepo,PaymentService,SMSService integrationLayer

🗄️ Data Storage Strategy¶

Mario's Pizzeria demonstrates multiple persistence approaches to support different deployment scenarios:

File-Based Storage (Development)¶

Perfect for development and testing environments with simple JSON persistence:

pizzeria_data/
├── orders/
│   ├── 2024-09-22/           # Orders by date
│   │   ├── order_001.json
│   │   ├── order_002.json
│   │   └── order_003.json
│   └── index.json            # Order index
├── menu/
│   └── pizzas.json           # Available pizzas
├── kitchen/
│   └── status.json           # Kitchen state
└── customers/
    └── customers.json        # Customer history

Benefits: Zero configuration, version control friendly, fast local development

MongoDB Storage (Production)¶

Scalable document database for production workloads:

// Orders Collection
{
  "_id": "order_001",
  "customer_name": "Mario Rossi",
  "customer_phone": "+1-555-0123",
  "pizzas": [
    {
      "name": "Margherita",
      "size": "large",
      "toppings": ["extra cheese"],
      "price": 15.99
    }
  ],
  "total_amount": 15.99,
  "status": "ready",
  "order_time": "2025-09-25T10:30:00Z"
}

Benefits: Horizontal scaling, rich queries, built-in replication, ACID transactions

Event Sourcing (Advanced)¶

Complete audit trail and temporal queries using event streams:

Event Store:
├── order_001_stream
│   ├── OrderPlacedEvent
│   ├── PaymentProcessedEvent
│   ├── OrderConfirmedEvent
│   ├── CookingStartedEvent
│   └── OrderReadyEvent

Benefits: Complete audit trail, temporal queries, replay capability, debugging

🌐 API Endpoints¶

Complete RESTful API designed for different client types (web, mobile, POS systems):

Order Management¶

Menu Operations¶

Kitchen Management¶

🔐 Security Architecture¶

OAuth 2.0 Scopes¶

Fine-grained access control using OAuth2 scopes:

SCOPES = {
    "orders:read": "Read order information",
    "orders:write": "Create and modify orders",
    "kitchen:read": "View kitchen status",
    "kitchen:manage": "Manage kitchen operations",
    "menu:read": "View menu items",
    "admin": "Full administrative access"
}

Role-Based Access Control¶

🚀 Scalability Considerations¶

Horizontal Scaling¶

• API Layer: Stateless controllers scale horizontally behind load balancer (see Clean Architecture)
• Application Layer: Event handlers can be distributed across multiple instances (see Event-Driven Architecture)
• Database Layer: MongoDB supports sharding and replica sets (see Repository Pattern)
• External Services: Circuit breakers prevent cascade failures

💡 Event-Driven Scalability: Kitchen event handlers can run on separate servers from order handlers, scaling independently based on load! Learn more: Event-Driven Architecture Benefits.

Performance Optimizations¶

• Caching: Redis for frequently accessed menu items and customer data
• Background Processing: Event-driven async handling for notifications and reporting
• Database Indexing: Optimized queries for order status and customer lookups
• CDN: Static assets (images, CSS) served from edge locations
• Read Models: Separate CQRS read models optimized for queries

Monitoring & Observability¶

• Health Checks: Endpoint monitoring for all critical services
• Metrics: Custom business metrics (orders/hour, kitchen efficiency)
• Logging: Structured logging with correlation IDs using Pipeline Behaviors
• Tracing: Distributed tracing for request flows

💡 Cross-Cutting Concerns: Logging, metrics, and tracing are implemented as Pipeline Behaviors that automatically wrap all command and query handlers!

🔧 Infrastructure Requirements¶

Development Environment¶

• Python: 3.9+ with FastAPI and Neuroglia framework
• Storage: Local JSON files for rapid development (see Repository Pattern)
• Authentication: Development OAuth server (Keycloak)

Production Environment¶

• Compute: 2+ CPU cores, 4GB RAM minimum per instance
• Database: MongoDB cluster with replica sets
• Caching: Redis cluster for session and menu caching
• Load Balancer: NGINX or cloud load balancer
• Authentication: Production OAuth provider (Auth0, Keycloak)

🔗 Related Documentation¶

Case Study Documents¶

• Business Analysis - Requirements and stakeholder analysis
• Domain Design - Business logic and data models
• Implementation Guide - Development patterns and APIs
• Testing & Deployment - Quality assurance and operations

Framework Patterns Used¶

• Clean Architecture - Four-layer separation with dependency rules
• CQRS Pattern - Separate read and write models for scalability
• Event-Driven Architecture - Async workflows and loose coupling
• Repository Pattern - Multiple storage implementations (File, MongoDB)
• Dependency Injection - Service lifetimes and testability
• Pipeline Behaviors - Logging, validation, error handling

💡 Architecture Learning: See how Mario's Pizzeria avoids common clean architecture mistakes like mixing layers and breaking dependency rules!

This technical architecture provides a scalable, maintainable foundation for Mario's Pizzeria using proven patterns from the Neuroglia framework.

• Testing & Deployment - Quality assurance and operations

This technical architecture ensures Mario's Pizzeria can scale from a single location to a multi-restaurant franchise while maintaining code quality and operational excellence.