goodgo-platform/docs/explorations/API_DOCUMENTATION_INDEX.md

GoodGo Platform API Documentation Index

Complete reference suite for mapping UI components to real API data.

Generated: April 21, 2026 | Status: ✅ Complete

---

📚 Documentation Suite

1. API_ENDPOINTS_REFERENCE.md — The Complete Reference

Best for: Developers implementing API integrations
Length: ~800 lines
Contains:

• All 15+ API endpoints with full signatures
• Request parameters (query, body, path)
• Response schemas in TypeScript
• Caching behavior per endpoint
• Rate limits
• Auth requirements
• Prisma model definitions
• Enum values

When to use:

• "What fields does the valuation response have?"
• "What query parameters does the heatmap endpoint accept?"
• "What's the database schema for Property?"

2. UI_MAPPING_QUICK_GUIDE.md — Fast Integration Reference

Best for: Frontend developers building UI components
Length: ~400 lines
Contains:

• Visual mockups with field labels
• Pre-formatted UI examples (property card, market snapshot, etc.)
• Direct field mappings from API → UI display
• Format conversion functions (price, confidence, distance)
• Status color schemes
• Engagement metric displays

When to use:

• "How should I display the market snapshot widget?"
• "What data goes in this property card?"
• "How do I convert the confidence score to stars?"

3. API_EXPLORATION_SUMMARY.md — Executive Overview

Best for: Project leads, architects, QA teams
Length: ~300 lines
Contains:

• High-level findings by module
• Field count & complexity metrics
• Quick integration checklist
• Data quality notes
• Next steps & action items
• Source files analyzed

When to use:

• Project planning
• Sprint estimation
• Quality assurance review
• Team onboarding

---

🗺️ Module-by-Module Breakdown

Analytics Module

• 15+ Endpoints: Market data, valuations, scores, POIs
• Key Files: See API_ENDPOINTS_REFERENCE.md → Analytics Module
• UI Components to Build:
  • Market snapshot widget
  • Price trend chart
  • Heatmap display
  • District stats table
  • Trending areas carousel
  • Valuation card
  • Neighborhood score card
  • POI map

Quick Field Map:

Feature	Endpoint	Key Fields
Market Overview	GET /analytics/market-snapshot	activeCount, avgPrice, medianPrice, priceChangePct
Price History	GET /analytics/price-trend	trend[].{period, medianPrice, avgPriceM2}
Heatmap	GET /analytics/heatmap	dataPoints[].{district, avgPriceM2}
District Stats	GET /analytics/district-stats	districts[].{medianPrice, totalListings, yoyChange}
Hot Areas	GET /analytics/trending-areas	areas[].{listings, inquiries, views, scoreRank}
Property Value	GET/POST /analytics/valuation	estimatedPrice, confidence, comparables[]
Scores	GET /analytics/neighborhoods/:district/score	educationScore, totalScore, poiCounts
POIs	GET /analytics/pois/nearby	pois[].{name, type, distance}

Listings Module

• 2 Core Entities: Property (45 fields), Listing (25 fields)
• Key Files: See API_ENDPOINTS_REFERENCE.md → Listings Module
• UI Components:
  • Property card (search results)
  • Property detail page
  • Listing editor
  • Status badges

Quick Field Map:

Display	Source	Field Path
Price	Listing	listing.priceVND
Beds/Baths	Property	property.bedrooms, property.bathrooms
Area	Property	property.areaM2
Status	Listing	listing.status
Views	Listing	listing.viewCount
Agent	Listing	listing.agent.user.fullName
Address	Property	property.address, property.district

Agents Module

• Key Fields: Profile, credentials, performance metrics
• Key Files: See API_ENDPOINTS_REFERENCE.md → Agents Module
• UI Components:
  • Agent card
  • Agent profile page
  • Agent rating badge

Quick Field Map:

Display	Field	Type
Name	user.fullName	string
Rating	qualityScore	0-100 → convert to stars
License	licenseNumber	string (nullable)
Verified	isVerified	boolean
Service Areas	serviceAreas[]	array of district IDs
Response Time	responseTimeAvg	seconds → hours

Search Module

