# 🚀 Quick Start - Property Image Tagging API

## Current Status: ✅ RUNNING

**URL:** http://localhost:3000  
**Mode:** Development (auto-reload enabled)  
**Auth:** Disabled (SKIP_AUTH=true)  
**Database:** Connected with 2 tagged images

---

## 🧪 Test Right Now

```bash
# Service information
curl http://localhost:3000/

# Health check
curl http://localhost:3000/api/images/health

# Statistics
curl http://localhost:3000/api/images/stats

# Search by tag
curl "http://localhost:3000/api/images/search?tag=modern"
```

---

## 📝 To Tag NEW Images

### Step 1: Get Anthropic API Key

1. Visit: https://console.anthropic.com/
2. Sign up and create an API key
3. Copy your key (starts with `sk-ant-api-...`)

### Step 2: Add to .env

Edit the `.env` file in the project root:

```env
ANTHROPIC_API_KEY=sk-ant-api-03-xxxxxxxxxxxxxxxxxxxx
```

### Step 3: Done!

The server will auto-reload. Now you can tag images:

```bash
# Upload and tag an image
curl -X POST http://localhost:3000/api/images/tag \
  -F "image=@/path/to/your/image.jpg"

# Tag a base64 image
curl -X POST http://localhost:3000/api/images/tag-base64 \
  -H "Content-Type: application/json" \
  -d '{
    "base64Image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "fileName": "property.jpg"
  }'
```

---

## 🎯 Key Features

### Automatic Duplicate Detection
- Same image = cached result (FREE, no API call)
- SHA256 hash-based deduplication

### Smart Image Processing
- Supports: JPEG, PNG, WebP, HEIC, TIFF, BMP
- Auto-resize to 2048px (saves API costs)
- Magic number validation (security)

### Rich Tagging
- 20-30 tags per image across categories:
  - Room Type (kitchen, bedroom, etc.)
  - Style (modern, traditional, etc.)
  - Condition (well-maintained, renovated, etc.)
  - Features (hardwood floors, granite counters, etc.)
- Includes AI-generated summary

### Batch Processing
- Tag up to 10 images in one request
- Parallel processing for speed

---

## 🛠️ Common Tasks

### Start/Stop Server

```bash
# Start in development mode (auto-reload)
npm run dev

# Start in production mode
npm start

# Stop server
Ctrl+C
```

### Database Management

```bash
# Set up database (creates tables)
npm run db:setup

# View logs
tail -f logs/combined-*.log
tail -f logs/error-*.log
```

### API Key Management

```bash
# Create new API key
npm run apikey:create

# List all API keys
npm run apikey:list

# Revoke an API key
npm run apikey:revoke
```

### Enable Authentication

Edit `.env`:
```env
SKIP_AUTH=false
```

Then use API keys in requests:
```bash
curl -X POST http://localhost:3000/api/images/tag \
  -H "X-API-Key: key_live_xxxxx" \
  -F "image=@photo.jpg"
```

---

## 📚 All API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/` | Service information |
| GET | `/api/images/health` | Health check |
| GET | `/api/images/stats` | Tagging statistics |
| POST | `/api/images/tag` | Tag uploaded image file |
| POST | `/api/images/tag-base64` | Tag base64-encoded image |
| POST | `/api/images/tag-batch` | Tag multiple files (up to 10) |
| POST | `/api/images/tag-batch-base64` | Tag multiple base64 images |
| GET | `/api/images/search?tag=value` | Search images by tag |

---

## 📦 Use Postman for Easy Testing

1. Open Postman
2. Import collection: `Property_Image_Tagging_API.postman_collection.json`
3. Test all endpoints with pre-configured requests

---

## 🏗️ Project Architecture

**Clean Architecture** - Separation of concerns:

```
src/
├── domain/           # Core business logic (entities, interfaces)
├── application/      # Use cases (business workflows)
├── infrastructure/   # External services (database, AI)
├── presentation/     # HTTP layer (controllers, routes)
└── shared/           # Common utilities (logger, errors)
```

**Benefits:**
- Testable (mock any layer)
- Maintainable (clear separation)
- Swappable (change DB or AI provider easily)

---

## ⚙️ Environment Variables Reference

```env
# Server
NODE_ENV=development          # or production
PORT=3000                     # Server port

# Database
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=                  # Your MySQL password
DB_NAME=property_tagging

# AI Provider (REQUIRED for tagging)
ANTHROPIC_API_KEY=            # From console.anthropic.com

# Development
SKIP_AUTH=true                # Skip API key auth (dev only)
LOG_LEVEL=info                # debug, info, warn, error
```

---

## 🔒 Security Features

- ✅ SHA256 hashed API keys (never stored plain text)
- ✅ Magic number file type validation
- ✅ File size limits (50MB)
- ✅ Image dimension limits (15000px)
- ✅ Helmet.js security headers
- ✅ CORS protection
- ✅ SQL injection prevention (parameterized queries)
- ✅ Input validation (Joi schemas)

---

## 📊 Response Format

### Success Response
```json
{
  "success": true,
  "message": "✅ New image tagged successfully",
  "data": {
    "imageId": 3,
    "imageHash": "abc123...",
    "tags": [
      {
        "category": "room_type",
        "value": "kitchen",
        "confidence": "high"
      }
    ],
    "summary": "Modern kitchen with...",
    "totalTags": 28,
    "isDuplicate": false
  },
  "timestamp": "2025-11-03T10:30:00.000Z"
}
```

### Error Response
```json
{
  "success": false,
  "message": "File size exceeds maximum allowed size",
  "timestamp": "2025-11-03T10:30:00.000Z"
}
```

---

## 🐛 Troubleshooting

### Server won't start
- Check MySQL is running: `systemctl status mysql`
- Verify `.env` credentials
- Check port 3000 is available

### Can't tag images
- Verify `ANTHROPIC_API_KEY` is set in `.env`
- Check API key is valid at console.anthropic.com
- View logs: `tail -f logs/error-*.log`

### Database connection error
- MySQL credentials in `.env`
- Run: `npm run db:setup`

### API key authentication failing
- Set `SKIP_AUTH=true` in `.env` for development
- Or create API key: `npm run apikey:create`

---

## 📖 Further Reading

- **SETUP_GUIDE.md** - Complete setup instructions
- **CURSOR_PROMPT.md** - Full project specification
- **.cursorrules** - Development best practices
- **logs/** - Application logs for debugging

---

## 🎉 You're All Set!

The server is running at **http://localhost:3000**

Add your Anthropic API key to start tagging images with AI! 🤖