Flask Tablatures API

High-performance Flask API for guitar tablature search and download with intelligent query parsing and file streaming.

Architecture

• Flask + Pydantic for type-safe request/response handling
• In-memory JSON database with pre-computed indexes for sub-100ms search
• Serverless-optimized with singleton pattern and cold-start mitigation
• Advanced query parsing supporting field-specific searches (artist:metallica song:enter)

Quick Start

# Setup with Poetry
poetry install --no-root
poetry shell

# Run
python -m api.app

API Endpoints

GET /api/search?q=artist:metallica&limit=10&page=1
GET /api/autocomplete?q=metal&limit=5  
GET /api/download/{tab_id}
GET /api/health

Search Features

• Field-specific: artist:metallica album:master song:enter
• Fuzzy matching: metal enter matches "Metallica - Enter Sandman"
• Weighted scoring: Exact matches (50pts) > Albums (30pts) > Words (10pts)
• Source filtering: source:ultimate-guitar

Database Schema

{
  "metadata" : {
    "lastUpdated": "",
    "totalTabs": "1",
    "version": ""
  },
  "tabs": {
    "tab_id": {
      "title": "Enter Sandman",
      "artist": "Metallica", 
      "source": "ultimate-guitar",
      "downloadUrl": "https://..."
    }
  },
  "index": {
    "artist": {"metallica": ["tab_id1", "tab_id2"]},
    "title": {"enter": ["tab_id1"]},
    "album": {"master": ["tab_id1"]}
  }
}

Deployment

# Generate requirements.txt
poetry export -f requirements.txt --output requirements.txt --without-hashes

# Deploy to Vercel
vercel deploy

Tech Stack

• Flask - Web framework
• Pydantic - Data validation and serialization
• Flask-Pydantic - Automatic request validation
• Poetry - Dependency management
• Requests - HTTP client for file streaming

Performance

• Cold start: ~500ms (JSON loaded once)
• Search latency: ~50-100ms (in-memory indexes)
• Memory usage: ~50MB (cached database)
• Throughput: 1000+ req/s (serverless)