goodgo-platform/docs/explorations/API_EXPLORATION_SUMMARY.md

# GoodGo Platform API Exploration Summary

## Executive Summary

Complete audit of GoodGo Platform monorepo API endpoints and data structures. All field names, types, and response formats documented for UI component mapping.

**Generated**: April 21, 2026  
**Scope**: `apps/api/src/modules/{analytics,listings,agents,search}` + `prisma/schema.prisma`

---

## 📋 Key Findings

### Analytics Module (✅ Fully Explored)

**Endpoints Count**: 15+ key endpoints
**Architecture**: CQRS with query handlers → DTOs
**Caching**: 30min - 24hr TTL across endpoints
**Auth**: JWT required (except public endpoints)

**Core Features**:
1. **Market Data** (snapshot, trends, heatmap, district stats)
   - Real-time aggregation from active listings
   - Price change metrics (1d, 7d, 30d)
   - Per-district inventory & absorption data

2. **Valuations (AVM)** (v1 & v2 models)
   - GET by property ID or coordinates
   - POST manual input with extended features
   - Batch operations (up to 50 properties)
   - Historical tracking & comparisons
   - Confidence scoring with explanations

3. **Trending Areas**
   - Scoring algorithm: `inquiries×0.6 + views×0.3 + listings×0.1`
   - Time-window configurable (default 30 days)
   - District/ward level aggregation

4. **Neighborhood Scores**
   - 6 dimensional scoring (education, healthcare, transport, shopping, greenery, safety)
   - POI counting (schools, hospitals, transit, malls, parks, restaurants)
   - 0-100 scale with aggregation

5. **Nearby POIs** (Public)
   - Geographic search within radius
   - 6 main categories with type mapping
   - Distance calculation using PostGIS

### Listings Module (✅ Fully Explored)

**Entity Count**: 2 main aggregates (Listing + Property)
**Field Count**: ~45 total fields across entities
**Key Features**:
- Listing status state machine (DRAFT → PENDING_REVIEW → ACTIVE → SOLD/RENTED)
- AI price estimates with confidence scores
- Moderation workflow with scoring
- Engagement metrics (views, saves, inquiries)
- Featured promotion with expiry tracking
- Rent pricing support
- Commission tracking

**Property Fields**:
- Core: type, title, description, location (PostGIS), area
- Rooms: bedrooms, bathrooms, floors, floor level
- Infrastructure: direction, year built, legal status, metro distance
- Amenities: JSON-based (flexible schema)
- Enhanced: furnishing, condition, parking, maintenance fee, pet-friendly, view types, suitability tags

### Agents Module (✅ Explored)

**Key Fields**:
- Profile: userId, licenseNumber, agency, bio
- Credentials: isVerified (boolean)
- Performance: qualityScore (0-100), totalDeals, responseTimeAvg
- Coverage: serviceAreas (array of district IDs)

**Performance Metrics**:
- Quality score as composite metric
- Response time in seconds (need conversion for display)
- Deal count as credibility indicator

### Search Module (✅ Explored)

**Architecture**: Meilisearch (typesense-compatible backend)
**Index Fields**: 31 fields per document
**Key Features**:
- Full-text + filtering + geo-search
- Featured listing flag
- Engagement metrics copied to index
- Amenities as string array

**Supported Filters**:
- propertyType, transactionType
- Price range, area range
- Bedrooms (>= operator)
- District, city
- Featured status

### Prisma Schema (✅ Full Review)

**Key Models**:
- User (role-based: BUYER, SELLER, AGENT, DEVELOPER, PARK_OPERATOR, ADMIN)
- Property (core real estate entity)
- Listing (marketplace listing wrapper)
- Agent (performance tracking)
- Valuation (AVM history)
- MarketIndex (market analytics cache)
- Transaction, Inquiry, Lead, Payment, Order, Escrow models

**Enums**:
- PropertyType: 6 values (APARTMENT, VILLA, TOWNHOUSE, LAND, OFFICE, SHOPHOUSE)
- TransactionType: 2 values (SALE, RENT)
- ListingStatus: 8 values (DRAFT...REJECTED)
- Direction: 8 compass values
- Furnishing: 3 levels
- PropertyCondition: 4 conditions

---

## 🎯 API Field Reference by Use Case

### For Property Card Display
```
Price           → listing.priceVND (format as VND)
Type            → listing.transactionType
Status          → listing.status
Area            → property.areaM2
Beds/Baths      → property.bedrooms, property.bathrooms
Location        → property.district, property.ward, property.city
Agent           → listing.agent.user.fullName, listing.agent.qualityScore
Engagement      → listing.viewCount, listing.saveCount, listing.inquiryCount
Featured        → listing.featuredUntil (if > now, show badge)
```

### For Valuation Display
```
Estimate        → ValuationDto.estimatedPrice (string, format as VND)
Confidence      → ValuationDto.confidence (0.0-1.0, convert to %)
Price/m²        → ValuationDto.pricePerM2
Model Version   → ValuationDto.modelVersion (v1|v2|ensemble)
Comparables     → ValuationDto.comparables[] with distance & price
```

