Python course Β· Module 12: Final Project
AI System Architecture
In this lesson4
A savanna camp where tents, water supplies and the campfire stand in one big mess works only until the first storm. After that, nobody knows what to move and what to leave. An AI application without architecture looks similar: the endpoint connects to the vector database itself, calls the language model itself and computes embeddings itself. Changing the database provider then means rewriting half of the project. Architecture is the skeleton that lets you swap parts without tearing down the whole camp.
Clean Architecture for AI Applications
Clean Architecture splits a system into layers. The key rule: dependencies point inward, so an outer layer may know an inner one, but never the other way round. Here are the four layers of our document assistant, from the interface at the top to the infrastructure at the bottom:
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β Presentation Layer β
β βββββββββββββββ βββββββββββββββ βββββββββββββββ β
β β REST API β β WebSocket β β CLI β β
β ββββββββ¬βββββββ ββββββββ¬βββββββ ββββββββ¬βββββββ β
βββββββββββΌβββββββββββββββββΌβββββββββββββββββΌββββββββββββββββββ€
β ββββββββββββββββββΌβββββββββββββββββ β
β βΌ β
β Application Layer β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Use Cases / Services β β
β β ββββββββββββ ββββββββββββ ββββββββββββ β β
β β β Query β β Upload β β Search β β β
β β β Service β β Service β β Service β β β
β β ββββββββββββ ββββββββββββ ββββββββββββ β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Domain Layer β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Entities & Business Logic β β
β β Document β Query β Response β User β Embedding β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β Infrastructure Layer β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
β β Vector DBβ β LLM β β Database β β Cache β β
β β Qdrant β β OpenAI β β Postgres β β Redis β β
β ββββββββββββ ββββββββββββ ββββββββββββ ββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββThe Presentation Layer accepts requests (REST, WebSocket, CLI), the Application Layer holds the use cases, the Domain Layer keeps the entities and business logic, and the Infrastructure Layer is the concrete tooling: Qdrant, OpenAI, Postgres, Redis. In Robert C. Martin's original description, the same circles are called Entities, Use Cases, Interface Adapters and Frameworks & Drivers. The names differ, the idea is the same: business logic does not know which database you use.
Domain Layer Implementation
The domain is the heart of the camp. We start with entities, objects that have an identity. We use field(default_factory=...) because a default value of type list or dict must be created separately for every object, and uuid4 generates a random identifier.
from dataclasses import dataclass, field
from datetime import datetime
from uuid import UUID, uuid4
from abc import ABC, abstractmethod
# Entities
@dataclass
class Document:
id: UUID = field(default_factory=uuid4)
title: str = ""
content: str = ""
metadata: dict = field(default_factory=dict)
created_at: datetime = field(default_factory=datetime.now)
chunks: list["DocumentChunk"] = field(default_factory=list)
@dataclass
class DocumentChunk:
id: UUID = field(default_factory=uuid4)
document_id: UUID | None = None
content: str = ""
embedding: list[float] = field(default_factory=list)
metadata: dict = field(default_factory=dict)DocumentChunk is a fragment of a document together with its embedding, a vector of numbers. The UUID | None annotation honestly says that a chunk may not belong to any document yet. Writing "DocumentChunk" in quotes refers to a class defined further down. Now the query and the response:
@dataclass
class Query:
id: UUID = field(default_factory=uuid4)
text: str = ""
user_id: UUID | None = None
created_at: datetime = field(default_factory=datetime.now)
@dataclass
class Response:
query_id: UUID | None = None
answer: str = ""
sources: list[DocumentChunk] = field(default_factory=list)
confidence: float = 0.0
latency_ms: float = 0.0None of these classes imports Qdrant or FastAPI. That is deliberate: you can test the domain without starting anything.
Repository Pattern
The Repository Pattern is an abstraction over data access. The domain says "save a document" or "find similar chunks", but it does not know where the data lives. An abstract class based on ABC with the @abstractmethod decorator defines a contract: the methods every implementation must provide.
from abc import ABC, abstractmethod
from typing import Optional
class DocumentRepository(ABC):
@abstractmethod
async def save(self, document: Document) -> Document:
pass
@abstractmethod
async def get_by_id(self, doc_id: UUID) -> Optional[Document]:
pass
@abstractmethod
async def search(self, query_embedding: list[float], limit: int) -> list[DocumentChunk]:
passYou cannot create a DocumentRepository object directly, Python raises TypeError until a subclass implements all abstract methods. The methods are async because talking to a database is an input/output operation. Here is the Qdrant implementation:
class QdrantDocumentRepository(DocumentRepository):
def __init__(self, client, collection_name: str):
self.client = client
self.collection = collection_name
async def save(self, document: Document) -> Document:
# Implementation
pass
async def get_by_id(self, doc_id: UUID) -> Optional[Document]:
# Implementation
pass
async def search(self, query_embedding: list[float], limit: int) -> list[DocumentChunk]:
response = await self.client.query_points(
collection_name=self.collection,
query=query_embedding,
limit=limit
)
return [self._to_chunk(point) for point in response.points]In the current qdrant-client, search is done with the query_points method, which returns an object with a list of points. The older search method was first deprecated and is gone from recent client versions, so you may still see it in older tutorials. For await to work, client must be an AsyncQdrantClient instance. The save and get_by_id methods and the _to_chunk helper are left as a sketch to complete in the project.
Dependency Injection
Dependency Injection means that a class receives its dependencies from outside instead of creating them itself. Thanks to that, you pass a fake in tests and the real Qdrant in production. Let's start with the simplest container, a dictionary of "interface, implementation" pairs:
from functools import lru_cache
from fastapi import Depends
class Container:
"""Simple DI container."""
def __init__(self):
self._services = {}
def register(self, interface: type, implementation):
self._services[interface] = implementation
def resolve(self, interface: type):
return self._services.get(interface)register stores an object under a type key, resolve hands it back. Registration looks like this (LLMService and OpenAILLMService are a matching interface and implementation pair, and qdrant_client and llm_client are clients created earlier at application startup):
# Setup
container = Container()
container.register(DocumentRepository, QdrantDocumentRepository(qdrant_client, "documents"))
container.register(LLMService, OpenAILLMService(llm_client))Notice that nothing changed in the domain classes, only the configuration changed. Finally, we plug the container into FastAPI through Depends, the framework's built-in dependency injection mechanism:
# Usage in FastAPI
@lru_cache
def get_container() -> Container:
return container
def get_document_repo(container: Container = Depends(get_container)):
return container.resolve(DocumentRepository)@lru_cache makes get_container always return the same object. An endpoint that declares a parameter with Depends(get_document_repo) receives the repository without knowing where it comes from. In tests you swap it through app.dependency_overrides.
My advice: a hand-written container like this plus Depends is enough to start. Add DI libraries only when dependencies really start to multiply. In the next lesson you will see how this architecture makes testing easier.
Remember: architecture is the camp layout in which every tent can be moved without tearing down the others.
Docs entries used in this lesson
Spotted a mistake in this lesson?
Check yourself
Answer the questions from this lesson. Pick an answer to see right away whether it is correct.
1. What is the main principle of Clean Architecture?
2. What does Dependency Injection allow?
These are 2 of 3 questions for this lesson. Solve the rest in the game.
Hands-on tasks in the game
- Vertical ordering
Arrange the layers of Clean Architecture from outermost to innermost:
- Code editor
Implement the Repository pattern with an abstract class and a concrete implementation
- Horizontal ordering
Arrange the import of ABC and abstractmethod in the correct order:
- Click in order
Click the elements to build an abstract method decorator and definition:
- Vertical ordering
Arrange the Clean Architecture layers from the most abstract to the most concrete: