178 lines
6.1 KiB
Markdown
178 lines
6.1 KiB
Markdown
# 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 |
|
|
| **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 3000)
|
|
│ └── web/ # Next.js frontend (port 3001)
|
|
├── libs/
|
|
│ ├── ai-services/ # Python FastAPI — AVM + content moderation
|
|
│ └── mcp-servers/ # MCP server implementations
|
|
├── prisma/ # Database schema & migrations
|
|
├── e2e/ # Playwright E2E tests
|
|
├── monitoring/ # Prometheus & Grafana configs
|
|
└── 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:3000` and the web app at `http://localhost:3001`.
|
|
|
|
### 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` |
|
|
| 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
|
|
|
|
| Module | Description |
|
|
|--------|-------------|
|
|
| **auth** | Registration, login, JWT + refresh token rotation, OAuth (Google/Zalo), KYC |
|
|
| **listings** | Property listing CRUD, status workflow, media management |
|
|
| **search** | Typesense full-text search with geo-spatial filters |
|
|
| **payments** | VNPay, MoMo, ZaloPay integration |
|
|
| **subscriptions** | Plan management, usage tracking |
|
|
| **notifications** | Email and in-app notifications |
|
|
| **admin** | Listing moderation, user management |
|
|
| **analytics** | Market reports, price indices, AVM integration |
|
|
| **mcp** | MCP server bridge (property search, valuation, analytics) |
|
|
| **metrics** | Prometheus metrics endpoint |
|
|
|
|
Each module follows Domain-Driven Design with `presentation/`, `application/`, `domain/`, and `infrastructure/` layers.
|
|
|
|
## Documentation
|
|
|
|
- [Development Environment](docs/dev-environment.md) — Docker setup and local services
|
|
- [Architecture](docs/architecture.md) — System design, data flow, module structure
|
|
- [Deployment](docs/deployment.md) — Production deployment guide
|
|
|
|
## License
|
|
|
|
Proprietary — All rights reserved.
|