# GoodGo Platform AI

Vietnam's intelligent real estate platform — property search, AI-powered valuation, and end-to-end transaction management.

## Tech Stack

| Layer | Technology |
|-------|-----------|
| **Backend** | NestJS 11, TypeScript, Prisma ORM, CQRS |
| **Frontend** | Next.js 14, React 18, Tailwind CSS, Zustand |
| **Database** | PostgreSQL 16 + PostGIS 3.4 |
| **Search** | Typesense 27 |
| **Cache/Queue** | Redis 7 |
| **AI/ML** | FastAPI, XGBoost, Claude API, Underthesea |
| **MCP** | Model Context Protocol servers (property search, valuation, analytics) |
| **Storage** | MinIO (S3-compatible) |
| **Monitoring** | Prometheus, Grafana, Loki + Promtail |
| **Payments** | VNPay, MoMo, ZaloPay |

## Architecture Overview

```
┌─────────────┐     ┌──────────────┐     ┌──────────────────┐
│  Next.js 14 │────▶│  NestJS API  │────▶│  PostgreSQL +    │
│  (Web App)  │     │  (REST)      │     │  PostGIS         │
└─────────────┘     └──────┬───────┘     └──────────────────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
        ┌─────▼──┐  ┌──────▼───┐  ┌────▼─────┐
        │ Redis  │  │Typesense │  │  MinIO   │
        │ Cache  │  │ Search   │  │ Storage  │
        └────────┘  └──────────┘  └──────────┘
              │
        ┌─────▼──────────────────────────┐
        │  MCP Servers                   │
        │  ├─ Property Search            │
        │  ├─ Market Analytics           │
        │  └─ Valuation                  │
        └─────────────┬─────────────────┘
                      │
              ┌───────▼────────┐
              │  AI Services   │
              │  (FastAPI)     │
              │  ├─ AVM        │
              │  └─ Moderation │
              └────────────────┘
```

## Monorepo Structure

```
goodgo-platform-ai/
├── apps/
│   ├── api/              # NestJS backend (port 3001)
│   └── web/              # Next.js frontend (port 3000)
├── libs/
│   ├── ai-services/      # Python FastAPI — AVM + content moderation
│   └── mcp-servers/      # MCP server implementations
├── prisma/               # Database schema & migrations
├── e2e/                  # Playwright E2E tests (API + Web)
├── monitoring/           # Prometheus, Grafana, Loki & Promtail configs
├── scripts/              # Backup, restore & utility scripts
└── docs/                 # Developer documentation
```

## Quick Start

### Prerequisites

- **Docker Engine 24+** & Docker Compose v2
- **Node.js 22 LTS**
- **pnpm 10.27+** (`corepack enable && corepack prepare pnpm@latest --activate`)

### Setup

```bash
# 1. Clone the repository
git clone <repo-url> && cd goodgo-platform-ai

# 2. Copy environment file
cp .env.example .env

# 3. Start infrastructure services
docker compose up -d

# 4. Verify services are healthy
docker compose ps

# 5. Install dependencies
pnpm install

# 6. Generate Prisma client
pnpm db:generate

# 7. Run database migrations
pnpm db:migrate:dev

# 8. Seed the database (optional)
pnpm db:seed

# 9. Start all apps in dev mode
pnpm dev
```

The API will be available at `http://localhost:3001/api/v1` and the web app at `http://localhost:3000`.

> **Swagger UI**: Open `http://localhost:3001/api/v1/docs` for interactive API documentation.

### Infrastructure Services

| Service | Port(s) | Dashboard |
|---------|---------|-----------|
| PostgreSQL + PostGIS | 5432 | — |
| Redis | 6379 | — |
| Typesense | 8108 | `http://localhost:8108/health` |
| MinIO | 9000 / 9001 | `http://localhost:9001` (console) |
| AI Services (FastAPI) | 8000 | `http://localhost:8000/health` |
| Loki (log aggregation) | 3100 | `http://localhost:3100/ready` |
| Prometheus | 9090 | `http://localhost:9090` |
| Grafana | 3002 | `http://localhost:3002` |

## Development

### Common Commands

```bash
pnpm dev              # Start all apps (API + Web)
pnpm build            # Build all packages
pnpm lint             # Run ESLint
pnpm typecheck        # TypeScript type checking
pnpm format           # Format with Prettier
pnpm test             # Run unit/integration tests
```

### Database

```bash
pnpm db:generate      # Regenerate Prisma client
pnpm db:migrate:dev   # Create and apply migrations
pnpm db:migrate:deploy # Apply migrations (CI/production)
pnpm db:seed          # Seed database
pnpm db:studio        # Open Prisma Studio (visual editor)
pnpm db:reset         # Reset database (destructive)
```

### E2E Testing

```bash
pnpm test:e2e         # Run all E2E tests
pnpm test:e2e:api     # API tests only
pnpm test:e2e:web     # Web UI tests only
pnpm test:e2e:report  # Open HTML test report
```

## API Modules

All API routes are prefixed with `/api/v1/`. Each module follows Domain-Driven Design with `presentation/`, `application/`, `domain/`, and `infrastructure/` layers.

| Module | Description |
|--------|-------------|
| **auth** | Registration, login, JWT + refresh token rotation, OAuth (Google/Zalo), KYC, user data export/deletion |
| **listings** | Property listing CRUD, status workflow, media management |
| **search** | Typesense full-text search with geo-spatial filters, saved searches |
| **payments** | VNPay, MoMo, ZaloPay integration with callback verification |
| **subscriptions** | Plan management, usage tracking, quota enforcement |
| **notifications** | Email and in-app notification history & preferences |
| **admin** | Listing moderation, user management, audit logs |
| **analytics** | Market reports, price indices, AVM integration |
| **agents** | Real estate agent profiles and verification |
| **inquiries** | Property inquiry management |
| **leads** | Lead tracking and conversion |
| **reviews** | Property reviews and ratings |
| **health** | Liveness and readiness health checks |
| **mcp** | MCP server bridge (property search, valuation, analytics) |
| **metrics** | Prometheus metrics and web vitals collection |
| **shared** | Cross-cutting concerns: guards, pipes, filters, Prisma/Redis services |

## Documentation

| Document | Description |
|----------|-------------|
| [Development Environment](docs/dev-environment.md) | Docker setup and local services |
| [Architecture](docs/architecture.md) | System design, data flow, module structure |
| [API Endpoints](docs/api-endpoints.md) | REST API endpoint reference |
| [API Error Codes](docs/api-error-codes.md) | Error response format and all error codes |
| [Deployment](docs/deployment.md) | Production deployment guide |
| [Backup & Restore](docs/backup-restore.md) | Backup procedures and disaster recovery |
| [Contributing](CONTRIBUTING.md) | Error handling conventions and coding patterns |

## License

Proprietary — All rights reserved.