flipstone-radar/CLAUDE.md

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 300 seconds)

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 300 seconds)
• 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