docs: add architecture, deployment guides and update dev environment docs
Co-Authored-By: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Ho Ngoc Hai
239
docs/architecture.md
Normal file
239
docs/architecture.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Architecture
|
||||
|
||||
## System Overview
|
||||
|
||||
GoodGo Platform AI is a monorepo containing a NestJS backend, Next.js frontend, Python AI services, and MCP (Model Context Protocol) servers. The system is orchestrated with Turborepo and pnpm workspaces.
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Client (Browser) │
|
||||
└──────────────────┬───────────────────────┘
|
||||
│
|
||||
┌──────────────────▼───────────────────────┐
|
||||
│ Next.js 14 (apps/web) │
|
||||
│ ┌─────────┐ ┌──────────┐ ┌───────┐ │
|
||||
│ │ Pages │ │Components│ │Zustand │ │
|
||||
│ │(App │ │(UI + │ │(State) │ │
|
||||
│ │ Router) │ │ Domain) │ │ │ │
|
||||
│ └─────────┘ └──────────┘ └───────┘ │
|
||||
└──────────────────┬───────────────────────┘
|
||||
│ REST API
|
||||
┌──────────────────▼───────────────────────┐
|
||||
│ NestJS 11 (apps/api) │
|
||||
│ │
|
||||
│ ┌────────┐ ┌────────┐ ┌─────────────┐ │
|
||||
│ │ Auth │ │Listings│ │ Payments │ │
|
||||
│ ├────────┤ ├────────┤ ├─────────────┤ │
|
||||
│ │ Search │ │ Admin │ │Subscriptions│ │
|
||||
│ ├────────┤ ├────────┤ ├─────────────┤ │
|
||||
│ │Analytics│ │ MCP │ │Notifications│ │
|
||||
│ └────────┘ └────────┘ └─────────────┘ │
|
||||
└───┬─────┬──────┬─────────┬──────────────┘
|
||||
│ │ │ │
|
||||
┌────────────▼┐ ┌─▼────┐ ▼ ┌───▼──────────┐
|
||||
│ PostgreSQL │ │Redis │ │ │ Typesense │
|
||||
│ + PostGIS │ │ │ │ │ (Search) │
|
||||
└─────────────┘ └──────┘ │ └──────────────┘
|
||||
│
|
||||
┌───────────────▼──────────────────────┐
|
||||
│ MCP Servers (libs/mcp-servers) │
|
||||
│ ┌──────────┐┌──────────┐┌────────┐ │
|
||||
│ │ Property ││ Market ││Valua- │ │
|
||||
│ │ Search ││Analytics ││tion │ │
|
||||
│ └──────────┘└──────────┘└───┬────┘ │
|
||||
└──────────────────────────────┼───────┘
|
||||
│
|
||||
┌──────────────────────────────▼───────┐
|
||||
│ AI Services (libs/ai-services) │
|
||||
│ FastAPI + XGBoost + Claude API │
|
||||
│ ┌──────────┐ ┌────────────────┐ │
|
||||
│ │ AVM │ │ Moderation │ │
|
||||
│ │(Pricing) │ │ (Claude API) │ │
|
||||
│ └──────────┘ └────────────────┘ │
|
||||
└──────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Module Architecture
|
||||
|
||||
Each API module follows a layered Domain-Driven Design structure:
|
||||
|
||||
```
|
||||
modules/{module-name}/
|
||||
├── presentation/ # HTTP layer
|
||||
│ ├── controllers/ # Route handlers
|
||||
│ └── dtos/ # Request/response DTOs (class-validator)
|
||||
├── application/ # Business orchestration
|
||||
│ ├── commands/ # Write operations (CQRS)
|
||||
│ ├── queries/ # Read operations (CQRS)
|
||||
│ ├── handlers/ # Command/query handlers
|
||||
│ └── services/ # Application services
|
||||
├── domain/ # Core business logic
|
||||
│ ├── entities/ # Domain entities & value objects
|
||||
│ ├── repositories/ # Repository interfaces (abstractions)
|
||||
│ └── events/ # Domain events
|
||||
├── infrastructure/ # External integrations
|
||||
│ ├── repositories/ # Prisma repository implementations
|
||||
│ └── services/ # External service adapters
|
||||
└── {module-name}.module.ts # NestJS module definition
|
||||
```
|
||||
|
||||
### CQRS Pattern
|
||||
|
||||
The platform uses NestJS CQRS (`@nestjs/cqrs`) for complex operations:
|
||||
|
||||
- **Commands** — mutate state (create listing, process payment, register user)
|
||||
- **Queries** — read state (search properties, get analytics)
|
||||
- **Events** — cross-module communication (listing published → index in Typesense, payment completed → send notification)
|
||||
|
||||
### Shared Module
|
||||
|
||||
The `shared/` module provides cross-cutting concerns:
|
||||
|
||||
- **Prisma service** — database connection and client
|
||||
- **Redis service** — caching and session management
|
||||
- **Guards** — JWT auth guard, roles guard, throttle guard
|
||||
- **Pipes** — global validation pipe (whitelist mode)
|
||||
- **Filters** — exception filters for consistent error responses
|
||||
- **Decorators** — `@CurrentUser()`, `@Roles()`, `@Public()`
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Property Listing Lifecycle
|
||||
|
||||
```
|
||||
DRAFT → PENDING_REVIEW → ACTIVE → RESERVED → SOLD/RENTED
|
||||
│ │
|
||||
▼ │
|
||||
REJECTED EXPIRED
|
||||
```
|
||||
|
||||
1. **Seller/Agent** creates listing (status: `DRAFT`)
|
||||
2. **Seller** submits for review → `PENDING_REVIEW`
|
||||
3. **Admin** moderates (AI moderation score assists) → `ACTIVE` or `REJECTED`
|
||||
4. Active listings are indexed in Typesense for search
|
||||
5. **Buyer** makes inquiry → `Inquiry` record created
|
||||
6. Transaction workflow: `OFFER_MADE → DEPOSIT_PAID → CONTRACT_SIGNING → COMPLETED`
|
||||
|
||||
### Search Flow
|
||||
|
||||
```
|
||||
User Query → NestJS Search Module → Typesense
|
||||
│
|
||||
├─ Full-text on title/description
|
||||
├─ Faceted filters (price, type, bedrooms)
|
||||
└─ Geo-spatial (lat/long + radius)
|
||||
```
|
||||
|
||||
### Payment Flow
|
||||
|
||||
```
|
||||
User → API (create payment) → Provider (VNPay/MoMo/ZaloPay)
|
||||
│
|
||||
[User pays on provider page]
|
||||
│
|
||||
Provider callback → API → Verify signature → Update Payment status
|
||||
│
|
||||
SUCCESS / FAILED
|
||||
```
|
||||
|
||||
### AI Valuation Flow
|
||||
|
||||
```
|
||||
API Request → MCP Valuation Server → AI Service (FastAPI)
|
||||
│
|
||||
XGBoost Model
|
||||
│
|
||||
┌─────▼──────┐
|
||||
│ Estimated │
|
||||
│ Price + │
|
||||
│ Confidence │
|
||||
│ + Factors │
|
||||
└─────────────┘
|
||||
```
|
||||
|
||||
## Database Schema
|
||||
|
||||
### Core Models
|
||||
|
||||
```
|
||||
User ──┬── Agent (1:1, for AGENT role users)
|
||||
├── OAuthAccount (1:N, Google/Zalo)
|
||||
├── RefreshToken (1:N, token families)
|
||||
├── Subscription (1:N)
|
||||
├── SavedSearch (1:N)
|
||||
└── UsageRecord (1:N)
|
||||
|
||||
Property ──┬── PropertyMedia (1:N, images/videos)
|
||||
├── Listing (1:N)
|
||||
└── Valuation (1:N)
|
||||
|
||||
Listing ──┬── Inquiry (1:N)
|
||||
├── Lead (1:N)
|
||||
├── Transaction (1:N)
|
||||
└── Agent (N:1)
|
||||
|
||||
Transaction ── Payment (1:N)
|
||||
|
||||
Plan ── Subscription (1:N)
|
||||
|
||||
MarketIndex (standalone — city/district/month aggregates)
|
||||
```
|
||||
|
||||
### Key Design Decisions
|
||||
|
||||
- **PostGIS** for spatial queries — property locations stored as `Point` geometry
|
||||
- **JSON columns** for flexible data: amenities, nearby POIs, KYC data, subscription features
|
||||
- **Token family tracking** for secure refresh token rotation (detects reuse attacks)
|
||||
- **Soft statuses** over soft deletes — listings use status workflow, not `deletedAt`
|
||||
|
||||
## MCP Servers
|
||||
|
||||
Three Model Context Protocol servers provide AI tool interfaces:
|
||||
|
||||
| Server | Tools | Data Source |
|
||||
|--------|-------|-------------|
|
||||
| **Property Search** | `search_properties`, `compare_properties`, `get_property_details` | Typesense |
|
||||
| **Market Analytics** | `get_market_report`, `analyze_trends`, `get_price_indices` | PostgreSQL |
|
||||
| **Valuation** | `estimate_valuation`, `extract_features`, `compare_valuations` | AI Services (FastAPI) |
|
||||
|
||||
MCP servers are registered via `McpModule` in NestJS, managed by `McpRegistryService`, and exposed through `McpTransportController` over HTTP.
|
||||
|
||||
## AI Services
|
||||
|
||||
Python FastAPI microservice (`libs/ai-services/`) provides:
|
||||
|
||||
| Endpoint | Model | Purpose |
|
||||
|----------|-------|---------|
|
||||
| `POST /avm/estimate` | XGBoost | Property price estimation with confidence score |
|
||||
| `POST /moderation/check` | Claude API | Content moderation for listing descriptions |
|
||||
| `GET /health` | — | Health check |
|
||||
|
||||
- **Underthesea** handles Vietnamese text tokenization and NLP preprocessing
|
||||
- XGBoost model uses engineered features (area, location, property type, amenities)
|
||||
|
||||
## Security
|
||||
|
||||
- **JWT + Refresh Token Rotation** — 15-minute access tokens, 7-day refresh tokens with family-based rotation
|
||||
- **OAuth** — Google and Zalo social login
|
||||
- **Rate Limiting** — 60 req/60s default, 10 req/60s for auth endpoints
|
||||
- **Helmet** — HTTP security headers
|
||||
- **CORS** — Configurable origins via `CORS_ORIGINS`
|
||||
- **Input Validation** — class-validator (backend), Zod (frontend)
|
||||
- **Content Sanitization** — sanitize-html for user-generated content
|
||||
- **KYC** — Agent verification workflow (NONE → PENDING → VERIFIED/REJECTED)
|
||||
|
||||
## Monitoring
|
||||
|
||||
- **Prometheus** scrapes `/metrics` endpoint every 15 seconds
|
||||
- **Grafana** dashboards auto-provisioned from `monitoring/grafana/dashboards/`
|
||||
- **Pino** structured JSON logging with configurable log levels
|
||||
- Metrics include HTTP request duration, error rates, and custom business metrics
|
||||
|
||||
## Event System
|
||||
|
||||
The platform uses `@nestjs/event-emitter` for loose coupling between modules:
|
||||
|
||||
- `listing.published` → Typesense indexer updates search index
|
||||
- `payment.completed` → Notification service sends confirmation
|
||||
- `inquiry.created` → Agent notification triggered
|
||||
- `user.registered` → Welcome email sent
|
||||
Reference in New Issue
Block a user