goodgo-platform/docs/audits/AUDIT_INDEX.md

Backend API Audit: Trading Exchange UI Refactor — Index

📋 Audit Documents

This audit analyzed the goodgo-platform-ai backend API to identify gaps for the frontend refactor into a "trading exchange" (sàn giao dịch) style UI.

Documents Generated

1. BACKEND_API_AUDIT_EXCHANGE_UI.md (261 lines)

   • Full detailed audit with endpoint inventory
   • Per-module breakdown (listings, analytics, search, agents, admin, reviews)
   • All 10 critical + medium priority gaps documented
   • Phased implementation roadmap (Phase 1–3)
   • Use this for: In-depth planning, requirement discussions with backend team

2. BACKEND_API_AUDIT_QUICK_REFERENCE.txt (130 lines)

   • One-page quick reference with visual formatting
   • Highlights only the 10 gaps that need attention
   • Sprint-by-sprint roadmap
   • Use this for: Daily standup reference, priority discussions, quick reviews

---

🎯 Key Findings

Summary Statistics

• Total Endpoints Audited: 70+
• Ready for FE: 58 ✅
• Critical Gaps: 5 🔴
• Medium Priority Gaps: 5 🟡
• Estimated Dev Effort: 2–3 sprints
• Quick Wins: 2 (sortBy, metadata)

The 10 Gaps at a Glance

#	Gap	Priority	Module	Effort
1	Recent listings ticker	🔴 CRITICAL	listings	Low
2	Market snapshot endpoint	🔴 CRITICAL	analytics	Medium
3	Trending areas	🔴 CRITICAL	analytics	Medium
4	Similar listings	🔴 CRITICAL	listings	Medium
5	Listing detail enrichment	🔴 CRITICAL	listings	Medium
6	Price movers (gainers/losers)	🟡 Medium	analytics	Low
7	Market history (12m trends)	🟡 Medium	analytics	Medium
8	Ward-level heatmap	🟡 Medium	analytics	Low
9	Real-time listing updates	🟡 Medium	listings	High
10	Cache metadata in responses	🟡 Medium	analytics	Low

---

📊 Detailed Breakdown by UI Screen

1. Home Dashboard (Market Overview)

Status: 40% ready

Currently Available:

• Market report (district-level stats) ✅
• Heatmap (by district) ✅
• Price trends ✅

Missing:

• Market snapshot (live tiles with totalActive, avgPrice, change%) ❌ Gap #2
• Recent listings ticker ❌ Gap #1
• Trending areas (hot markets by inquiry volume) ❌ Gap #3

