feat: add guide

2026-08-22 08:29:30 +07:00
parent 3d22e0dfc0
commit 1715e366c6
5 changed files with 447 additions and 0 deletions
@@ -0,0 +1,116 @@
+# APLP Backend — Architecture
+
+| | |
+| --- | --- |
+| **Module** | `aplp.backend.spring` |
+| **Role** | Backend cho **aplp-web** (learner application) |
+| **Status** | Draft |
+
+---
+
+## 1. Architectural Direction
+
+Backend theo **Modular Monolith**, kết hợp:
+
+```
+Modular Monolith
+ Clean Architecture 4 Layers
+ DDD-oriented
+ Vertical Slice / Business Module
+```
+
+Nguyên tắc nền tảng:
+
+> **Business behavior first, database second.**
+
+> **Modular Monolith first; extract service chỉ khi có demonstrated need.**
+
+## 2. Request Flow
+
+```
+Controller (API layer)
+    ↓
+Application / Service (use case)
+    ↓
+Domain (business rules / model)
+    ↓
+Persistence (repository)
+    ↓
+Database
+```
+
+## 3. Clean Architecture — 4 Layers
+
+Mỗi business module có 4 layer rõ ràng:
+
+| Layer | Trách nhiệm | Should NOT do |
+| --- | --- | --- |
+| **Interface/API** | HTTP entry point, DTO request/response, validation cơ bản, tách biệt khỏi domain | Chứa business logic |
+| **Application** | Use case orchestration, transactions, authorization | Chứa domain business rules |
+| **Domain** | Entities, value objects, business rules, domain services | Phụ thuộc DB/HTTP |
+| **Persistence** | Repository implementation, mapping, DB access | Chứa business rules |
+
+**Dependency rule:** chỉ phụ thuộc từ ngoài vào trong (API → Application → Domain); Persistence implement interface do Domain/Application định nghĩa.
+
+## 4. Modular Monolith
+
+- Code tổ chức theo **business module** (vertical slice), không theo technical layer toàn cục.
+- Mỗi module đóng gói `interface + application + domain + persistence` cho một business capability.
+- Module giao tiếp qua public API/interface; **không** import nội bộ module khác.
+- Module registry/config ở application root.
+
+### Module Boundary
+
+```
+com.aplp.backend
+└── <module> (vd: identity, learner, content, learning, assessment, adaptive, ...)
+    ├── api         (controller, dto)
+    ├── application (use case, service)
+    ├── domain      (model, domain service, rules, repository interface)
+    └── persistence (repository impl, entity mapping, jpa)
+```
+
+## 5. DDD Orientation
+
+- **Aggregate** là ranh giới bảo toàn bất biến (invariant) trong cùng transaction.
+- **Value Objects** dùng cho khái niệm không có identity riêng (Score, Money, MasteryLevel).
+- **Domain Event** (optional, temporal) dùng khi cần tách rời side-effect giữa modules — **không** lạm dụng cho tất cả luồng.
+- **Repository interface** ở domain, implementation ở persistence.
+
+## 6. Database
+
+- Relational database: **PostgreSQL** (chosen). Dev chạy qua `docker-compose` (port 5433); test dùng H2 (PostgreSQL mode).
+- Migrations: **Flyway** (chosen) tại `src/main/resources/db/migration`. `spring.jpa.hibernate.ddl-auto=validate`.
+- Schema phản ánh domain model, không thiết kế "database-first".
+
+## 7. Cross-Cutting Concerns
+
+- **Security / AuthN**: xử lý ở API/boundary layer (Phase 0).
+- **Validation**: input validation ở API; business invariant validation ở domain.
+- **Logging & Observability**: structured logging, common config (Phase 9 mở rộng metrics/tracing).
+- **Errors**: exception mapping, đồng nhất response format.
+
+## 8. Deferred (tránh dùng khi chưa có justification)
+
+- Microservices split
+- API Gateway
+- Kafka / Event-driven
+- Redis
+- Elasticsearch
+- CQRS / Event Sourcing
+
+## 9. Deployment
+
+- **Docker first** (containerize backend).
+- **Kubernetes later** khi có nhu cầu scale/ops.
+
+## 10. Open Questions (backend-specific)
+
+| ID | Question | Impact | Proposed Direction | Status |
+| --- | --- | --- | --- | --- |
+| ARC-001 | Spring Boot version nào cho foundation? | Setup | Dùng phiên bản ổn định mới nhất hỗ trợ Java LTS | **Resolved**: Spring Boot 3.5.16 + Java 21 (Maven) |
+| ARC-002 | JWT hay session cho authentication? | Security | JWT stateless + refresh flow | **Resolved**: JWT (access + rotating refresh, refresh token hash lưu DB) |
+| ARC-003 | DB: PostgreSQL vs MySQL? | Setup | PostgreSQL | **Resolved**: PostgreSQL 17 (docker-compose) |
+| ARC-004 | Migration: Flyway vs Liquibase? | Setup | Flyway | **Resolved**: Flyway |
+| ARC-005 | Content đọc từ LMS qua API hay shared read model? | Module boundary | API/read model của LMS | Open (Phase 2) |
+| ARC-006 | Transaction boundary giữa module nào cần được phân tách? | Data consistency | Ghi rõ trong từng use case | Open |