Technical Strategy & Architecture Decision Making

# ADR-042: Dùng PostgreSQL + pgvector thay vì Qdrant cho RAG System

**Status**: Accepted (2024-03-15)
**Deciders**: @khoa (Tech Lead), @tuan (Backend), @hoa (DevOps)

## Context
Chúng ta đang build RAG system cho chatbot hỗ trợ khách hàng.
Cần lưu trữ và tìm kiếm ~5M embeddings (1536 dims).
Team hiện tại đã quen vận hành PostgreSQL, chưa có kinh nghiệm với
distributed vector database.

## Decision
Dùng PostgreSQL với extension pgvector thay vì deploy Qdrant riêng.

## Consequences
**Positive:**
- Giảm infra complexity (không cần vận hành thêm 1 service)
- Tận dụng được row-level security của Postgres cho multi-tenancy
- Team đã quen với Postgres ops (backup, monitoring, failover)
- SQL JOIN với relational data đơn giản hơn

**Negative:**
- Throughput thấp hơn Qdrant (benchmark: ~3K vs ~100K QPS)
- Nếu scale lên >50M vectors, sẽ cần migrate sang dedicated solution
- Index build time chậm hơn với HNSW lớn

## Alternatives Considered
- **Qdrant**: Performance tốt hơn, nhưng tốn effort vận hành. Rejected vì
  team size nhỏ và current load chưa cần thiết.
- **Pinecone**: SaaS, không cần ops, nhưng vendor lock-in và data privacy concern.
  Rejected vì data sensitivity.

## Review Trigger
Revisit khi: vector count > 20M, hoặc p99 search latency > 100ms under load.

Cần ADR:
  - Chọn technology stack mới (database, message queue, cache)
  - Thay đổi API contract (backward-incompatible)
  - Quyết định kiến trúc ảnh hưởng nhiều team
  - Bất kỳ tradeoff nào mà tương lai sẽ hỏi "tại sao lại làm vậy?"

Không cần ADR:
  - Bug fix
  - Refactoring không thay đổi behavior
  - Upgrade patch version của dependency
  - Implementation detail trong module nhỏ

Tech Debt tốt (Deliberate):
  → Biết mình đang "vay", có kế hoạch trả
  → "Ship MVP với in-memory storage, sẽ migrate sang Redis sau khi validate"
  → Trade-off có ý thức với business benefit rõ ràng

Tech Debt xấu (Accidental):
  → Không biết mình đang tạo ra debt
  → "Mọi người cứ copy-paste cái function này, tốt nhất không nên đụng vào"
  → Debt ẩn, không ai muốn nhận ownership

Technical Debt Map:
  ┌──────────────────────────────────────────────────────┐
  │                                                        │
  │   Architecture Debt:  Kiến trúc sai từ căn bản        │
  │   Ví dụ: Monolith không thể scale theo request pattern │
  │   Cost: Thường cần nhiều tháng, multiple team          │
  │                                                        │
  │   Code Debt:  Code khó hiểu, không test được          │
  │   Ví dụ: 2000-line functions, spaghetti dependencies   │
  │   Cost: Days to weeks per area                         │
  │                                                        │
  │   Infrastructure Debt: Infra outdated, không secure    │
  │   Ví dụ: Still on Ubuntu 18.04, HTTP không HTTPS       │
  │   Cost: Days to weeks, risk-driven                     │
  │                                                        │
  │   Dependency Debt: Dependencies outdated               │
  │   Ví dụ: 3 major versions behind, security CVEs        │
  │   Cost: Hours to days per dependency                   │
  └──────────────────────────────────────────────────────┘

❌ Nói với Product:
"Hệ thống authentication của mình có tech debt nặng,
middleware viết từ 2019, khó maintain lắm."

✅ Nói với Product:
"Hiện tại mỗi khi add feature mới vào flow authentication,
team mất trung bình 2 tuần thay vì 3 ngày vì codebase phức tạp.
Nếu đầu tư 3 sprint để refactor, velocity của team sẽ tăng ~40%
cho tất cả auth-related work trong 6 tháng tới.
Ngoài ra, đợt security audit tháng trước flag 2 potential vulnerabilities
trong code cũ này — risk cần address trước Q2."

Build khi:
  ✅ Đây là core competency / competitive advantage của sản phẩm
     Ví dụ: Netflix build recommendation engine vì đó là giá trị cốt lõi
  
  ✅ Requirements cực kỳ specific, không solution nào fit
     Ví dụ: Trading algorithm với latency microseconds
  
  ✅ Existing solutions đều quá nặng hoặc bring unwanted complexity
     Ví dụ: Build in-house config management thay vì deploy full Consul
     cho 5-service startup

