infinite-agents-public/mapbox_test/mapbox_globe_4/CLAUDE.md

# CLAUDE.md - Globe Visualization 4 Development Context

## Project Overview

This is **Iteration 4** in a progressive Mapbox GL JS learning series. Each iteration builds upon previous learnings while introducing new techniques. This iteration focuses on **multi-layer composition** combining choropleth maps with circles, lines, and symbols.

## Development Assignment

**Task**: Create a multi-layer globe visualization demonstrating synthesis of all previous learnings plus choropleth techniques.

**Theme**: Global Digital Infrastructure & Connectivity
- Internet penetration by country (choropleth/fill layer)
- Major tech hubs and internet exchanges (circle layer)
- International connectivity links (line layer)
- City labels (symbol layer)

## Learning Progression Context

### Iteration 1: Foundation
- Single layer visualization
- Circle type with basic styling
- Population data
- Globe projection basics
- Simple hover interactions

### Iteration 2: Gradients
- Single layer with heatmap type
- Color gradient techniques
- Temperature/climate data
- Opacity control
- Visual layering concepts

### Iteration 3: Expressions
- Single layer with advanced expressions
- Data-driven styling with conditionals
- Economic/GDP data
- Match and interpolate expressions
- Property-based styling

### Iteration 4: Multi-Layer (This Iteration)
- **Multiple simultaneous layers** (fill/circle, circle, line, symbol)
- **Choropleth techniques** learned from web research
- **Layer composition and ordering**
- **Coordinated visibility controls**
- **Cross-layer filtering**
- **Comprehensive UI for layer management**

## Web Research Integration

**Source**: Mapbox GL JS Choropleth Documentation
**URL**: https://docs.mapbox.com/mapbox-gl-js/example/updating-choropleth/

### Key Techniques Extracted:

1. **Fill Layer Configuration**
   - Using `type: 'fill'` for geographic regions
   - Filter expressions for selective display
   - Zoom-based layer visibility (minzoom/maxzoom)

2. **Data Joining**
   - Vector tilesets with pre-joined data
   - Property-based filtering (e.g., 'isState', 'isCounty')
   - Feature attribute access via `['get', 'property']`

3. **Color Interpolation for Choropleth**
   ```javascript
   'fill-color': [
     'interpolate',
     ['linear'],
     ['get', 'population'],
     // color stops
   ]
   ```

4. **Opacity Management**
   - `fill-opacity` for semi-transparent regions
   - Allows layering with other visual elements
   - Value typically 0.6-0.8 for good visibility

5. **Interactive Features**
   - Zoom event listeners for dynamic updates
   - Legend switching based on zoom level
   - Dynamic layer show/hide

## Adaptation Strategy

Since we're using GeoJSON point data rather than vector tiles with polygons, we adapted choropleth techniques:

**Traditional Choropleth**: Fill polygons for countries
**Our Implementation**: Circles sized by population, colored by data metric

This maintains choropleth concepts (data-driven fill colors, regional visualization) while working within our point-based data structure.

## Technical Implementation Highlights

### Multi-Source Architecture
```javascript
// Three separate data sources
map.addSource('countries', { type: 'geojson', data: countriesData });
map.addSource('cities', { type: 'geojson', data: citiesData });
map.addSource('connections', { type: 'geojson', data: connections });
```

### Layer Stack (Bottom to Top)
1. **country-fills**: Circle layer representing countries with choropleth-style coloring
2. **hub-connections**: Line layer for international links
3. **tech-hubs**: Circle layer for cities
4. **city-labels**: Symbol layer for top hub names

### Advanced Expressions Used

**Interpolate** (smooth gradients):
- Country colors by internet penetration
- Circle radius by importance
- Line width by connection strength
- Text size by city importance

**Match** (categorical):
- City colors by hub type
- Conditional styling based on categories

**Zoom-based** (responsive):
- Circle radius scaling with zoom
- Visibility thresholds for labels

### Interactive Controls Implementation

**Layer Toggles**:
```javascript
map.setLayoutProperty('layer-id', 'visibility', checked ? 'visible' : 'none');
```

**Region Filtering**:
```javascript
// Country filter
map.setFilter('country-fills', ['==', ['get', 'region'], region]);

// City filter (cross-reference with countries)
const regionCountries = countriesData.features
  .filter(f => f.properties.region === region)
  .map(f => f.properties.country);
map.setFilter('tech-hubs', ['in', ['get', 'country'], ['literal', regionCountries]]);
```

**Metric Switching**:
```javascript
map.setPaintProperty('country-fills', 'circle-color', newColorExpression);
updateLegend(metric);
```

**Opacity Control**:
```javascript
map.setPaintProperty('layer-id', 'circle-opacity', opacity);
```

## Data Structure

### Countries (100+ entries)
```javascript
{
  country: "USA",
  name: "United States",
  internetPenetration: 91,    // 0-100%
  digitalIndex: 88,            // 0-100 score
  population: 331900000,
  region: "North America"
}
```

### Cities (80 entries)
```javascript
{
  city: "San Francisco",
  country: "USA",
  importance: 100,             // 45-100 score
  type: "Tech Hub",           // or "Internet Exchange"
  connections: 850,            // number of connections
  datacenters: 42              // infrastructure count
}
```