• 31 Indexed Fields: ListingDocument structure
• Key Files: See API_ENDPOINTS_REFERENCE.md → Search Module
• UI Components:
  • Search bar
  • Filter sidebar
  • Results list with pagination
  • Geo-search on map

Quick Field Map:

Filter	Field	Values
Type	propertyType	APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE
Transaction	transactionType	SALE, RENT
Price Range	priceVND	numeric range
Area Range	areaM2	numeric range
Bedrooms	bedrooms	>= operator
Location	district, city	equality match

---

🚀 Common Integration Patterns

Pattern 1: Display Property Card

1. Fetch from search index or detail endpoint
2. Map fields:
   - listing.priceVND → format as VND string
   - property.bedrooms → display or show "Studio" if null
   - listing.status → map to color & icon
   - listing.featuredUntil → show "Featured" badge if > now
3. Fetch agent data via listing.agent.id
4. Render with caching indicator

Pattern 2: Display Market Snapshot

1. GET /analytics/market-snapshot?city=HCMC
2. Map response fields to widgets
3. Show priceChangePct.d1/d7/d30 as trend indicators
4. Display nextRefreshAt for cache status
5. Poll again at nextRefreshAt or use web socket

Pattern 3: Implement Property Valuation

1. For existing property: GET /analytics/valuation?propertyId=X
2. For manual input: POST /analytics/valuation with form data
3. Display estimatedPrice (format as VND)
4. Convert confidence (0.0-1.0) to percentage
5. Show comparables[] in carousel
6. Cache for 24 hours

Pattern 4: Build District Search

1. Get districts from heatmap or district-stats endpoint
2. Render as map overlay or list
3. Allow filtering by avgPriceM2 (color intensity)
4. Show tooltip with medianPrice, totalListings, daysOnMarket
5. Update heatmap as user changes period

---

📊 Field Type Quick Reference

Prices (all VND)

• Type: string (in API DTOs) | BigInt (database)
• Display: Format with thousand separators + currency symbol
• Range: 0 to 9,223,372,036,854,775,807 (BigInt max)
• Example: "2500000000" → "2.5B" or "2,500,000,000 ₫"

Confidence Scores

• Valuation: 0.0-1.0 (multiply by 100 for %)
• Moderation: 0-100 (direct use)
• Quality (Agent): 0.0-100.0 (divide by 20 for stars: 0-5)

Distances

• Storage: meters (int/float)
• Display: < 1000m → show "XXXm", >= 1000m → show "X.Xkm"

Timestamps

• Format: ISO 8601 strings
• Cache: cachedAt, nextRefreshAt, calculatedAt, valuedAt, publishedAt
• Type: Most are Date in entities, string in API responses

Enums (Map to Display Labels)

PropertyType: {
  APARTMENT: "Căn hộ",
  VILLA: "Biệt thự",
  TOWNHOUSE: "Nhà phố",
  LAND: "Đất",
  OFFICE: "Văn phòng",
  SHOPHOUSE: "Nhà mặt phố"
}

ListingStatus: {
  DRAFT: "Nháp" (Gray),
  PENDING_REVIEW: "Chờ duyệt" (Yellow),
  ACTIVE: "Hoạt động" (Green),
  RESERVED: "Đặt" (Blue),
  SOLD: "Đã bán" (Dark),
  RENTED: "Đã thuê" (Dark),
  EXPIRED: "Hết hạn" (Orange),
  REJECTED: "Từ chối" (Red)
}

Direction: {
  NORTH: "Hướng Bắc",
  SOUTH: "Hướng Nam",
  EAST: "Hướng Đông",
  WEST: "Hướng Tây",
  NORTHEAST: "Hướng Đông Bắc",
  // ... etc
}

---

⚡ Performance Considerations

Caching Strategy

Market Snapshot:  30 minutes
Price Trend:      1 hour
Heatmap:          1 hour
District Stats:   6 hours
Trending Areas:   30 minutes
Valuation:        24 hours
Neighborhood:     24 hours

→ Check nextRefreshAt in response to avoid redundant calls

Rate Limits (Per User)

Valuation POST:   10 req/min
Search:           200 req/min
Analytics Queries: 100 req/min
Batch Operations: Limited to 50 items

