> **git tag only — never published to PyPI.** The pip-install instructions below do not apply. See CHANGELOG.md (single source of truth); this build's code shipped in 0.10.54+.

# CorvinOS 0.10.52 — Phase 3.2 Complete Visualization

**Release Date:** 2026-07-20  
**Status:** ✅ Ready  
**Previous:** [0.10.51](CHANGELOG-0.10.51.md)

---

## 🎯 Phase 3.2 Complete: Tier 2/3 Visualization Layers

### What's New

**Full Multi-Tier Visualization Dashboard** with regional breakdown, city-level heatmaps, and 7-day trend analytics. Completes the geo-tracking feature from Phase 3.1.

#### Backend

- **Tier 2 API** — `/v1/stats/instances/country/{code}?tier=2`
  - Regional aggregation by state/province
  - 30-day retention window
  - Active 24h tracking per region

- **Tier 3 API** — `/v1/stats/heatmap?country=DE`
  - 10km grid-based clustering
  - City-level breakdown
  - 14-day retention (maximum privacy)

- **Trends API** — `/v1/stats/trends?country=DE&days=7`
  - Daily instance count aggregation
  - Configurable lookback (1-30 days)
  - Time-series ready for analytics

#### Frontend (Completely Redesigned)

- **Tab Navigation:** Tier 1 → Tier 3 + Trends
- **Tier 1 Map:** Interactive Leaflet with country markers (existing)
- **Tier 2 Regions:** Dropdown country selector + regional grid breakdown
- **Tier 3 Heatmap:** 600px Leaflet map + grid cell breakdown
- **Trends Chart:** Chart.js line chart with 7-day progression
- **KPI Cards:** Real-time stats (Total, Online, Retention)
- **Responsive:** Mobile-optimized grid layout

### Performance

- All queries < 100ms (10M+ rows)
- Indexes on country, region, city, created_at
- Aggregation optimized (GROUP BY efficiency)
- Chart rendering optimized (canvas-based)

### Testing

- 8 unit tests (geo_schema.py) — all passing
- E2E coverage: map rendering, tab switching, API fallback
- Mock fallback verified for all tiers

### Compliance

✅ GDPR/DSGVO maintained across all tiers:
- Grid rasterization (Tier 3: 100+ users per 10km cell)
- No IP storage (lookup result only)
- TTL-based auto-delete (30d Tier 2, 14d Tier 3)
- Audit logging of all operations

### Configuration

No new configuration required. Existing `DATABASE_URL` env var enables all features.

### Links

- GitHub: [CorvinOS v0.10.52](https://github.com/CorvinLabs/CorvinOS/releases/tag/v0.10.52)
- Dashboard: [corvin-labs.com/stats](https://corvin-labs.com/stats)

---

## 📊 Release Stats

- **Files Changed:** 2 (stats_geo.py + stats/index.html)
- **API Endpoints:** +3 (Tier 2/3/Trends)
- **UI Tabs:** 4 (Tier 1/2/3/Trends)
- **Breaking Changes:** 0

---

## 🚀 Installation

```bash
pip install --upgrade corvinos==0.10.52
```

