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

# CLAUDE.md - Globe Visualization 9

## Project Guidelines for Claude Code

### Local Development

#### Starting a Local Server
```bash
# From the mapbox_globe_9 directory:

# Python 3 (recommended)
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000

# Node.js
npx http-server -p 8000
```

Access at: `http://localhost:8000`

### Project Structure

```
mapbox_globe_9/
├── index.html              # Main HTML with UI overlays
├── src/
│   ├── index.js           # Mapbox initialization & choropleth logic
│   └── data/
│       └── data.js        # Educational funding GeoJSON data
├── README.md              # Full documentation
└── CLAUDE.md              # This file
```

### Code Organization Patterns

#### Mapbox Token
- Uses public token: `pk.eyJ1IjoibGludXhpc2Nvb2wiLCJhIjoiY2w3ajM1MnliMDV4NDNvb2J5c3V5dzRxZyJ9.wJukH5hVSiO74GM_VSJR3Q`
- Configured in `src/index.js`

#### Data Structure
**Country Educational Data** (`educationalFundingData`):
```javascript
{
    type: "FeatureCollection",
    features: [{
        type: "Feature",
        geometry: { type: "Point", coordinates: [lng, lat] },
        properties: {
            country: "Country Name",
            iso: "ISO",
            spendingPerCapita: 2850,
            budgetPercent: 5.4,
            avgTeacherSalary: 62000,
            teacherStudentRatio: 16,
            educationIndex: 0.92,
            trainingCenters: 15
        }
    }]
}
```

**Training Centers** (`trainingCentersData`):
- Generated dynamically from country data
- Distributed around country coordinates with random offset

#### Key Mapbox Techniques

**Choropleth Color Interpolation**:
```javascript
'circle-color': [
    'interpolate',
    ['linear'],
    ['get', 'spendingPerCapita'],
    0, '#440154',      // Purple
    500, '#31688e',    // Blue
    1000, '#35b779',   // Green
    2000, '#fde724'    // Yellow
]
```

**Size Scaling**:
```javascript
'circle-radius': [
    'interpolate',
    ['linear'],
    ['get', 'spendingPerCapita'],
    0, 3,
    5000, 25
]
```

**Zoom-Based Opacity**:
```javascript
'text-opacity': [
    'interpolate',
    ['linear'],
    ['zoom'],
    1.5, 0,
    2.5, 0.7
]
```

### Mapbox Layers

1. **education-circles**: Main choropleth layer with size + color encoding
2. **training-centers-layer**: Red point markers for training facilities
3. **training-centers-halo**: Glow effect around centers
4. **country-labels**: Country name labels (zoom-dependent)

### Data Processing Pipeline

1. **Load GeoJSON data** from `data.js`
2. **Process features** to calculate derived metrics:
   - Funding gap classification
   - Efficiency scores
   - Salary gap tiers
3. **Sort for rankings** (top countries by spending)
4. **Calculate statistics** (avg, max, min)
5. **Generate training centers** from country data
6. **Add to map** as GeoJSON sources
7. **Apply data-driven styling** with expressions

### Interactive Features

**Hover Events**:
- Countries: Show comprehensive funding metrics popup
- Training Centers: Show facility details popup

**Click Events**:
- Countries: Fly to location with camera animation

**Toggle Controls**:
- Training centers visibility
- Country labels visibility

**Leaderboard**:
- Top 10 countries by spending
- Click to navigate

### Globe Configuration

```javascript
map.setFog({
    color: 'rgba(10, 15, 35, 0.9)',
    'high-color': 'rgba(25, 50, 100, 0.5)',
    'horizon-blend': 0.3,
    'space-color': '#000814',
    'star-intensity': 0.7
});
```

### Animation

**Auto-Rotation**:
- Smooth continuous rotation when user not interacting
- Pauses on mouse down/drag/pitch/rotate
- Resumes on interaction end

### Styling Guidelines

**Color Palette**:
- Background: `#000814` (deep blue-black)
- Primary accent: `#fde724` (bright yellow)
- Secondary accent: `#35b779` (green)
- Training centers: `#ff6b6b` (coral red)
- Choropleth: Viridis scale (purple → blue → green → yellow)

**Typography**:
- Font family: 'Inter' (Google Fonts)
- Weights: 300, 400, 600, 700

**UI Patterns**:
- Glassmorphism: `rgba(0, 8, 20, 0.92)` + `backdrop-filter: blur(10px)`
- Border accents: `rgba(253, 231, 36, 0.2)`
- Shadows: `0 8px 32px rgba(0, 0, 0, 0.5)`

### Responsive Design

**Mobile Breakpoint**: `@media (max-width: 768px)`
- Hides legend and leaderboard
- Repositions controls to bottom
- Reduces font sizes
- Adjusts padding

### Performance Considerations

- Single-pass data processing on load
- Efficient GeoJSON structure
- Optimized layer ordering
- Smooth animations with requestAnimationFrame
- Minimal DOM manipulation

### Browser Console Logging

On successful load, logs:
```
Globe loaded successfully!
Total countries: [count]
Total training centers: [count]
Average spending: $[amount]
Top 5 countries by spending: [list]
```

### Common Tasks

**Add a New Country**:
1. Add feature to `educationalFundingData.features` in `data.js`
2. Include all required properties
3. Training centers will auto-generate

**Modify Color Scale**:
1. Edit `circle-color` interpolate expression in `src/index.js`
2. Adjust color stops and values
3. Update legend in `index.html`

**Change Globe Style**:
1. Modify `style` parameter in map initialization
2. Options: `dark-v11`, `light-v11`, `satellite-v9`, `streets-v12`

**Adjust Rotation Speed**:
1. Change `rotationSpeed` variable or modify timestamp divisor in `rotateCamera()`
2. Current: `(timestamp / 200) % 360`

### Web Learning Applied

This iteration implements **choropleth data visualization techniques** learned from:
- **Mapbox GL JS Documentation**: [Update a choropleth layer by zoom level](https://docs.mapbox.com/mapbox-gl-js/example/updating-choropleth/)

**Key learnings applied**:
1. Interpolate expressions for continuous color scaling
2. Linear interpolation for smooth gradients
3. Data-driven property access with `['get', 'property']`
4. Multi-stop color ramps for choropleth maps
5. Layer-based data visualization architecture

### Quality Standards

**Code**:
- Clear variable naming
- Commented sections
- Consistent formatting
- Error-free execution

**Visual**:
- Professional color scheme
- Clear data hierarchy
- Smooth animations
- Readable typography

**Data**:
- Realistic values
- Complete coverage (180+ countries)
- Proper coordinate format
- Meaningful correlations

### Future Enhancement Ideas

1. Add time-series slider for historical data
2. Implement 3D extrusions for total budget
3. Add filter controls for regions/income levels
4. Include comparison mode (side-by-side countries)
5. Real-time data integration from APIs
6. Export functionality for charts/data
7. Accessibility improvements (ARIA labels, keyboard nav)

---

This iteration demonstrates **intermediate-to-advanced Mapbox techniques** with a focus on choropleth data visualization, multi-layer composition, and rich interactivity on a 3D globe projection.