██████╗ ██╗  ██╗ ██████╗ ███╗   ██╗ ██████╗ ██╗  ██╗
 ██╔══██╗██║  ██║██╔═══██╗████╗  ██║██╔═══██╗╚██╗██╔╝
 ██████╔╝███████║██║   ██║██╔██╗ ██║██║   ██║ ╚███╔╝ 
 ██╔═══╝ ██╔══██║██║   ██║██║╚██╗██║██║   ██║ ██╔██╗ 
 ██║     ██║  ██║╚██████╔╝██║ ╚████║╚██████╔╝██╔╝ ██╗
 ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═╝

AI-powered Vinyl Collection Agent – Cataloguing, Valuation, and Documentation

---

What is Phonox?

Phonox is an intelligent assistant for vinyl record collectors. It helps you:

• 📸 Identify records by snapping photos or uploading images
• 💰 Get valuations using multiple data sources (Discogs, MusicBrainz)
• 🎵 Find Spotify links for listening to your collection
• 📝 Organize your collection with metadata, ratings, and notes
• 💬 Chat about records with an AI agent that remembers your collection

🖼️ See it in action → UI Gallery & feature walkthrough 📝 Blog → phonox-blog.web.app

Perfect for collectors managing large vinyl libraries or insuring valuable collections.

---

Prerequisites

Before you start, make sure you have:

1. Docker & Docker Compose installed

   • Windows/Mac
   • Linux
   • Verify: Run docker --version and docker compose version

2. Git (to clone the repository)

   • Install Git

3. API Keys (optional but recommended)

   • Anthropic API Key (for Claude AI)
   • Tavily API Key (for web search, optional – DuckDuckGo fallback is free)

---

Quick Start (3 Simple Steps)

1. Clone the Repository

git clone https://github.com/yourusername/phonox.git
cd phonox

2. Setup Environment with API Key

# Copy the environment template
cp .env.example .env

# Add your Anthropic API key
./phonox-cli configure --anthropic YOUR_ANTHROPIC_KEY

Get your API key: console.anthropic.com

3. Install and Start

# Make executable and run (installs + starts everything)
chmod +x start-cli.sh
./start-cli.sh

The start-cli.sh script will:

• ✅ Build Docker images
• ✅ Start all services (database, backend, frontend)
• ✅ Initialize the database

Done! Open your browser:

• Frontend (UI): http://localhost:5173
• API Docs: http://localhost:8000/docs
• Backend Health: http://localhost:8000/health

---

Key Environment Variables

The .env file contains all configuration. Key variables:

Variable	Required	Description
ANTHROPIC_API_KEY	✅ Yes	Claude AI API key from console.anthropic.com
TAVILY_API_KEY	⚠️ Optional	Web search API key from tavily.com
DATABASE_URL	✅ Pre-configured	PostgreSQL connection (auto-configured for Docker)

For all configuration options, see .env.example

---

How to Use Phonox

Identify a Vinyl Record

1. Click "Upload Image" on the home page
2. Take a photo or upload an image of:
   • The album cover (front or back)
   • The barcode (if visible)
   • The vinyl itself (for condition assessment)
3. Phonox AI will:
   • Scan for the barcode
   • Search Discogs and MusicBrainz
   • Extract album metadata automatically
4. Review the results and save to your collection

Manage Your Collection

1. Visit "Register" to see all your vinyl records
2. Edit any record to:
   • Add notes or condition notes
   • Add Spotify link
   • Update valuation
   • Rate the record
3. Delete records from your collection
4. Export your collection (future feature)

Chat with the Agent

1. Open the Chat panel on the right
2. Ask questions about your collection:
   • "What's my rarest record?"
   • "Show me all records from the 80s"
   • "What's the total value of my collection?"
3. The agent remembers context from your collection

---

How to Stop, Start, and Manage Services

Start Services

./phonox-cli start
# or
docker compose up -d

Stop Services

./phonox-cli stop
# or
docker compose down

View Logs

docker compose logs -f backend
docker compose logs -f frontend

Check Service Status

./phonox-cli status
# or
curl http://localhost:8000/health

---

Phonox CLI Commands

Full CLI Reference:

# Install (build Docker images)
./phonox-cli install

# Install + start services
./phonox-cli install --up

