Claude Code で GitHub スターの地理分布を可視化するオープンソースソフトウェアをつくった

- **NEVER EVER use `git add -A` or `git add .`** - ALWAYS stage specific files only
- Follow conventional commit format (fix:, feat:, docs:, etc.)
- Keep commit messages to one line unless body is absolutely necessary
- For commits fixing bugs or adding features based on user reports add:
  `git commit --trailer "Reported-by:"`
  Where `name>` is the name of the user
- For commits related to a Github issue, add:
  `git commit --trailer "Github-Issue:#"`
- **NEVER mention co-authored-by or similar**
- **NEVER mention the tool used to create the commit message**
- **NEVER ever include *Generated with* or similar in commit messages**
- **NEVER ever include *Co-Authored-By* or similar in commit messages**

> i want to create a dead simple website that displays GitHub star gazers location geography map for any give github public repository. first let's discuss the detailed specification of the project thoroughly. Requirements for this application are as follows:

project name: GeoStarMap

usecases:
- user can input github repository url
- user can see the github user's location on the map
- user can input GitHub API token
- no authentication is required

requirements:
- Create as SPA without backend
- Use pnpm
- Use Vite
- Use React and shadcn library
- Use TypeScript
- Use ESLint
- Use minimum dependencies
- Use open street map API for geo coding with rate limiting of 1 req/sec
- Do not save user's API token
- Minimulism design
- Responsive for mobile device
- Format files with prettier
- No need for writing tests for this project
- Display progress on processing users
- Cache geolocation data

ultrathink

# GeoStarMap - GitHub Stars Geography Visualizer

## Project Overview
GeoStarMap is a minimalist single-page application that visualizes the geographic distribution of GitHub repository stargazers on an interactive world map.

## Core Requirements

### Technical Stack
- **Framework**: React with TypeScript
- **Build Tool**: Vite
- **Package Manager**: pnpm
- **UI Library**: shadcn/ui
- **Code Quality**: ESLint + Prettier
- **Map Library**: Leaflet with OpenStreetMap tiles
- **Architecture**: Client-side only SPA (no backend)

### Features
1. **Repository Input**: Accept GitHub repository URL (format: `https://github.com/owner/repo`)
2. **API Token Support**: Optional GitHub API token input (not persisted)
3. **Geographic Visualization**: Display stargazers' locations on an interactive map
4. **Progress Tracking**: Show real-time progress while processing users
5. **Caching**: Cache geocoded locations in localStorage to minimize API calls
6. **Responsive Design**: Mobile-first, works on all screen sizes

## Implementation Details

### GitHub API Integration
- **Endpoint**: `GET https://api.github.com/repos/{owner}/{repo}/stargazers`
- **Headers**: 
  - Accept: `application/vnd.github.v3+json`
  - Authorization: `Bearer {token}` (if provided)
- **Pagination**: Handle `Link` header for repos with many stars
- **Rate Limits**: 
  - Unauthenticated: 60 requests/hour
  - Authenticated: 5,000 requests/hour

### Geocoding Service
- **Service**: Nominatim (OpenStreetMap)
- **Endpoint**: `https://nominatim.openstreetmap.org/search`
- **Rate Limit**: 1 request per second (must be enforced client-side)
- **Query Format**: `?q={location}&format=json&limit=1`
- **User-Agent**: Required header with app name

### Caching Strategy
- **Storage**: localStorage
- **Key Format**: `geostarmap_cache_{normalized_location}`
- **Data Structure**:
  {
    lat: number;
    lng: number;
    displayName: string;
    timestamp: number;
  }
- **Expiry**: 30 days
- **Size Limit**: Monitor localStorage quota (~5-10MB)

### UI Components

#### 1. Header
- App title and brief description
- Minimalist design with consistent spacing

#### 2. Input Section
- Repository URL input field
- "Analyze Repository" button
- Collapsible "Advanced Options" with API token input
- Clear visual feedback for invalid inputs

#### 3. Progress Indicator
- Show current operation: "Fetching stargazers...", "Geocoding locations..."
- Progress bar with percentage
- Cancel button for long operations

#### 4. Map View
- Full-width map container
- Marker clustering for better performance
- Popup on marker click showing:
  - GitHub username
  - Location string
  - Link to GitHub profile
- Zoom controls and fullscreen option

### Error Handling
- Invalid repository URL format
- Repository not found (404)
- Rate limit exceeded (403)
- Network errors
- Invalid/ungeocoded locations (show in a separate list)

### Performance Considerations
- Batch API requests where possible
- Implement request queue for geocoding
- Use React.memo for expensive components
- Lazy load map library
- Virtual scrolling for large user lists

### Design Principles
- **Minimalism**: Clean, uncluttered interface
- **Accessibility**: ARIA labels, keyboard navigation
- **Feedback**: Clear loading states and error messages
- **Privacy**: No data persistence beyond cache, no analytics

## File Structure
src/
├── components/
│   ├── Header.tsx
│   ├── RepoInput.tsx
│   ├── ProgressBar.tsx
│   ├── Map.tsx
│   └── ErrorBoundary.tsx
├── hooks/
│   ├── useGitHubAPI.ts
│   ├── useGeocoding.ts
│   └── useCache.ts
├── services/
│   ├── github.ts
│   ├── geocoding.ts
│   └── cache.ts
├── types/
│   └── index.ts
├── utils/
│   ├── rateLimit.ts
│   └── validation.ts
├── App.tsx
├── main.tsx
└── index.css

## Development Guidelines
- Use conventional commits (feat:, fix:, docs:, etc.)
- Format all files with Prettier on save
- Follow React best practices and hooks rules
- Keep components small and focused
- Use TypeScript strict mode
- Minimize external dependencies

## Future Enhancements (Out of Scope)
- Export visualization as image
- Historical star growth animation
- Contributor location analysis
- Repository comparison mode
- Backend API for caching/analytics

### Development Guidelines
1. Keep dependencies minimal
2. Use async/await for all asynchronous operations
3. Implement proper error boundaries
4. Use semantic HTML for accessibility
5. Follow mobile-first responsive design
6. Keep bundle size under 500KB (excluding map tiles)

### Deployment
- Static site deployment (Vercel, Netlify, GitHub Pages)
- No backend or serverless functions needed
- Environment variables not required

## Future Enhancements (Out of Scope)
- Light theme toggle
- Export map as image
- Time-based animation of stars
- Repository comparison
- User authentication
- Data persistence