FORMAT

Title: System Architecture

1. Architecture Overview

Nguyên tắc thiết kế

User-Centric: Ưu tiên trải nghiệm người dùng, giảm thiểu sự phức tạp
Data-Oriented Programming (DOP): Thiết kế xoay quanh luồng dữ liệu và các biến đổi dữ liệu
Domain-Driven Design (DDD): Áp dụng các khái niệm cốt lõi (Bounded Context, Aggregates, Domain Events)

System-Wide Error Handling Strategy

Detection & Categorization: Errors will be detected at various layers (API validation, Transaction logic, Adapter communication). Errors will be categorized (e.g., user input error, resource not found, external service failure, internal server error).
Propagation: Errors from lower layers (Adapters, Resources) will be propagated up to the calling Transaction or API Handler, potentially wrapped for context.
Logging: All significant errors (especially non-user correctable ones) will be logged centrally with structured information (timestamp, error type, stack trace if applicable, request context). A dedicated Logging Helper will be used.
State Consistency: Database transactions within the PersistenceAdapter will be used to ensure atomic updates to Resources, maintaining consistency in case of errors during writes. Sagas (Transaction components) will handle logical consistency across multiple steps (though complex compensation is expected to be minimal).
Communication:
- To Users (via HTMX/API): User input errors will result in user-friendly messages, potentially rendered directly into HTML fragments by the backend. Generic messages will be used for unexpected server errors to avoid exposing internal details. Standard HTTP status codes will be used (e.g., 400 for bad input, 404 for not found, 500 for server error).
- To Admins: Detailed error information will be available in logs. The Admin Dashboard might display specific error summaries or alerts for critical issues.

Thành phần kiến trúc chính

Resource: Các Aggregate DDD đại diện cho đối tượng nghiệp vụ
Transaction: Các Saga/Process Manager điều phối luồng nghiệp vụ phức tạp
Adapter: Xử lý giao tiếp với các hệ thống bên ngoài
Helper: Các thư viện, tiện ích dùng chung
UIUX: Lớp giao diện người dùng

Container Architecture

Docker Setup:
- Multi-stage builds để tối ưu kích thước image
- Non-root user cho bảo mật
- Healthcheck tự động kiểm tra trạng thái
- Resource limits (CPU/Memory) cho từng service

Deployment Diagram

graph TD
  A[User] --> B[Frontend]
  B --> C[Backend API]
  C --> D[(PostgreSQL)]
  C --> E[Email Service]
  C --> F[S3 Storage]
  style A fill:#f9f,stroke:#333
  style B fill:#bbf,stroke:#333
  style C fill:#f96,stroke:#333

Phân cấp độ chi tiết (U-Hierarchy)

ubit: Đơn vị logic nhỏ nhất (hàm, type, hằng số)
ubrick: Tập hợp các ubit liên quan
ublock: Thành phần hoạt động độc lập tương đối
ubundle: Tính năng hoàn chỉnh cho người dùng

Công nghệ

Backend: Go
Database: PostgreSQL (có thể dùng JSONB cho một số trường linh hoạt)
Frontend: HTMX (ưu tiên), JavaScript hạn chế
Deployment: Docker, triển khai trên Cloud (VPS Storage)
CI/CD Integration: DroneCI
Database: Managed PostgreSQL Service
Frontend Serving: Backend render HTML fragments, CDN cho static assets

2. Project Structure

Directory Tree

matchmaking-microsite/ ├── cmd/ │ └── api/ │ └── main.go ├── internal/ │ ├── resource/ │ │ ├── profile/ │ │ │ ├── profile_aggregate.go │ │ │ ├── profile_state.go │ │ │ ├── profile_validation.go │ │ │ ├── profile_access.go │ │ │ ├── profile_zodiac.go │ │ │ └── profile_types.go │ │ ├── matchoutcome/ │ │ │ ├── matchoutcome_aggregate.go │ │ │ ├── matchoutcome_state.go │ │ │ ├── matchoutcome_formatter.go │ │ │ └── matchoutcome_types.go │ │ ├── giftallocation/ │ │ │ ├── giftallocation_aggregate.go │ │ │ └── giftallocation_notifier.go │ │ └── gift/ │ │ ├── gift_aggregate.go │ │ └── gift_validator.go │ ├── transaction/ │ │ ├── registration/ │ │ │ └── saga.go │ │ ├── matching/ │ │ │ ├── saga.go │ │ │ └── filter.go │ │ ├── resultnotif/ │ │ │ └── saga.go │ │ └── giftalloc/ │ │ └── saga.go │ ├── adapter/ │ │ ├── postgres/ │ │ │ ├── connection.go │ │ │ ├── profile_repo.go │ │ │ ├── match_repo.go │ │ │ ├── gift_repo.go │ │ │ └── models.go │ │ ├── email/ │ │ │ ├── client.go │ │ │ └── templates.go │ │ └── filestorage/ │ │ ├── s3_client.go │ │ └── validation.go │ ├── helper/ │ │ ├── config/ │ │ │ └── load.go │ │ ├── logger/ │ │ │ └── log.go │ │ ├── validation/ │ │ │ └── common.go │ │ ├── datetime/ │ │ │ └── calc.go │ │ └── security/ │ │ └── hash.go │ └── api/ │ ├── handler/ │ │ ├── profile.go │ │ ├── result.go │ │ ├── admin.go │ │ └── middleware.go │ ├── router.go │ └── dto/ │ ├── request.go │ └── response.go ├── configs/ │ ├── config.dev.yaml │ └── config.prod.yaml ├── migrations/ │ └── 001_create_tables.sql ├── go.mod ├── go.sum ├── .gitignore └── README.md

Structure Explanation

Cấu trúc tổ chức theo mô hình Domain-Driven Design: cmd chứa entrypoint, internal phân chia theo domain (resource, transaction, adapter, helper, api) đảm bảo tách biệt concern. Thư mục ngoài (configs, migrations, go.mod, README.md) phục vụ cấu hình, database migration và thông tin dự án.

3. Key Components

[Detailed description of the important components of the system. For each component, can include:]

3.1. [Component Name]

Description: [Detailed description of the component's function and responsibilities.]
Location in Directory Tree (if relevant): [Directory path]
Dependencies: [List of components this component depends on.]
Interactions with Other Components: [Description of how this component interacts with other parts of the system.]

3.2. [Another Component Name]

Description: [...]
Location in Directory Tree (if relevant): [...]
Dependencies: [...]
Interactions with Other Components: [...]

4. Main Data Flow

[Description of the most important data flows in the system, such as user creation flow, order processing flow. Can use a Mermaid diagram for visualization.]

flowchart LR
    UI -->|Events| BLoC
    BLoC -->|Calls| UseCase
    UseCase -->|Uses| Repository
    Repository -->|Calls| DataSource
    DataSource -->|API/DB| Backend

7.6 KiB Raw Blame History