`README.md`

92 lines
# Japanese Handbag Arbitrage Platform

AI-powered platform for finding arbitrage opportunities on Japanese handbag marketplaces.

## Features

- **Multi-Site Crawling**: Komehyo, Yahoo Auctions JP, Mercari JP, Rakuten
- **AI Price Analysis**: Compares prices with US markets (eBay, The RealReal, Vestiaire, Fashionphile)
- **Automated Crawling**: Runs every 6 hours via cron
- **Web Interface**: Sortable grid with thumbnails, filters by deal percentage, price, date, auction type
- **Data Export**: Export to CSV/Excel spreadsheet
- **Deal Detection**: Automatically flags items significantly below market value

## Setup

1. Install dependencies:
```bash
npm install
```

2. Copy `.env.example` to `.env` and configure:
```bash
cp .env.example .env
# Edit .env with your OpenAI API key
```

3. Initialize database:
```bash
node scripts/init-db.js
```

4. Configure firewall (Ubuntu/Debian):
```bash
sudo ufw allow 7989/tcp
sudo ufw reload
```

5. Setup cron job:
```bash
npm run setup-cron
```

## Usage

### Start Web Server
```bash
npm start
# Visit http://localhost:7989
```

### Manual Crawl
```bash
npm run crawler
```

## Project Structure

```
handbags/
├── crawler/           # Web scraping modules
│   ├── index.js      # Main crawler orchestrator
│   ├── komehyo.js    # Komehyo scraper
│   ├── yahoo-jp.js   # Yahoo Auctions JP
│   ├── mercari.js    # Mercari JP
│   └── rakuten.js    # Rakuten
├── ai/               # AI price comparison
│   ├── analyzer.js   # Price analysis engine
│   └── us-sites.js   # US market data fetchers
├── db/               # Database layer
│   └── schema.js     # SQLite schema
├── public/           # Frontend assets
│   ├── css/
│   ├── js/
│   └── index.html
├── views/            # EJS templates
├── scripts/          # Utility scripts
├── server.js         # Express server
└── package.json
```

## API Endpoints

- `GET /api/listings` - Get all listings with filters
- `GET /api/deals` - Get best deals
- `GET /api/export/csv` - Export data to CSV
- `POST /api/crawl` - Trigger manual crawl

## Sorting & Filtering

- Sort by: Deal %, Price (high/low), Date, Type (auction/buy)
- Filter by: Brand, Condition, Price range, Deal threshold