18b5980f29
- Fix port numbers across all docs (API :3001, Web :3000) - Add 6 missing modules to README, CLAUDE.md, and architecture doc (agents, health, inquiries, leads, reviews, metrics/web-vitals) - Add Swagger UI reference and /api/v1 prefix notes - Create docs/api-endpoints.md with complete REST API reference - Create docs/README.md as documentation index - Update deployment guide with Loki, Promtail, pg-backup services - Update health check table with all current endpoints Co-Authored-By: Paperclip <noreply@paperclip.ing>
194 lines
7.3 KiB
Markdown
194 lines
7.3 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, 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.
|