pos-system/docs/en/skills/project-rules.md

Project Rules / Quy Tắc Dự Án

EN: GoodGo Microservices Platform coding standards and architecture patterns. Use when working with services, apps, packages, or infrastructure. VI: Tiêu chuẩn mã hóa và mẫu kiến trúc của GoodGo Microservices Platform. Sử dụng khi làm việc với services, apps, packages, hoặc infrastructure.

Overview / Tổng Quan

EN: The Project Rules skill provides comprehensive guidelines for the GoodGo Microservices Platform architecture, coding standards, naming conventions, workflows, and best practices. This skill ensures consistency across all services, packages, and applications in the monorepo.

VI: Skill Project Rules cung cấp hướng dẫn toàn diện về kiến trúc GoodGo Microservices Platform, tiêu chuẩn mã hóa, quy ước đặt tên, quy trình làm việc và thực hành tốt nhất. Skill này đảm bảo tính nhất quán trên tất cả services, packages và applications trong monorepo.

When to Use / Khi Nào Sử Dụng

EN: Use this skill when:

• Creating a new service or package
• Setting up project structure
• Following naming conventions
• Understanding deployment patterns
• Working with dependencies
• Configuring Docker containers
• Setting up CI/CD workflows
• Understanding the monorepo structure

VI: Sử dụng skill này khi:

• Tạo service hoặc package mới
• Thiết lập cấu trúc dự án
• Tuân theo quy ước đặt tên
• Hiểu các mẫu triển khai
• Làm việc với dependencies
• Cấu hình Docker containers
• Thiết lập CI/CD workflows
• Hiểu cấu trúc monorepo

Key Concepts / Khái Niệm Chính

Architecture / Kiến Trúc

EN: The platform follows a microservices architecture with:

• Apps: Next.js (web) + Flutter (mobile)
• Services: Node.js/TypeScript microservices (Express)
• Packages: Shared libraries (logger, types, http-client, auth-sdk, tracing)
• Infrastructure: Traefik (API Gateway), Redis, Neon PostgreSQL, Observability
• Deployments: Local (Docker Compose), Staging/Production (Kubernetes)

VI: Nền tảng tuân theo kiến trúc microservices với:

• Apps: Next.js (web) + Flutter (mobile)
• Services: Node.js/TypeScript microservices (Express)
• Packages: Thư viện dùng chung (logger, types, http-client, auth-sdk, tracing)
• Infrastructure: Traefik (API Gateway), Redis, Neon PostgreSQL, Observability
• Deployments: Local (Docker Compose), Staging/Production (Kubernetes)

Tech Stack / Công Nghệ

Frontend:

• Next.js 14+ (App Router), TypeScript, Tailwind CSS, Zustand
• Flutter 3.x with Provider pattern
• Use @goodgo/types and @goodgo/http-client

Backend:

• Node.js 20+, TypeScript 5+, Express
• Prisma ORM + Neon PostgreSQL
• Zod validation, @goodgo/logger, @goodgo/tracing, @goodgo/auth-sdk

Infrastructure:

• Traefik (path-based routing), Redis (cache), Prometheus + Grafana + Loki

Common Patterns / Các Pattern Thường Dùng

Service Structure / Cấu Trúc Service

EN: Standard service structure:

services/[service-name]/
├── src/
│   ├── config/          # Configuration files
│   ├── modules/         # Feature modules
│   ├── middlewares/     # Express middlewares
│   ├── repositories/    # Data access layer
│   ├── routes/          # Route definitions
│   └── main.ts         # Entry point
├── prisma/             # Database schema
├── Dockerfile          # Container definition
└── package.json        # Dependencies

VI: Cấu trúc service chuẩn:

services/[service-name]/
├── src/
│   ├── config/          # File cấu hình
│   ├── modules/         # Module tính năng
│   ├── middlewares/     # Express middlewares
│   ├── repositories/    # Lớp truy cập dữ liệu
│   ├── routes/          # Định nghĩa routes
│   └── main.ts         # Điểm vào
├── prisma/             # Database schema
├── Dockerfile          # Định nghĩa container
└── package.json        # Dependencies

