# Time-to-First-Property Performance Optimization

## Problem

Initial page load takes 5+ seconds before the first property appears on screen, even when the Redis GeoJSON cache is warm. The target is sub-500ms time-to-first-property.

## Measured Baseline (2026-02-22)

10,000 RENT listings, streaming endpoint via port-forward (no ingress overhead):

| Metric | Cold (DB) | Warm (Cache) |
|--------|-----------|--------------|
| Time to first property | 877ms | 334ms |
| Total stream time | 13,411ms | 2,060ms |
| Throughput | 745 feat/s | 4,854 feat/s |

Real-world user experience adds: Traefik ingress + TLS (~50-100ms), frontend auth waterfall (~100-300ms), POI fetch blocking stream start (~200-500ms), and browser NDJSON parsing + rendering. Total: **5+ seconds**.

## Root Causes

### 1. CPU Throttling (High Impact)

The API pods have no explicit resource declarations. The namespace `LimitRange` (created 2026-02-21) silently injects defaults:

- **CPU limit: 500m (0.5 cores)**
- Memory limit: 1Gi

Measured throttling during a single streaming request:

| Path | Throttle events | CPU time stolen |
|------|----------------|-----------------|
| Cold (DB) | +12 | +240ms |
| Warm (cache) | +10 | +462ms |

Cgroup proof: `cpu.max = 50000/100000`, `nr_throttled` increases by 10-12 per request.

Current pod usage at idle is only 3m CPU / 134-159Mi memory, so the limit only bites during streaming bursts when the pod needs to serialize thousands of GeoJSON features.

### 2. Frontend Waterfall (Medium Impact)

The request chain is sequential:

```
Page load -> Auth check -> user state -> POI fetch (blocks) -> loadListings()
```

`loadListings()` reads `userPOIs.length` to set `includePoiDistances=true`, so it cannot fire until the POI fetch resolves. When POI distances are requested, the Redis cache is bypassed entirely, forcing a DB path every time.

### 3. Pre-Stream Server Work (Medium Impact)

Before the first byte is sent, `stream_listing_geojson()` synchronously:

1. Fetches disliked/liked IDs from DB (`decision_service.get_disliked_ids`)
2. Checks Redis cache count
3. If POIs enabled: builds full POI distances lookup table

Steps 1 and 3 are blocking DB queries that delay the metadata message.

### 4. Batch Size (Low Impact)

First batch requires 50 features to accumulate before yielding. At 500m CPU, building 50 GeoJSON features from cache (Redis LRANGE + JSON parse + re-serialize) takes measurable time.

## Design

### Change 1: Set Explicit API Pod Resources

Add explicit resource requests/limits to the `realestate-crawler-api` deployment, overriding the LimitRange defaults.

Proposed values:
- **Requests**: 50m CPU, 128Mi memory
- **Limits**: 2000m CPU, 1Gi memory

This gives the pod 4x the current CPU headroom during streaming bursts while keeping requests modest for scheduling. The celery-beat pod should also get explicit resources since it only needs minimal CPU.

Implementation: K8s deployment manifest stored in `k8s/api-deployment.yaml` and applied via kubectl.

### Change 2: Decouple POI Distances from Listing Stream

Split POI distance fetching into a separate request so the listing stream can fire immediately and hit the cache.

- `loadListings()` always sends `includePoiDistances=false`
- New endpoint `GET /api/listing_poi_distances?listing_type=RENT` returns `{<listing_id>: [distances...]}` for the user's configured POIs
- Frontend fetches POI distances in parallel, merges into existing features when both resolve
- Redis cache is no longer bypassed when POIs are configured

Trade-off: POI-based distance filters won't apply until the POI distances request completes (~200-300ms after first property renders). Acceptable since the user sees data immediately.

### Change 3: Adaptive First Batch Size

Send a small primer batch (5 features) immediately, then switch to normal batch size (50) for throughput.

Backend change in `_stream_from_cache()` and `_stream_from_db()`:
- First yield: after 5 features
- Subsequent yields: after `batch_size` features

Expected improvement: first property rendered ~10x faster on the server side.

### Change 4: Defer Decision ID Fetch

Move the decision ID lookup (disliked/liked sets) out of the blocking pre-stream path:

- Send `metadata` message immediately
- Fetch decision IDs concurrently with the first (small) batch
- Apply decision filtering starting from the second batch
- The first 5 features may include a disliked listing, but client-side filtering in `processedListingData` already handles this

### Change 5: Eliminate Frontend POI Waterfall

Current: `useEffect(user) -> fetchPOIs() -> loadListings()`

Proposed: Fire both in parallel on user auth:
```
useEffect(user) -> fetchPOIs()          (async, no blocking)
                -> loadListings()        (fires immediately)
```

POI distances arrive separately (Change 2), so the stream doesn't need to wait.

### Change 6: Server-Timing Headers

Add `Server-Timing` headers to the streaming response for ongoing observability:

```
Server-Timing: auth;dur=12, decisions;dur=85, cache_check;dur=3, first_batch;dur=42
```

Visible in browser DevTools Network tab without any frontend code changes.

## Expected Impact

| Change | TTFP improvement | Effort |
|--------|-----------------|--------|
| CPU limit bump (500m -> 2000m) | ~200-400ms (eliminates throttling) | Low |
| Eliminate POI waterfall | ~200-500ms (parallel fetch) | Medium |
| Adaptive first batch (50 -> 5) | ~150-300ms (fewer features to build) | Low |
| Defer decision IDs | ~100-200ms (no pre-stream DB query) | Low |
| Decouple POI distances endpoint | Enables cache hits with POIs | Medium |
| Server-Timing headers | Observability, no direct improvement | Low |

Conservative estimate: **warm cache TTFP drops from 334ms to ~100-150ms server-side**, and real-world user experience drops from **5s+ to under 1s**.

## What Does NOT Change

- NDJSON protocol (same 3 message types: metadata, batch, complete)
- Redis cache structure, TTL, or key format
- Database schema or repository layer
- Client-side decision filtering in `processedListingData`
- Total data delivered (all features still streamed)

## Files Modified

- `k8s/api-deployment.yaml` (new) - explicit API pod resources
- `api/app.py` - adaptive batch, deferred decisions, Server-Timing, POI distances endpoint
- `services/listing_cache.py` - no changes
- `frontend/src/App.tsx` - parallel fetch, POI merge
- `frontend/src/services/streamingService.ts` - remove POI coupling
- `frontend/src/services/listingService.ts` - new POI distances fetch function