### For Market Analysis
```
Market Snapshot → GET /analytics/market-snapshot
├─ activeCount, avgPrice, medianPrice, avgPricePerM2
├─ daysOnMarket, newListings24h
└─ priceChangePct { d1, d7, d30 }

Price Trend     → GET /analytics/price-trend
├─ trend[] { period, medianPrice, avgPriceM2, totalListings }

Heatmap         → GET /analytics/heatmap
├─ dataPoints[] { district, avgPriceM2, totalListings, medianPrice }

District Stats  → GET /analytics/district-stats
├─ districts[] { district, medianPrice, avgPriceM2, totalListings, daysOnMarket, yoyChange }

Trending Areas  → GET /analytics/trending-areas
├─ areas[] { name, listings, inquiries, views, priceChangePct, scoreRank }
```

### For Location Intelligence
```
Neighborhood Score  → GET /analytics/neighborhoods/:district/score
├─ educationScore, healthcareScore, transportScore, shoppingScore
├─ greeneryScore, safetyScore, totalScore (all 0-100)
├─ poiCounts { schools, hospitals, transit, shopping, parks, restaurants }

Nearby POIs         → GET /analytics/pois/nearby
├─ pois[] { name, type, category, lat, lng, distance, address }
```

---

## 🔌 Quick Integration Checklist

### Before Mapping UI Components:

- [ ] **Understand Caching**: Most analytics endpoints have 30min-24hr cache
  - Include `cachedAt` and `nextRefreshAt` in UI
  - Plan refresh UX accordingly

- [ ] **Price Handling**: All prices in VND
  - Received as strings (precision preservation)
  - Must format for display (thousand separators, currency symbol)
  - BigInt in DB, may overflow JS numbers

- [ ] **Confidence Scores**: Different scales
  - Valuation confidence: 0.0-1.0 (multiply by 100 for %)
  - Moderation score: 0-100 (direct use)
  - Quality score (agent): 0-100 (convert 0-5 stars)

- [ ] **Enum Handling**: Map enum values to display labels
  - PropertyType: 6 values (need translations)
  - ListingStatus: 8 values (map to colors/icons)
  - TransactionType: 2 values (SALE vs RENT)

- [ ] **Coordinates**: Use `property.location` (PostGIS geometry)
  - Accessible as `lat`, `lng` in API responses
  - Distance calculations use PostGIS functions

- [ ] **Rate Limits**: Per endpoint
  - Valuation POST: 10 req/min/user
  - Search: 200 req/min/user
  - Implement backoff/retry logic

- [ ] **Null Handling**: Many fields optional
  - `bedrooms`/`bathrooms` can be null (studio)
  - `agentId` can be null (direct seller)
  - Valuation `confidence` may have `null` comparables
  - Handle gracefully in UI

- [ ] **Pagination**: Search results include
  - `page`, `perPage`, `totalPages`, `totalFound`
  - Implement lazy loading or infinite scroll

---

## 📚 Documentation Files Generated

1. **API_ENDPOINTS_REFERENCE.md** (~800 lines)
   - Complete endpoint documentation
   - Request/response schemas in TypeScript
   - Query parameters & caching info
   - Prisma model definitions

2. **UI_MAPPING_QUICK_GUIDE.md** (~400 lines)
   - Visual mockups with field mappings
   - Pre-formatted example layouts
   - Common conversions (price, confidence, distance)
   - UI integration patterns

3. **API_EXPLORATION_SUMMARY.md** (this file)
   - Executive overview
   - Key findings by module
   - Integration checklist
   - References

---

## 🔗 Source Files Analyzed

### Analytics Module
- `controllers/analytics.controller.ts` → 15 endpoints
- `domain/services/avm-service.ts` → AVM interface & types
- `application/queries/{...}/handler.ts` → 10+ query handlers with DTO definitions
- `presentation/dto/{...}.ts` → Request/response types

### Listings Module
- `domain/entities/listing.entity.ts` → Listing aggregate (status machine, events)
- `domain/entities/property.entity.ts` → Property aggregate (updateable fields)

### Agents Module
- `domain/entities/agent.entity.ts` → Agent profile & performance metrics

### Search Module
- `domain/repositories/search.repository.ts` → SearchResult interface & 31 indexed fields

### Database
- `prisma/schema.prisma` → 30+ models with enums & indexes

---

## ✅ Data Quality Notes

**Strengths**:
- Strong type safety (NestJS + Prisma)
- Comprehensive DTOs for API contracts
- Clear status machine for listings
- Well-indexed database schema
- Separation of concerns (domain → application → presentation)

**Considerations**:
- JSON fields in Property (amenities, nearbyPOIs) — verify schema client-side
- Price precision — use strings, not numbers, for financial data
- Confidence scores use different scales — easy to mix up
- Service areas stored as JSON array of district IDs — need mapping table
- Valuation comparables may be null if insufficient data

---

## 🎓 Next Steps

1. **API Client Generation**
   - Use Swagger/OpenAPI docs from NestJS controllers
   - Generate TypeScript client with `openapi-generator`

2. **Component Development**
   - Start with property card components
   - Wire market snapshot widget
   - Build valuation display components

3. **Data Transformation Layer**
   - Create utility functions for price formatting
   - Build confidence score converters
   - Implement district ID → name mappings

4. **Testing**
   - Mock response data from this reference
   - Test edge cases (null values, precision, formatting)
   - Verify caching behavior

---

## 📞 Key Contacts & Resources

**API Documentation**: Swagger/OpenAPI available at `/api/docs` (NestJS Swagger module)

**Prisma Models**: Comprehensive schema with relationships in `prisma/schema.prisma`

**Code Examples**: Query handlers in `apps/api/src/modules/analytics/application/queries/`

---

**Document Version**: 1.0  
**Last Updated**: April 21, 2026  
**Status**: Complete ✅

All information current as of repository scan on 2026-04-21.