goodgo-platform/docs/onboarding.md

Developer Onboarding Guide

Chào mừng đến với GoodGo Platform — một sàn giao dịch bất động sản Việt Nam được xây dựng trên NestJS, Next.js, PostgreSQL, và PostGIS.

Hướng dẫn này giúp bạn setup môi trường phát triển trong < 30 phút.

---

Prerequisites (Yêu cầu)

Trước khi bắt đầu, hãy cài đặt:

Tool	Version	Link
Node.js	≥ 22.0.0	https://nodejs.org/
pnpm	≥ 10.0.0	https://pnpm.io/
PostgreSQL	16 + PostGIS	https://www.postgresql.org/
Docker & Docker Compose	Latest	https://docker.com/
Git	Latest	https://git-scm.com/
VS Code (recommended)	Latest	https://code.visualstudio.com/

macOS

# Install Homebrew (if not already)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install node@22 pnpm postgresql@16 docker
brew install postgis  # PostGIS extension

# Verify
node --version     # v22.x.x
pnpm --version     # 10.x.x
psql --version     # PostgreSQL 16.x

Ubuntu/Debian

# Update package manager
sudo apt update

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install pnpm
npm install -g pnpm@latest

# Install PostgreSQL 16 + PostGIS
sudo apt install -y postgresql-16 postgresql-16-postgis

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

Windows (WSL2 Recommended)

# Inside WSL2 Ubuntu:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs postgresql-16 postgresql-16-postgis
npm install -g pnpm@latest

---

1. Clone Repository

# Clone the repo
git clone https://github.com/hongochai10/goodgo-bds-platform-ai.git
cd goodgo-platform-ai

# Add your SSH key to GitHub (for faster clone/push)
# https://docs.github.com/en/authentication/connecting-to-github-with-ssh

---

2. Install Dependencies

# Install all packages using pnpm workspaces
pnpm install

# This installs:
# - Root dependencies
# - apps/api dependencies
# - apps/web dependencies
# - libs/ai-services dependencies
# - libs/mcp-servers dependencies

Expected time: ~2-5 minutes

---

3. Setup PostgreSQL (Database)

Option A: Docker Compose (Recommended for Development)

# Start PostgreSQL + Redis in Docker
docker-compose -f docker-compose.dev.yml up -d

# Verify containers are running
docker-compose ps

# Output should show:
# NAME              STATUS
# goodgo-postgres   Up 2 seconds
# goodgo-redis      Up 2 seconds

Option B: Local PostgreSQL Installation

# Create database
createdb goodgo_dev

# Enable PostGIS extension
psql goodgo_dev -c "CREATE EXTENSION IF NOT EXISTS postgis;"

# Verify
psql goodgo_dev -c "SELECT PostGIS_version();"

---

4. Setup Environment Variables

# Copy .env.example to .env
cp .env.example .env

# Edit .env with your local values
# Minimal required variables:
cat > .env << 'EOF'
NODE_ENV=development
DATABASE_URL="postgresql://postgres:password@localhost:5432/goodgo_dev"
REDIS_URL="redis://localhost:6379"
JWT_SECRET="dev-secret-change-in-production"
JWT_REFRESH_SECRET="dev-refresh-secret-change-in-production"
MAPBOX_TOKEN="your-mapbox-token-here"  # Get from https://account.mapbox.com/
EOF

# For Firebase Cloud Messaging (optional, for push notifications):
# FIREBASE_PROJECT_ID="your-project-id"
# FIREBASE_PRIVATE_KEY="..."
# FIREBASE_CLIENT_EMAIL="..."

---

5. Initialize Database

# Generate Prisma client
pnpm db:generate

# Run migrations
pnpm db:migrate:dev

# Seed sample data (users, listings, districts)
pnpm db:seed

# Verify seeding
pnpm db:studio  # Opens Prisma Studio GUI at http://localhost:5555

---

6. Start Development Servers

# Start all services (API + Web + AI services) in watch mode
pnpm dev

# Output shows:
# - API running at http://localhost:3001
# - Web running at http://localhost:3000
# - Logs from both services

Expected time: ~30 seconds for startup

Alternative: Start Individual Services

# Terminal 1: API only
pnpm --filter api dev

# Terminal 2: Web only  
pnpm --filter web dev

# Terminal 3: AI services (Python) - optional
pnpm --filter ai-services dev

---

7. Verify Setup

Open your browser and test:

API Health Check

# Terminal or Postman
curl http://localhost:3001/health

# Should return:
# {
#   "status": "ok",
#   "timestamp": "2026-04-22T10:30:00Z"
# }

Web App

Open http://localhost:3000 in your browser

• You should see the GoodGo home page
• Try registering an account (test phone: 0987654321, any password)

API Swagger Docs

Open http://localhost:3001/api/docs

• Interactive API documentation
• Try endpoints: GET /api/v1/listings, POST /api/v1/auth/login, etc.

---

Key Commands

Command	Purpose
pnpm install	Install all dependencies
pnpm dev	Start all services in watch mode
pnpm lint	Run ESLint (check code style)
pnpm lint --fix	Auto-fix lint issues
pnpm typecheck	TypeScript type checking
pnpm test	Run unit tests
pnpm test:e2e	Run E2E tests with Playwright
pnpm build	Production build
pnpm db:generate	Generate Prisma client
pnpm db:migrate:dev	Run pending migrations
pnpm db:seed	Seed sample data
pnpm db:studio	Open Prisma Studio GUI

