# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Development Commands

### Common Commands
- `npm run dev` - Start development server (runs both frontend and backend concurrently)
- `npm run server` - Start backend server only
- `npm run build` - Build for production (TypeScript compilation + Vite build)
- `npm run lint` - Run ESLint on TypeScript files
- `npm run test` - Run tests with Vitest
- `npm run preview` - Preview production build

### Development Workflow
- Use `npm run dev` for full-stack development
- Backend runs on port 3001, frontend on port 3000
- Frontend proxies API calls to backend via `/api` routes

## Architecture Overview

### Full-Stack Structure
This is a GitHub Actions monitoring dashboard with a React frontend and Express backend that communicates with GitHub's API.

**Frontend (React + TypeScript + Vite)**
- Modern React with TypeScript and Tailwind CSS
- Context providers for theme and settings management
- Component-based architecture with clean separation of concerns
- API communication handled through dedicated service classes

**Backend (Express + TypeScript)**
- RESTful API server with CORS enabled
- GitHub API integration with token-based authentication
- Live configuration reloading with file watching
- Graceful shutdown handling

### Key Components

**Frontend Structure:**
- `src/App.tsx` - Main app with context providers
- `src/components/Dashboard.tsx` - Main dashboard component
- `src/contexts/` - Theme and settings context providers
- `src/services/api.ts` - Frontend API client using Axios
- `src/types/github.ts` - TypeScript interfaces for GitHub API

**Backend Structure:**
- `server/index.ts` - Express server with API routes
- `server/config.ts` - Configuration management with live reloading
- `server/github.ts` - GitHub API service integration

### Configuration System
- Primary config in `config.json` (created from `config.example.json`)
- Live configuration reloading via file watching
- Environment variable fallbacks for deployment
- Validation for required GitHub tokens and repository configs
- Optional cache timeout configuration (defaults to 5 minutes)

### API Endpoints
- `GET /api/health` - Health check
- `GET /api/config` - Repository configuration
- `GET /api/workflow-runs` - Latest workflow runs from all repos
- `GET /api/repository/:owner/:repo/workflow-runs` - Repository-specific runs
- `GET /api/rate-limit` - GitHub API rate limit status
- `GET /api/cache/stats` - Cache statistics
- `DELETE /api/cache` - Clear cache

### GitHub Integration
- Uses GitHub Personal Access Tokens for authentication
- Requires `repo` and `actions:read` permissions
- Fetches workflow runs from multiple repositories
- Supports both public and private repositories

### Rate Limiting and Caching
- **Parallel Processing**: API requests are made in parallel with intelligent rate limiting
- **Smart Caching**: Responses are cached with configurable TTL (defaults to 5 minutes)
- **Rate Limit Monitoring**: Tracks and respects GitHub's rate limits with automatic waiting
- **Controlled Concurrency**: Maximum 10 concurrent requests with 10 requests/second limit
- **Cache Management**: Provides API endpoints to view cache statistics and clear cache when needed

## Development Notes

### Configuration Setup
1. Copy `config.example.json` to `config.json`
2. Add GitHub Personal Access Token with required permissions
3. Configure repositories to monitor
4. Server automatically reloads when config changes

### TypeScript Configuration
- Strict TypeScript enabled with comprehensive type checking
- Vite bundler with React plugin
- Separate tsconfig for Node.js server code

### Testing
- Vitest for unit testing
- Run tests with `npm run test`

### Build Process
- TypeScript compilation followed by Vite build
- Production build outputs to `dist/`
- Server code compiled separately