# 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

- [x] All 70+ endpoints enumerated by module
- [x] Route prefixes, methods, query params documented
- [x] Auth/guard requirements identified
- [x] Gaps mapped to UI screen requirements
- [x] Implementation roadmap created
- [x] Sprint-by-sprint effort estimates provided
- [x] No mock data recommended—all real backend data
- [x] 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