metadata-agregator/docs/research/minimediametadataapi/analysis/OVERVIEW.md

MiniMediaMetadataAPI - Project Overview

Project Identity

Name: MiniMediaMetadataAPI
Repository: https://github.com/MusicMoveArr/MiniMediaMetadataAPI
License: GPL-3.0 (copyleft)
Maintainer: Single maintainer (MusicMoveArr organization)
Status: Active development

Technology Stack

Runtime & Language

• .NET 8.0 (SDK 8.0.0)
• C# (modern language features)
• ASP.NET Core web framework

Database Layer

• PostgreSQL as primary data store
• Dapper 2.1.72 micro-ORM (NOT Entity Framework)
• Npgsql 10.0.2 PostgreSQL driver for .NET
• pg_trgm extension for fuzzy text search

Core Dependencies

Package	Version	Purpose
Dapper	2.1.72	Lightweight ORM, SQL mapping
Npgsql	10.0.2	PostgreSQL connectivity
FuzzySharp	2.0.2	String similarity matching
Polly	8.6.6	Resilience and transient fault handling
Quartz	3.17.0	Job scheduling framework
SpotifyAPI.Web.Auth	7.4.2	Spotify authentication (unused in API)
prometheus-net	8.2.1	Metrics collection and export
Swashbuckle	10.1.7	OpenAPI/Swagger documentation

Provider Coverage

The API aggregates metadata from 6 music providers:

1. Spotify - Streaming service with rich metadata
2. Tidal - High-fidelity streaming platform
3. MusicBrainz - Open music encyclopedia
4. Deezer - European streaming service
5. Discogs - Music database and marketplace
6. SoundCloud - User-generated content platform

Each provider has dedicated database models and repository implementations.

Solution Structure

The codebase is organized into 3 projects:

1. MiniMediaMetadataAPI (Main API)

• ASP.NET Core web application
• Controllers for HTTP endpoints
• Middleware for request processing
• Configuration and dependency injection
• Entry point: Program.cs

2. MiniMediaMetadataAPI.Application (Business Logic)

• Repository pattern implementations
• Service layer (SearchArtist, SearchAlbum, SearchTrack)
• Database models for all 6 providers
• Entity models for API responses
• Helper utilities

3. MiniMediaMetadataAPI.Tests (Testing)

• xUnit test framework
• Current state: Empty stub only (0% coverage)

Dependency Injection Configuration

Program.cs registers the following components:

Repositories (7 total)

• ISpotifyRepository → SpotifyRepository
• ITidalRepository → TidalRepository
• IMusicBrainzRepository → MusicBrainzRepository
• IDeezerRepository → DeezerRepository
• IDiscogsRepository → DiscogsRepository
• ISoundCloudRepository → SoundCloudRepository
• IJobRepository → JobRepository

Services (3 total)

• ISearchArtistService → SearchArtistService
• ISearchAlbumService → SearchAlbumService
• ISearchTrackService → SearchTrackService

Resource Footprint

Memory Usage: <250MB
Connection Pooling: MinPoolSize=5, MaxPoolSize=100

This lightweight footprint makes the API suitable for containerized deployments and resource-constrained environments.

Database Relationship

Critical architectural note: This API does NOT own the database schema.

• Schema Owner: MiniMediaScanner (separate project)
• API Role: Read-only consumer
• Data Sync: Handled entirely by MiniMediaScanner
• No Migrations: This project contains no database migration code

The API queries pre-populated tables. Data freshness depends on MiniMediaScanner's sync schedule.

Codebase Metrics

• Total C# files: 99
• Database models: 60+
• Controllers: 4
• Repositories: 7
• Services: 3
• Middleware: 1 (Prometheus request tracking)

Key Architectural Decisions

Why Dapper over Entity Framework?

• Lightweight, minimal overhead
• Direct SQL control for complex queries
• Better performance for read-heavy workloads
• No change tracking overhead (read-only API)

Why Repository Pattern?

• Clean separation between data access and business logic
• Provider-specific implementations isolated
• Easy to mock for testing (though tests are missing)
• Consistent interface across all providers

Why No Schema Ownership?

• Separation of concerns: MiniMediaScanner handles sync complexity
• API focuses on query optimization and response formatting
• Avoids dual-write problems
• Simpler deployment (no migration coordination)

Integration Points

External Dependencies

• PostgreSQL database (shared with MiniMediaScanner)
• Prometheus metrics collector (optional)

Internal Dependencies

• No inter-service communication
• No message queues
• No caching layer
• No external API calls (data pre-populated)

Configuration Surface

Primary configuration via appsettings.json:

{
  "DatabaseConfiguration": {
    "ConnectionString": "Host=...;Database=...;Username=...;Password=..."
  },
  "Prometheus": {
    "MetricsUrl": "/metrics"
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

Deployment Artifacts

• Dockerfile: Multi-stage build, non-root user, ports 8080/8081
• compose.yaml: Minimal build configuration
• Production compose: Port mapping (56232:8080), memory limit (256M), volume mount for config

CI/CD Pipeline

GitHub Actions: docker-image.yml

• Trigger: Push to main branch
• Steps: Build Docker image → Push to Docker Hub
• Missing: Test execution, deployment automation, health checks

API Surface

Base Path: /api
Documentation: /swagger (Swagger UI)
Metrics: /metrics (Prometheus format)

Endpoints

• GET /api/SearchArtist - Search artists across providers
• GET /api/SearchAlbum - Search albums across providers
• GET /api/SearchTrack - Search tracks across providers
• GET /api/Search - Stub endpoint (not implemented)

Security Posture

Authentication: None (fully open API)
Authorization: None
Rate Limiting: None
CORS: Not configured
HTTPS: Commented out in production

This is a trust-based deployment suitable only for internal networks or behind authentication gateway.

Observability

Metrics: Prometheus request counters (path, method, status labels)
Logging: ASP.NET Core default (console output)
Tracing: None
Health Checks: None
Error Tracking: None (no Sentry, no structured logging)

Testing Strategy

Current State: No meaningful tests
Test Framework: xUnit configured but unused
Coverage: 0%
CI Integration: Tests not run in pipeline

This is a significant gap for production readiness.

License Implications

GPL-3.0 is a copyleft license requiring:

• Source code disclosure for derivative works
• Same license for modifications
• Patent grant to users

Impact on integration:

• Cannot incorporate code into proprietary systems without GPL compliance
• Can use as separate service (API boundary preserves license isolation)
• Database schema and API patterns can inspire clean-room implementations

Relevance to metadata-aggregator Project

High relevance - this is the closest existing implementation to our goals:

1. Multi-provider aggregation - exactly our use case
2. Unified search API - provider-agnostic queries
3. Database schema design - proven model for multi-provider storage
4. Provider isolation - clean separation via repository pattern
5. Fuzzy search - pg_trgm implementation reference

Key learnings:

• Repository-per-provider scales well
• Dapper performs well for read-heavy metadata queries
• Separate sync process (MiniMediaScanner) simplifies API
• Provider=Any pattern enables cross-provider search

Gaps to address:

• Add comprehensive testing
• Implement authentication/authorization
• Add caching layer for performance
• Health checks for production readiness
• API versioning for evolution
• Rate limiting for abuse prevention

Project Maturity Assessment

Strengths:

• Clean architecture
• Multiple providers working
• Lightweight and performant
• Good separation of concerns

Weaknesses:

• Single maintainer risk
• No test coverage
• Missing production hardening (auth, rate limiting, health checks)
• Schema coupling with external project
• Limited observability

Maturity Level: Early production / Advanced prototype

Suitable for internal use or as reference implementation. Needs hardening for public deployment.