pos-system/docs/vi/templates/architecture.md

[Architecture Name] / [Tên Kiến trúc]

EN: Brief English description of this architectural component or system VI: Mô tả ngắn gọn bằng tiếng Việt về thành phần kiến trúc hoặc hệ thống này

Overview Diagram / Sơ đồ Tổng quan

graph TD
    A[Component A] --> B[Component B]
    B --> C[Component C]
    C --> D[Component D]
    
    style A fill:#e1f5ff
    style B fill:#fff4e1
    style C fill:#f0e1ff
    style D fill:#e1ffe1

Architecture Description / Mô tả Kiến trúc

EN: English Section

Detailed English explanation of the architecture, including:

• Purpose and goals
• Key components
• Design decisions
• Technology choices
• Trade-offs and considerations

VI: Phần Tiếng Việt

Giải thích chi tiết bằng tiếng Việt về kiến trúc, bao gồm:

• Mục đích và mục tiêu
• Các thành phần chính
• Quyết định thiết kế
• Lựa chọn công nghệ
• Đánh đổi và cân nhắc

System Context / Bối cảnh Hệ thống

C4Context
    title System Context Diagram for GoodGo Microservices Platform
    
    Person(user, "End User", "Platform users")
    Person(admin, "Administrator", "System administrators")
    
    System_Boundary(platform, "GoodGo Platform") {
        System(gateway, "Traefik Gateway", "API Gateway, routing, load balancing")
        System(services, "Microservices", "IAM, Storage, Chat, Membership, etc.")
        System(rabbitmq, "RabbitMQ", "Message broker for async events")
    }
    
    System_Ext(neon, "Neon PostgreSQL", "Serverless database")
    System_Ext(redis, "Redis", "Cache and session store")
    System_Ext(minio, "MinIO/Aliyun OSS", "Object storage")
    System_Ext(monitoring, "Observability Stack", "Prometheus + Grafana + Loki + Jaeger")
    
    Rel(user, gateway, "Uses", "HTTPS")
    Rel(admin, gateway, "Manages", "HTTPS")
    Rel(gateway, services, "Routes to", "HTTP")
    Rel(services, neon, "Stores data", "PostgreSQL")
    Rel(services, redis, "Caches data", "Redis Protocol")
    Rel(services, rabbitmq, "Pub/Sub events", "AMQP")
    Rel(services, minio, "Stores files", "S3 API")
    Rel(services, monitoring, "Sends telemetry", "HTTP/gRPC")

EN: The GoodGo Platform uses microservices architecture where all client requests go through Traefik API Gateway. Services communicate synchronously via REST/HTTP and asynchronously via RabbitMQ events. Each service has its own database schema in Neon PostgreSQL and uses Redis for caching.

VI: Nền tảng GoodGo sử dụng kiến trúc microservices nơi tất cả requests từ client đi qua Traefik API Gateway. Các services giao tiếp đồng bộ qua REST/HTTP và bất đồng bộ qua RabbitMQ events. Mỗi service có database schema riêng trong Neon PostgreSQL và sử dụng Redis cho caching.

Components / Thành phần

Component A / Thành phần A

EN: Description of Component A, its responsibilities, and how it fits into the overall architecture.

VI: Mô tả Thành phần A, trách nhiệm của nó và cách nó khớp vào kiến trúc tổng thể.

Key Features / Tính năng chính:

• Feature 1 / Tính năng 1
• Feature 2 / Tính năng 2
• Feature 3 / Tính năng 3

Technologies Used / Công nghệ sử dụng:

• Technology 1
• Technology 2

Code Reference / Tham chiếu Code:

// EN: Example code showing how this component is implemented
// VI: Ví dụ code cho thấy cách thành phần này được triển khai
import { ComponentA } from './component-a';

const componentA = new ComponentA({
  config: appConfig,
});

File Location: component-a.ts

---

Real-World Example: Storage Service / Ví dụ Thực tế: Storage Service

EN: File storage management service supporting multiple cloud providers (MinIO, Aliyun OSS).

VI: Service quản lý lưu trữ file hỗ trợ nhiều cloud providers (MinIO, Aliyun OSS).

Key Features / Tính năng chính:

