# CLAUDE.md

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

## Project Overview

Preloop Console is a modern web application frontend for Preloop, built with:
- **Lit** (Web Components framework)
- **TypeScript** for type safety
- **Vaadin components** for UI (Vaadin router, forms, layouts)
- **Shoelace components** for additional UI elements
- **Vite** for build tooling and development server
- **Chart.js** for data visualization

The application is a single-page application (SPA) that provides an interface for managing issue trackers through the Preloop API.

## Development Commands

```bash
# Install dependencies
npm install

# Start development server with HMR (http://localhost:5173)
npm run dev

# Build for production
npm run build

# Run tests
npm run test

# Format code
npm run format
npm run format:check

# Docker commands
npm run docker:dev    # Development with HMR
npm run docker:prod   # Production with real API
npm run docker:mock   # Production with mock API
npm run docker:build  # Build production image
npm run docker:test   # Run tests in container
```

## Architecture

### Application Structure
- **Entry point**: `src/main.ts` imports the main app component
- **Root component**: `src/components/lit-app.ts` - defines routing and app shell
- **Router**: Uses Vaadin Router for client-side routing, configured in `lit-app.ts:39-74`
- **API layer**: `src/api.ts` - handles authentication and API calls

### Component Architecture
- All components extend `LitElement` from the Lit framework
- Authenticated components should extend `AuthedElement` from `api.ts` for built-in auth handling
- Components use `@customElement` decorator for registration
- TypeScript decorators are enabled (`experimentalDecorators: true`)

### Authentication Flow
- JWT-based authentication with access/refresh tokens stored in localStorage
- `fetchWithAuth()` function in `api.ts:38-72` handles automatic token refresh
- Failed auth automatically redirects to `/login`
- `AuthedElement` base class provides `fetchData()` method for authenticated requests

### Routing Structure
```
/ - Landing page
/login - Login form
/register - Registration form
/forgot-password - Password reset
/console - Authenticated app shell
  ├── / - Dashboard
  ├── /trackers - Issue tracker management
  ├── /issues - Issue management
  │   ├── /duplicates - Duplicate issue detection
  │   └── /assignments - Issue assignments
  ├── /api-usage - API usage statistics
  └── /settings - User settings
      ├── /profile - User profile
      ├── /security - Security settings
      ├── /api-keys - API key management
      └── /ai-models - AI model configuration
```

### Development Server Configuration
- Vite dev server runs on port 5173
- API requests proxy to `http://127.0.0.1:8000` (backend)
- Static files proxy to same backend
- WebSocket support enabled for HMR

### Testing
- Uses Web Test Runner (`@web/test-runner`) with Playwright
- Test files: `src/**/*.test.{ts,js}`
- Testing utilities: `@open-wc/testing`, Chai, Sinon
- Test runner configured to run headed (browser visible) for debugging
- **Important**: Stub `window.fetch` (not ES module functions) for API testing
- Use `waitUntil()` for async DOM updates and `await new Promise(resolve => setTimeout(resolve, 100))` for API calls
- **Note**: Browser console errors during tests are expected for error handling tests - they indicate proper error flow, not test failures

### Code Style
- Prettier for formatting (configured in `lint-staged`)
- No ESLint configuration present
- TypeScript strict mode enabled
- Use `experimentalDecorators` for Lit decorators

### CI/CD
- GitLab CI configured in `.gitlab-ci.yml` with Docker-based pipeline
- Pipeline stages: test → build → deploy
- **Container-based testing**: Tests run in Docker containers for consistency
- **Format validation**: `npm run format:check` ensures code follows Prettier standards
- **Docker image builds**: Separate dev and production images pushed to GitLab registry
- **Security scanning**: Trivy scans for vulnerabilities in production images
- **Manual deployments**: Staging and production deployments with environment protection
- **Alternative config**: `.gitlab-ci.simple.yml` available for simpler setups without registry

### Docker Support
- **Production**: Multi-stage build with nginx serving static files (`Dockerfile`)
- **Development**: Vite dev server with HMR for live debugging (`Dockerfile.dev`)
- **API Flexibility**: Easy switching between real API and mock API for testing
- **Management Script**: `./docker-run.sh` provides simple commands for all Docker operations

#### Docker Quick Start
```bash
# Development with live debugging
npm run docker:dev     # or ./docker-run.sh dev

# Production with real API
npm run docker:prod    # or ./docker-run.sh prod

# Production with mock API (testing)
npm run docker:mock    # or ./docker-run.sh mock
```

#### Docker Environments
- **Development** (`docker-compose.dev.yml`): Vite dev server on :5173, mock API on :8000
- **Production** (`docker-compose.yml`): Nginx on :3000, expects real API backend
- **Mock Testing** (`docker-compose.mock.yml`): Nginx on :3000, mock API on :8000
- **Environment Variables**: `API_URL` and `MOCK_API` control backend routing

## Key Files
- `src/components/lit-app.ts:39-74` - Route definitions
- `src/api.ts:38-72` - Authentication handling
- `src/api.ts:74-87` - AuthedElement base class
- `vite.config.ts:21-32` - Development proxy configuration
