Courses/Python/Architecture Patterns for Python Apps (MVC, Clean Architecture)

Lesson 39 • Advanced

Architecture Patterns for Python Apps (MVC, Clean Architecture)

Master architectural patterns that separate concerns, enforce dependency rules, and build maintainable Python applications that scale from prototype to production

Note: To run Python code on your computer, you'll need Python installed. Download Python here. Keep the website open and test our code examples with Python running on your computer.

What You'll Learn

What architecture means in Python applications
MVC pattern and its modern interpretations
Clean Architecture principles and dependency rules
Ports and Adapters (Hexagonal Architecture)
Layer separation: Domain, Application, Infrastructure, Interface
Dependency inversion and abstraction
Building testable, modular systems
Real project structures for production apps
Anti-patterns to avoid
Refactoring strategies for existing codebases
When to use complex architecture vs. simple patterns
Testing strategies for each layer

What Is Architecture?

🏗️ Real-World Analogy: Think of architecture like designing a building. Where do the bathrooms go? How do people move between floors? If you want to add a new room later, can you do it without demolishing half the building? Good architecture makes future changes easy!

Architecture is how you organize code and responsibilities in an application. It determines where business rules live, how modules depend on each other, and how easy it is to change, test, and extend your system.

❌ Bad Architecture Symptoms	✅ Good Architecture Signs
"God files" with 1000+ lines	Small, focused modules
Business logic mixed with SQL/HTTP	Clear layer boundaries
Can't test without starting servers	Each component testable in isolation
Changing DB breaks half the app	Can swap DB without major rewrites
New features cause ripple effects	Features added without breaking others

💡 Key Question: "If I need to change the database from PostgreSQL to MongoDB, how much of my app would I need to rewrite?" The answer reveals your architecture quality!

MVC Pattern Basics

🍽️ Real-World Analogy: Think of a restaurant. The Model is the kitchen (prepares the actual food/data). The View is how food is plated and presented. The Controller is the waiter taking orders and coordinating between you and the kitchen!

Model-View-Controller separates an application into three interconnected components:

Model

Represents data and business rules:

Domain entities (User, Order, Product)
Validation rules (email format, stock limits)
Business operations (apply discount, cancel order)
Domain logic that exists regardless of UI

View

Responsible for presenting data:

HTML templates (Django, Flask + Jinja2)
JSON responses (FastAPI, Flask-RESTful)
CLI output formatting
GUI windows

Views should be thin: format and present data, don't implement business rules

Controller

Coordinates between Model and View:

Accept request/input
Validate and parse data
Call appropriate business logic
Select and render the view

Clean Architecture Core Principle

🧅 Real-World Analogy: Think of Clean Architecture like an onion. The innermost layer (core business rules) knows nothing about outer layers. Each layer can only "see" inward, never outward. The database? That's way on the outside — your core logic doesn't even know it exists!

"Dependencies point inward toward business rules, never outward."

This single rule prevents most long-term maintainability problems. Business logic should never depend on frameworks, databases, or UI code.

The Four Layers

1. Domain / Entities (Core)

Pure business objects and rules. Zero framework or database imports. Contains entities, value objects, and domain services.

2. Application / Use Cases

Orchestrates domain actions. Implements "what happens when..." logic. Defines interfaces (ports) for external dependencies.

3. Infrastructure / Adapters

Implements interfaces defined by inner layers. Contains DB, HTTP clients, file storage, external API wrappers, caching, queues.

4. Interface / Presentation

Entry points: web routes, CLI commands, event handlers, cron jobs. Thin layer that delegates to use cases.

Dependency Inversion Principle

🔌 Real-World Analogy: Think of electrical outlets. Your laptop doesn't care if power comes from solar, wind, or coal — it just needs a standard plug interface! Similarly, your business logic shouldn't care if data comes from PostgreSQL, MongoDB, or a JSON file.

Key Principle: High-level modules should not depend on low-level modules. Both should depend on abstractions (interfaces).

