The Clean Architecture

01 Screaming Architecture — kiến trúc phải "HÉT LÊN"

Mở thư mục cấp cao nhất của dự án ra. Nó hét lên "Hệ thống Y tế", "Hệ thống Kế toán", "Quản lý Kho" — hay chỉ hét lên "Rails", "Spring/Hibernate", "ASP"? Nếu cấu trúc thư mục chỉ phơi ra models / views / controllers, kiến trúc đang hét về framework chứ không về nghiệp vụ.

Web là một detail

Web có phải là kiến trúc không? Không. Web chỉ là một cơ chế phân phối — một thiết bị I/O. Việc ứng dụng được phân phối qua web là một chi tiết, và là quyết định nên trì hoãn. Kiến trúc nên "ngu" nhất có thể về cách nó được phân phối: cùng một lõi nghiệp vụ phải chạy được dưới dạng console app, web app, thick-client, hay web service mà không phải đổi cấu trúc nền tảng.

02 Bốn vòng tròn đồng tâm

Clean Architecture hợp nhất Hexagonal (Ports & Adapters), Onion, DCI và BCE thành một ý tưởng khả thi duy nhất — mục tiêu chung: separation of concerns bằng cách chia phần mềm thành các tầng. Càng đi vào trong, phần mềm càng trừu tượng & cấp policy càng cao; vòng ngoài là cơ chế (mechanisms), vòng trong là chính sách (policies).

03 The Dependency Rule & Crossing Boundaries

Nhưng đôi khi control flow cần đi ngược ra ngoài: use case cần gọi presenter (vòng ngoài). Gọi thẳng sẽ vi phạm Dependency Rule. Lời giải kinh điển ở góc dưới-phải sơ đồ: dùng Dependency Inversion Principle (DIP) — use case gọi một interface (vd "use case output port") nằm ở vòng trong, còn presenter ở vòng ngoài implement interface đó.

flowchart LR
  C["Controller
(adapter)"]:::out -- "control flow" --> UC["Use Case
Interactor"]:::core
  UC -- "control flow" --> P["Presenter
(adapter)"]:::out
  UC -. "định nghĩa interface" .-> OP{{"Output Port
(interface, vòng trong)"}}:::port
  P == "source dep: implements →" ==> OP
  classDef core fill:#c6d6e8,stroke:#2e5e8c,color:#14233b;
  classDef out fill:#e2edf3,stroke:#2f6d93,color:#14233b;
  classDef port fill:#14233b,stroke:#0c1830,color:#fffdf7;
            

RAG · core import abstraction, main ráp concrete

RAG  Use case AnswerQuestion (vòng trong) chỉ biết interface; FAISS & OpenAI (vòng ngoài) implement chúng. Tên faiss, openai không bao giờ xuất hiện trong tầng use case:

# Vòng trong — KHÔNG import faiss, openai, fastapi
class Retriever(Protocol):
    def search(self, q: str) -> list["Chunk"]: ...
class Generator(Protocol):
    def complete(self, prompt: str) -> str: ...

class AnswerQuestion:                       # Use Case Interactor
    def __init__(self, ret: Retriever, gen: Generator):
        self.ret, self.gen = ret, gen
    def run(self, q: str) -> str:           # control flow ra ngoài qua interface
        ctx = self.ret.search(q)            # source dep: trỏ VÀO TRONG
        return self.gen.complete(self.prompt(ctx, q))

04 Presenters & The Humble Object Pattern

Presenter là một dạng của Humble Object pattern — mẫu sinh ra để giúp unit tester tách hành vi KHÓ test khỏi hành vi DỄ test. Cách làm rất đơn giản: chia hành vi thành hai module. Một module humble chứa phần khó test đã được lược bỏ tối đa; module kia chứa toàn bộ phần dễ test vừa được tách ra.

Cả hai nửa đều là thiết kế tốt: gom phần khó test vào một vỏ "khiêm tốn" càng mỏng càng tốt, để phần còn lại test thoải mái — "khó test" ở đây là cố ý, không phải khuyết điểm.

RAG · tách format câu trả lời (dễ test) khỏi gọi LLM (khó test)

RAG  LlmPresenter chỉ format ViewModel — thuần, test được. Phần gọi OpenAI qua mạng (khó test, không tất định) bị đẩy ra humble adapter ở vòng ngoài:

# DỄ test — thuần, không I/O: format answer thành ViewModel
class LlmPresenter:
    def present(self, answer: str, sources: list[str]) -> "AnswerVM":
        return AnswerVM(
            text=answer.strip(),
            citation=", ".join(sources) or "—",
            is_empty=not answer.strip(),     # cờ boolean cho View tô trạng thái
        )

# KHÓ test — humble: chỉ gọi OpenAI rồi giao lại, không chứa logic
class OpenAiGenerator:                       # Frameworks & Drivers
    def complete(self, prompt: str) -> str:
        return openai.responses.create(model="gpt-4o", input=prompt).output_text

05 The Main Component — kẻ "bẩn" nhất

Trong mọi hệ thống luôn có ít nhất một component tạo, điều phối & giám sát những component khác. Martin gọi nó là Main. Nó là the ultimate detail — lowest-level policy, nằm ở vòng ngoài cùng của clean architecture.

RAG · main ráp concrete, đẩy vào use case

RAG  Toàn bộ chi tiết "bẩn" (FAISS, OpenAI, FastAPI route) tập trung ở main; nó wire concrete vào use case rồi giao quyền. Bên PHP web chỉ chạm ranh giới service qua HTTP:

# main = ultimate detail: chỉ ở đây mới import concrete framework
from faiss_store import FaissRetriever
from openai_gen import OpenAiGenerator
from fastapi import FastAPI

def build_ask() -> AnswerQuestion:          # Factory: ráp concrete vào port
    return AnswerQuestion(FaissRetriever("idx.faiss"), OpenAiGenerator())

app = FastAPI()                             # Frameworks & Drivers
ask = build_ask()                          # wire xong, trao quyền cho use case
@app.post("/ask")
def ask_route(q: str): return {"answer": ask.run(q)}

// PHP CHỈ ở ranh giới — web là detail ở vòng ngoài cùng
$res = Http::post('http://rag-svc/ask', ['q' => $question]);
return view('answer', ['vm' => $res->json()]);  // View humble: chỉ đổ ViewModel

06 Ghi nhớ nhanh