---

Project Structure

goodgo-platform-ai/
├── apps/
│   ├── api/                    # NestJS backend
│   │   ├── src/
│   │   │   ├── main.ts         # Entry point
│   │   │   └── modules/        # Domain modules
│   │   │       ├── auth/
│   │   │       ├── listings/
│   │   │       ├── payments/
│   │   │       └── ...
│   │   └── package.json
│   └── web/                    # Next.js frontend
│       ├── src/
│       │   ├── app/            # App Router pages
│       │   ├── components/
│       │   ├── lib/
│       │   └── hooks/
│       └── package.json
├── libs/
│   ├── ai-services/            # Python FastAPI (AVM, moderation)
│   └── mcp-servers/            # MCP server library
├── prisma/
│   ├── schema.prisma           # Database schema
│   └── migrations/             # SQL migrations
├── docs/                       # Documentation
├── .github/workflows/          # CI/CD
└── package.json (root)         # pnpm workspaces config

---

Development Workflow

1. Create a Feature Branch

# Always create a feature branch from main/master
git checkout -b feature/awesome-feature

# Branch naming convention:
# - feature/new-feature-name
# - fix/bug-description
# - refactor/code-cleanup
# - docs/documentation-update

2. Make Changes

# Install dependencies for new package
pnpm install

# Run type checking + linting
pnpm typecheck
pnpm lint

# Run tests for your changes
pnpm test -- path/to/module

# Fix auto-fixable issues
pnpm lint --fix

3. Commit & Push

# Commit following conventional commits format
git add .
git commit -m "feat(module): short description"

# Commit message format:
# feat(scope): description
# fix(scope): description
# docs(scope): description
# refactor(scope): description
# test(scope): description
# chore(scope): description

# Push branch
git push origin feature/awesome-feature

4. Create Pull Request

• Go to GitHub: https://github.com/hongochai10/goodgo-bds-platform-ai/pulls
• Click New Pull Request
• Select your branch
• Add description (what changed, why, testing notes)
• Ensure all checks pass ✅ (lint, typecheck, test, build)
• Request review from team lead
• Merge after approval

---

Debugging Tips

API Debugging

# Enable debug logging
DEBUG=*:* pnpm --filter api dev

# Or in VS Code: use `.vscode/launch.json` for breakpoints
# F5 to start debugger

Web Debugging

# Chrome DevTools: F12
# React DevTools extension: https://chrome.google.com/webstore/

# Debug Next.js:
# .next/server/pages shows compiled route handlers

Database Debugging

# Connect to database directly
psql $DATABASE_URL

# Common queries:
SELECT * FROM "User" LIMIT 5;
SELECT COUNT(*) FROM "Listing";
SELECT * FROM "Listing" WHERE "status" = 'ACTIVE' LIMIT 5;

Redis Debugging

# Connect to Redis CLI
redis-cli

# Check keys
KEYS *
GET session:user:123
INCR counter

---

VS Code Setup (Optional)

Recommended Extensions

// .vscode/extensions.json
{
  "recommendations": [
    "esbenp.prettier-vscode",          // Code formatter
    "dbaeumer.vscode-eslint",          // ESLint linting
    "ms-vscode.makefile-tools",        // Makefile support
    "ms-vscode.extension-pack-fe",     // Frontend bundle
    "ms-vscode-remote.remote-containers", // Docker support
    "bradlc.vscode-tailwindcss",       // Tailwind CSS support
    "vivaxy.vscode-conventional-commits", // Commit helper
    "Prisma.prisma"                    // Prisma schema support
  ]
}

Launch Configuration (Debugging)

Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "NestJS Debug",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/@nestjs/cli/bin/nest.js",
      "args": ["start", "--debug", "--watch"],
      "cwd": "${workspaceFolder}/apps/api",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

---

Troubleshooting

Problem: pnpm install hangs

Solution:

rm -rf node_modules .pnpm-store pnpm-lock.yaml
pnpm install --no-frozen-lockfile

Problem: PostgreSQL connection refused

Solution:

# Check if PostgreSQL is running
docker-compose ps

# If not running, start it
docker-compose -f docker-compose.dev.yml up -d

# Or check local PostgreSQL
pg_isready -h localhost -p 5432

Problem: pnpm dev fails with "EADDRINUSE"

Solution:

# Port 3000 or 3001 is already in use
# Kill existing process
lsof -i :3000  # Find process ID
kill -9 <PID>

# Or use different port
PORT=3002 pnpm --filter web dev

Problem: TypeScript errors in IDE but tests pass

Solution:

# Regenerate Prisma types
pnpm db:generate

# Restart VS Code
Cmd+Shift+P → "Developer: Reload Window"

---

Getting Help

• Slack: #dev channel (if you have access)
• GitHub Issues: https://github.com/hongochai10/goodgo-bds-platform-ai/issues
• Documentation: /docs folder
• Architecture: /docs/architecture.md
• API Reference: /docs/api-endpoints.md

---

Next Steps

1. ✅ Setup complete? Start with a small bug fix or feature
2. 📖 Read Architecture: /docs/architecture.md (understand module structure)
3. 🏗️ Understand CQRS: /docs/QUICK_REFERENCE.md (command/query handlers)
4. 🧪 Write Tests: Follow patterns in existing .spec.ts files
5. 📝 Update Docs: When adding features, update relevant docs

---

Welcome to GoodGo! Happy coding! 🚀