✗ Bad: Direct Dependency

# use_case.py
from infrastructure.postgres import PostgresUserRepo

def register_user(email: str):
    repo = PostgresUserRepo()  # Tightly coupled!
    repo.save(user)

Problem: Use case knows about PostgreSQL. Can't test without DB. Can't switch to MongoDB.

✓ Good: Depend on Abstraction

# interfaces.py
class UserRepository(Protocol):
    def save(self, user: User) -> None: ...

# use_case.py
def register_user(email: str, repo: UserRepository):
    repo.save(user)  # Works with any implementation!

Benefit: Use case depends on interface. Can test with fakes. Infrastructure is swappable.

Ports and Adapters (Hexagonal)

🎮 Real-World Analogy: Think of a gaming console. The console (core logic) has ports — USB, HDMI, power. Different adapterscan plug in — any controller, any TV, any power source. Your app's core logic works the same way!

Hexagonal Architecture formalizes Clean Architecture with two key concepts:

Ports

Abstract interfaces defining what the application needs:

• UserRepository
• EmailSender
• PaymentGateway
• NotificationService

Adapters

Concrete implementations of ports:

• PostgresUserRepository
• SMTPEmailSender
• StripePaymentGateway
• SlackNotificationService

Key Benefits

• Switch PostgreSQL → SQLite without touching business logic
• Test workflows with fake implementations (no network/DB)
• Change from CLI → Web UI → Mobile without rewriting core logic
• Each adapter is isolated - easier to maintain and replace

Production Project Structure

A professional Python application typically follows this structure:

project/
│
├── domain/                   # Core business logic
│   ├── entities/            # Business objects
│   │   ├── user.py
│   │   ├── order.py
│   │   └── product.py
│   ├── value_objects/       # Immutable values
│   │   ├── email.py
│   │   └── money.py
│   └── services/            # Domain services
│       └── pricing.py
│
├── application/             # Use cases / workflows
│   ├── use_cases/
│   │   ├── create_order.py
│   │   ├── pay_order.py
│   │   └── cancel_order.py
│   ├── dto/                 # Data transfer objects
│   │   └── order_dto.py
│   └── interfaces/          # Ports (abstractions)
│       ├── repositories.py
│       └── gateways.py
│
├── infrastructure/          # Technical implementations
│   ├── database/
│   │   ├── sql_repository.py
│   │   └── models.py       # ORM models
│   ├── cache/
│   │   └── redis_cache.py
│   ├── email/
│   │   └── smtp_sender.py
│   └── external/
│       └── payment_api.py
│
├── interface/               # Entry points
│   ├── api/                 # REST API
│   │   ├── routes.py
│   │   └── schemas.py
│   ├── cli/                 # Command line
│   │   └── commands.py
│   └── events/              # Event handlers
│       └── consumers.py
│
├── tests/
│   ├── unit/                # Domain & use case tests
│   ├── integration/         # Infrastructure tests
│   └── e2e/                 # Full system tests
│
└── config/                  # Configuration
    ├── settings.py
    └── container.py         # DI container

Testing Different Layers

🎯 Why This Matters: Good architecture makes testing EASY. You can test 90% of your business logic without databases, networks, or servers. Fast tests = more tests = fewer bugs!

Test Type	What It Tests	Speed
Unit	Domain entities, value objects	⚡ Milliseconds
Integration	Use cases with fake repositories	⚡ Milliseconds
Infrastructure	Adapters with real DB/APIs	🐢 Seconds
E2E	Full system, HTTP → DB	🐌 Minutes

Common Anti-Patterns

🚨 Warning: These patterns seem convenient at first but cause massive pain later. Learn to recognize them early — your future self will thank you!

Anti-Pattern	The Problem	The Fix
Fat Controller	Route handler does EVERYTHING	Extract logic to use cases
Anemic Domain	Entities are just data bags	Put behavior where data is
DB-Driven Design	Models mirror DB tables	Design domain first, map later
Framework-First	Logic coupled to Django/Flask	Core logic is framework-agnostic
God Object	One class knows everything	Break into focused modules

