ADR-0001: Kiến trúc microservices với NestJS trong NX monorepo

Status: Accepted
Date: ~2026-06-27 (backfilled 2026-07-25 — quyết định gốc có thể sớm hơn, trước khi repo này được tách/migrate sang K3s)
Supersedes: —
Superseded by: —

Bối cảnh

Hệ thống football booking cần tách biệt các bounded context rõ ràng (user, field, booking, payment, notification) để scale độc lập và giới hạn blast radius khi một domain lỗi. Team cần một cách tổ chức code cho phép chia sẻ logic chung (DTO, exception, cấu hình, observability...) giữa nhiều service mà không copy-paste.

Quyết định

Dùng kiến trúc microservices + API Gateway, xây trên NestJS, tổ chức trong một NX monorepo:

apps/api-gateway — entry point, auth, proxy routing, cross-cutting concerns (port 3000)
apps/user-service (3001), apps/field-service (3002), apps/booking-service (3003), apps/payment-service (3004), apps/notification-service (3005)
Code dùng chung đặt ở libs/: shared, database, messaging, cache, observability, config
Giao tiếp: sync qua api-gateway proxy HTTP tới các service nội bộ; async qua Kafka topics (xem ADR-0006)

Lựa chọn khác đã cân nhắc

Monolith NestJS module hoá: đơn giản hơn để vận hành ở giai đoạn đầu, nhưng không tách được scaling/deploy theo từng domain — loại vì mục tiêu học/triển khai theo hướng microservices + K3s.
Đa repo (polyrepo) mỗi service 1 repo: cô lập tốt hơn nhưng chi phí đồng bộ version của libs/shared giữa các repo cao, khó refactor cross-service — loại.

Hệ quả

Được: scale/deploy độc lập từng service trên K3s; chia sẻ code qua libs/ mà vẫn build/test riêng từng app nhờ NX; đường biên domain rõ ràng.
Đánh đổi: cần API Gateway để tổng hợp/route request; distributed tracing bắt buộc để debug xuyên service (xem ADR-0004); thêm chi phí vận hành nhiều container/DB so với monolith.

Liên kết

Docs liên quan: docs/ARCHITECTURE.md, docs/requirements/06-SYSTEM-DESIGN.md