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