matching_app/docs/adapter.md

FORMAT

Title: External System Adapters

Description:

Component Adapter xử lý giao tiếp với các hệ thống bên ngoài. Adapter giúp tách biệt core domain logic khỏi các chi tiết triển khai bên ngoài.

Adapter Categories

Database Adapters

• PersistenceAdapter:
  • Functionality: Interface with PostgreSQL database
  • Location: internal/adapter/postgres/
  • Key Components:
    • connection.go: Database connection pool management
    • profile_repo.go: Repository for Profile aggregate
    • match_repo.go: Repository for MatchOutcome aggregate
    • gift_repo.go: Repository for Gift and GiftAllocation aggregates
    • models.go: Database model definitions

Email Adapters

• EmailAdapter:
  • Functionality: Send emails for user registration, match results, and gift notifications
  • Location: internal/adapter/email/
  • Key Components:
    • client.go: Client interface to email service
    • templates.go: Email templates management

Storage Adapters

• FileStorageAdapter:
  • Functionality: Upload and retrieve files (profile photos)
  • Location: internal/adapter/filestorage/
  • Key Components:
    • s3_client.go: S3 API client implementation
    • validation.go: File validation

Implementation Guidelines

• All adapters should implement a standard interface defined in their respective domain
• Error handling should follow the system-wide error handling strategy
• Configuration should be loaded from environment variables and config files
• Connection pooling should be used where appropriate
• Adapters should be easily replaceable with mock implementations for testing

System Connections

1. External Connections

1.1. Database (PostgreSQL)

• Purpose: Lưu trữ các Aggregate nghiệp vụ (Profile, MatchOutcome, Gift, GiftAllocation)
• Type: Relational Database (PostgreSQL)
• Connection Details: DSN qua biến môi trường (host, port, user, password, dbname)
• Authentication: Credential DB
• Adapter Module: internal/adapter/postgres/connection.go
• Notes: Hỗ trợ JSONB cho các trường linh hoạt

1.2. Email Service

• Purpose: Gửi email xác nhận, kết quả match, thông báo quà tặng
• Type: SMTP/REST
• Connection Details: Cấu hình SMTP server hoặc API endpoint qua env vars
• Authentication: Basic Auth/API Key qua env vars
• Adapter Module: internal/adapter/email/client.go
• Notes: Templates tại internal/adapter/email/templates.go

1.3. File Storage (AWS S3)

• Purpose: Lưu trữ ảnh người dùng
• Type: Object Storage (Amazon S3)
• Connection Details: S3 bucket và credentials qua env vars
• Authentication: AWS IAM Role/Access Keys
• Adapter Module: internal/adapter/filestorage/s3_client.go
• Notes: Validation logic tại internal/adapter/filestorage/validation.go

2. Internal Connections

2.1. API Handlers <-> Persistence Adapter

• Purpose: Thao tác dữ liệu nghiệp vụ
• Interaction Type: Direct function calls
• Details: Ví dụ: handler.profile gọi các method của ProfileRepository

2.2. Transactions <-> Adapters

• UserRegistrationTransaction: PersistenceAdapter, EmailAdapter, FileStorageAdapter
• MatchingTransaction: PersistenceAdapter
• ResultNotificationTransaction: PersistenceAdapter, EmailAdapter
• MatchSelectionTransaction: PersistenceAdapter
• GiftAllocationTransaction: PersistenceAdapter
• GiftNotificationTransaction: PersistenceAdapter, EmailAdapter

Adapters

1. Persistence Adapter (PostgreSQL)

Profile Repository

• SaveProfile(profile Profile) error
• GetProfileByID(id string) (Profile, error)
• GetProfileByAccessCode(code string) (Profile, error)

MatchOutcome Repository

• SaveMatchOutcome(outcome MatchOutcome) error
• GetMatchOutcomeByProfileID(profileID string) (MatchOutcome, error)
• UpdateMatchOutcomeStatus(id string, status string) error

Gift Repository

• GetActiveGifts() ([]Gift, error)
• GetGiftByID(id string) (Gift, error)

2. Email Adapter

Email Client

• SendConfirmationEmail(to string, name string, accessCode string) error
• SendMatchResultEmail(to string, profile Profile, matches []Profile) error
• SendGiftNotificationEmail(to string, profile Profile, gift Gift) error

Email Templates

• Pre-defined templates for each email type with support for variables

3. File Storage Adapter (S3)

Photo Storage

• UploadPhoto(file []byte, filename string) (string, error)
• GetPhotoURL(reference string) (string, error)
• ValidatePhoto(file []byte) error

---