pos-system/docs/en/guides/development.md

Development Guide

Note

: This guide provides comprehensive standards and workflows for contributing to the GoodGo Microservices Platform.

Table of Contents

1. Project Structure
2. Code Standards
3. Git Workflow
4. Backend Development
5. Testing Strategy
6. Database Workflow
7. Kubernetes Deployment

---

Project Structure

We follow a strict monorepo structure managed by PNPM Workspaces.

Base/
├── apps/                 # Frontend applications
│   ├── web-client/       # Next.js 14+ (App Router)
│   └── mobile-client/    # Flutter
├── services/             # Backend microservices
│   ├── _template/        # Template for new services
│   ├── iam-service/      # Identity & Access Management
│   └── ...
├── packages/             # Shared libraries
│   ├── logger/           # Structured logging (Winston)
│   ├── types/            # Shared DTOs & Interfaces
│   ├── http-client/      # Internal Service Client
│   └── tracing/          # OpenTelemetry configuration
├── infra/                # Infrastructure-as-Code
│   ├── traefik/          # API Gateway
│   └── databases/        # Database setup scripts
└── docs/                 # Documentation (EN & VI)

---

Code Standards

Naming Conventions

• Files: kebab-case.ts (e.g., user.controller.ts, app.config.ts)
• Classes: PascalCase (e.g., UserController, AuthService)
• Functions/Variables: camelCase (e.g., getUserById, isValid)
• Constants: UPPER_SNAKE_CASE (e.g., MAX_RETRIES, DEFAULT_TIMEOUT)
• Interfaces: PascalCase (e.g., User, CreateUserDto) - No 'I' prefix

Bilingual Comments

For core logic and public APIs, assume both international and Vietnamese developers reading the code.

/**
 * EN: Validates user credentials and returns a token
 * VI: Xác thực thông tin người dùng và trả về token
 */
async login(dto: LoginDto): Promise<TokenResponse> { ... }

TypeScript Usage

• Strict Mode: Enabled in tsconfig.json. No any allowed (use unknown if needed).
• DTOs: Use Zod for runtime validation and type inference.
• Return Types: Explicitly declare return types for all public methods.

---

Git Workflow

Branching Strategy

• main: Production-ready code.
• develop: Integration branch for next release.
• feature/xyz: New features (branch off develop).
• fix/xyz: Bug fixes (branch off develop).
• hotfix/xyz: Critical fixes (branch off main).

Commit Messages

We follow Conventional Commits:

feat(iam): add multi-factor authentication
fix(db): correct unique constraint on email
docs(guide): update development setup
style: format code with prettier
refactor: simplify auth middleware
test: add unit tests for user service
chore: update dependencies

---

Backend Development

Creating a New API Endpoint

1. Define DTO (modules/user/user.dto.ts):

   export const CreateUserDto = z.object({
     email: z.string().email(),
     name: z.string().min(2),
   });
   export type CreateUserDto = z.infer<typeof CreateUserDto>;
   

2. Create Service Method (modules/user/user.service.ts):

   • Implement business logic.
   • Use BaseRepository.
   • Throw HttpError (e.g., NotFound, BadRequest).

3. Create Controller (modules/user/user.controller.ts):

   • Parse body with DTO: const dto = CreateUserDto.parse(req.body).
   • Call service.
   • Return success response: res.json({ success: true, data: result }).

4. Register Route (modules/user/index.ts):

   • Add to Express router with middlewares.

Error Handling

Always use the custom error classes from core/errors:

import { NotFoundError, ConflictError } from '../../core/errors';

if (!user) {
  throw new NotFoundError('User not found');
}

---

Testing Strategy

Unit Tests (*.test.ts)

• Scope: Individual classes/functions.
• Mocking: Mock all external dependencies (DB, other services) using jest-mock-extended.
• Location: Co-located with source files.
• Run: pnpm test

E2E Tests (tests/**/*.e2e.ts)

• Scope: Full API flows (Controller -> Service -> DB).
• Database: Use a separate test database (Dockerized).
• Run: pnpm test:e2e

Linting & Formatting

• Lint: pnpm lint (ESLint)
• Format: pnpm format (Prettier)
• Typecheck: pnpm typecheck (TSC)

---

Database Workflow

We use Prisma with Neon PostgreSQL.

Migrations

1. Modify prisma/schema.prisma.
2. Create migration (Dev):

   ./scripts/db/migrate.sh iam-service dev --name add_user_profile
   

3. Apply to Production (CI/CD):

   ./scripts/db/migrate.sh iam-service deploy
   

Seed Data

Populate database with initial data:

./scripts/db/seed.sh iam-service

Visualizing Data

Use Prisma Studio:

pnpm --filter @goodgo/iam-service prisma studio

---

Kubernetes Deployment

For local Kubernetes testing (Docker Desktop / Minikube):

# 1. Build images
docker build -t goodgo/iam-service:latest -f services/iam-service/Dockerfile .

# 2. Deploy
cd deployments/local/kubernetes
./deploy.sh

# 3. Verify
kubectl get pods -n iam-local
kubectl logs -f -l app=iam-service -n iam-local

See Kubernetes Guide for detailed setup.