Python course Β· Module 12: Final Project

AI System Architecture

6 min read Β·
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.0

None 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]:
        pass

You 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. 1. What is the main principle of Clean Architecture?

  2. 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:

  1. QuestionClean Architecture
  2. QuestionDependency Injection
  3. QuestionRepository Pattern
  4. Put in orderClean Architecture pattern
  5. Coding taskRepository Implementation
  6. Put in orderABC import
  7. Click in orderAbstract method
  8. Put in orderClean Architecture layers

Useful articles