Effort to Complete: ~1 week (gaps #1–3)

---

2. Listings Board (Search + Filter)

Status: 80% ready

Currently Available:

• Full search with faceted filters ✅
• Pagination, sorting (but not by publishedAt) ✅
• Real-time updates endpoint exists but needs sortBy=publishedAt ⚠️

Missing:

• Sort by "newest first" (publishedAt) ❌ Gap #1
• "Just posted" / "price dropped" badges (needs real-time) ❌ Gap #9
• Similar listings comparables ❌ Gap #4

Effort to Complete: ~2–3 days (gaps #1, #4)

---

3. Listing Detail

Status: 70% ready

Currently Available:

• Full property data (description, media, location) ✅
• Seller & agent info ✅
• Price history ✅
• Media gallery ✅
• AVM endpoint exists (separate call) ✅

Missing:

• Valuation estimate in detail response ❌ Gap #5
• Inquiry count exposed ❌ Gap #5
• Agent quality score denormalized ❌ Gap #5
• Similar listings carousel ❌ Gap #4

Effort to Complete: ~3–4 days (gaps #4, #5)

---

4. Agent Profile Card

Status: 85% ready

Currently Available:

• Public agent profile ✅
• Quality score ✅
• Agency info ✅

Missing:

• Review stats (avg, count) — have separate endpoint but not denormalized ⚠️
• Active listings count ❌ (search + filter workaround: count by agent)
• Response time metrics ❌ (not tracked)

Effort to Complete: ~2–3 days (no new endpoints needed, just denormalization)

---

5. Admin Panel

Status: 95% ready

Currently Available:

• Moderation queue ✅
• KYC queue ✅
• User management ✅
• Audit logs ✅
• Revenue analytics ✅

Missing:

• None for core features; only nice-to-haves like queue statistics

Effort to Complete: Complete, ready for FE

---

6. Market Analytics Page

Status: 60% ready

Currently Available:

• Market report (current snapshot) ✅
• Price trends ✅
• Heatmap (by district) ✅
• Neighborhood scores ✅

Missing:

• Market history (12-month data for trend charts) ❌ Gap #7
• Ward-level heatmap drill-down ❌ Gap #8
• Price movers (top gainers/losers) ❌ Gap #6
• Cache metadata (data age indicators) ❌ Gap #10

Effort to Complete: ~1 week (gaps #6–8, #10)

---

🚀 Recommended Implementation Order

Sprint 1 (Days 1–4)

• Gap #1: Add sortBy=publishedAt to /listings search

  • File: apps/api/src/modules/listings/presentation/dto/search-listings.dto.ts
  • Effort: 1 day

• Gap #4: Add GET /listings/:id/similar endpoint

  • File: New query: apps/api/src/modules/listings/application/queries/get-similar-listings/
  • Effort: 1.5 days

Sprint 2 (Days 5–8)

• Gap #2: Add GET /analytics/market-snapshot endpoint

  • File: New query in analytics module
  • Effort: 2 days

• Gap #3: Add GET /analytics/trending-areas endpoint

  • Effort: 1.5 days

Sprint 3 (Days 9–12)

• Gap #5: Enrich GET /listings/:id with valuationEstimate, inquiryCount, agentScore

  • Effort: 1.5 days

• Gap #10: Add cachedAt, nextRefreshAt to all /analytics/* responses

  • Effort: 1 day

Sprint 4 (Days 13–17) — Medium Priority

• Gap #6: GET /analytics/price-movers

  • Effort: 1.5 days

• Gap #7: GET /analytics/market-history?period=12m

  • Effort: 2 days

Sprint 5+ (Optional)

• Gap #8: Ward-level heatmap enhancement
• Gap #9: Real-time updates (WebSocket/SSE)

---

📁 File Structure Reference

All controllers follow this pattern:

apps/api/src/modules/{MODULE}/
├── presentation/
│   ├── controllers/
│   │   └── {name}.controller.ts
│   └── dto/
│       └── *.dto.ts
├── application/
│   ├── commands/
│   └── queries/
│       └── {query-name}/
│           ├── {query-name}.query.ts
│           └── {query-name}.handler.ts
├── domain/
│   └── repositories/
└── infrastructure/

Key files to modify:

• Listings module: apps/api/src/modules/listings/presentation/controllers/listings.controller.ts
• Analytics module: apps/api/src/modules/analytics/presentation/controllers/analytics.controller.ts
• Search module: apps/api/src/modules/search/presentation/controllers/search.controller.ts

---

✅ Audit Checklist

• All 70+ endpoints enumerated by module
• Route prefixes, methods, query params documented
• Auth/guard requirements identified
• Gaps mapped to UI screen requirements
• Implementation roadmap created
• Sprint-by-sprint effort estimates provided
• No mock data recommended—all real backend data
• File paths provided for easy navigation

---

🎓 How to Use This Audit

For Backend TechLead:

1. Read BACKEND_API_AUDIT_EXCHANGE_UI.md for full context
2. Prioritize gaps 1–5 (critical) in Sprint 1–2
3. Reference "Implementation Roadmap" section for sequencing
4. Use "Recommendations" section for effort estimates

For Frontend Lead:

1. Read BACKEND_API_AUDIT_QUICK_REFERENCE.txt for quick summary
2. For each screen needing data:
   • Check "Available Endpoints" section
   • If gaps exist, reference "Critical Gaps" section
   • Communicate blocker status to backend

For Product Manager:

1. Review "Detailed Breakdown by UI Screen" section above
2. Readiness % shows which screens are ready for FE work
3. Effort estimates help with release planning

---

📞 Questions / Follow-ups

Q: Can we use mock data on FE while waiting for gaps?
A: No — requirement is for real backend data only. Gaps must be closed before FE integration.

Q: Which gap is easiest to complete first?
A: Gap #1 (sortBy=publishedAt) — adds 1 parameter to existing search endpoint, ~1 day.

Q: Which gap has the most impact?
A: Gap #2 (market-snapshot) — powers entire home dashboard, enables real-time trading feel.

Q: Can gaps #8 and #9 be skipped?
A: Yes — Gap #8 (ward-level heatmap) is nice-to-have; Gap #9 (real-time) is polish. Gaps #1–7 are blocking.

---

Audit Date: 2026-04-21
Repository: goodgo-platform-ai
Scope: 70+ endpoints across 12 modules
Status: Ready for planning | No mock data allowed
Next Step: TechLead prioritization of gaps 1–7 for sprint planning