`CLAUDE.md`

183 lines
# CLAUDE.md

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

## Project Overview

Omega Watch Price History System - A comprehensive price tracking and visualization platform for Omega watch collections. Tracks 32 models with historical data from 1957-2024. Includes React frontend, Express backend, PostgreSQL database, and real-time WebSocket support.

**Server:** 45.61.58.125  
**Main Port:** 7600  
**Vite Dev Port:** 5173  
**Process Manager:** PM2

## Essential Commands

### Development
```bash
# Install dependencies
npm install

# Start development server (Vite + backend)
npm run dev

# Start production server
npm start

# PM2 management
pm2 start ecosystem.config.cjs
pm2 restart omega-watches
pm2 logs omega-watches

# Run API tests
./test/api-tests.sh
```

### Build & Deploy
```bash
# Build frontend (Vite)
npm run build

# Deploy to production
npm run deploy

# Rollback deployment
npm run rollback
```

### Backup & Recovery
```bash
# Create backup
npm run backup

# Restore latest backup  
npm run restore-latest-backup

# List backups
npm run backup:list
```

### Health & Monitoring
```bash
# Health check
npm run health-check

# View logs
npm run logs

# Monitor processes
npm run monitor
```

## Architecture

### Backend Structure
- **server.js** - Express server (port 7600)
  - RESTful APIs at `/api/*`
  - WebSocket support for real-time updates
  - In-memory caching with 5-minute TTL
  - Swagger documentation at `/api-docs`

### Frontend Structure  
- **React + Vite** - Modern build pipeline
  - Component-based architecture in `src/components/`
  - PWA support with offline capability
  - Code splitting for charts/animations
  - Responsive design with Tailwind CSS

### Data Layer
- **Primary:** JSON file (`data/omega-watches.json`)
- **Database:** PostgreSQL schema ready (`database/schema.sql`)
- **Caching:** In-memory cache, Redis-ready infrastructure
- **Real-time:** WebSocket server for live updates

## Key API Endpoints

### Core Watch Data
- `GET /api/watches` - All models (cached)
- `GET /api/watches/:id` - Specific watch with price history
- `POST /api/watches/compare` - Compare multiple models
- `GET /api/statistics` - Market statistics & appreciation

### Search & Filter
- `GET /api/search?q={query}` - Fuzzy search
- `GET /api/watches?series={name}` - Filter by series
- `GET /api/watches?minPrice={n}&maxPrice={m}` - Price range
- `GET /api/watches/trending` - Most viewed watches

### User Features
- `POST /api/watchlist` - Add/remove from watchlist
- `GET /api/watchlist/:userId` - Get user's watchlist
- `GET /api/export/{format}` - Export data (json/csv)

## Testing Protocol

Always run tests before deployment:
```bash
# API test suite
./test/api-tests.sh

# Check service health
curl http://45.61.58.125:7600/api/health

# Verify PM2 status
pm2 status omega-watches
```

## Performance Optimizations

### Current Implementation
- Brotli/gzip compression for assets
- Aggressive code splitting (React, Charts, Animations)
- Service Worker for offline functionality
- Cache headers for static assets (1-7 days)
- In-memory caching for API responses

### Frontend Bundle Management
- React core: Immediate load
- Charts (Chart.js): Lazy loaded
- Animations (Framer Motion): Lazy loaded
- Target: Modern browsers (ES2020)

## Data Management

### Adding Watch Models
Edit `data/omega-watches.json`:
```json
"watch-id": {
  "name": "Watch Name",
  "collection": "Collection",
  "reference": "REF123",
  "year_introduced": 2000,
  "priceHistory": [
    {"year": 2000, "price": 5000, "condition": "new"}
  ]
}
```

### Database Migration
When ready to migrate from JSON to PostgreSQL:
```bash
node database/migrate-json-to-postgres.js
```

## Deployment Configuration

### PM2 Ecosystem
- **Main app:** `omega-watches` (cluster mode)
- **Health monitor:** `omega-health-monitor` (fork mode)
- **Auto-restart:** Max 10 restarts, 500MB memory limit
- **Logs:** `./logs/pm2-*.log`

### Environment Variables
- `NODE_ENV`: production/development
- `PORT`: 7600 (production)
- Database credentials in `.env` when migrating to PostgreSQL

## Important Notes

1. **Port Management:** Always verify port 7600 is free before starting
2. **Cache Clearing:** Clear cache after data updates via `/api/admin/clear-cache`
3. **WebSocket:** Real-time updates broadcast to all connected clients
4. **Security:** Helmet.js disabled currently to avoid CSP issues with CDN resources
5. **PWA:** Service Worker auto-updates, caches API responses for 5-10 minutes