• Multi-provider pattern (MinIO/Aliyun OSS)
• Pre-signed URL generation for secure uploads/downloads
• User quota management
• File sharing với time-limited tokens
• Direct client upload pattern

Technologies Used / Công nghệ sử dụng:

• .NET 10, Entity Framework Core
• MinIO Client, Aliyun OSS SDK
• Redis (caching)
• PostgreSQL (Neon)

Architecture Pattern:

// Provider abstraction
public interface IStorageProvider
{
    Task<string> UploadFileAsync(Stream fileStream, string fileName, CancellationToken ct);
    Task<string> GeneratePresignedUrlAsync(string objectKey, int expiryMinutes, CancellationToken ct);
}

// Concrete implementations
public class MinioStorageProvider : IStorageProvider { }
public class AliyunOssStorageProvider : IStorageProvider { }

// Factory pattern for provider selection
public class StorageProviderFactory
{
    public IStorageProvider CreateProvider(string providerName) { }
}

File Location: services/storage-service-net/

---

Real-World Example: IAM Service / Ví dụ Thực tế: IAM Service

EN: Identity and Access Management service handling authentication, authorization, and RBAC.

VI: Service quản lý định danh và truy cập xử lý xác thực, phân quyền và RBAC.

Key Features / Tính năng chính:

• JWT authentication (RS256)
• Role-Based Access Control (RBAC)
• MFA support (TOTP)
• Session management
• Permission caching

Technologies Used / Công nghệ sử dụng:

• .NET 10, Duende IdentityServer
• Entity Framework Core
• Redis (caching)
• PostgreSQL (Neon)

File Location: services/iam-service-net/

Data Flow / Luồng Dữ liệu

sequenceDiagram
    participant Client
    participant API
    participant Service
    participant Database
    
    Client->>API: Request
    API->>Service: Process
    Service->>Database: Query
    Database-->>Service: Result
    Service-->>API: Response
    API-->>Client: JSON

EN: Detailed explanation of the data flow:

1. Step 1: Description
2. Step 2: Description
3. Step 3: Description

VI: Giải thích chi tiết về luồng dữ liệu:

1. Bước 1: Mô tả
2. Bước 2: Mô tả
3. Bước 3: Mô tả

Database Architecture / Kiến trúc Database