# Configure API keys and models
./phonox-cli configure --anthropic YOUR_KEY --tavily YOUR_KEY

# Configure Anthropic models (for advanced users)
./phonox-cli configure --vision-model claude-sonnet-4-6
./phonox-cli configure --chat-model claude-haiku-4-5-20251001

# Start services
./phonox-cli start

# Stop services
./phonox-cli stop

# Backup your data
./phonox-cli backup

# Restore from backup (use timestamp from backup folder)
./phonox-cli restore 20260128_143000

Interactive Menu

Run without arguments to launch interactive menu:

./phonox-cli
# Shows menu with all options above

---

Troubleshooting & Maintenance

Common Issues

❌ "Port already in use" (8000 or 5173)

# Kill process using port 8000
lsof -i :8000 | grep LISTEN | awk '{print $2}' | xargs kill -9

# Or restart Docker
docker compose down
docker compose up -d

❌ "Database connection refused"

# Reset database
docker compose down -v
docker compose up -d

❌ Images not uploading

# Check upload folder permissions
ls -la data/uploads/

# Restart services
docker compose restart backend frontend

❌ API keys not working

# Verify .env file
cat .env

# Restart backend to reload keys
docker compose restart backend

Regular Maintenance

Backup Your Data (Weekly)

./phonox-cli backup
# Backups stored in: ./backups/

View Backup History

ls -lh backups/

Restore from a Backup

./phonox-cli restore 20260128_143000

Check Database Size

docker compose exec db psql -U phonox -d phonox -c "
  SELECT 
    schemaname,
    sum(pg_total_relation_size(schemaname||'.'||tablename)) AS size
  FROM pg_tables
  GROUP BY schemaname
  ORDER BY size DESC;"

View Vinyl Records in Database

docker compose exec db psql -U phonox -d phonox -c "
  SELECT id, title, artist, release_date, confidence, created_at
  FROM vinyl_records
  ORDER BY created_at DESC
  LIMIT 10;"

---

Testing

Run All Tests

docker compose exec backend pytest tests/ -v

Run Specific Test Categories

# Unit tests
docker compose exec backend pytest tests/unit -v

# Integration tests
docker compose exec backend pytest tests/integration -v

# With coverage report
docker compose exec backend pytest tests/ --cov=backend --cov-report=html

View Test Results

# Open coverage report
open htmlcov/index.html  # macOS
xdg-open htmlcov/index.html  # Linux
start htmlcov/index.html  # Windows

📖 Getting Started

• What is Phonox? – Overview and features
• How to Use – Step-by-step user guide
• Troubleshooting – Common issues and fixes

👨‍💻 For Developers

• Tech Stack Guide – Architecture and technologies
• Requirements Spec – Complete feature list
• API Reference – Interactive Swagger UI (live)

🏗️ For Teams & Contributors

1. Implementation Plan – Project roadmap and progress
2. Contributing Guide – How to contribute code
3. Agent Collaboration Instructions – Team workflow
4. Deployment Guide – Production setup

---

Project Structure

phonox/
├── README.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docker-compose.yml
├── Dockerfile.backend
├── Dockerfile.frontend
├── start-cli.sh
├── phonox-cli
│
├── .github/
│   └── agents/              (AI agent collaboration docs)
│
├── backend/
│   ├── main.py              (FastAPI entry point)
│   ├── database.py          (SQLAlchemy ORM)
│   ├── agent/
│   │   ├── graph.py         (LangGraph workflow)
│   │   ├── vision.py        (Claude vision extraction)
│   │   ├── websearch.py     (Tavily + DuckDuckGo)
│   │   ├── metadata.py      (Discogs + MusicBrainz lookup)
│   │   ├── metadata_enhancer.py
│   │   ├── barcode_utils.py
│   │   └── state.py         (State models)
│   ├── api/
│   │   ├── routes.py        (Identification + chat endpoints)
│   │   ├── register.py      (Collection management endpoints)
│   │   └── models.py        (Pydantic models)
│   └── tools/
│       └── web_tools.py
│
├── frontend/
│   └── src/
│       ├── App.tsx
│       ├── components/
│       │   ├── VinylCard.tsx
│       │   ├── VinylRegister.tsx
│       │   ├── ChatPanel.tsx
│       │   ├── ImageUpload.tsx
│       │   ├── UserManager.tsx
│       │   └── ...
│       ├── api/             (API client)
│       └── services/        (Register API client)
│
├── tests/                   (unit, integration, api)
├── docs/                    (MkDocs documentation)
├── scripts/                 (backup, restore, CLI)
└── backups/                 (local backups)

