# CLAUDE.md

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

## Development Commands

### Frontend (Next.js)
- `cd frontend && bun install` - Install dependencies
- `cd frontend && bun run dev` - Start development server with Turbopack
- `cd frontend && bun run build` - Build production version
- `cd frontend && bun run start` - Start production server
- `cd frontend && bun run lint` - Run ESLint checks
- `cd frontend && bun run generate:api` - Generate API client from OpenAPI spec
- `cd frontend && bun run generate:api:watch` - Generate API client with watch mode

### Backend (FastAPI)
- `cd backend && uv sync` - Install dependencies with UV
- `cd backend && uv run python app/main.py` - Run development server
- `cd backend && uv run python scripts/start_arq_worker.py` - Start ARQ worker
- `cd backend && uv run pytest` - Run tests
- `cd backend && uv run black .` - Format code with Black
- `cd backend && uv run isort .` - Sort imports with isort
- `cd backend && uv run mypy .` - Type checking with MyPy
- `cd backend && uv run ruff check .` - Lint with Ruff

### Docker Development
- `cd backend && docker-compose up -d` - Start all services with Docker Compose
- `cd backend && docker-compose down` - Stop all services
- `cd backend && docker-compose logs -f` - View logs

## Architecture Overview

### Project Structure
This is a full-stack application with:
- **Frontend**: Next.js 15 with App Router, React 18, TypeScript
- **Backend**: FastAPI with Python 3.13, async/await architecture
- **Infrastructure**: Docker, Kubernetes, Redis, PostgreSQL

### Frontend Architecture
- **Framework**: Next.js 15 with App Router
- **UI**: Apple-style design system with custom components
- **State Management**: React Context + TanStack Query for server state
- **Forms**: React Hook Form + Zod validation
- **HTTP**: Axios with enhanced client
- **Styling**: Tailwind CSS + Less for complex styles
- **Animation**: Framer Motion
- **Package Manager**: Bun (configured in bunfig.toml)

### Backend Architecture
- **Framework**: FastAPI with async/await
- **Architecture**: Distributed microservices with ARQ task queues
- **Browser Automation**: Playwright for web scraping
- **Database**: PostgreSQL with asyncpg
- **Cache**: Redis for distributed locking and state management
- **Task Queue**: ARQ with Redis broker
- **Monitoring**: OpenTelemetry integration
- **Package Manager**: UV (configured in pyproject.toml)

### Key Directories

#### Frontend (`frontend/`)
- `src/app/` - Next.js App Router pages
- `src/components/` - Reusable components
  - `dashboard/` - Main dashboard components
  - `forms/` - Form components with validation
  - `layout/` - Layout and theme components
  - `ui/` - Base UI components (Apple-style)
  - `animate-ui/` - Animated UI components
- `src/lib/` - Utility libraries
  - `api/` - API client and generated types
  - `contexts/` - React contexts (theme, refresh)
  - `hooks/` - Custom React hooks
  - `telemetry/` - OpenTelemetry integration

#### Backend (`backend/`)
- `app/api/` - FastAPI routes and endpoints
- `app/core/` - Core functionality (config, database, redis, etc.)
- `app/models/` - SQLAlchemy data models
- `app/schemas/` - Pydantic schemas
- `app/services/` - Business logic services
- `app/tasks/` - ARQ task definitions
- `app/repositories/` - Data access layer
- `deploy/` - Docker and deployment configurations
- `docs/` - Architecture and project documentation

### Core Features

#### Frontend Features
- Real-time dashboard with auto-refresh
- Apple-style UI with smooth animations
- File upload and data management
- Order and task monitoring
- Link management system
- Theme switching (dark/light)
- OpenTelemetry telemetry integration

#### Backend Features
- Distributed web scraping with Playwright
- Redis-based distributed locking
- ARQ task queue system
- Automatic task recovery and failure handling
- Kubernetes deployment support
- Graceful shutdown handling
- Comprehensive health checks
- Structured logging with OpenTelemetry

### API Integration
- Backend provides OpenAPI specification at `http://localhost:8000/openapi.json`
- Frontend auto-generates API client code using Orval
- Generated files in `frontend/src/lib/api/generated/`
- Enhanced axios client with interceptors and error handling

### State Management

#### Frontend State
- **Global State**: React Context for theme and refresh settings
- **Server State**: TanStack Query for API data management
- **Local State**: React hooks for component state
- **Form State**: React Hook Form with Zod schemas

#### Backend State
- **Database**: PostgreSQL with SQLAlchemy ORM
- **Cache**: Redis for distributed state and locking
- **Task State**: ARQ backend for task progress tracking
- **Session State**: Redis-based session management

### Deployment Configuration

#### Development
- Frontend: Bun development server
- Backend: UV development server
- Services: Docker Compose for Redis, PostgreSQL

#### Production
- Frontend: Docker container with Nginx
- Backend: Multi-service Docker deployment
- Orchestration: Kubernetes with Helm charts
- Monitoring: Prometheus + Grafana
- Logging: Structured logs with OpenTelemetry

### Development Notes

#### Environment Variables
**Frontend** (`.env.local`):
- `NEXT_PUBLIC_API_URL` - Backend API URL
- `NEXT_PUBLIC_ENV` - Environment (development/production)
- `NEXT_PUBLIC_TELEMETRY_ENDPOINT` - OpenTelemetry endpoint

**Backend** (`.env`):
- `REDIS_URL` - Redis connection URL
- `DATABASE_URL` - PostgreSQL connection URL
- `SERVICE_TYPE` - Service type (api/worker/recovery)
- `LOG_LEVEL` - Logging level

#### Code Quality
- **Frontend**: ESLint + Prettier + TypeScript
- **Backend**: Black + isort + MyPy + Ruff + pytest
- **Pre-commit**: Hooks for both frontend and backend
- **Testing**: pytest for backend, Jest setup available for frontend

#### Key Architectural Patterns
- **Microservices**: Backend uses service-oriented architecture
- **Distributed Systems**: Redis-based coordination and locking
- **Event-Driven**: ARQ task queues for async processing
- **Reactive UI**: Frontend uses real-time updates with polling
- **Type Safety**: Full TypeScript coverage on both ends

#### Special Considerations
- **Distributed Locking**: Critical for multi-replica deployments
- **Graceful Shutdown**: Ensures task completion during deployments
- **Error Handling**: Comprehensive error recovery mechanisms
- **Monitoring**: Full observability with OpenTelemetry
- **Scaling**: Horizontal scaling support with Kubernetes HPA