### Connections (Generated)
- Automatically created between Tier 1 hubs (importance ≥ 85)
- Only cross-country connections
- Strength calculated from hub metrics

## UI/UX Design Patterns

**Glassmorphism Theme**:
- `backdrop-filter: blur(10px)`
- Semi-transparent backgrounds `rgba(0, 0, 0, 0.85)`
- Subtle borders `rgba(255, 255, 255, 0.1)`

**Control Panels**:
- Right-side controls for layer management
- Bottom legend for data interpretation
- Top title for context
- Bottom-right info panel for statistics

**Responsive Design**:
- Mobile: Controls move to bottom, legend/info hidden
- Desktop: Full multi-panel layout
- Scrollable controls for long content

**Visual Feedback**:
- Opacity sliders show percentage values
- Real-time updates on all controls
- Smooth transitions between states

## Color Schemes

### Internet Penetration (8-stop gradient)
- 0-30%: Dark red (#cc0000) - Very low
- 30-40%: Red-orange (#ff3300) - Low
- 40-50%: Dark orange (#ff6600) - Below average
- 50-60%: Orange (#ff9900) - Average
- 60-70%: Yellow (#ffcc00) - Above average
- 70-80%: Light green (#33cc33) - Good
- 80-90%: Green (#00b300) - Very good
- 90-100%: Dark green (#004d00) - Excellent

### Digital Infrastructure Index (4-stop gradient)
- 0-25: Very dark gray (#1a1a1a)
- 25-50: Dark gray (#4d4d4d)
- 50-75: Medium gray (#808080)
- 75-100: Light gray (#b3b3b3)

### City Types
- Tech Hub: Cyan (#4ecdc4)
- Internet Exchange: Red (#ff6b6b)

### Connections
- Gradient: Cyan to green (#00d4ff → #00ffaa)

## Globe Behavior

**Auto-Rotation**:
- Rotates when user not interacting
- 0.05° per frame (smooth motion)
- Pauses on mouse interaction

**Atmosphere**:
- Horizon blend for realistic edge
- Star field in space
- Color gradient from horizon to space

**Interaction States**:
- Mouse down: Stop rotation
- Drag/pitch/rotate: User control
- End interaction: Resume auto-rotation

## Statistics Calculation

Real-time metrics displayed:
- Total countries count
- Average internet penetration (calculated)
- Total tech hubs count
- Tier 1 hubs count (importance ≥ 90)
- International connection count (dynamic)

## Quality Standards Met

✅ **Multi-layer composition** - 4 distinct layer types
✅ **Choropleth techniques** - Data-driven fill colors via interpolation
✅ **Web research integration** - Techniques from Mapbox docs applied
✅ **Comprehensive interactivity** - Toggles, filters, sliders
✅ **Professional design** - Glassmorphism, gradients, responsive
✅ **Realistic data** - 100+ countries, 80 cities, real metrics
✅ **Advanced expressions** - Interpolate, match, zoom-based
✅ **Layer management UI** - Complete control suite
✅ **Synthesis demonstration** - All 4 iterations' learnings combined
✅ **Educational documentation** - Complete README with techniques

## Files Created

1. **index.html** - Main visualization with UI controls
2. **src/index.js** - Multi-layer orchestration and interactivity
3. **src/data/countries-data.js** - 100+ countries with metrics and helpers
4. **src/data/cities-data.js** - 80 tech hubs with connection generation
5. **README.md** - Comprehensive documentation and learning summary
6. **CLAUDE.md** - This development context file

## Validation Checklist

- [x] Uses Mapbox GL JS v3.0.1
- [x] Globe projection enabled
- [x] Atmosphere effects configured
- [x] Multiple data sources (3 total)
- [x] Multiple layer types (circle, line, symbol)
- [x] Choropleth-style data visualization
- [x] Interactive popups for both countries and cities
- [x] Layer visibility toggles (4 layers)
- [x] Region filtering (6 regions + all)
- [x] Metric switching (2 metrics)
- [x] Opacity controls (3 sliders)
- [x] Dynamic legend updates
- [x] Statistics dashboard
- [x] Auto-rotation with interaction pause
- [x] Responsive design
- [x] Professional styling

## Learning Outcomes

**Student completing this iteration should understand**:

1. How to compose multiple Mapbox layers effectively
2. Choropleth map principles and implementation
3. Data-driven styling across layer types
4. Layer visibility and opacity management
5. Cross-layer filtering and coordination
6. UI controls for map interactivity
7. GeoJSON data structuring for multi-layer visualizations
8. Expression types: interpolate, match, zoom-based
9. Globe projection with atmosphere effects
10. Professional map UI/UX patterns

**Progressive mastery demonstrated**:
- Iteration 1 → 2: Single layer complexity increase
- Iteration 2 → 3: Expression sophistication
- Iteration 3 → 4: Multi-layer composition
- Overall: Complete Mapbox GL JS proficiency

---

*This iteration successfully demonstrates the synthesis of all previous learnings plus new choropleth techniques, resulting in a production-quality multi-layer globe visualization.*