Alexander
de674376ed
- 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
105 lines
2.5 KiB
Markdown
105 lines
2.5 KiB
Markdown
# 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
|