image_tagger/QUICK_START.md

🚀 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

# 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:

ANTHROPIC_API_KEY=sk-ant-api-03-xxxxxxxxxxxxxxxxxxxx

Step 3: Done!

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

# 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

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

# Start in production mode
npm start

# Stop server
Ctrl+C

Database Management

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

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

API Key Management

# 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:

SKIP_AUTH=false

Then use API keys in requests:

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 50)
POST	/api/images/tag-base64/batch	Tag multiple base64 images
POST	/api/images/tag-s3-folder	Tag all images from S3 folder
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

# 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

# AWS S3 (REQUIRED for S3 folder endpoint)
AWS_ACCESS_KEY_ID=            # AWS IAM user access key ID
AWS_SECRET_ACCESS_KEY=        # AWS IAM user secret access key
AWS_REGION=us-east-1          # AWS region (default: us-east-1)
AWS_S3_BUCKET=                # S3 bucket name (e.g., tso3listingimages)

# 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

{
  "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

{
  "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! 🤖