# 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`
---