Refactoring Toward Clean Architecture

🎯 Good News: You don't need to rewrite everything at once! Refactor incrementally — each small improvement makes the next one easier. Think of it like renovating a house room by room, not demolishing and rebuilding.

Follow these steps in order:

1.
Identify Core Business Rules
Extract pure logic into separate modules with no framework/DB imports
2.
Introduce Interfaces (Ports)
Define Protocol interfaces for repositories and external services
3.
Wrap External Code in Adapters
Move SQL, HTTP, cache logic into adapter modules implementing interfaces
4.
Create Use Case Classes
Extract workflow orchestration into dedicated use case modules
5.
Thin Out Controllers
Controllers become: parse input → call use case → format response

When to Use Clean Architecture

⚖️ Balance Is Key: Clean Architecture adds complexity. For a weekend project, it's overkill. For a startup's main product with 5 developers? Essential! Match your architecture complexity to your project's expected lifespan.

✓ Use Clean Architecture When:

• Building production applications
• Multiple developers on the team
• Long-term maintenance expected
• Multiple interfaces (web + CLI + mobile)
• Business logic is complex
• High refactoring risk
• Need comprehensive testing
• Compliance/audit requirements

⚠ Simple Structure Is Better For:

• Small personal projects
• One-off scripts or tools
• MVPs with unclear requirements
• Solo developer, low complexity
• Short-lived applications
• Prototypes and experiments
• Simple CRUD applications
• When speed matters more than structure

Choose architecture proportional to your project's expected lifespan and complexity.

Validating Your Architecture

Ask yourself these questions to evaluate your architecture:

Can I change the database without rewriting core logic?

✓ Good architecture isolates DB behind interfaces

Can I test workflows without starting servers or databases?

✓ Use cases should work with fake implementations

Does business logic import framework modules?

✗ Red flag - domain should be framework-agnostic

Is complexity growing linearly or exponentially?

✓ Good architecture scales linearly as features are added

Can I add a CLI interface without touching existing code?

✓ Multiple interfaces should share the same core logic

Complete Architecture Example

Domain entities, use cases, and repository pattern in action

Try it Yourself »

Python

# Python Architecture Patterns Examples

# ============================================
# 1. DOMAIN ENTITY WITH BUSINESS RULES
# ============================================

from dataclasses import dataclass, field
from decimal import Decimal
from typing import List
from datetime import datetime

@dataclass
class OrderItem:
    """Pure domain entity - no dependencies"""
    product_id: str
    product_name: str
    quantity: int
    unit_price: Decimal
    
    def subtotal(self) -> Decimal:
  
...

Key Takeaways

Architecture determines how easy your app is to change, test, and grow
MVC separates presentation, business logic, and control flow
Clean Architecture enforces dependency inversion: core depends on nothing
Layers: Domain (core) → Application (use cases) → Infrastructure (adapters) → Interface (API/CLI)
Ports and Adapters make external dependencies swappable
Test domain logic without databases or networks using fakes
Avoid anti-patterns: fat controllers, anemic models, database-driven design
Refactor incrementally - you don't need to rewrite everything at once
Choose architecture complexity proportional to project lifespan
Good architecture makes growth linear, not exponential in complexity

📋 Quick Reference — Architecture Patterns

Pattern	What it achieves
MVC	Separates data, display, and logic
Clean Architecture	Domain core independent of frameworks
Repository Pattern	Abstract data access behind an interface
Dependency Injection	Decouple components for testability
Event-Driven Architecture	Decouple services via events/messages

🎉 Great work! You've completed this lesson.

You can now apply Clean Architecture, MVC, and the Repository Pattern to structure Python apps that scale across teams and years.

Up next: Final Project — bring everything together and build a portfolio-worthy Python project.