From 7171488b8b7f63036b4af9c49746eac5d57dbf3d Mon Sep 17 00:00:00 2001 From: Pier-Jean Malandrino Date: Thu, 23 Apr 2026 22:47:16 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20rename=20Clean=20Architecture=20?= =?UTF-8?q?=E2=86=92=20Hexagonal=20Architecture=20(ports=20&=20adapters)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Le backend suit le pattern ports & adapters (ports dans domain/ports.py, adaptateurs dans infra/), pas Clean Architecture au sens Uncle Bob. Aligne la terminologie dans README, docs/architecture.md, ADR guide, audit master, fiche audit 01, et la nav mkdocs. Les noms de fichiers et la commande /audit:clean-architecture restent stables pour preserver les liens croises et les skills existants. --- README.md | 2 +- docs/architecture.md | 6 +++--- docs/architecture/adr-guide.md | 2 +- docs/audit/audits/01-clean-architecture.md | 4 ++-- docs/audit/master.md | 4 ++-- mkdocs.yml | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 936dc10..3d6d6a7 100644 --- a/README.md +++ b/README.md @@ -59,7 +59,7 @@ Upload a PDF, configure the extraction pipeline, and visualize the results — t | **frontend** | Vue 3, TypeScript, Vite, Pinia | UI, PDF viewer, results display | | **document-parser** | FastAPI, Docling, SQLite, pdf2image | REST API, document parsing, storage | -### Backend structure (clean architecture) +### Backend structure (hexagonal architecture — ports & adapters) ``` document-parser/ diff --git a/docs/architecture.md b/docs/architecture.md index 764795a..231bdf5 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -8,7 +8,7 @@ Two services communicating via REST. The frontend is a Vue 3 SPA served by Nginx ### Zooming into the backend -The schema above shows the macro view. Inside the backend, the code follows a **Clean Architecture** with strict layer boundaries: +The schema above shows the macro view. Inside the backend, the code follows a **Hexagonal Architecture** (ports & adapters) with strict layer boundaries: ``` ┌──────────────────────────────────────────────────────┐ @@ -34,9 +34,9 @@ The schema above shows the macro view. Inside the backend, the code follows a ** Dependencies flow **inward**: `api → services → domain`. The domain layer has zero knowledge of HTTP or database. -## Backend — Clean Architecture +## Backend — Hexagonal Architecture (ports & adapters) -The backend follows a strict layered architecture. Dependencies flow inward: API → Services → Domain. The domain layer has zero knowledge of HTTP or database. +The backend follows the hexagonal / ports-and-adapters pattern. The domain layer defines **ports** (abstract protocols in `domain/ports.py`); `infra/` provides **adapters** that implement them. Dependencies flow inward: API → Services → Domain. The domain layer has zero knowledge of HTTP, database, or any framework. ``` document-parser/ diff --git a/docs/architecture/adr-guide.md b/docs/architecture/adr-guide.md index b428a86..7953eaf 100644 --- a/docs/architecture/adr-guide.md +++ b/docs/architecture/adr-guide.md @@ -34,7 +34,7 @@ These decisions were made before the ADR process was introduced. They are docume | Decision | Rationale | Date | |----------|-----------|------| -| Clean Architecture (hexagonal) for backend | Decouple domain from framework — enable converter swapping (local/remote) | 2025-01 | +| Hexagonal Architecture (ports & adapters) for backend | Decouple domain from framework — enable converter swapping (local/remote) via ports | 2025-01 | | FastAPI over Django | Async-first, lightweight, Pydantic-native — better fit for a single-purpose API | 2025-01 | | Vue 3 + Pinia over React | Composition API + built-in reactivity — smaller bundle for this use case | 2025-01 | | SQLite over PostgreSQL | Single-file DB, zero ops — appropriate for a document processing tool | 2025-01 | diff --git a/docs/audit/audits/01-clean-architecture.md b/docs/audit/audits/01-clean-architecture.md index 3e8538d..9bda091 100644 --- a/docs/audit/audits/01-clean-architecture.md +++ b/docs/audit/audits/01-clean-architecture.md @@ -1,6 +1,6 @@ -# Audit 01 — Clean Architecture +# Audit 01 — Hexagonal Architecture (ports & adapters) -**Objectif** : verifier que le backend respecte le flux de dependances strict `api -> services -> domain` et que chaque couche a une responsabilite claire. +**Objectif** : verifier que le backend respecte le pattern hexagonal (ports dans `domain/ports.py`, adaptateurs dans `infra/`), le flux de dependances strict `api -> services -> domain`, et que chaque couche a une responsabilite claire. **Cible** : `document-parser/` (hors `.venv/`, `__pycache__/`, `tests/`) diff --git a/docs/audit/master.md b/docs/audit/master.md index 38d5427..7209c9f 100644 --- a/docs/audit/master.md +++ b/docs/audit/master.md @@ -74,7 +74,7 @@ Les audits sont executes dans l'ordre ci-dessous. Chacun est une fiche autonome | # | Audit | Fichier | Focus | |---|-------|---------|-------| -| 01 | Clean Architecture | [01-clean-architecture.md](audits/01-clean-architecture.md) | Respect des couches, flux de dependances | +| 01 | Hexagonal Architecture | [01-clean-architecture.md](audits/01-clean-architecture.md) | Ports & adapters, respect des couches, flux de dependances | | 02 | DDD | [02-ddd.md](audits/02-ddd.md) | Bounded contexts, entites, value objects, ubiquitous language | | 03 | Clean Code | [03-clean-code.md](audits/03-clean-code.md) | Nommage, taille, lisibilite | | 04 | KISS | [04-kiss.md](audits/04-kiss.md) | Simplicite, pas de sur-ingenierie | @@ -161,7 +161,7 @@ Le fichier `reports/release-X.Y.Z/summary.md` consolide tous les audits : | # | Audit | Score | CRIT | MAJ | MIN | INFO | Verdict | |---|-------|-------|------|-----|-----|------|---------| -| 01 | Clean Architecture | XX | N | N | N | N | GO | +| 01 | Hexagonal Architecture | XX | N | N | N | N | GO | | 02 | DDD | XX | N | N | N | N | GO | | ... | ... | ... | ... | ... | ... | ... | ... | diff --git a/mkdocs.yml b/mkdocs.yml index 6b680c8..9804d4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -57,7 +57,7 @@ nav: - Audit: - Audit Master: audit/master.md - Audits: - - Clean Architecture: audit/audits/01-clean-architecture.md + - Hexagonal Architecture: audit/audits/01-clean-architecture.md - DDD: audit/audits/02-ddd.md - Clean Code: audit/audits/03-clean-code.md - KISS: audit/audits/04-kiss.md