admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate and update project documentation

Browse Source 
- 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>
This commit is contained in:
Ho Ngoc Hai
2026-04-10 23:32:00 +07:00
parent d4652fd0f9
commit 18b5980f29
7 changed files with 345 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
README.md
View File

@@ -14,7 +14,7 @@ Vietnam's intelligent real estate platform — property search, AI-powered valua
| **AI/ML** | FastAPI, XGBoost, Claude API, Underthesea |
| **MCP** | Model Context Protocol servers (property search, valuation, analytics) |
| **Storage** | MinIO (S3-compatible) |
| **Monitoring** | Prometheus + Grafana |
| **Monitoring** | Prometheus, Grafana, Loki + Promtail |
| **Payments** | VNPay, MoMo, ZaloPay |
## Architecture Overview
@@ -52,14 +52,15 @@ Vietnam's intelligent real estate platform — property search, AI-powered valua
```
goodgo-platform-ai/
├── apps/
│ ├── api/ # NestJS backend (port 3000)
│ └── web/ # Next.js frontend (port 3001)
│ ├── 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
├── monitoring/ # Prometheus & Grafana configs
├── e2e/ # Playwright E2E tests (API + Web)
├── monitoring/ # Prometheus, Grafana, Loki & Promtail configs
├── scripts/ # Backup, restore & utility scripts
└── docs/ # Developer documentation
```
@@ -102,7 +103,9 @@ pnpm db:seed
pnpm dev
```
The API will be available at `http://localhost:3000` and the web app at `http://localhost:3001`.
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
@@ -113,6 +116,7 @@ The API will be available at `http://localhost:3000` and the web app at `http://
| 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` |
@@ -151,26 +155,38 @@ 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 |
| **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 |
| **payments** | VNPay, MoMo, ZaloPay integration |
| **subscriptions** | Plan management, usage tracking |
| **notifications** | Email and in-app notifications |
| **admin** | Listing moderation, user 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 endpoint |
Each module follows Domain-Driven Design with `presentation/`, `application/`, `domain/`, and `infrastructure/` layers.
| **metrics** | Prometheus metrics and web vitals collection |
| **shared** | Cross-cutting concerns: guards, pipes, filters, Prisma/Redis services |
## 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
| 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