feat: initial implementation of metadata aggregator

- gRPC service with MusicBrainz provider - PostgreSQL schema with migrations - Service layer with database-first caching - Repository pattern for data access - YAML configuration support - Research documentation for 17 music metadata projects
2026-04-28 16:27:14 +02:00
parent a1f6701bac
commit de674376ed
5 changed files with 686 additions and 0 deletions
@@ -0,0 +1,104 @@
+# 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