Metadata Aggregator

gRPC service for aggregating music metadata from multiple providers with PostgreSQL caching.

Features

• Multi-provider support - Currently MusicBrainz, extensible for Spotify, Discogs, etc.
• Database-first caching - Check local DB before hitting external APIs
• Rate limiting - Respects provider API limits (1 req/sec for MusicBrainz)
• Provider-only mode - Works without database for quick testing

Quick Start

# Build
nix build .#server

# Run (no database)
./result/bin/server

# Run (with database)
./result/bin/server -config config.yaml

Configuration

server:
  port: 50051

database:
  host: localhost
  port: 5432
  user: metadata
  password: metadata
  name: metadata
  sslmode: disable

Or via environment: DATABASE_URL=postgres://user:pass@host:5432/db

Database

cd database
docker compose up -d

PostgreSQL 16 with pg_prewarm for automatic cache warming.

API

# Search artists
grpcurl -plaintext -d '{"query": "Radiohead"}' localhost:50051 metadata.v1.MetadataService/SearchArtists

# Get artist
grpcurl -plaintext -d '{"id": "a74b1b7f-71a5-4011-9441-d0b5e4122711"}' localhost:50051 metadata.v1.MetadataService/GetArtist

# Get album
grpcurl -plaintext -d '{"id": "b1392450-e666-3926-a536-22c65f834433"}' localhost:50051 metadata.v1.MetadataService/GetAlbum

# Get album tracks
grpcurl -plaintext -d '{"album_id": "b1392450-e666-3926-a536-22c65f834433"}' localhost:50051 metadata.v1.MetadataService/GetAlbumTracks

Project Structure

├── cmd/server/          # Server entrypoint
├── internal/
│   ├── config/          # YAML configuration
│   ├── domain/          # Domain types
│   ├── provider/        # External API clients
│   │   └── musicbrainz/ # MusicBrainz implementation
│   ├── repository/      # Database access
│   │   └── postgres/    # PostgreSQL implementation
│   ├── server/          # gRPC handlers
│   └── service/         # Business logic (DB-first caching)
├── pkg/gen/             # Generated protobuf code
├── proto/               # Proto definitions
├── database/            # Docker compose + migrations
└── tests/e2e/           # End-to-end tests

Development

# Enter dev shell
nix develop

# Generate protobuf
buf generate

# Run tests
go test ./...

# Run e2e tests (requires network)
go test -v ./tests/e2e/...

License

MIT