100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
# 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 |