Module Pattern / Pattern Module

EN: Controller → Service → Repository pattern:

// DTO with Zod
export const CreateFeatureDto = z.object({
  name: z.string().min(1),
  email: z.string().email()
});
export type CreateFeatureDto = z.infer<typeof CreateFeatureDto>;

// Controller
export class FeatureController {
  constructor(private service: FeatureService) {}
  async create(req: Request, res: Response, next: NextFunction) {
    try {
      const dto = CreateFeatureDto.parse(req.body);
      const result = await this.service.create(dto);
      res.json({ success: true, data: result });
    } catch (error) { next(error); }
  }
}

// Service
export class FeatureService {
  constructor(private repository: FeatureRepository) {}
  async create(dto: CreateFeatureDto) {
    return this.repository.create(dto);
  }
}

// Repository
export class FeatureRepository extends BaseRepository<Feature> {
  async create(data: CreateFeatureDto) {
    return this.prisma.feature.create({ data });
  }
}

VI: Pattern Controller → Service → Repository:

// DTO với Zod
export const CreateFeatureDto = z.object({
  name: z.string().min(1),
  email: z.string().email()
});
export type CreateFeatureDto = z.infer<typeof CreateFeatureDto>;

// Controller
export class FeatureController {
  constructor(private service: FeatureService) {}
  async create(req: Request, res: Response, next: NextFunction) {
    try {
      const dto = CreateFeatureDto.parse(req.body);
      const result = await this.service.create(dto);
      res.json({ success: true, data: result });
    } catch (error) { next(error); }
  }
}

// Service
export class FeatureService {
  constructor(private repository: FeatureRepository) {}
  async create(dto: CreateFeatureDto) {
    return this.repository.create(dto);
  }
}

// Repository
export class FeatureRepository extends BaseRepository<Feature> {
  async create(data: CreateFeatureDto) {
    return this.prisma.feature.create({ data });
  }
}

API Response Pattern / Pattern Phản Hồi API

EN: Standardized API responses:

// Success response
{
  success: true,
  data: any,
  timestamp: string
}

// Error response
{
  success: false,
  error: {
    code: string,
    message: string,
    details?: any
  },
  timestamp: string
}

VI: Phản hồi API chuẩn hóa:

// Phản hồi thành công
{
  success: true,
  data: any,
  timestamp: string
}

// Phản hồi lỗi
{
  success: false,
  error: {
    code: string,
    message: string,
    details?: any
  },
  timestamp: string
}

Best Practices / Thực Hành Tốt Nhất

Naming Conventions / Quy Ước Đặt Tên

EN:

• Services/Packages: kebab-case (e.g., iam-service, http-client)
• Files: kebab-case.type.ts (e.g., user.controller.ts)
• Components: PascalCase.tsx (React), snake_case.dart (Flutter)
• Classes: PascalCase
• Functions: camelCase
• Constants: UPPER_SNAKE_CASE
• Package Names: @goodgo/package-name

VI:

• Services/Packages: kebab-case (ví dụ: iam-service, http-client)
• Files: kebab-case.type.ts (ví dụ: user.controller.ts)
• Components: PascalCase.tsx (React), snake_case.dart (Flutter)
• Classes: PascalCase
• Functions: camelCase
• Constants: UPPER_SNAKE_CASE
• Package Names: @goodgo/package-name

TypeScript Standards / Tiêu Chuẩn TypeScript

EN:

• Strict mode enabled
• No any type (use unknown instead)
• Zod for runtime validation
• Export shared types from @goodgo/types

VI:

• Bật strict mode
• Không dùng type any (dùng unknown thay thế)
• Zod cho runtime validation
• Export shared types từ @goodgo/types

Logging / Ghi Log

EN: Use @goodgo/logger:

