# 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

```bash
# Build
nix build .#server

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

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

## Configuration

```yaml
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

```bash
cd database
docker compose up -d
```

PostgreSQL 16 with `pg_prewarm` for automatic cache warming.

## API

```bash
# 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

```bash
# 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