docs: move 8 audit report files to docs/audits/

Move remaining root-level audit and CQRS handler analysis files to the centralized docs/audits/ directory for consistency. Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-04-11 19:15:24 +07:00
parent 80725ed81f
commit 514aa507db
8 changed files with 3673 additions and 398 deletions
--- a/docs/audits/CODEBASE_AUDIT_2026-04-11.md
+++ b/docs/audits/CODEBASE_AUDIT_2026-04-11.md
@@ -0,0 +1,372 @@
+# GoodGo Platform AI — Comprehensive Codebase Audit
+
+**Date:** April 11, 2026 | **Scope:** Full monorepo (NestJS API + Next.js Web + MCP servers)
+
+---
+
+## 1. DIRECTORY STRUCTURE
+
+### Top-Level Organization
+```
+goodgo-platform-ai/
+├── apps/               (1.4 GB) — 2 applications
+│   ├── api/            NestJS backend (port 3001)
+│   └── web/            Next.js frontend (port 3000)
+├── libs/               (560 KB) — Shared libraries
+│   ├── mcp-servers/    MCP implementations
+│   └── ai-services/    Python FastAPI (AVM + moderation)
+├── prisma/             (100 KB) — Database schema + migrations
+│   ├── schema.prisma   ✓ 21 data models
+│   └── migrations/     ✓ 13 migrations (latest: cascade delete strategies)
+├── e2e/                (196 KB) — End-to-end tests
+│   ├── api/            31 E2E test specs
+│   ├── web/            Playwright tests
+│   └── load/           K6 load testing
+├── .github/workflows/  ✓ 7 CI/CD pipelines (1,431 lines)
+├── infra/              Docker configs, PgBouncer
+├── monitoring/         Prometheus, Grafana, Loki configs
+├── docs/               ✓ 74 markdown files (see docs audit)
+└── scripts/            Backup, restore, utility scripts
+```
+
+### API Module Structure (apps/api/src/modules/)
+**16 feature modules + 1 shared module:**
+- **auth** — JWT, OAuth (Google/Zalo), KYC, user deletion
+- **listings** — CRUD, status workflow, media management
+- **search** — Typesense full-text + geo-spatial filters
+- **payments** — VNPay, MoMo, ZaloPay integration
+- **subscriptions** — Plans, usage tracking, quota enforcement
+- **notifications** — Email + in-app, preferences
+- **admin** — Listing moderation, user management, audit logs
+- **analytics** — Market reports, price indices, AVM
+- **agents** — Agent profiles, verification
+- **inquiries, leads, reviews, health, metrics, mcp, shared**
+
+**Code Metrics:**
+- 23 services | 19 controllers | 85 CQRS handlers (event-driven)
+- 226 unit test specs (.spec.ts files)
+
+### Frontend Structure (apps/web/)
+**Route Layout:** i18n-aware with locale prefix `[locale]`
+```
+app/[locale]/
+├── (public)/          Home, about, property listings
+├── (auth)/            Login, registration, password reset
+├── (dashboard)/       User dashboard, saved searches, profile
+├── (admin)/           Admin panel (moderation, users)
+└── api/               Next.js API routes (health check)
+```
+
+**Component Organization (11 directories):**
+- ui/ — Base design system components
+- auth/, listings/, search/, map/, charts/ — Feature components
+- agents/, valuation/, comparison/, seo/, providers/
+
+**Total:** 110 .tsx files (pages + components)
+
+---
+
+## 2. PACKAGE HEALTH
+
+### Root (pnpm workspace)
+| Property | Value |
+|----------|-------|
+| **Node** | ≥22.0.0 (LTS) |
+| **pnpm** | 10.27.0 |
+| **TypeScript** | 6.0.2 |
+| **Turbo** | 2.9.4 |
+| **Security** | Overrides: axios ≥1.15.0, lodash ≥4.18.0 |
+| **Test Runner** | Vitest + Playwright |
+
+### Backend (apps/api)
+| Category | Count |
+|----------|-------|
+| **Direct Dependencies** | 32 |
+| **DevDependencies** | 18 |
+| **Key Stack** | NestJS 11, Prisma 7.7, CQRS 11, Event Emitter 3 |
+| **AI/ML** | Claude API, XGBoost (via ai-services) |
+| **Storage** | AWS S3 SDK, Presigner |
+| **Auth** | Passport (JWT, Google OAuth, local) |
+| **Database** | Prisma ORM + PostgreSQL adapter |
+| **Cache** | ioredis 5.4 |
+| **Search** | Typesense 3 |
+| **Monitoring** | Sentry, Prometheus (@willsoto 6.1.0) |
+| **Email** | Nodemailer 8 |
+| **Payments** | (VNPay/MoMo via custom handlers) |
+
+### Frontend (apps/web)
+| Category | Count |
+|----------|-------|
+| **Direct Dependencies** | 15 |
+| **DevDependencies** | 17 |
+| **Key Stack** | Next.js 15.5, React 18, TailwindCSS 3.4 |
+| **Forms** | React Hook Form, Zod validation |
+| **State** | Zustand 5 |
+| **Data** | TanStack React Query 5.96 |
+| **UI** | Lucide icons, Class Variance Authority, Tailwind Merge |
+| **Maps** | Mapbox GL 3.21 |
+| **Charts** | Recharts 3.8 |
+| **i18n** | next-intl 4.9 |
+| **SEO** | Web Vitals 5.2 |
+| **Monitoring** | Sentry/nextjs 10.47 |
+
+### Build Pipeline Issues
+- ⚠️ TypeScript 6.0.2 is experimental (released 2026) — monitor stability
+- ✓ ESLint 9.39.4 (latest), proper ignores configured
+- ✓ Prettier 3.8.1 (configured) + lint-staged hooks
+- ✓ Dependency cruiser installed (circular deps check)
+
+---
+
+## 3. DATABASE STATE
+
+### Schema Summary
+**21 Prisma Models:**
+```
+User                Listing              Inquiry
+RefreshToken        SavedSearch          Lead
+OAuthAccount        Transaction          Payment
+Agent               Property             Plan
+PropertyMedia       Review               Subscription
+                                         UsageRecord
+                                         Valuation
+                                         MarketIndex
+                                         NotificationLog
+                                         NotificationPreference
+                                         AdminAuditLog
+```
+
+**Database Features:**
+- PostgreSQL 16 + PostGIS 3.4 extension
+- Composite indexes for query optimization
+- Soft deletes (User: deletedAt, deletionScheduledAt)
+- CUID2 primary keys (@paralleldrive/cuid2)
+- Enum types: UserRole, KYCStatus, OAuthProvider, etc.
+
+**Migration History:**
+- ✓ 13 total migrations (no gaps)
+- Latest: `20260411000000_add_cascade_delete_strategies`
+- Migration log tracked in `migration_lock.toml`
+
+**Seed File:**
+- ✓ `prisma/seed.ts` configured in package.json
+- Prisma Studio available via `pnpm db:studio`
+
+---
+
+## 4. TEST COVERAGE
+
+### Test Breakdown
+| Category | Count | Type |
+|----------|-------|------|
+| **API Unit/Integration** | 226 | vitest (.spec.ts) |
+| **E2E (API)** | 31 | playwright |
+| **Frontend Unit** | 0 | ⚠️ Gap |
+| **Total** | 257 | — |
+
+**Test Configuration:**
+- API: `vitest.config.ts` + `vitest.integration.config.ts`
+- Frontend: `vitest.config.ts` (configured but 0 tests written)
+- E2E: `playwright.config.ts` (matrix: api + web projects)
+- Playwright report: `playwright-report/` directory
+
+**Gap Analysis:**
+- ❌ **Critical:** No frontend component/unit tests (React Testing Library setup exists but unused)
+- ⚠️ Frontend integration tests missing
+- ✓ Backend API well-tested (226 specs)
+- ✓ E2E coverage for core flows (31 tests)
+
+---
+
+## 5. CI/CD PIPELINE
+
+### 7 Workflow Files (1,431 lines total)
+
+| Pipeline | Trigger | Key Steps |
+|----------|---------|-----------|
+| **ci.yml** | push/PR → master | Lint → TypeCheck → Test → Build (Node 22 matrix) |
+| **e2e.yml** | triggered | Playwright API + Web tests |
+| **deploy.yml** | manual dispatch | Docker build → push to registry → K8s deploy |
+| **load-test.yml** | scheduled + manual | K6 performance tests |
+| **security.yml** | scheduled | CodeQL, dependency scan |
+| **backup-verify.yml** | scheduled | Database backup verification |
+| **codeql.yml** | PR + scheduled | Static analysis (C, C++, C#, Java, JS/TS, Python, Ruby) |
+
+**Infrastructure:**
+- ✓ PostgreSQL 16 + PostGIS sidecar for CI
+- ✓ Dependency injection: CI matrix for Node 22
+- ✓ Concurrency: cancel previous runs on re-push
+
+---
+
+## 6. DOCKER & INFRASTRUCTURE
+
+### Docker Compose Stack
+**Services in docker-compose.yml:**
+1. **PostgreSQL 16** + PostGIS 3.4 (port 5432)
+2. **Redis 7-alpine** with maxmemory policy (port 6379)
+3. **Typesense 27.1** (port 8108)
+4. **MinIO S3-compatible** (ports 9000/9001)
+5. **AI Services (FastAPI)** (port 8000)
+6. **Loki** log aggregation (port 3100)
+7. **Prometheus** (port 9090)
+8. **Grafana** dashboard (port 3002)
+
+**Compose Variants:**
+- `docker-compose.yml` — development
+- `docker-compose.ci.yml` — CI environment
+- `docker-compose.prod.yml` — production (14 KB, optimized)
+
+**Dockerfiles:**
+- ✓ `apps/api/Dockerfile` (NestJS build)
+- ✓ `apps/web/Dockerfile` (Next.js build)
+- ✓ `libs/ai-services/Dockerfile` (Python FastAPI)
+
+**Infrastructure:**
+- ✓ PgBouncer config in `infra/pgbouncer/` (connection pooling)
+- ✓ Monitoring configs in `monitoring/` (Prometheus scrape, Grafana dashboards)
+
+---
+
+## 7. ENVIRONMENT CONFIGURATION
+
+### .env.example (Comprehensive)
+**Sections Defined:**
+- PostgreSQL + PostGIS connection (DATABASE_URL, DATABASE_URL_DIRECT)
+- PgBouncer pooling (pool size, max connections, credentials)
+- Redis (host, port, password, URL)
+- Typesense (host, port, API key, protocol)
+- MinIO S3 storage (endpoint, credentials, bucket)
+- Firebase (service account)
+- AWS S3 (region, credentials for media)
+- Stripe/Payment APIs (test keys)
+- Email (Nodemailer SMTP or SendGrid)
+- JWT (secret, access/refresh token TTL)
+- OAuth (Google Client ID/Secret, Zalo App ID)
+- Claude API (for valuation/moderation)
+- Sentry (DSN for error tracking)
+- Logging (Loki, Grafana, Prometheus)
+- Node environment (dev/test/staging/production)
+
+**Status:** ✓ All critical vars documented; test/prod configs in `.env.test`
+
+---
+
+## 8. DOCUMENTATION
+
+### Available Docs (docs/ folder, 74 markdown files)
+| Document | Purpose | Lines |
+|----------|---------|-------|
+| **README.md** | Overview + quick start | ~65 |
+| **architecture.md** | System design, module hierarchy | ~350 |
+| **api-endpoints.md** | REST endpoints reference | ~250 |
+| **api-error-codes.md** | Error response format + codes | ~400 |
+| **deployment.md** | K8s, Docker, CI/CD setup | ~350 |
+| **backup-restore.md** | Disaster recovery procedures | ~200 |
+| **dev-environment.md** | Local setup, Docker services | ~150 |
+| **RUNBOOK.md** | Troubleshooting + ops guide | ~900 |
+
+### Additional Docs in Root
+- `CLAUDE.md` — AI/Claude integration guide
+- `CONTRIBUTING.md` — Error handling conventions
+- `CHANGELOG.md` — Version history
+- `CODE_AUDIT_REPORT.md`, `CQRS_HANDLER_AUDIT.csv` — Analysis artifacts
+
+**Strengths:** ✓ Comprehensive; covers deployment, architecture, API reference
+**Gap:** ⚠️ Limited frontend component documentation (no Storybook)
+
+---
+
+## 9. BUILD HEALTH
+
+### TypeScript Configuration
+| File | Purpose |
+|------|---------|
+| `tsconfig.base.json` | Root config with path aliases |
+| `apps/api/tsconfig.json` | Backend-specific settings |
+| `apps/web/tsconfig.json` | Frontend-specific settings |
+| `libs/mcp-servers/tsconfig.json` | Library settings |
+
+**Status:** ✓ Proper monorepo setup with shared base config
+
+### ESLint & Code Quality
+- **eslint.config.mjs** (149 lines) — FlatConfig v9 format
+- Ignores: node_modules, dist, .next, coverage
+- Plugins: TypeScript ESLint, import-x, prettier
+- **Status:** ✓ Modern flat config, no issues detected
+
+### Turbo Build System
+- `turbo.json` (22 lines) configured:
+  - `build` → outputs dist/ + .next/, depends on ^build
+  - `dev` → persistent, no caching
+  - `lint, test, typecheck` → depend on ^build
+- **Status:** ✓ Correct dependency graph for monorepo
+
+### Build Artifacts
+- Root `pnpm-lock.yaml` (470 KB) — pinned dependencies
+- `.turbo/` cache directory present
+- Corepack configured via `.pnpmrc.json`
+
+---
+
+## 10. FRONTEND INSIGHTS
+
+### Next.js 15.5 Setup
+- ✓ App Router (not Pages Router)
+- ✓ i18n via next-intl with locale-prefixed routes
+- ✓ TypeScript strict mode
+- ✓ Tailwind CSS 3.4 with custom config
+
+### Component Library Coverage
+**Feature Components (11 directories):**
+- auth — Login, signup, password reset flows
+- listings — Search results, detail page, filters
+- search — Saved searches, advanced filters
+- map — Mapbox integration for location display
+- charts — Analytics dashboards (revenue, trends)
+- agents — Agent profiles, verification badge
+- valuation — AVM integration UI
+- seo — Meta tags, Open Graph, structured data
+- comparison — Side-by-side property compare
+- providers — API/context providers setup
+- ui — Buttons, forms, modals, cards (base design system)
+
+**Status:** ✓ Well-organized, feature-driven architecture
+
+### State Management
+- Zustand stores (5-10 typical size)
+- React Query for server state caching
+- React Hook Form for form logic
+- Context API for theme/i18n providers
+
+---
+
+## KEY FINDINGS
+
+| Category | Status | Notes |
+|----------|--------|-------|
+| **Architecture** | ✅ Excellent | DDD + CQRS backend, clean layers |
+| **Database** | ✅ Production-Ready | 21 models, soft deletes, indexes, migrations |
+| **API Test Coverage** | ✅ Strong | 226 unit/integration specs |
+| **Frontend Test Coverage** | ❌ **Critical Gap** | 0 unit tests; vitest setup exists but unused |
+| **CI/CD** | ✅ Mature | 7 pipelines, CodeQL, load testing, backups |
+| **Docker** | ✅ Complete | Multi-service, dev/CI/prod configs |
+| **Documentation** | ✅ Comprehensive | 74 files covering architecture, API, deployment |
+| **Build System** | ✅ Optimized | Turbo monorepo with proper caching |
+| **Dependencies** | ⚠️ Watch | TypeScript 6.0.2 experimental; monitor stability |
+| **Code Quality** | ✅ Good | ESLint, Prettier, pre-commit hooks configured |
+
+---
+
+## RECOMMENDATIONS
+
+1. **Frontend Testing:** Write 50+ React component tests for critical paths (auth, search, checkout)
+2. **API Docs:** Generate OpenAPI/Swagger docs automatically; docs exist but could be auto-indexed
+3. **E2E Expansion:** Add 20+ more Playwright tests for payment flows, agent workflows
+4. **Monitoring:** Verify Prometheus scrape config + Grafana dashboards are production-ready
+5. **Load Testing:** Schedule K6 tests weekly; track performance baselines
+6. **Dependency Audit:** Review TypeScript 6.0 stability pre-production deployment
+
+---
+
+**Generated:** 2026-04-11 | **Auditor:** Codebase Analysis Tool