Goondex/README.md

Goondex

Fast, local-first media indexer for adult content.

Goondex ingests metadata from external sources (ThePornDB, etc.), normalizes it, and stores it in a small SQLite database for quick search via CLI/TUI and background daemon tasks.

Version

v0.1.0-dev2 - TPDB Integration Release

Features (v0.1.0-dev2)

• ✅ SQLite database with WAL mode for performers, studios, scenes, and tags
• ✅ Full TPDB scraper integration with real API calls
• ✅ CLI import commands - Fetch data directly from ThePornDB
• ✅ CLI search commands for local database queries
• ✅ Automatic relationship management (scenes ↔ performers, scenes ↔ tags)
• ✅ Pluggable scraper architecture
• ✅ Configuration via YAML files
• ⏳ Stash-inspired metadata resolution strategies (coming in v0.2.x)

Architecture

Scrapers (TPDB, AE, etc.)
    ↓
Metadata Resolver (field strategies, merge rules)
    ↓
SQLite DB (performers, studios, scenes, tags)
    ↓
CLI/TUI + Daemon (search, identify, sync)

Installation

# Clone the repository
git clone <repository-url>
cd Goondex

# Build the CLI
go build -o bin/goondex ./cmd/goondex

# (Optional) Build the daemon
go build -o bin/goondexd ./cmd/goondexd

Configuration

Set your API keys as environment variables:

export TPDB_API_KEY="your-tpdb-api-key"

Edit configuration files in config/:

• goondex.yml - Runtime settings (database path, cache dir, timeouts)
• metadata.yml - Field strategies (MERGE/OVERWRITE/IGNORE)
• source.yml - Scraper sources and priorities

Usage

Quick Start

# 1. Set your TPDB API key
export TPDB_API_KEY="your-api-key-here"

# 2. Import some data from ThePornDB
./bin/goondex import performer "Riley Reid"
./bin/goondex import studio "Brazzers"
./bin/goondex import scene "Big Wet Butts"

# 3. Search your local database
./bin/goondex performer-search "Riley"
./bin/goondex studio-search "Brazzers"
./bin/goondex scene-search "Big Wet"

All Commands

Import from ThePornDB (requires TPDB_API_KEY):

./bin/goondex import performer [query]  # Import performers
./bin/goondex import studio [query]     # Import studios
./bin/goondex import scene [query]      # Import scenes (+ performers, tags, studio)

Search Local Database:

./bin/goondex performer-search [query]  # Search performers
./bin/goondex studio-search [query]     # Search studios
./bin/goondex scene-search [query]      # Search scenes

Other:

./bin/goondex version                   # Show version
./bin/goondex --help                    # Show help

See CLI Reference for complete documentation.

Database Schema

• performers: id, name, aliases, nationality, country, gender, images, bio
• studios: id, name, parent_id, images, description
• tags: id, name
• scenes: id, title, code, date, studio_id, description, images, director, url
• scene_performers: junction table for scenes ↔ performers
• scene_tags: junction table for scenes ↔ tags

Documentation

Comprehensive documentation is available in the docs/ directory:

• Index - Documentation overview
• Architecture - System design and components
• Database Schema - Complete schema reference
• CLI Reference - All commands and usage
• TPDB Integration - ThePornDB API guide

Roadmap

v0.1.x (Current)

• CLI search commands
• SQLite stores for all entities
• TPDB scraper implementation with real API integration
• Import commands (performer, studio, scene)
• Comprehensive documentation
• Image cache

v0.2.x

• Identify/import commands
• TUI list + preview
• Alias normalization
• Full-text search (FTS5)

v0.3.x

• Daemon (goondexd) with schedules
• Incremental updates
• Duplicate scene detection
• Preview sprite generation

v0.4.x

• Plugin scrapers
• Headless HTTP API
• Web UI

Development

# Run tests (when available)
go test ./...

# Build for development
go build -o bin/goondex ./cmd/goondex

# Run without installing
go run ./cmd/goondex performer-search "test"

Contributing

This is a personal project, but contributions are welcome! Please open an issue before submitting large changes.

License

[Your License Here]

Acknowledgments

Inspired by Stash and its metadata identification flow.