erDiagram
    Entity1 ||--o{ Entity2 : has
    Entity2 ||--o{ Entity3 : contains
    
    Entity1 {
        string id PK
        string name
        datetime createdAt
    }
    
    Entity2 {
        string id PK
        string entity1Id FK
        string description
    }

EN: Database schema description, relationships, and design decisions.

VI: Mô tả schema database, mối quan hệ và quyết định thiết kế.

Design Decisions / Quyết định Thiết kế

Decision 1 / Quyết định 1: [Decision Title]

EN Context: Why this decision was needed

VI Bối cảnh: Tại sao quyết định này cần thiết

EN Decision: What was decided

VI Quyết định: Điều gì đã được quyết định

EN Consequences: Impact of the decision (positive and negative)

VI Hậu quả: Tác động của quyết định (tích cực và tiêu cực)

EN Alternatives Considered: Other options that were evaluated

VI Các lựa chọn thay thế: Các tùy chọn khác đã được đánh giá

Performance Characteristics / Đặc điểm Hiệu suất

EN: Description of performance expectations and optimizations based on GoodGo Platform standards.

VI: Mô tả kỳ vọng hiệu suất và tối ưu hóa dựa trên chuẩn GoodGo Platform.

Metric / Chỉ số	Target / Mục tiêu	Notes / Ghi chú
API Response Time (P95) / Thời gian phản hồi API	< 200ms	Excluding external API calls
API Response Time (P99) / Thời gian phản hồi API	< 500ms	Peak load scenarios
Throughput / Thông lượng	1000 req/s	Per service instance
Database Query Time (P95) / Truy vấn Database	< 50ms	Simple queries with indexes
Cache Hit Rate (L1) / Tỷ lệ cache hit	> 40%	In-memory cache
Cache Hit Rate (L2) / Tỷ lệ cache hit	> 80%	Redis cache
Service Availability / Tính khả dụng	> 99.9%	Monthly uptime target
Error Rate / Tỷ lệ lỗi	< 1%	4xx + 5xx errors

Optimization Strategies / Chiến lược Tối ưu:

• Multi-layer caching: L1 (Memory) + L2 (Redis)
• Connection pooling: For PostgreSQL connections
• Pagination: Max 100 items per page for list endpoints
• Database indexes: On frequently queried fields
• Async events: Fire-and-forget với RabbitMQ
• CDN: For static assets (Next.js)

Security Considerations / Cân nhắc Bảo mật

EN: Security features, authentication, authorization, data protection

VI: Tính năng bảo mật, xác thực, phân quyền, bảo vệ dữ liệu

• Security feature 1 / Tính năng bảo mật 1
• Security feature 2 / Tính năng bảo mật 2

Deployment / Triển khai

EN: How this architecture is deployed and scaled in GoodGo Platform.

VI: Cách kiến trúc này được triển khai và mở rộng trong GoodGo Platform.

Traefik API Gateway Routing

# docker-compose.yml
services:
  storage-service-net:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.storage-service.rule=PathPrefix(`/api/v1/storage`)"
      - "traefik.http.services.storage-service.loadbalancer.server.port=8080"
      - "traefik.http.routers.storage-service.middlewares=strip-prefix@docker"

Kubernetes Deployment

graph LR
    LB[Load Balancer] --> Traefik[Traefik Gateway<br/>2-3 replicas]
    Traefik --> A[Service A<br/>2-10 replicas HPA]
    Traefik --> B[Service B<br/>2-10 replicas HPA]
    Traefik --> C[Service C<br/>2-10 replicas HPA]
    A --> DB[(Neon PostgreSQL<br/>Serverless)]
    B --> DB
    C --> DB
    A --> Cache[(Redis Cluster<br/>3 nodes)]
    B --> Cache
    C --> Cache
    
    style LB fill:#1565c0,stroke:#fff,stroke-width:2px,color:#fff
    style Traefik fill:#0f4c81,stroke:#fff,stroke-width:2px,color:#fff
    style A fill:#283593,stroke:#fff,stroke-width:2px,color:#fff
    style B fill:#4527a0,stroke:#fff,stroke-width:2px,color:#fff
    style C fill:#4527a0,stroke:#fff,stroke-width:2px,color:#fff
    style DB fill:#5e35b1,stroke:#fff,stroke-width:2px,color:#fff
    style Cache fill:#ef6c00,stroke:#fff,stroke-width:2px,color:#fff

Resource Allocation / Phân bổ Tài nguyên:

Service	Requests	Limits
Microservices	256Mi RAM, 250m CPU	512Mi RAM, 500m CPU
Traefik	512Mi RAM, 500m CPU	1Gi RAM, 1000m CPU
Redis	2Gi RAM, 1 CPU	4Gi RAM, 2 CPU

Monitoring & Observability / Giám sát & Khả năng quan sát

EN: How to monitor this architecture, key metrics, alerts

VI: Cách giám sát kiến trúc này, các chỉ số chính, cảnh báo

Key Metrics / Chỉ số chính:

• Metric 1 / Chỉ số 1
• Metric 2 / Chỉ số 2

Health Checks / Kiểm tra Sức khỏe:

• /health/live - Liveness probe
• /health/ready - Readiness probe

Related Documentation / Tài liệu Liên quan

Architecture Documents

• System Design - EN: Overall platform architecture / VI: Kiến trúc tổng thể platform
• Microservices Communication - EN: Service communication patterns / VI: Patterns giao tiếp services
• Caching Architecture - EN: Redis caching strategies / VI: Chiến lược Redis caching
• Event-Driven Architecture - EN: RabbitMQ event patterns / VI: Patterns RabbitMQ events

Skills Reference

• CQRS with MediatR - EN: CQRS pattern / VI: Pattern CQRS
• Repository Pattern - EN: EF Core repository / VI: Repository EF Core
• Domain-Driven Design - EN: DDD patterns / VI: Patterns DDD

Guides

• Local Development - EN: Setup dev environment / VI: Setup môi trường dev
• Deployment - EN: Kubernetes deployment / VI: Triển khai Kubernetes

References / Tham khảo

• External Resource 1 - EN: Description
• External Resource 2 - EN: Description

---

Authors / Tác giả: VelikHo (hongochai10@icloud.com)
Reviewers / Người đánh giá: Reviewer Names