import { logger } from '@goodgo/logger';
logger.info('Message', { context });
logger.error('Error', { error, context });

VI: Sử dụng @goodgo/logger:

import { logger } from '@goodgo/logger';
logger.info('Message', { context });
logger.error('Error', { error, context });

Environment Variables / Biến Môi Trường

EN:

• Use .env.example template
• Never commit .env files
• Validate with Zod at startup
• Document all variables in README

VI:

• Sử dụng template .env.example
• Không bao giờ commit file .env
• Validate với Zod khi khởi động
• Tài liệu hóa tất cả biến trong README

Examples from Project / Ví Dụ Từ Dự Án

Service Template / Template Service

EN: See services/_template/ for a complete service template with:

• Standard structure
• Middleware setup
• Error handling
• Health checks
• Swagger documentation

VI: Xem services/_template/ để có template service hoàn chỉnh với:

• Cấu trúc chuẩn
• Thiết lập middleware
• Xử lý lỗi
• Health checks
• Tài liệu Swagger

Traefik Configuration / Cấu Hình Traefik

EN: Services are registered in deployments/local/docker-compose.yml:

services:
  my-service:
    build:
      context: ../..
      dockerfile: services/my-service/Dockerfile
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-service.rule=PathPrefix(`/api/v1/my-service`)"
      - "traefik.http.services.my-service.loadbalancer.server.port=5002"
      - "traefik.http.services.my-service.loadbalancer.healthcheck.path=/health/live"

VI: Services được đăng ký trong deployments/local/docker-compose.yml:

services:
  my-service:
    build:
      context: ../..
      dockerfile: services/my-service/Dockerfile
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-service.rule=PathPrefix(`/api/v1/my-service`)"
      - "traefik.http.services.my-service.loadbalancer.server.port=5002"
      - "traefik.http.services.my-service.loadbalancer.healthcheck.path=/health/live"

Real Service Examples / Ví Dụ Service Thực Tế

EN:

• services/iam-service/ - Identity and Access Management service (RBAC, OIDC, MFA, Identity, Access, Governance)
• packages/logger/ - Shared logging package
• packages/types/ - Shared TypeScript types

VI:

• services/iam-service/ - Service quản lý danh tính và quyền truy cập (RBAC, OIDC, MFA, Identity, Access, Governance)
• packages/logger/ - Package logging dùng chung
• packages/types/ - TypeScript types dùng chung

Quick Reference / Tham Khảo Nhanh

Creating New Service / Tạo Service Mới

# 1. Copy template
cp -r services/_template services/my-service

# 2. Update package.json name
# Change to: "@goodgo/my-service"

# 3. Add to docker-compose.yml
# Add service configuration with Traefik labels

# 4. Configure Prisma schema
cd services/my-service
pnpm prisma migrate dev

# 5. Add health check endpoint
# Already included in template

Working with Dependencies / Làm Việc Với Dependencies

# Add external package
pnpm --filter @goodgo/service-name add package-name

# Add workspace package
pnpm --filter @goodgo/service-name add @goodgo/logger

# Add dev dependency
pnpm --filter @goodgo/service-name add -D @types/pkg

Database Commands / Lệnh Database

# Run migrations
pnpm --filter @goodgo/service-name prisma migrate dev

# Generate Prisma client
pnpm --filter @goodgo/service-name prisma generate

# Seed database
pnpm --filter @goodgo/service-name prisma db seed

Related Skills / Skills Liên Quan

• API Design - RESTful API design standards
• Database Prisma - Prisma ORM patterns
• Security - Security best practices
• Testing Patterns - Testing guidelines
• Documentation - Documentation writing guidelines

Resources / Tài Nguyên

EN:

• Architecture Docs
• API Specs
• Development Guide
• Deployment Guide
• Contributing Guide

VI:

• Tài Liệu Kiến Trúc
• Spec API
• Hướng Dẫn Phát Triển
• Hướng Dẫn Triển Khai
• Hướng Dẫn Đóng Góp