Advanced

Python software architecture

Choose clear boundaries for UI, rules, data, and external systems.

Chapter goal: Choose clear boundaries for UI, rules, data, and external systems.

Simple explanation

Architecture is the building plan for code. It decides which parts own the UI, rules, data, and communication with outside systems.

In Python, this chapter is about designing dependencies so important rules do not depend on fragile details. Start with the idea above. Then connect each symbol to a value or action in the example.

Do not try to remember every symbol. First ask what data the program has, what it does with that data, and what result it creates. Technical words become easier when you connect them to those three questions.

Why this topic is important

Architecture makes large changes safer. It should solve real coupling, not add impressive names. In Python, the syntax may look different from other languages, but the thinking skill transfers: name the data, choose the right operation, and make the next step obvious.

When to use it

Use architectural boundaries when features share rules, external services may change, or testing is difficult.

Example code

class LessonRepository:
    def save(self, lesson_id):
        raise NotImplementedError

class InMemoryLessonRepository(LessonRepository):
    def __init__(self):
        self.saved = []
    def save(self, lesson_id):
        self.saved.append(lesson_id)

def complete_lesson(repository, lesson_id):
    repository.save(lesson_id)

complete_lesson(InMemoryLessonRepository(), "loops")

Line-by-line explanation

class LessonRepository: — This begins a class: a blueprint that groups related data and behavior.
def save(self, lesson_id): — This defines a reusable function. Its name describes the job that other code can call.
raise NotImplementedError — This line supports one focused piece of application logic. Read it together with the block directly around it.
class InMemoryLessonRepository(LessonRepository): — This begins a class: a blueprint that groups related data and behavior.
def __init__(self): — This defines a reusable function. Its name describes the job that other code can call.
self.saved = [] — This stores or updates self.saved. The value on the right is worked out first, then saved under that name.
def save(self, lesson_id): — This defines a reusable function. Its name describes the job that other code can call.
self.saved.append(lesson_id) — This line supports one focused piece of application logic. Read it together with the block directly around it.
def complete_lesson(repository, lesson_id): — This defines a reusable function. Its name describes the job that other code can call.
repository.save(lesson_id) — This line supports one focused piece of application logic. Read it together with the block directly around it.

What the output means

No visible output: the example wires one in-memory repository into completeLesson(). Swap in a different repository and completeLesson() does not need to change.

The output is evidence that the program followed the instructions. If your result is different, read from the first line and write down how each value changes. That is debugging, not failure.

Mistake example

class LessonRepository:
    def save(self, lesson_id):
        raise NotImplementedError

class InMemoryLessonRepository(LessonRepository):
    def __init__(self):
        self.saved = None # extra layers are added without solving a real dependency problem
    def save(self, lesson_id):
        self.saved.append(lesson_id)

def complete_lesson(repository, lesson_id):
    repository.save(lesson_id)

complete_lesson(InMemoryLessonRepository(), "loops")

This version intentionally shows how extra layers are added without solving a real dependency problem. The changed assignment stores a missing value, or a required line is removed, so later code cannot complete its job safely.

Fixed version

class LessonRepository:
    def save(self, lesson_id):
        raise NotImplementedError

class InMemoryLessonRepository(LessonRepository):
    def __init__(self):
        self.saved = []
    def save(self, lesson_id):
        self.saved.append(lesson_id)

def complete_lesson(repository, lesson_id):
    repository.save(lesson_id)

complete_lesson(InMemoryLessonRepository(), "loops")

The corrected version restores the real value or required operation. It fixes the chapter-specific problem: extra layers are added without solving a real dependency problem.

Common mistakes

Copying an architecture without understanding its problem.
Adding interfaces that have only one meaningless use.
Letting framework code own every business rule.

Warning: Change one part at a time. If you change many lines together, it becomes harder to learn which change caused the result.

Real use cases

Separate a checkout rule from its screen.
Replace an API in tests.
Keep RedM validation on the server boundary.

Practice exercise

Identify one dependency that should be swappable for testing.
Separate one business rule from the code that displays it.
Explain which layer would break first if the data source changed.

Tip: If the exercise feels too large, complete only steps 1 to 3. Small working code teaches more than a large unfinished project.

Mini quiz

Match the term to its meaning: "coupling" versus "boundary".
Select the safer option: UI code calling the database directly, or going through a defined interface?
Explain a real scenario: what breaks first if you swap out one external service for another?

How to read AI-generated code

Do not copy AI code first. Read it like a detective. Find the data, follow the changes, and locate the final output. Ask AI to explain a line only after you have made your own guess.

What data goes in?
What values are stored?
What calculation or decision happens?
What is printed, displayed, saved, or returned?
What can go wrong?
Can you rename one value and still explain the code?

Language reading check

Find the program entry point, follow function calls one at a time, and keep track of each value's type. Do not jump into a class or helper until you know who calls it.

Before you move on

I can explain this topic in my own words.
I can read the small example without AI.
I can change the example and predict the new result.
I can find and fix one simple mistake.
I can name one real project that uses this idea.

Next topic

Next, learn testing behavior. Before opening it, explain this chapter out loud in under one minute.

Open the interactive lesson →

← Python best practices and clean code Python testing behavior →