admin/goodgo-platform
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a9fa2145447e5335e461c64ba78caafa229dd727
goodgo-platform/CODEBASE_OVERVIEW.md
Ho Ngoc Hai 1617921993 feat(payments): add Order & Escrow repository tests, prisma config, docs 
Add 26 unit tests for PrismaOrderRepository and PrismaEscrowRepository
covering CRUD operations, pagination, domain mapping (bigint → Money),
idempotency key lookup, and escrow dispute workflow fields.

Update prisma.config.ts with dotenv import and seed command for Prisma 7.
Add architecture summary and codebase overview documentation files.

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-13 00:36:49 +07:00

413 lines
15 KiB
Markdown
Raw Blame History

# GoodGo Platform — Comprehensive Codebase Overview
**Generated:** April 12, 2026
**Project Status:** MVP Complete — Phase 7 Wave 14 ✅ Build Green
---
## 1. TOP-LEVEL DIRECTORY STRUCTURE
```
goodgo-platform-ai/
├── apps/ # Monorepo applications
│ ├── api/ # NestJS backend
│ └── web/ # Next.js frontend
├── libs/ # Shared libraries
│ ├── mcp-servers/ # MCP server implementations
│ └── ai-services/ # AI/ML services (Python FastAPI)
├── prisma/ # Database schema & migrations
│ ├── schema.prisma # Complete data model
│ └── migrations/ # 7+ migration files
├── docs/ # Technical documentation
├── e2e/ # End-to-end tests (Playwright)
├── monitoring/ # Observability stack
│ ├── grafana/ # Dashboards
│ ├── loki/ # Log aggregation
│ ├── alertmanager/ # Alerts
│ └── promtail/ # Log forwarding
├── load-tests/ # K6 performance tests
├── scripts/ # DevOps & automation
├── infra/ # Infrastructure config
│ └── pgbouncer/ # DB connection pooling
├── .github/workflows/ # CI/CD pipelines
├── docker-compose.yml # Local development
├── docker-compose.prod.yml # Production stack
├── PROJECT_TRACKER.md # Issue & phase tracking
├── IMPLEMENTATION_PLAN.md # Feature roadmap
└── package.json # Monorepo config (pnpm workspaces)
```
---
## 2. API MODULES (`apps/api/src/modules/`) — 18 MODULES
### Core Authentication & Authorization
- **auth/** — JWT, OAuth (Google/Zalo), MFA, TOTP backup codes
- Subdirs: application, domain, infrastructure, presentation, __tests__
- Key: JWT guards, passport strategies, role-based access
### Listings & Properties
- **listings/** — CRUD, status management, media, AI price estimates
- Moderation scoring, featured listings, expiration logic
- Media upload with pre-signed URLs (AWS S3)
### Search & Discovery
- **search/** — Typesense integration (full-text), geospatial (PostGIS)
- Resilient repository with fallback to PostgreSQL
- Filters: location, price, property type, bedrooms
### Transactions & Inquiries
- **inquiries/** — Buyer-to-seller messages for specific listings
- **leads/** — Agent CRM (lead scoring, status tracking, notes)
### Monetization
- **payments/** — VNPay, MoMo, ZaloPay, Bank Transfer
- Idempotency keys, webhook callbacks, refund handling
- 4 payment types: subscription, listing fee, deposit, featured
- **subscriptions/** — Plans (FREE, AGENT_PRO, INVESTOR, ENTERPRISE)
- Usage tracking, quota management, billing cycles
### Operations
- **agents/** — Agent profiles, quality scores, service areas, verification
- **admin/** — User bans, KYC approval, listing moderation, audit logs
- **notifications/** — Email, SMS, Push (FCM), Zalo OA
- Preferences per user/channel, template system
### Analytics & Intelligence
- **analytics/** — Market reports, price index by district/city/type
- Valuation engine integration (AI/ML service)
### Infrastructure & System
- **health/** — Liveness/readiness probes, Kubernetes hooks
- **metrics/** — Prometheus metrics, HTTP latency, error rates
- **mcp/** — Model Context Protocol server for AI tools
- **shared/** — Domain primitives, encryption, logging, error handling
**Code Metrics:**
- ~845 TypeScript files
- Layered DDD architecture: presentation → application → domain → infrastructure
- Uses NestJS modules, CQRS pattern for complex operations
---
## 3. FRONTEND STRUCTURE (`apps/web/`)
### Root Layout
- **app/layout.tsx** — Root wrapper
- **app/[locale]/** — i18n routing (Vietnamese + English)
### Page Groups (Route Groups with Shared Layouts)
- **(public)/** — Landing, listings, search (no auth required)
- **(auth)/** — Login, register, OAuth callbacks
- **(dashboard)/** — Seller/agent dashboard
- **(admin)/** — Admin moderation, KYC review, user management
### Components (`components/`)
```
├── agents/ — Agent profiles, cards
├── auth/ — Login forms, OAuth buttons
├── charts/ — Market analytics, performance graphs (Recharts)
├── comparison/ — Property comparison tool
├── inquiries/ — Message threads
├── leads/ — Lead management UI
├── listings/ — List, create, edit, detail views
├── map/ — Mapbox integration
├── search/ — Filters, saved searches
├── subscription/ — Plan selection, billing
├── valuation/ — AI price estimates
├── ui/ — Shadcn/ui components (button, card, modal, etc.)
└── providers/ — Context providers (auth, query, etc.)
```
### Libraries (`lib/`)
```
├── *-api.ts — React Query API clients (6 main ones)
├── *-store.ts — Zustand state stores (auth, comparison)
├── hooks/ — Custom React hooks (8 hooks)
├── validations/ — Zod schemas (listing, auth, search)
├── currency.ts — VND formatting & exchange rates
├── image-blur.ts — Blur hash for image placeholders
└── web-vitals.ts — Core Web Vitals tracking
```
### i18n (`i18n/`)
- Vietnamese & English message files
- next-intl integration
**Frontend Metrics:**
- ~245 TypeScript/TSX files
- Built on: Next.js 15, React 18, Tailwind CSS, Shadcn/ui
- State: Zustand + React Query
- Forms: React Hook Form + Zod validation
---
## 4. PRISMA SCHEMA — DATA MODEL
**Database:** PostgreSQL 16 + PostGIS extension
### Total Models: 31
#### Authentication (5)
| Model | Purpose |
|-------|---------|
| User | Main user profile + KYC status, MFA fields |
| RefreshToken | JWT refresh token chain management |
| OAuthAccount | Google/Zalo OAuth linkage |
| Agent | Seller/Agent extended profile |
| MfaChallenge | TOTP/backup code verification tracking |
#### Listings & Properties (4)
| Model | Purpose |
|-------|---------|
| Property | Physical property details + geolocation |
| PropertyMedia | Images/videos per property |
| Listing | Listing instance (sale/rent) + status |
| SavedSearch | User's saved search preferences |
#### Transactions (4)
| Model | Purpose |
|-------|---------|
| Transaction | Buyer-seller transaction flow (inquiry → completed) |
| Inquiry | Buyer questions on specific listings |
| Lead | Agent CRM lead records |
| Review | User reviews of agents/transactions |
#### Payments (2)
| Model | Purpose |
|-------|---------|
| Payment | Payment records (all providers) |
| Plan | Subscription tier definitions |
#### Orders & Escrow (3)
| Model | Purpose |
|-------|---------|
| Order | Auction settlement order |
| Escrow | Escrow holding for transactions |
| Subscription | User's active subscription |
#### Analytics (2)
| Model | Purpose |
|-------|---------|
| Valuation | AI-generated property valuations |
| MarketIndex | Market statistics per district/city |
#### Operations (6)
| Model | Purpose |
|-------|---------|
| NotificationLog | Sent notification records |
| NotificationPreference | User notification opt-in/out |
| AdminAuditLog | Admin action audit trail |
| UsageRecord | Subscription usage tracking |
**Index Strategy:**
- Single-column indexes on foreign keys, status fields, dates
- Compound indexes for common query patterns (e.g., `[role, isActive, createdAt DESC]`)
- GIST index on PostGIS location geometry
**Key Enums:**
- UserRole: BUYER, SELLER, AGENT, ADMIN
- PropertyType: APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE
- TransactionType: SALE, RENT
- PaymentProvider: VNPAY, MOMO, ZALOPAY, BANK_TRANSFER
- PaymentStatus: PENDING, PROCESSING, COMPLETED, FAILED, REFUNDED
---
## 5. DOCUMENTATION & TRACKING
### Root-Level Planning Docs
- **PROJECT_TRACKER.md** — 7 phases, 40+ issues, current status (Phase 7 Wave 14)
- **IMPLEMENTATION_PLAN.md** — Feature roadmap with priority/status
- **COMPREHENSIVE_AUDIT_2026-04-12.md** — Full system audit with implementation notes
### Technical Docs (`docs/`)
- **architecture.md** — DDD layering, CQRS, module boundaries
- **api-endpoints.md** — Swagger-generated endpoint reference
- **api-error-codes.md** — Structured error code taxonomy
- **deployment.md** — Docker, K8s, CI/CD pipeline steps
- **RUNBOOK.md** — Operational procedures, troubleshooting
- **PRODUCTION_READINESS.md** — Security, compliance, performance checklist
### Audit Directory (`docs/audits/`)
- 80+ audit files documenting feature implementations
- Pricing audit, checkout flow, KYC, payment gateway testing
---
## 6. DEPENDENCIES & TOOLING
### Monorepo Setup
- **pnpm** v10.27.0 (workspace) — faster, strict peer deps
- **Turbo** v2.9.4 — task orchestration & caching
- **Node** ≥22.0.0
### Backend (NestJS)
```
Core: @nestjs/core ^11.0, @nestjs/common ^11.0
DB: @prisma/client ^7.7, pg ^8.20
Auth: @nestjs/jwt, @nestjs/passport, passport-jwt, passport-google-oauth20
Cache: ioredis ^5.4
Search: typesense ^3.0.5
File Upload: @aws-sdk/client-s3, @aws-sdk/s3-request-presigner
Payments: (custom integrations for VNPay, MoMo, ZaloPay)
Monitoring: @sentry/nestjs, pino, prom-client
Email: nodemailer
2FA: otplib, qrcode
```
### Frontend (Next.js)
```
Core: next ^15.5, react ^18.3, react-dom ^18.3
Forms: react-hook-form ^7.72, @hookform/resolvers
Validation: zod ^4.3
State: zustand ^5.0, @tanstack/react-query ^5.96
UI: tailwindcss ^3.4, lucide-react ^1.7, recharts ^3.8
i18n: next-intl ^4.9
Maps: mapbox-gl ^3.21
Monitoring: @sentry/nextjs
```
### Testing & Quality
```
Test: vitest ^4.1.3, @playwright/test ^1.59
Lint: eslint ^9.39, prettier ^3.8, typescript-eslint
Dependencies: dependency-cruiser (architecture validation)
```
---
## 7. TEST COVERAGE & QUALITY
### Test Files: 242 total
#### API Tests
- **Unit tests:** Payment gateways (VNPay, MoMo, ZaloPay), Money value objects, Platform fee logic
- **Integration tests:** Auth flows, health checks, notifications
- Located in `__tests__` subdirs within each module
#### Frontend Tests
- **Unit tests:** Auth store, comparison store, currency formatting, validations
- **E2E tests (Playwright):** 15+ web tests, 16+ API tests
#### E2E Test Coverage
**Web Tests (15):**
- auth-login, auth-register, auth-oauth-callback
- homepage, navigation, responsive
- create-listing, listing-detail
- search, analytics
- admin dashboard, KYC, moderation, users
- dashboard
**API Tests (16):**
- auth (login, register, profile, refresh, KYC)
- listings, listing media, moderation
- search
- payments, payment callbacks
- subscriptions
- inquiries
- mcp, admin
**Load Tests (K6):**
- Baseline benchmarks for search, listings, auth endpoints
- Concurrency testing up to 1000 virtual users
---
## 8. IMPLEMENTATION STATUS
### ✅ COMPLETE (Phase 7 MVP)
1. **Foundation** — Monorepo, Docker, Prisma schema, CI/CD
2. **Auth** — JWT, OAuth, MFA/TOTP, session management
3. **Listings** — Full CRUD, media upload, status workflow
4. **Search** — Typesense + PostGIS geo-search
5. **Payments** — 3 VN payment gateways, webhook handling
6. **Subscriptions** — 4 tiers, quota tracking
7. **Notifications** — Email, SMS, Push, Zalo OA
8. **Admin Panel** — Moderation, user management, audit logs
9. **Agents** — Portal, inquiries, lead CRM, quality metrics
10. **Analytics** — Market reports, AI valuation service
11. **Security** — Rate limiting, CSRF, field encryption, PII masking
12. **Monitoring** — Prometheus, Grafana, Sentry, log aggregation
13. **Testing** — Unit tests, E2E tests (Playwright), load tests (K6)
### 🔄 IN PROGRESS / REMAINING
- Per Wave 14:
- TEC-1650: Listing detail non-existent ID error handling
- TEC-1652: Full E2E test suite validation
- TEC-1657: Comprehensive audit logging
### Database Migrations
- 7+ migrations applied
- Connection pooling (PgBouncer)
- PostGIS extension enabled
---
## 9. PROJECT MATURITY INDICATORS
| Dimension | Status | Evidence |
|-----------|--------|----------|
| **Architecture** | Production-Ready | DDD, CQRS, layered modules, clear boundaries |
| **Code Quality** | High | 242 tests, ESLint enforcement, module cruiser |
| **Security** | Hardened | JWT, MFA, encryption, rate limiting, CSRF, PII masking |
| **Documentation** | Comprehensive | 80+ audit files, runbooks, error codes, architecture |
| **Performance** | Optimized | Redis caching, Typesense search, query optimization, load tests |
| **Monitoring** | Complete | Prometheus, Grafana, Sentry, structured logging |
| **DevOps** | Mature | Docker, Kubernetes config, CI/CD pipelines, smoke tests |
| **Scaling** | Prepared | Connection pooling, caching layer, resilient services |
---
## 10. KEY STATISTICS
```
Backend Files: ~845 TypeScript files
Frontend Files: ~245 TypeScript/TSX files
Total Test Files: 242 (unit + E2E + load)
API Modules: 18 feature modules + 1 shared
Database Models: 31 (fully normalized)
Migrations: 7+ applied to PostgreSQL 16
API Endpoints: 100+ documented
E2E Test Cases: 31 (web + API)
Load Test Scenarios: 5+ K6 scripts
Documentation: 80+ audit files + runbooks
Lines of Code: ~50,000+ (excluding node_modules)
```
---
## 11. TECH STACK SUMMARY
| Layer | Technology |
|-------|-----------|
| **Frontend** | Next.js 15, React 18, Tailwind CSS, Shadcn/ui |
| **Backend** | NestJS 11, TypeScript 6 |
| **Database** | PostgreSQL 16 + PostGIS |
| **Cache** | Redis (ioredis) |
| **Search** | Typesense 3.0 |
| **File Storage** | AWS S3 |
| **Payments** | VNPay, MoMo, ZaloPay |
| **Auth** | JWT + OAuth2 (Google, Zalo) |
| **Notifications** | Email (Nodemailer), SMS, FCM, Zalo OA |
| **Monitoring** | Prometheus, Grafana, Sentry |
| **Logs** | Pino + Loki |
| **Testing** | Playwright (E2E), Vitest (unit), K6 (load) |
| **Package Manager** | pnpm 10.27 |
| **Orchestration** | Turbo |
| **Containerization** | Docker + Docker Compose |
| **i18n** | next-intl (Vietnamese + English) |
---
## 12. NEXT STEPS FOR DEVELOPERS
1. **Local Setup:** `docker-compose up` → database + API + frontend
2. **Run Tests:** `pnpm test` (unit), `pnpm test:e2e` (E2E)
3. **Check Status:** Review PROJECT_TRACKER.md for ongoing issues
4. **Architecture:** Read docs/architecture.md for module boundaries
5. **API:** Browse docs/api-endpoints.md (Swagger-generated)
6. **Deploy:** Follow docs/deployment.md for production setup
Reference in New Issue View Git Blame Copy Permalink