---

Architecture Overview

React PWA → FastAPI backend → LangGraph AI agent → PostgreSQL, with multi-source metadata enrichment (Discogs, MusicBrainz, Tavily/DuckDuckGo).

→ Full data flows, component diagrams, security and scaling notes: ARCHITECTURE.md

---

Tech Stack

Layer	Technology
Backend	Python 3.12, FastAPI, LangGraph, Pydantic v2, SQLAlchemy
Frontend	React 18, TypeScript, Vite, PWA
Database	PostgreSQL 16
AI / Vision	Claude (Anthropic) — multimodal identification and chat
Web Search	Tavily + DuckDuckGo fallback
Metadata	Discogs API, MusicBrainz API, Spotify API
Infrastructure	Docker, Docker Compose

See ARCHITECTURE.md for detailed component breakdown and data flows.

---

Need Help?

Common Questions

Q: I don't have an Anthropic API key. Can I still use Phonox?
A: No, Claude API is required. Get a free tier key at console.anthropic.com.

Q: Can I use Phonox without Docker?
A: Not recommended. Docker ensures all dependencies work correctly. If you must, install: Python 3.12, PostgreSQL 16, Node.js 20.

Q: How do I backup my vinyl collection?
A: Run ./phonox-cli backup weekly. Backups are stored in ./backups/.

Q: Can I run Phonox on my phone?
A: Yes! It's a Progressive Web App (PWA). Open http://localhost:5173 on your phone and tap "Install" or "Add to Home Screen".

Q: How do I import my existing vinyl spreadsheet?
A: Currently manual. We're working on CSV import (see roadmap). For now, use the UI to add records.

Get Support

• 📖 Documentation: See links above
• 🐛 Report Issues: Open an issue on GitHub
• 💬 Discuss Features: Start a discussion
• 👥 Join Community: See CONTRIBUTING.md

---

What's New (Latest Version: 2.0.1)

✨ Version 2.0.1 (March 14, 2026)

• Repository cleanup: removed stale Makefile, status.sh, docker-status.sh, API_GUIDE.md, and TESTING_GUIDE.md
• ARCHITECTURE.md updated to reflect v2.0.0 security and chat changes
• README API reference now points to live Swagger UI

✨ Version 2.0.0 (March 14, 2026)

• Collection analysis report is now fully visible to Claude in follow-up chat — was silently dropped from context due to system-role filtering
• Fixed broken access control: GET /api/register/ without a user tag no longer returns all users' records (required parameter enforced on backend)

✨ Version 1.9.9 (March 13, 2026)

• Chat now includes full record context (barcode, condition, user notes, estimated value, Spotify URL) in Claude system prompt
• Fixed chat response ending with a stray "0" when no web sources were used
• Added blog link in header

See CHANGELOG.md for complete history.

---

Status & Roadmap

Last Updated: 2026-03-14
Current Version: 2.0.1
Status: Production Ready ✅

Completed Features

• ✅ Image-based vinyl identification
• ✅ Metadata lookup (Discogs, MusicBrainz)
• ✅ AI-powered valuation
• ✅ Web-based UI (mobile + desktop)
• ✅ Spotify integration
• ✅ Enhanced web search

Planned Features

• 🔄 CSV import/export
• 🔄 Barcode printing
• 🔄 Collection insurance reports
• 🔄 Social sharing
• 🔄 Mobile app (iOS/Android)

See Implementation Plan for details.

---

License

This project is licensed under the MIT License - see LICENSE file for details.

---

Contributing

Contributions are welcome! Please see Contributing Guide for guidelines on how to get started, including:

• Setting up your development environment
• Git workflow and branching strategy
• Code style and commit message conventions
• Testing and validation procedures

---

Support

• Issues & Feature Requests: GitHub Issues
• Documentation: See docs/ folder for detailed technical documentation

---

Acknowledgments

• Built with Claude AI for record identification and chat
• Uses Tavily for web search (with DuckDuckGo fallback)
• Data enrichment from MusicBrainz and Spotify API
• Powered by FastAPI, React, and LangGraph