# GoodGo Platform

Vietnamese real estate platform — monorepo powered by pnpm workspaces + Turborepo.

## Quick Start

```bash
pnpm install
pnpm db:generate        # Generate Prisma client
pnpm db:migrate:dev     # Run migrations (needs PostgreSQL 16 + PostGIS)
pnpm db:seed            # Seed sample data (users, listings, districts)
pnpm dev                # Start all apps (API :3001, Web :3000)
```

## Architecture

- **apps/api** — NestJS backend (CQRS, DDD, clean architecture)
- **apps/web** — Next.js 14 frontend (App Router, Tailwind, Zustand)
- **libs/mcp-servers** — MCP tool server library
- **prisma/** — Schema, migrations, seed scripts
- **e2e/** — Playwright E2E tests (API + Web projects)

## Key Commands

| Command | Description |
|---------|-------------|
| `pnpm lint` | ESLint (auto-fixable with `--fix`) |
| `pnpm typecheck` | TypeScript type checking |
| `pnpm test` | Unit tests via Vitest (API only) |
| `pnpm build` | Production build (all packages) |
| `pnpm test:e2e` | Playwright E2E tests |
| `pnpm db:studio` | Prisma Studio GUI |

## Tech Stack

- **Runtime**: Node.js >= 22, pnpm 10
- **Backend**: NestJS, Prisma ORM, PostgreSQL 16 + PostGIS, Redis
- **Frontend**: Next.js 14, React 18, Tailwind CSS 3, Zustand, Mapbox GL
- **Testing**: Vitest (unit), Playwright (E2E)
- **CI**: GitHub Actions (lint → typecheck → test → build)

## Project Structure (API)

```
apps/api/src/modules/
  auth/          — Authentication (JWT, OAuth, refresh tokens, CSRF)
  listings/      — Property listings CRUD
  payments/      — VNPay payment integration
  subscriptions/ — Plans, quotas, usage tracking
  admin/         — Moderation, KYC, user management
  analytics/     — Market data, heatmaps, price trends
  search/        — Geo search, full-text search (Typesense)
  notifications/ — Email, push (FCM), in-app notifications
  metrics/       — Prometheus metrics
  mcp/           — MCP tool server endpoints
  shared/        — Domain primitives, guards, pipes, logging
```

Each module follows DDD layers: `domain/` → `application/` → `infrastructure/` → `presentation/`.

## Database

- PostgreSQL 16 with PostGIS extension for geospatial queries
- 22 models (User, Property, Listing, Payment, Subscription, etc.)
- Migrations in `prisma/migrations/`
- Seed data covers: users, agents, Ho Chi Minh City districts/wards, sample properties, subscription plans

## Environment Variables

Required in `.env`:
- `DATABASE_URL` — PostgreSQL connection string
- `JWT_SECRET`, `JWT_REFRESH_SECRET` — Auth tokens
- `VNPAY_*` — Payment gateway config
- `MAPBOX_TOKEN` — Map rendering (frontend)
- `REDIS_URL` — Cache layer (optional for dev)

## Conventions

- Import order enforced by eslint-plugin-import-x (external → internal → relative)
- Path aliases: `@modules/*` in API, `@/*` in Web
- Vietnamese UI text throughout (property types, districts, currency in VND)
- All handlers return typed `Result<T>` or throw `DomainException`
- Commit messages follow conventional commits