From 118ba5005832f4539bc3b9e41534754ec90d84c5 Mon Sep 17 00:00:00 2001 From: Ho Ngoc Hai Date: Mon, 19 Jan 2026 09:34:11 +0700 Subject: [PATCH] feat: Add initial documentation for WebClientBase architecture and usage in English and Vietnamese. --- .../docs/en/ARCHITECTURE.md | 99 +++++++++++++++++++ apps/web-client-base-net/docs/en/README.md | 65 ++++++++++++ .../docs/vi/ARCHITECTURE.md | 99 +++++++++++++++++++ apps/web-client-base-net/docs/vi/README.md | 65 ++++++++++++ 4 files changed, 328 insertions(+) create mode 100644 apps/web-client-base-net/docs/en/ARCHITECTURE.md create mode 100644 apps/web-client-base-net/docs/en/README.md create mode 100644 apps/web-client-base-net/docs/vi/ARCHITECTURE.md create mode 100644 apps/web-client-base-net/docs/vi/README.md diff --git a/apps/web-client-base-net/docs/en/ARCHITECTURE.md b/apps/web-client-base-net/docs/en/ARCHITECTURE.md new file mode 100644 index 00000000..421f8ef4 --- /dev/null +++ b/apps/web-client-base-net/docs/en/ARCHITECTURE.md @@ -0,0 +1,99 @@ +# WebClientBase Architecture + +Base frontend architecture for GoodGo Platform using Blazor WebAssembly with BFF Pattern. + +## Overview + +This application implements the **Backend for Frontend (BFF)** pattern with YARP reverse proxy: + +- **Client**: Blazor WebAssembly running in browser +- **BFF**: ASP.NET Core server proxying requests to microservices +- **Shared**: Common DTOs with validation (shared between Client/BFF) + +## Architecture Diagram + +```mermaid +flowchart TD + subgraph Browser["🌐 Browser"] + C[Blazor WASM Client] + end + + subgraph BFF["⚙️ BFF Layer"] + Y[YARP Reverse Proxy] + SA[Static Assets] + end + + subgraph MS["🔧 Microservices"] + IAM[IAM Service] + MER[Merchant Service] + CAT[Catalog Service] + ORD[Order Service] + end + + C -->|Static Files| SA + C -->|/api/*| Y + Y -->|/api/iam/**| IAM + Y -->|/api/merchants/**| MER + Y -->|/api/catalog/**| CAT + Y -->|/api/orders/**| ORD + + style C fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px + style Y fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px + style SA fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px + style IAM fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px + style MER fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px + style CAT fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px + style ORD fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px +``` + +## Project Structure + +``` +web-client-base-net/ +├── src/ +│ ├── WebClientBase.Client/ # Blazor WebAssembly +│ │ ├── Layout/ # MainLayout, NavMenu +│ │ ├── Pages/ # Razor pages +│ │ └── wwwroot/ # Static assets, CSS +│ ├── WebClientBase.Server/ # BFF + YARP Proxy +│ │ ├── Program.cs # App configuration +│ │ └── yarp.json # Proxy routes +│ └── WebClientBase.Shared/ # Shared DTOs +│ └── DTOs/ # ProductDto, UserDto +└── docs/ +``` + +## Shared DTOs + +| DTO | Purpose | Validation | +|-----|---------|------------| +| `ProductDto` | Product data | Name (3-100 chars), Price (0.01-1B) | +| `RegisterDto` | User registration | Email, Password (8+ chars, complexity) | +| `LoginDto` | User login | Email, Password | +| `ApiResponse` | Standard response wrapper | Success, Data, Error | + +## YARP Routes + +| Route | Target Service | Port | +|-------|---------------|------| +| `/api/iam/**` | IAM Service | 5101 | +| `/api/merchants/**` | Merchant Service | 5102 | +| `/api/catalog/**` | Catalog Service | 5103 | +| `/api/orders/**` | Order Service | 5104 | + +## Blazor Pages + +| Page | Route | Description | +|------|-------|-------------| +| Home | `/` | Landing page | +| Products | `/products` | Product management | +| Auth | `/auth` | Login/Register | +| Counter | `/counter` | Demo component | +| Weather | `/weather` | Demo data fetch | + +## Key Technologies + +- **.NET 10** - Latest framework +- **Blazor WebAssembly** - Client-side SPA +- **YARP** - Reverse proxy for microservices +- **Data Annotations** - Shared validation diff --git a/apps/web-client-base-net/docs/en/README.md b/apps/web-client-base-net/docs/en/README.md new file mode 100644 index 00000000..01ddc1e4 --- /dev/null +++ b/apps/web-client-base-net/docs/en/README.md @@ -0,0 +1,65 @@ +# WebClientBase + +Base frontend application cho GoodGo Platform. + +## Quick Start + +```bash +# Navigate to project +cd apps/web-client-base-net + +# Restore packages +dotnet restore + +# Run BFF server +dotnet run --project src/WebClientBase.Server + +# Open browser at http://localhost:5091 +``` + +## Tech Stack + +| Component | Technology | +|-----------|------------| +| Client | Blazor WebAssembly (.NET 10) | +| BFF | ASP.NET Core + YARP | +| Shared | Class Library with Data Annotations | +| Styling | CSS Variables, Dark Mode | + +## Project Structure + +``` +src/ +├── WebClientBase.Client/ # Blazor WASM frontend +├── WebClientBase.Server/ # BFF with YARP proxy +└── WebClientBase.Shared/ # Shared DTOs +``` + +## Features + +- ✅ BFF Pattern with YARP reverse proxy +- ✅ Shared validation (Client + Server) +- ✅ Dark/Light mode support +- ✅ Glassmorphism UI design +- ✅ Health check endpoint `/health` + +## Configuration + +YARP proxy routes in `yarp.json`: + +```json +{ + "ReverseProxy": { + "Routes": { + "iam-route": { "Match": { "Path": "/api/iam/{**catch-all}" } } + }, + "Clusters": { + "iam-cluster": { "Destinations": { "d1": { "Address": "http://localhost:5101" } } } + } + } +} +``` + +## Related Documentation + +- [Architecture](ARCHITECTURE.md) - System architecture details diff --git a/apps/web-client-base-net/docs/vi/ARCHITECTURE.md b/apps/web-client-base-net/docs/vi/ARCHITECTURE.md new file mode 100644 index 00000000..3db57a1f --- /dev/null +++ b/apps/web-client-base-net/docs/vi/ARCHITECTURE.md @@ -0,0 +1,99 @@ +# Kiến trúc WebClientBase + +Kiến trúc frontend cơ sở cho GoodGo Platform sử dụng Blazor WebAssembly với mô hình BFF. + +## Tổng quan + +Ứng dụng này triển khai mô hình **Backend for Frontend (BFF)** với YARP reverse proxy: + +- **Client**: Blazor WebAssembly chạy trên trình duyệt +- **BFF**: ASP.NET Core server proxy yêu cầu đến microservices +- **Shared**: DTOs chung với validation (chia sẻ giữa Client/BFF) + +## Sơ đồ Kiến trúc + +```mermaid +flowchart TD + subgraph Browser["🌐 Trình duyệt"] + C[Blazor WASM Client] + end + + subgraph BFF["⚙️ Lớp BFF"] + Y[YARP Reverse Proxy] + SA[Tài nguyên tĩnh] + end + + subgraph MS["🔧 Microservices"] + IAM[Dịch vụ IAM] + MER[Dịch vụ Merchant] + CAT[Dịch vụ Catalog] + ORD[Dịch vụ Order] + end + + C -->|Tệp tĩnh| SA + C -->|/api/*| Y + Y -->|/api/iam/**| IAM + Y -->|/api/merchants/**| MER + Y -->|/api/catalog/**| CAT + Y -->|/api/orders/**| ORD + + style C fill:#3498DB,color:#ECF0F1,stroke:#2980B9,stroke-width:3px + style Y fill:#8E44AD,color:#ECF0F1,stroke:#7D3C98,stroke-width:2px + style SA fill:#34495E,color:#ECF0F1,stroke:#2C3E50,stroke-width:2px + style IAM fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px + style MER fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px + style CAT fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px + style ORD fill:#27AE60,color:#ECF0F1,stroke:#229954,stroke-width:2px +``` + +## Cấu trúc Dự án + +``` +web-client-base-net/ +├── src/ +│ ├── WebClientBase.Client/ # Blazor WebAssembly +│ │ ├── Layout/ # MainLayout, NavMenu +│ │ ├── Pages/ # Trang Razor +│ │ └── wwwroot/ # Tài nguyên tĩnh, CSS +│ ├── WebClientBase.Server/ # BFF + YARP Proxy +│ │ ├── Program.cs # Cấu hình ứng dụng +│ │ └── yarp.json # Routes proxy +│ └── WebClientBase.Shared/ # DTOs chung +│ └── DTOs/ # ProductDto, UserDto +└── docs/ +``` + +## Shared DTOs + +| DTO | Mục đích | Validation | +|-----|----------|------------| +| `ProductDto` | Dữ liệu sản phẩm | Tên (3-100 ký tự), Giá (0.01-1 tỷ) | +| `RegisterDto` | Đăng ký người dùng | Email, Mật khẩu (8+ ký tự, độ phức tạp) | +| `LoginDto` | Đăng nhập | Email, Mật khẩu | +| `ApiResponse` | Wrapper response chuẩn | Success, Data, Error | + +## YARP Routes + +| Route | Dịch vụ đích | Cổng | +|-------|-------------|------| +| `/api/iam/**` | Dịch vụ IAM | 5101 | +| `/api/merchants/**` | Dịch vụ Merchant | 5102 | +| `/api/catalog/**` | Dịch vụ Catalog | 5103 | +| `/api/orders/**` | Dịch vụ Order | 5104 | + +## Trang Blazor + +| Trang | Route | Mô tả | +|-------|-------|-------| +| Home | `/` | Trang chủ | +| Products | `/products` | Quản lý sản phẩm | +| Auth | `/auth` | Đăng nhập/Đăng ký | +| Counter | `/counter` | Component demo | +| Weather | `/weather` | Demo fetch dữ liệu | + +## Công nghệ chính + +- **.NET 10** - Framework mới nhất +- **Blazor WebAssembly** - SPA phía client +- **YARP** - Reverse proxy cho microservices +- **Data Annotations** - Validation chia sẻ diff --git a/apps/web-client-base-net/docs/vi/README.md b/apps/web-client-base-net/docs/vi/README.md new file mode 100644 index 00000000..a7048929 --- /dev/null +++ b/apps/web-client-base-net/docs/vi/README.md @@ -0,0 +1,65 @@ +# WebClientBase + +Ứng dụng frontend cơ sở cho GoodGo Platform. + +## Bắt đầu nhanh + +```bash +# Di chuyển đến dự án +cd apps/web-client-base-net + +# Khôi phục packages +dotnet restore + +# Chạy BFF server +dotnet run --project src/WebClientBase.Server + +# Mở trình duyệt tại http://localhost:5091 +``` + +## Công nghệ + +| Thành phần | Công nghệ | +|------------|-----------| +| Client | Blazor WebAssembly (.NET 10) | +| BFF | ASP.NET Core + YARP | +| Shared | Class Library với Data Annotations | +| Styling | CSS Variables, Dark Mode | + +## Cấu trúc Dự án + +``` +src/ +├── WebClientBase.Client/ # Blazor WASM frontend +├── WebClientBase.Server/ # BFF với YARP proxy +└── WebClientBase.Shared/ # DTOs chia sẻ +``` + +## Tính năng + +- ✅ Mô hình BFF với YARP reverse proxy +- ✅ Validation chia sẻ (Client + Server) +- ✅ Hỗ trợ chế độ Sáng/Tối +- ✅ Thiết kế UI Glassmorphism +- ✅ Endpoint kiểm tra sức khỏe `/health` + +## Cấu hình + +Routes YARP proxy trong `yarp.json`: + +```json +{ + "ReverseProxy": { + "Routes": { + "iam-route": { "Match": { "Path": "/api/iam/{**catch-all}" } } + }, + "Clusters": { + "iam-cluster": { "Destinations": { "d1": { "Address": "http://localhost:5101" } } } + } + } +} +``` + +## Tài liệu liên quan + +- [Kiến trúc](ARCHITECTURE.md) - Chi tiết kiến trúc hệ thống