feat(docs): Update getting started and local development guides with new prerequisites and improved flow

- Enhanced Node.js and PNPM version recommendations in the getting started guide. - Added a color palette section with Mermaid diagrams for better visual representation. - Improved the workflow steps in the local development guide for clarity and consistency. - Updated Vietnamese documentation to reflect changes in the English version. - Refactored database migration and seeding scripts for better error handling and user feedback.
2026-01-08 15:37:25 +07:00
parent 489adbd314
commit 510e2306cd
7 changed files with 310 additions and 160 deletions
--- a/docs/en/guides/getting-started.md
+++ b/docs/en/guides/getting-started.md
@@ -16,20 +16,20 @@

 Before starting, ensure you have the following installed:

-*   **Node.js**: v20.0.0 or higher
+*   **Node.js**: v20.0.0 or higher (recommended v22+ or v25+)
    ```bash
    node -v
-    # v20.10.0
+    # v25.2.1
    ```
-*   **PNPM**: v8.0.0 or higher (we use pnpm workspaces)
+*   **PNPM**: v8.15.0 or higher (we use pnpm workspaces)
    ```bash
    pnpm -v
-    # 8.12.0
+    # 8.15.0
    ```
-*   **Docker & Docker Compose**: For local infrastructure
+*   **Docker & Docker Compose**: v24.0.0 or higher for local infrastructure
    ```bash
    docker -v
-    # Docker version 24.0.0
+    # Docker version 29.1.3, build f52814d
    ```
 *   **Git**: For version control
 *   **Neon Account**: Serverless PostgreSQL (https://neon.tech)
@@ -49,9 +49,35 @@ graph TD
    IAM --> Redis[(Redis Cache)]
    IAM --> Kafka[Kafka Events]
    
-    style Traefik fill:#e1f5ff
-    style DB fill:#f0e1ff
-    style Redis fill:#fff4e1
+    style Client fill:#7F8C8D,color:#fff
+    style Traefik fill:#2980B9,color:#fff
+    style IAM fill:#27AE60,color:#fff
+    style Template fill:#E67E22,color:#fff
+    style DB fill:#8E44AD,color:#fff
+    style Redis fill:#F39C12,color:#fff
+    style Kafka fill:#3498DB,color:#fff
+```
+
+### Color Palette
+
+```mermaid
+graph LR
+    A["Primary<br/>#2980B9"] --> B["Data/Cache<br/>#F39C12"]
+    B --> C["Success<br/>#27AE60"]
+    C --> D["Warning<br/>#E67E22"]
+    D --> E["Error<br/>#C0392B"]
+    E --> F["Processing<br/>#8E44AD"]
+    F --> G["Info<br/>#3498DB"]
+    G --> H["Neutral<br/>#7F8C8D"]
+    
+    style A fill:#2980B9,color:#fff
+    style B fill:#F39C12,color:#fff
+    style C fill:#27AE60,color:#fff
+    style D fill:#E67E22,color:#fff
+    style E fill:#C0392B,color:#fff
+    style F fill:#8E44AD,color:#fff
+    style G fill:#3498DB,color:#fff
+    style H fill:#7F8C8D,color:#fff
 ```

 ## Project Structure
@@ -60,23 +86,42 @@ The repository follows a monorepo structure:

 ```
 Base/
-├── apps/                 # Frontend applications
-│   ├── web-client/       # Next.js web application
-│   └── mobile-client/    # Flutter mobile application
-├── services/             # Backend microservices
-│   ├── iam-service/      # Authentication & Authorization
-│   └── _template/        # Template for new services
-├── packages/             # Shared libraries
-│   ├── logger/           # Structured logging
-│   ├── types/            # Shared TypeScript types
-│   └── http-client/      # Internal HTTP client
-├── infra/                # Infrastructure configuration
-│   ├── traefik/          # API Gateway config
-│   └── databases/        # Database setup scripts
-├── deployments/          # Deployment configurations
-│   ├── local/            # Docker Compose for dev
-│   └── k8s/              # Kubernetes manifests
-└── docs/                 # Documentation
+├── apps/                    # Frontend applications
+│   ├── app-admin/           # Admin dashboard application
+│   ├── app-client/          # Client mobile application (Flutter)
+│   ├── web-client/          # Next.js web application
+│   └── web-docs/            # Documentation website (Next.js)
+├── services/                # Backend microservices
+│   ├── iam-service/         # Authentication & Authorization service
+│   └── _template/           # Template for new services
+├── packages/                # Shared libraries
+│   ├── auth-sdk/            # Authentication SDK
+│   ├── config/              # Shared configuration utilities
+│   ├── http-client/         # Internal HTTP client
+│   ├── logger/              # Structured logging (@goodgo/logger)
+│   ├── tracing/             # OpenTelemetry tracing
+│   └── types/               # Shared TypeScript types
+├── infra/                   # Infrastructure configuration
+│   ├── databases/           # Database setup scripts
+│   ├── docker/              # Docker configurations
+│   ├── observability/       # Prometheus, Grafana, Loki configs
+│   ├── secrets/             # Secrets management templates
+│   └── traefik/             # API Gateway configuration
+├── deployments/             # Deployment configurations
+│   ├── local/               # Docker Compose for development
+│   ├── staging/             # Staging environment configs
+│   └── production/          # Production Kubernetes manifests
+├── scripts/                 # Automation scripts
+│   ├── build/               # Build scripts
+│   ├── db/                  # Database utilities
+│   ├── deploy/              # Deployment scripts
+│   ├── dev/                 # Development helpers
+│   ├── observability/       # Monitoring setup scripts
+│   ├── setup/               # Initial setup scripts
+│   └── utils/               # Utility scripts
+└── docs/                    # Documentation
+    ├── en/                  # English documentation
+    └── vi/                  # Vietnamese documentation
 ```

 ## Installation & Setup
--- a/docs/en/guides/local-development.md
+++ b/docs/en/guides/local-development.md
@@ -13,25 +13,32 @@
 ```mermaid
 graph TD
    Start([Start]) --> Prerequisites[1. System Prerequisites]
-    Prerequisites --> Clone[2. Clone & Install]
-    Clone --> Env[3. Configure Environment<br/>(Shared & Service-Specific)]
-    Env --> DB[4. Setup Database<br/>(Migrate & Seed)]
-    DB --> Run[5. Run Project<br/>(Native/Docker/Hybrid)]
-    Run --> Dev[6. Development Loop<br/>(Watch Mode)]
-    Dev --> Test[7. Testing & Verify]
+    Prerequisites --> Clone["2. Clone and Install"]
+    Clone --> Env["3. Configure Environment - Shared and Service-Specific"]
+    Env --> DB["4. Setup Database - Migrate and Seed"]
+    DB --> Run["5. Run Project - Native/Docker/Hybrid"]
+    Run --> Dev["6. Development Loop - Watch Mode"]
+    Dev --> Test["7. Testing and Verify"]
    Test --> End([Complete])

    subgraph "Run Modes"
-        Run --> Mode1[Mode 1: Native (Fastest)]
-        Run --> Mode2[Mode 2: Hybrid (Flexible)]
-        Run --> Mode3[Mode 3: Full Docker (Production-like)]
+        Run --> Mode1[Mode 1: Native - Fastest]
+        Run --> Mode2[Mode 2: Hybrid - Flexible]
+        Run --> Mode3[Mode 3: Full Docker - Production-like]
    end

-    style Start fill:#d4edda,stroke:#28a745,stroke-width:2px
-    style End fill:#d4edda,stroke:#28a745,stroke-width:2px
-    style Env fill:#fff3cd,stroke:#ffc107
-    style DB fill:#fff3cd,stroke:#ffc107
-    style Run fill:#cce5ff,stroke:#007bff
+    style Start fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style End fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style Prerequisites fill:#7F8C8D,color:#fff
+    style Clone fill:#7F8C8D,color:#fff
+    style Env fill:#E67E22,color:#fff
+    style DB fill:#E67E22,color:#fff
+    style Run fill:#2980B9,color:#fff
+    style Dev fill:#2980B9,color:#fff
+    style Test fill:#3498DB,color:#fff
+    style Mode1 fill:#8E44AD,color:#fff
+    style Mode2 fill:#8E44AD,color:#fff
+    style Mode3 fill:#8E44AD,color:#fff
 ```

 ## Overview
--- a/docs/vi/guides/getting-started.md
+++ b/docs/vi/guides/getting-started.md
@@ -62,13 +62,13 @@ graph TD

 ```mermaid
 graph LR
-    A["Primary<br/>#2980B9"] --> B["Data/Cache<br/>#F39C12"]
-    B --> C["Success<br/>#27AE60"]
-    C --> D["Warning<br/>#E67E22"]
-    D --> E["Error<br/>#C0392B"]
-    E --> F["Processing<br/>#8E44AD"]
-    F --> G["Info<br/>#3498DB"]
-    G --> H["Neutral<br/>#7F8C8D"]
+    A["Primary #2980B9"] --> B["Data/Cache #F39C12"]
+    B --> C["Success #27AE60"]
+    C --> D["Warning #E67E22"]
+    D --> E["Error #C0392B"]
+    E --> F["Processing #8E44AD"]
+    F --> G["Info #3498DB"]
+    G --> H["Neutral #7F8C8D"]
    
    style A fill:#2980B9,color:#fff
    style B fill:#F39C12,color:#fff
--- a/docs/vi/guides/local-development.md
+++ b/docs/vi/guides/local-development.md
@@ -1,37 +1,40 @@
 # Hướng Dẫn Phát Triển Local (Local Development)

-> **EN**: Local Development Guide
->
-> **VI**: Hướng dẫn phát triển cục bộ
+>Hướng dẫn phát triển cục bộ

-**Cập nhật**: 2026-01-05
-**Độ khó**: Trung bình (Intermediate)
 **Thời gian thiết lập**: 15-30 phút

 ## Workflow / Quy Trình

 ```mermaid
 graph TD
-    Start([Bắt đầu / Start]) --> Prerequisites[1. Yêu cầu Hệ thống<br/>Prerequisites]
-    Prerequisites --> Clone[2. Clone & Install]
-    Clone --> Env[3. Cấu hình Environment<br/>(Shared & Service-Specific)]
-    Env --> DB[4. Setup Database<br/>(Migrate & Seed)]
-    DB --> Run[5. Chạy Dự án<br/>(Native/Docker/Hybrid)]
-    Run --> Dev[6. Development Loop<br/>(Watch Mode)]
-    Dev --> Test[7. Testing & Verify]
+    Start([Bắt đầu / Start]) --> Prerequisites["1. Yêu cầu Hệ thống - Prerequisites"]
+    Prerequisites --> Clone["2. Clone và Install"]
+    Clone --> Env["3. Cấu hình Environment - Shared và Service-Specific"]
+    Env --> DB["4. Setup Database - Migrate và Seed"]
+    DB --> Run["5. Chạy Dự án - Native/Docker/Hybrid"]
+    Run --> Dev["6. Development Loop - Watch Mode"]
+    Dev --> Test["7. Testing và Verify"]
    Test --> End([Hoàn tất / Complete])

    subgraph "Các Chế độ Chạy / Run Modes"
-        Run --> Mode1[Cách 1: Native (Nhanh nhất)]
-        Run --> Mode2[Cách 2: Hybrid (Linh hoạt)]
-        Run --> Mode3[Cách 3: Full Docker (Production-like)]
+        Run --> Mode1["Cách 1: Native - Nhanh nhất"]
+        Run --> Mode2["Cách 2: Hybrid - Linh hoạt"]
+        Run --> Mode3["Cách 3: Full Docker - Production-like"]
    end

-    style Start fill:#d4edda,stroke:#28a745,stroke-width:2px
-    style End fill:#d4edda,stroke:#28a745,stroke-width:2px
-    style Env fill:#fff3cd,stroke:#ffc107
-    style DB fill:#fff3cd,stroke:#ffc107
-    style Run fill:#cce5ff,stroke:#007bff
+    style Start fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style End fill:#27AE60,color:#fff,stroke:#27AE60,stroke-width:2px
+    style Prerequisites fill:#7F8C8D,color:#fff
+    style Clone fill:#7F8C8D,color:#fff
+    style Env fill:#E67E22,color:#fff
+    style DB fill:#E67E22,color:#fff
+    style Run fill:#2980B9,color:#fff
+    style Dev fill:#2980B9,color:#fff
+    style Test fill:#3498DB,color:#fff
+    style Mode1 fill:#8E44AD,color:#fff
+    style Mode2 fill:#8E44AD,color:#fff
+    style Mode3 fill:#8E44AD,color:#fff
 ```

 ## Tổng Quan / Overview
@@ -53,12 +56,10 @@ Trước khi bắt đầu, đảm bảo máy của bạn đã cài đặt các c
 ### 2.1 Clone và Cài Đặt Dependencies

 ```bash
-# EN: Clone the repository
 # VI: Clone repository về máy
 git clone <repository-url>
 cd Base

-# EN: Install dependencies using pnpm
 # VI: Cài đặt các thư viện phụ thuộc bằng pnpm
 pnpm install
 ```
@@ -68,7 +69,6 @@ pnpm install
 Dự án có script tự động hóa các bước khởi tạo cơ bản:

 ```bash
-# EN: Run initialization script
 # VI: Chạy script khởi tạo
 ./scripts/setup/init-project.sh
 ```
@@ -88,7 +88,6 @@ File: `deployments/local/.env.local`
 Chứa các biến dùng chung cho toàn bộ hệ thống (JWT, Redis, Logging).

 ```bash
-# EN: Create shared env file from example
 # VI: Tạo file môi trường chung từ file mẫu
 cp deployments/local/env.local.example deployments/local/.env.local
 ```
@@ -98,7 +97,6 @@ cp deployments/local/env.local.example deployments/local/.env.local
 Mỗi service (ví dụ `iam-service`) cần file `.env.local` riêng chứa thông tin đặc thù như Database URL và Port.

 ```bash
-# EN: Create service-specific env file
 # VI: Tạo file môi trường riêng cho service
 cp services/iam-service/env.local.example services/iam-service/.env.local
 ```
@@ -124,11 +122,9 @@ REDIS_HOST=localhost
 Sau khi cấu hình `DATABASE_URL`, bạn cần đồng bộ schema và tạo dữ liệu mẫu.

 ```bash
-# EN: Run migrations for iam-service
 # VI: Chạy migration cho iam-service
 ./scripts/db/migrate.sh iam-service dev

-# EN: Seed initial data (optional)
 # VI: Tạo dữ liệu mẫu (tùy chọn)
 ./scripts/db/seed.sh iam-service
 ```
@@ -143,7 +139,6 @@ Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh n

 1.  **Khởi động Hạ tầng (Infrastructure)**:
    ```bash
-    # EN: Start Redis and Traefik in Docker background
    # VI: Khởi động Redis và Traefik chạy ngầm bằng Docker
    cd deployments/local
    docker-compose up -d redis traefik
@@ -152,7 +147,6 @@ Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh n

 2.  **Chạy Service**:
    ```bash
-    # EN: Start iam-service in watch mode
    # VI: Chạy iam-service ở chế độ watch
    pnpm --filter @goodgo/iam-service dev
    ```
@@ -162,11 +156,9 @@ Chạy trực tiếp trên máy host. Tốc độ cao nhất, hot-reload nhanh n
 Dùng khi bạn cần chạy nhiều service phụ trợ trong Docker, nhưng muốn dev trực tiếp 1 service chính.

 ```bash
-# EN: Start dependent services in Docker
 # VI: Chạy các service phụ thuộc trong Docker
 docker-compose -f deployments/local/docker-compose.yml up -d user-service payment-service

-# EN: Run the service you are working on natively
 # VI: Chạy service bạn đang làm việc trực tiếp trên máy
 pnpm --filter @goodgo/iam-service dev
 ```
@@ -176,7 +168,6 @@ pnpm --filter @goodgo/iam-service dev
 Chạy toàn bộ hệ thống trong Docker. Tốt cho việc kiểm tra tích hợp (Integration Test) nhưng không có hot-reload.

 ```bash
-# EN: Start everything with Docker Compose
 # VI: Chạy tất cả bằng Docker Compose
 cd deployments/local
 docker-compose up -d
@@ -197,11 +188,9 @@ Sau khi khởi động, bạn có thể truy cập các điểm cuối sau:
 ### Kiểm tra Health Check

 ```bash
-# EN: Check liveness
 # VI: Kiểm tra liveness
 curl http://localhost:5001/health/live

-# EN: Check readiness
 # VI: Kiểm tra readiness
 curl http://localhost:5001/health/ready
 ```
@@ -214,11 +203,9 @@ curl http://localhost:5001/health/ready

 **Giải pháp**:
 ```bash
-# EN: Find process using port 5001
 # VI: Tìm process đang chiếm port 5001
 lsof -i :5001

-# EN: Kill the process
 # VI: Tắt process đó
 kill -9 <PID>
 ```
@@ -238,7 +225,6 @@ kill -9 <PID>

 **Giải pháp**:
 ```bash
-# EN: Re-install dependencies and build packages
 # VI: Cài lại dependencies và build lại packages
 pnpm install
 pnpm build
--- a/scripts/db/migrate.sh
+++ b/scripts/db/migrate.sh
@@ -1,61 +1,75 @@
 #!/bin/bash
-# EN: Database migration script for individual services
 # VI: Script migration database cho từng service riêng lẻ

 set -e

 SERVICE=$1
+MODE=$2

-# EN: Validate service name parameter
 # VI: Xác thực tham số tên service
 if [ -z "$SERVICE" ]; then
-    echo "Usage: $0 <service-name> [dev|deploy] / Cách dùng: $0 <tên-service> [dev|deploy]"
-    echo "Example: $0 iam-service dev / Ví dụ: $0 iam-service dev"
-    echo "Example: $0 iam-service deploy / Ví dụ: $0 iam-service deploy"
+    echo "Cách dùng: $0 <tên-service> [dev|deploy|reset]"
+    echo "Ví dụ: $0 iam-service dev"
+    echo "Ví dụ: $0 iam-service deploy"
+    echo "Ví dụ: $0 iam-service reset"
    exit 1
 fi

-# EN: Check if service directory exists
 # VI: Kiểm tra thư mục service có tồn tại không
 if [ ! -d "services/$SERVICE" ]; then
-    echo "❌ Service $SERVICE not found / Không tìm thấy service $SERVICE"
+    echo "❌ Không tìm thấy service $SERVICE"
    exit 1
 fi

-echo "🔄 Running migrations for $SERVICE... / Chạy migrations cho $SERVICE..."
+echo "🔄 Chạy migrations cho $SERVICE..."

 cd "services/$SERVICE"

-# EN: Load environment variables (hybrid pattern)
 # VI: Load biến môi trường (hybrid pattern)
-# EN: 1. Load shared env (JWT secrets, Redis config)
 # VI: 1. Load shared env (JWT secrets, Redis config)
 if [ -f "../../deployments/local/.env.local" ]; then
-    export $(grep -v '^#' ../../deployments/local/.env.local | xargs)
+    set -a
+    source ../../deployments/local/.env.local
+    set +a
 fi

-# EN: 2. Load service-specific env (DATABASE_URL, PORT, etc.)
 # VI: 2. Load service-specific env (DATABASE_URL, PORT, etc.)
 if [ -f ".env.local" ]; then
-    export $(grep -v '^#' .env.local | xargs)
+    set -a
+    source .env.local
+    set +a
 fi

-# EN: Check if DATABASE_URL is set
 # VI: Kiểm tra DATABASE_URL có được thiết lập không
 if [ -z "$DATABASE_URL" ]; then
-    echo "⚠️  DATABASE_URL not set. Please check your .env.local files: / DATABASE_URL chưa được thiết lập. Vui lòng kiểm tra file .env.local:"
+    echo "⚠️  DATABASE_URL chưa được thiết lập. Vui lòng kiểm tra file .env.local:"
    echo "   - Shared config: ../../deployments/local/.env.local"
    echo "   - Service config: .env.local"
-    echo "   For Neon: postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require&pgbouncer=true"
+    echo "   Ví dụ Neon: postgresql://user:pass@ep-xxx.region.neon.tech/dbname?sslmode=require"
    exit 1
 fi

-if [ "$2" = "dev" ]; then
-    echo "📝 Running development migration (creates new migration)..."
+# VI: Thực hiện migration dựa trên mode
+if [ "$MODE" = "dev" ]; then
+    echo "📝 Chạy development migration (tạo migration mới)..."
    pnpm prisma migrate dev
-else
-    echo "🚀 Running production migration (applies existing migrations)..."
+elif [ "$MODE" = "deploy" ]; then
+    echo "🚀 Chạy production migration (áp dụng migrations có sẵn)..."
    pnpm prisma migrate deploy
+    pnpm prisma generate
+elif [ "$MODE" = "reset" ]; then
+    echo "⚠️  CẢNH BÁO: Sẽ xóa toàn bộ database và chạy lại migrations!"
+    read -p "Bạn có chắc chắn? (yes/no): " confirm
+    if [ "$confirm" = "yes" ]; then
+        echo "🔄 Reset database..."
+        pnpm prisma migrate reset --force
+    else
+        echo "❌ Hủy reset database"
+        exit 0
+    fi
+else
+    echo "⚠️  Mode không hợp lệ. Sử dụng: dev, deploy, hoặc reset"
+    exit 1
 fi

-echo "✅ Migrations completed!"
+echo "✅ Migrations hoàn tất!"
--- a/scripts/db/seed.sh
+++ b/scripts/db/seed.sh
@@ -1,41 +1,56 @@
 #!/bin/bash
+# VI: Script seed database cho từng service riêng lẻ

 set -e

 SERVICE=$1

-# EN: Validate argument
 # VI: Xác thực tham số
 if [ -z "$SERVICE" ]; then
-    echo "Usage: $0 <service-name>"
-    echo "Example: $0 iam-service"
+    echo "Cách dùng: $0 <tên-service>"
+    echo "Ví dụ: $0 iam-service"
    exit 1
 fi

-# EN: Check if service exists
 # VI: Kiểm tra xem service có tồn tại không
 if [ ! -d "services/$SERVICE" ]; then
-    echo "❌ Service $SERVICE not found"
+    echo "❌ Không tìm thấy service $SERVICE"
    exit 1
 fi

-echo "🌱 Seeding database for $SERVICE..."
+echo "🌱 Seed database cho $SERVICE..."

 cd "services/$SERVICE"

-# EN: Check if DATABASE_URL is set
-# VI: Kiểm tra DATABASE_URL đã được thiết lập chưa
-if [ -z "$DATABASE_URL" ]; then
-    if [ -f ".env" ]; then
-        export $(grep -v '^#' .env | xargs)
-    elif [ -f "../../deployments/local/.env.local" ]; then
-        export $(grep -v '^#' ../../deployments/local/.env.local | xargs)
-    else
-        echo "⚠️  DATABASE_URL not set. Please set it in .env or environment variable."
-        exit 1
-    fi
+# VI: Load biến môi trường (hybrid pattern - ĐỒNG BỘ với migrate.sh)
+# VI: 1. Load shared env (JWT secrets, Redis config)
+if [ -f "../../deployments/local/.env.local" ]; then
+    set -a
+    source ../../deployments/local/.env.local
+    set +a
 fi

+# VI: 2. Load service-specific env (DATABASE_URL, PORT, etc.)
+if [ -f ".env.local" ]; then
+    set -a
+    source .env.local
+    set +a
+fi
+
+# VI: Kiểm tra DATABASE_URL đã được thiết lập chưa
+if [ -z "$DATABASE_URL" ]; then
+    echo "⚠️  DATABASE_URL chưa được thiết lập. Vui lòng kiểm tra file .env.local:"
+    echo "   - Shared config: ../../deployments/local/.env.local"
+    echo "   - Service config: .env.local"
+    exit 1
+fi
+
+# VI: Generate Prisma client trước khi seed (đảm bảo client updated)
+echo "📦 Generate Prisma client..."
+pnpm prisma generate
+
+# VI: Chạy seed script
+echo "🌱 Chạy seed data..."
 pnpm prisma:seed

-echo "✅ Database seeded!"
+echo "✅ Database đã được seed thành công!"
--- a/scripts/setup/init-project.sh
+++ b/scripts/setup/init-project.sh
@@ -2,60 +2,143 @@

 set -e

+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
 echo "🚀 Initializing GoodGo Microservices Project..."
+echo ""

 # EN: Check prerequisites
 # VI: Kiểm tra các điều kiện tiên quyết
-if ! command -v pnpm &> /dev/null; then
-    echo "❌ PNPM is not installed. Please install it first: npm install -g pnpm"
+
+# Check Node.js version
+if ! command -v node &> /dev/null; then
+    echo -e "${RED}❌ Node.js is not installed. Please install Node.js v20.0.0 or higher${NC}"
    exit 1
 fi

-if ! command -v docker &> /dev/null; then
-    echo "⚠️  Docker is not installed. Some features may not work."
+NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
+if [ "$NODE_VERSION" -lt 20 ]; then
+    echo -e "${RED}❌ Node.js version is too old. Required: v20.0.0+, Current: $(node -v)${NC}"
+    exit 1
 fi
+echo -e "${GREEN}✓ Node.js $(node -v) detected${NC}"
+
+# Check PNPM
+if ! command -v pnpm &> /dev/null; then
+    echo -e "${RED}❌ PNPM is not installed. Please install it first:${NC}"
+    echo "   npm install -g pnpm"
+    exit 1
+fi
+
+PNPM_VERSION=$(pnpm -v)
+echo -e "${GREEN}✓ PNPM v${PNPM_VERSION} detected${NC}"
+
+# Check Docker
+if ! command -v docker &> /dev/null; then
+    echo -e "${YELLOW}⚠️  Docker is not installed. Local infrastructure features will not work.${NC}"
+    echo -e "${YELLOW}   Please install Docker Desktop: https://www.docker.com/products/docker-desktop${NC}"
+else
+    DOCKER_VERSION=$(docker -v | cut -d' ' -f3 | cut -d',' -f1)
+    echo -e "${GREEN}✓ Docker ${DOCKER_VERSION} detected${NC}"
+fi
+
+echo ""
+echo -e "${BLUE}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""

 # EN: Install dependencies
 # VI: Cài đặt các gói phụ thuộc
-echo "📦 Installing dependencies..."
+echo -e "${BLUE}📦 Installing dependencies...${NC}"
 pnpm install
-
-# EN: Generate Prisma clients
-# VI: Tạo Prisma generic clients
-echo "🔧 Generating Prisma clients..."
-cd services/iam-service
-pnpm prisma:generate || echo "⚠️  Prisma generation skipped (database not available)"
-cd ../..
+echo -e "${GREEN}✓ Dependencies installed${NC}"
+echo ""

 # EN: Setup environment files
 # VI: Thiết lập các file biến môi trường
-echo "📝 Setting up environment files..."
-if [ ! -f "services/iam-service/.env" ]; then
-    cp services/iam-service/env.local.example services/iam-service/.env.local 2>/dev/null || echo "⚠️  IAM service .env file not found"
-fi
+echo -e "${BLUE}📝 Setting up environment files...${NC}"

-if [ ! -f "deployments/local/.env.local" ]; then
-    cp deployments/local/env.local.example deployments/local/.env.local
-    echo "✅ Created deployments/local/.env.local"
-    echo "⚠️  IMPORTANT: Edit .env.local and add your Neon DATABASE_URL"
-fi
+# Function to copy env file
+copy_env_file() {
+    local source=$1
+    local target=$2
+    local description=$3
+    
+    if [ -f "$source" ]; then
+        if [ ! -f "$target" ]; then
+            cp "$source" "$target"
+            echo -e "${GREEN}✓ Created ${target}${NC}"
+            if [ -n "$description" ]; then
+                echo -e "${YELLOW}  ⚠️  ${description}${NC}"
+            fi
+        else
+            echo -e "${BLUE}→ ${target} already exists (skipped)${NC}"
+        fi
+    else
+        echo -e "${YELLOW}⚠️  ${source} not found (skipped)${NC}"
+    fi
+}

-if [ ! -f "apps/web-admin/.env.local" ]; then
-    cp apps/web-admin/.env.example apps/web-admin/.env.local 2>/dev/null || echo "⚠️  Web admin .env.example not found"
-fi
+# Copy env files
+copy_env_file "deployments/local/env.local.example" "deployments/local/.env.local" "IMPORTANT: Edit .env.local and add your Neon DATABASE_URL"
+copy_env_file "services/iam-service/env.local.example" "services/iam-service/.env.local" ""
+copy_env_file "apps/web-client/.env.local" "apps/web-client/.env.local.backup" "" 2>/dev/null || true

-if [ ! -f "apps/web-client/.env.local" ]; then
-    cp apps/web-client/.env.example apps/web-client/.env.local 2>/dev/null || echo "⚠️  Web client .env.example not found"
-fi
-
-echo "✅ Project initialization complete!"
 echo ""
-echo "Next steps:"
-echo "1. Setup Neon database: ./scripts/db/setup-neon.sh"
-echo "2. Update .env files with your Neon DATABASE_URL"
-echo "3. Start all services: ./scripts/dev/start-all.sh"
-echo "4. Run migrations: ./scripts/db/migrate.sh iam-service dev"
-echo "5. Seed database: ./scripts/db/seed.sh iam-service"
-echo "6. Start services: pnpm dev"
+
+# EN: Generate Prisma clients
+# VI: Tạo Prisma clients
+echo -e "${BLUE}🔧 Generating Prisma clients...${NC}"
+if [ -d "services/iam-service" ]; then
+    cd services/iam-service
+    if pnpm prisma generate 2>/dev/null; then
+        echo -e "${GREEN}✓ Prisma client generated for iam-service${NC}"
+    else
+        echo -e "${YELLOW}⚠️  Prisma generation skipped (database schema may need setup)${NC}"
+    fi
+    cd ../..
+fi
+echo ""
+
+# EN: Check for additional setup needed
+# VI: Kiểm tra các thiết lập bổ sung cần thiết
+echo -e "${BLUE}🔍 Checking additional setup requirements...${NC}"
+
+if [ ! -f "deployments/local/.env.local" ] || ! grep -q "DATABASE_URL=" deployments/local/.env.local 2>/dev/null; then
+    echo -e "${YELLOW}⚠️  Neon database not configured${NC}"
+fi
+
+echo ""
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo -e "${GREEN}✅ Project initialization complete!${NC}"
+echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+echo ""
+echo -e "${BLUE}📋 Next steps:${NC}"
+echo ""
+echo "  1. 🗄️  Setup Neon database:"
+echo "     ./scripts/db/setup-neon.sh"
+echo ""
+echo "  2. ⚙️  Update environment variables:"
+echo "     Edit deployments/local/.env.local and add your DATABASE_URL"
+echo ""
+echo "  3. 🔄 Run database migrations:"
+echo "     pnpm --filter @goodgo/iam-service prisma migrate dev"
+echo ""
+echo "  4. 🌱 Seed database (optional):"
+echo "     ./scripts/db/seed.sh iam-service"
+echo ""
+echo "  5. 🐳 Start local infrastructure:"
+echo "     cd deployments/local && docker-compose up -d"
+echo ""
+echo "  6. 🚀 Start development servers:"
+echo "     pnpm dev"
+echo ""
+echo -e "${BLUE}📚 Documentation:${NC}"
+echo "   • Neon setup: docs/vi/guides/neon-database.md"
+echo "   • Getting started: docs/vi/guides/getting-started.md"
+echo "   • Development: docs/vi/guides/development.md"
 echo ""
-echo "📚 See infra/databases/neon/README.md for Neon setup details"