`README.md`

284 lines
# Omega Watch Price History System

## Overview
A comprehensive price tracking and visualization system for all Omega watch models throughout history. This application provides interactive charts, historical price data, and appreciation analysis for collectors and enthusiasts.

## Features

### Core Functionality
- **Complete Price History**: Historical pricing data for 16 major Omega models from 1957 to 2024
- **Interactive Charts**: Real-time price comparison charts using Chart.js
- **Model Comparison**: Compare up to 5 watch models simultaneously
- **Appreciation Tracking**: View top appreciating models with percentage gains
- **Search & Filter**: Find watches by name, reference, or collection
- **Data Export**: Export price data to CSV format

### Watch Collections Included
- **Speedmaster**: Moonwatch, Alaska Project, Reduced, Mark II
- **Seamaster**: 300, PloProf, Bond, Aqua Terra, Planet Ocean
- **Constellation**: Pie Pan, Manhattan
- **De Ville**: Trésor, Co-Axial Chronometer
- **Special Models**: Railmaster, Flightmaster

## Technical Architecture

### Backend (Node.js/Express)
```
server.js           - Express server with API endpoints
├── /api/watches    - Get all watch models
├── /api/watches/:id - Get specific watch with price history
├── /api/watches/compare - Compare multiple watches
├── /api/statistics - Get market statistics
└── /health        - Health check endpoint
```

### Frontend (Vanilla JavaScript)
```
public/
├── index.html     - Main application interface
├── styles.css     - Responsive styling
└── app.js         - Chart management and interactions
```

### Data Structure
```
data/omega-watches.json - Complete price history database
```

## Installation & Setup

### Prerequisites
- Node.js 14+ installed
- PM2 (optional, for process management)

### Quick Start
```bash
# Navigate to project directory
cd /root/Projects/watches

# Install dependencies
npm install

# Start the server
npm start

# Or with PM2
pm2 start server.js --name omega-watches
```

### Access the Application
Open your browser and navigate to:
```
http://45.61.58.125:7250
```

## API Endpoints

### GET /api/watches
Returns list of all watch models (without full price history).

**Response Example:**
```json
[
  {
    "id": "speedmaster-moonwatch",
    "name": "Speedmaster Professional Moonwatch",
    "collection": "Speedmaster",
    "reference": "311.30.42.30.01.005",
    "year_introduced": 1957,
    "description": "The legendary chronograph..."
  }
]
```

### GET /api/watches/:id
Returns complete watch data including price history.

**Response Example:**
```json
{
  "id": "speedmaster-moonwatch",
  "name": "Speedmaster Professional Moonwatch",
  "priceHistory": [
    { "year": 1969, "price": 185, "condition": "new" },
    { "year": 2024, "price": 7500, "condition": "new" }
  ]
}
```

### POST /api/watches/compare
Compare multiple watches by providing array of IDs.

**Request Body:**
```json
{
  "watchIds": ["speedmaster-moonwatch", "seamaster-300"]
}
```

### GET /api/statistics
Returns market statistics and top appreciating models.

## Adding New Watch Models

To add a new watch model, edit `data/omega-watches.json`:

```json
"new-watch-id": {
  "name": "Watch Name",
  "collection": "Collection Name",
  "reference": "Reference Number",
  "year_introduced": 2000,
  "description": "Watch description",
  "priceHistory": [
    { "year": 2000, "price": 5000, "condition": "new" },
    { "year": 2024, "price": 8000, "condition": "new" }
  ]
}
```

## Updating Price Data

### Manual Update
1. Edit `data/omega-watches.json`
2. Add new price points to existing watches
3. Restart the server to reload data

### Programmatic Update (Future Enhancement)
```javascript
// Example function to add price point
async function addPricePoint(watchId, year, price, condition) {
  const data = require('./data/omega-watches.json');
  data.watches[watchId].priceHistory.push({
    year, price, condition
  });
  await fs.writeFile('./data/omega-watches.json', JSON.stringify(data, null, 2));
}
```

## Future Enhancements

### Planned Features
1. **Real-time Price Updates**: Integration with watch market APIs
2. **User Authentication**: Personal watch collections and wishlists
3. **Price Alerts**: Notifications when prices drop/rise
4. **Market Predictions**: ML-based price forecasting
5. **Mobile App**: React Native companion app
6. **Database Migration**: Move from JSON to PostgreSQL
7. **Image Gallery**: Watch photos and specifications
8. **Condition Grading**: Detailed condition-based pricing
9. **Currency Support**: Multi-currency price display
10. **Social Features**: Share collections and discussions

### API Integrations (Planned)
- Chrono24 API for real-time market prices
- WatchCharts for market analytics
- Exchange rate APIs for currency conversion

## Performance Optimization

### Current Optimizations
- Compression middleware for response size reduction
- Static file caching for assets
- Efficient data structure for quick lookups

### Recommended Optimizations
1. Implement Redis caching for frequently accessed data
2. Use CDN for static assets
3. Implement pagination for large datasets
4. Add database indexing when migrating from JSON

## Security Considerations

### Current Security Measures
- Helmet.js for security headers
- CORS configuration
- Input validation
- Rate limiting ready (can be added)

### Recommended Additions
```javascript
// Rate limiting example
const rateLimit = require('express-rate-limit');
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100 // limit each IP to 100 requests
});
app.use('/api/', limiter);
```

## Troubleshooting

### Common Issues

**Server won't start:**
```bash
# Check if port is in use
lsof -ti:7250
# Kill process if needed
lsof -ti:7250 | xargs kill -9
```

**Data not loading:**
- Verify `data/omega-watches.json` exists and is valid JSON
- Check server logs for parsing errors

**Charts not displaying:**
- Ensure Chart.js CDN is accessible
- Check browser console for JavaScript errors
- Verify API endpoints are returning data

## Development

### Project Structure
```
/root/Projects/watches/
├── server.js              # Main server file
├── package.json           # Dependencies
├── README.md             # This file
├── data/
│   └── omega-watches.json # Price history database
└── public/
    ├── index.html        # Main UI
    ├── styles.css        # Styling
    └── app.js           # Frontend logic
```

### Code Style
- ES6+ JavaScript features
- Async/await for asynchronous operations
- RESTful API design principles
- Responsive, mobile-first CSS

## Contributing

To contribute new watch models or price data:
1. Fork the repository
2. Add watch data to `omega-watches.json`
3. Test locally
4. Submit pull request with sources cited

## License

MIT License - Free for personal and commercial use.

## Support

For issues or questions:
- Check the troubleshooting section
- Review API documentation
- Contact system administrator

## Credits

Price data compiled from:
- Historical auction results
- Vintage watch dealer records
- Omega official retail prices
- Collector market observations

---

**Version:** 1.0.0
**Last Updated:** 2024
**Server:** http://45.61.58.125:7250