Đừng Build khi:
  ❌ Đây là commodity problem (auth, logging, monitoring)
  ❌ Team không có domain expertise để maintain long-term
  ❌ Timeline quả ngắn để build đúng cách

Buy khi:
  ✅ Problem là non-differentiating (không phải lợi thế cạnh tranh)
     Ví dụ: Email sending, Payment processing, Analytics
  
  ✅ Vendor cung cấp expertise mà team không có
     Ví dụ: Security compliance (SOC2), ML model serving
  
  ✅ TCO của self-host cao hơn SaaS fee
     (TCO = licensing + eng time + ops time + incident cost)

Risks của Buy:
  ❌ Vendor lock-in: Khó migrate sau nếu cần
  ❌ Data privacy: Data đi ra third party
  ❌ Cost có thể tăng đột ngột (pricing change)
  ❌ SLA của vendor ảnh hưởng đến SLA của bạn

Open Source khi:
  ✅ Community active, project mature (không abandoned)
  ✅ License phù hợp với business model của bạn
     (MIT/Apache 2.0: OK; GPL: cẩn thận với commercial; AGPL: risky)
  ✅ Team có capacity để maintain fork nếu cần
  ✅ Không cần commercial support

Risks:
  ❌ Maintainer burnout → project abandoned
  ❌ Security vulnerability không được patch kịp
  ❌ License change (HashiCorp → BSL, Redis → SSPLv1)
  ❌ "Not invented here" trap: tự build khi OSS đã đủ tốt

Scenario: Cần message queue cho event-driven system

Build: ❌ (commodity, đã có solutions mature)

Buy (AWS SQS/SNS): 
  + Managed, scale tự động
  + Không ops burden
  - Vendor lock-in
  - Latency cao hơn self-host
  → Chọn nếu: team nhỏ, startup giai đoạn early

OSS (Kafka self-host):
  + Full control, performance cao
  + Không vendor lock-in
  - Ops burden nặng (Kafka là infra phức tạp)
  - Cần specialist knowledge
  → Chọn nếu: scale lớn, team có Kafka expertise, latency critical

OSS (Managed Confluent/MSK):
  + Best of both: OSS Kafka + managed ops
  - Đắt hơn raw SQS
  → Chọn nếu: cần Kafka feature nhưng không muốn tự ops

Product Roadmap (Q1-Q4 2025):
  Q1: Launch mobile app
  Q2: International expansion (EU)
  Q3: Enterprise tier
  Q4: ML-powered recommendations

Tương ứng, Technical Roadmap:
  Q4 2024 (prerequisites):
    - Set up CDN cho performance mobile
    - Data residency compliance (GDPR) cho EU
  Q1:
    - API versioning để support mobile client
    - Mobile auth (push notifications, biometric)
  Q2:
    - Multi-region deployment (EU datacenter)
    - i18n framework
  Q3:
    - SSO/SAML cho Enterprise
    - Advanced audit logging
  Q4:
    - ML infrastructure (feature store, model serving)
    - A/B testing platform

Step 1: Understand Product Strategy (6-12 months)
  → Meeting với Product/Business để hiểu direction
  → Identify technical implications của mỗi product goal

Step 2: Audit Technical Health hiện tại
  → Đánh giá tech debt, scalability bottlenecks, security gaps
  → Identify: "Cái gì sẽ fall apart nếu load tăng 10x?"

Step 3: Identify Technical Enablers
  → Những gì team cần xây để unlock product features nhanh hơn?
  → Platform investments: observability, CI/CD, developer experience

Step 4: Prioritize và Sequence
  → Dependencies giữa các items
  → Risk-adjusted priority: urgent (security) > important (scale) > nice-to-have
  → Realistic capacity planning (thường team overestimate 30-40%)

Step 5: Communicate và Iterate
  → Present cho Product/Leadership với tradeoffs rõ ràng
  → Review quarterly, update assumptions
  → "Roadmap là living document, không phải commitment"

Pitfall 1: Over-engineering future
  "Chúng ta sẽ cần sharding khi có 1 tỷ users"
  → Bạn có 10K users hiện tại. Focus on what's needed next 6 months.
  
Pitfall 2: Tech Roadmap không sync với Product Roadmap
  → Technical work cần deliver value cho product goals, không phải 
  chỉ là "tech for tech's sake"
  
Pitfall 3: Quên Buffer time
  → Incidents, on-call, recruiting, onboarding ăn 30-40% capacity
  → Kế hoạch phải tính đến điều này