175 lines
7.6 KiB
Markdown
175 lines
7.6 KiB
Markdown
# 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
|
||
```mermaid
|
||
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.]
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
UI -->|Events| BLoC
|
||
BLoC -->|Calls| UseCase
|
||
UseCase -->|Uses| Repository
|
||
Repository -->|Calls| DataSource
|
||
DataSource -->|API/DB| Backend
|
||
```
|
||
--- |