Initial commit

CLAUDE.md

@@ -0,0 +1,100 @@
+# 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