→ Implement exponential backoff for 429 responses

Pagination

Search results include: page, perPage, totalPages, totalFound
Implement: Lazy loading or infinite scroll
Typical perPage: 20-50 listings

---

🔍 Field Validation Rules

Required Fields (Cannot be null)

• Listing: priceVND, transactionType, status, sellerId
• Property: propertyType, title, location, areaM2
• Agent: userId, isVerified

Nullable Fields (Default to null)

• property.bedrooms → null means studio/no specific bedroom count
• property.bathrooms → null if not specified
• listing.agentId → null means direct seller (no agent)
• listing.aiPriceEstimate → null if valuation not run
• Agent bio, licenseNumber → optional fields

String Length Limits

• Description fields: typically @db.Text (no limit imposed)
• Titles: reasonable limit (~200 chars implied)
• Enum values: fixed options (no arbitrary strings)

---

🧪 Testing & Mock Data

Mock Market Snapshot Response

{
  "city": "HCMC",
  "activeCount": 2345,
  "avgPrice": 2800000000,
  "medianPrice": 2500000000,
  "priceChangePct": {"d1": 2, "d7": 5, "d30": 12},
  "avgPricePerM2": 35000000,
  "daysOnMarket": 45,
  "newListings24h": 12,
  "cachedAt": "2026-04-21T10:30:00Z",
  "nextRefreshAt": "2026-04-21T11:00:00Z"
}

Mock Valuation Response

{
  "estimatedPrice": "2500000000",
  "confidence": 0.82,
  "pricePerM2": 33300000,
  "comparables": [
    {
      "propertyId": "prop-1",
      "address": "123 Nguyen Hue",
      "priceVND": "2340000000",
      "pricePerM2": 31200000,
      "distanceMeters": 450,
      "soldAt": "2026-04-15T00:00:00Z"
    }
  ],
  "modelVersion": "v2"
}

Mock Property Card Fields

{
  "listing": {
    "id": "list-1",
    "priceVND": "2500000000",
    "transactionType": "SALE",
    "status": "ACTIVE",
    "viewCount": 342,
    "saveCount": 28,
    "inquiryCount": 12,
    "featuredUntil": null,
    "publishedAt": "2026-04-15T08:30:00Z"
  },
  "property": {
    "id": "prop-1",
    "title": "Căn hộ sang trọng Quận 1",
    "propertyType": "APARTMENT",
    "areaM2": 75,
    "bedrooms": 2,
    "bathrooms": 1,
    "district": "Quận 1",
    "ward": "Phường Bến Nghé",
    "city": "Hồ Chí Minh"
  }
}

---

📖 Quick Start by Role

Frontend Developer

1. Start with UI_MAPPING_QUICK_GUIDE.md
2. Reference API_ENDPOINTS_REFERENCE.md for exact field names
3. Use mock data above for testing
4. Implement price formatting utilities

Backend/Full-Stack Developer

1. Read API_EXPLORATION_SUMMARY.md for overview
2. Use API_ENDPOINTS_REFERENCE.md as API contract
3. Reference Prisma models for database design
4. Review rate limits & caching strategy

QA / Test Automation

1. Start with API_EXPLORATION_SUMMARY.md
2. Review rate limits & error handling
3. Test edge cases (null values, precision, bounds)
4. Verify caching behavior using cachedAt/nextRefreshAt

Product / Project Lead

1. Read API_EXPLORATION_SUMMARY.md
2. Review integration checklist
3. Identify potential blockers
4. Estimate component complexity

---

📝 Document Update Protocol

These documents were generated by scanning source code on April 21, 2026.

To update:

1. Re-scan source modules if API changes
2. Update DTOs → API_ENDPOINTS_REFERENCE.md
3. Update Prisma schema → Prisma Schema section
4. Verify UI mappings → UI_MAPPING_QUICK_GUIDE.md
5. Update this index with changelog

Changelog:

• v1.0 (2026-04-21): Initial complete documentation

---

Last Updated: April 21, 2026
Status: ✅ Complete
Maintainer: Generated by API exploration task

For questions or updates, reference the source files in:

• apps/api/src/modules/ (API layer)
• prisma/schema.prisma (Database)