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)
```typescript
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
```json
{
  "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
```json
{
  "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
```json
{
  "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)