docs: add architecture, deployment guides and update dev environment docs

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-08 05:03:29 +07:00
parent e5f370ced1
commit ea10c28539
4 changed files with 723 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,177 @@
+# 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.