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

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

```mermaid
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**:
```typescript
// 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`](file:///path/to/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**:
```csharp
// 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/`](file:///Users/velikho/Desktop/WORKING/Base/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/`](file:///Users/velikho/Desktop/WORKING/Base/services/iam-service-net)

## Data Flow / Luồng Dữ liệu

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

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

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

```mermaid
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](../architecture/system-design.md) - EN: Overall platform architecture / VI: Kiến trúc tổng thể platform
- [Microservices Communication](../architecture/microservices-communication.md) - EN: Service communication patterns / VI: Patterns giao tiếp services
- [Caching Architecture](../architecture/caching-architecture.md) - EN: Redis caching strategies / VI: Chiến lược Redis caching
- [Event-Driven Architecture](../architecture/event-driven-architecture.md) - EN: RabbitMQ event patterns / VI: Patterns RabbitMQ events

### Skills Reference
- [CQRS with MediatR](../skills/cqrs-mediatr.md) - EN: CQRS pattern / VI: Pattern CQRS
- [Repository Pattern](../skills/repository-pattern.md) - EN: EF Core repository / VI: Repository EF Core
- [Domain-Driven Design](../skills/domain-driven-design.md) - EN: DDD patterns / VI: Patterns DDD

### Guides
- [Local Development](../guides/local-development.md) - EN: Setup dev environment / VI: Setup môi trường dev
- [Deployment](../guides/deployment.md) - EN: Kubernetes deployment / VI: Triển khai Kubernetes

## References / Tham khảo

- [External Resource 1](https://example.com) - EN: Description
- [External Resource 2](https://example.com) - EN: Description

---

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