mcma-backend/graphify-out/GRAPH_REPORT.md

# Graph Report - mcma-backend  (2026-07-11)

## Corpus Check
- 180 files · ~52,130 words
- Verdict: corpus is large enough that graph structure adds value.

## Summary
- 1994 nodes · 5692 edges · 133 communities (89 shown, 44 thin omitted)
- Extraction: 90% EXTRACTED · 10% INFERRED · 0% AMBIGUOUS · INFERRED: 573 edges (avg confidence: 0.55)
- Token cost: 0 input · 0 output

## Graph Freshness
- Built from commit: `fb5ce3c7`
- Run `git rev-parse HEAD` and compare to check if the graph is stale.
- Run `graphify update .` after code changes (no API cost).

## Community Hubs (Navigation)
- Storage Backend & Disk Usage
- Auth Schemas & Tokens
- Error Mapping & Search Schemas
- Download Service Orchestration
- Playlist Schemas & API
- Album Repository
- ORM Base & Models
- Correlation ID Middleware & Config
- Auth Services (native + Subsonic)
- Audio Tags & Metadata Test Fakes
- YouTube Source Backend
- Dependency Wiring (deps.py)
- Library Stats & Track Availability
- Library Import Service
- Subsonic Response Envelope
- Chromaprint Fingerprinting
- Album/Search Response Schemas
- Pagination & Likes Endpoints
- Metadata Enrichment Service
- Subsonic ID Encoding
- Track & Artist Domain Entities
- Source Port Protocols
- User Management Service
- Metadata Enrichment Value Objects
- DB Session & Health Checks
- Download Service Tests
- Download Job Domain Entity
- Credentials & User Repository
- Streaming Auth Dependencies
- Subsonic Browsing Endpoints
- Remote Library Service Tests
- Worker Session Scope & Download Task
- Metadata Enrichment Pipeline
- Album Domain & Cover Value Object
- Downloads API Tests
- Subsonic Search Encoding
- In-Memory Auth Repository Fakes
- Storage Stats Response Schemas
- Subsonic App-Password Crypto
- Artist Schemas & Endpoints
- Download Request/Response Schemas
- Settings & MusicBrainz User-Agent
- Subsonic API Integration Tests
- Playlist Endpoints
- Play History Domain & Repository
- DB Engine Lifecycle
- Shared Query Param Annotations
- Local Folder Source Backend
- Track Metadata Match Schemas
- Like Domain Entity (event log)
- Auth API Integration Tests
- Cover API Tests
- Upload/Stream API Tests
- Tag Parsing Helpers
- Metadata API Tests
- Subsonic Auth Service Tests
- Cover Art Serving
- Play History Schemas
- Refresh Token Repository
- Radio Endpoints
- Subsonic Legacy Password Decoding
- Management CLI
- Sources API Tests
- Hexagonal Architecture Layers (doc)
- Test DB Fixtures (conftest)
- Upload Response Schemas
- Cover Art Extraction (Vorbis/MP4)
- Storage Stats API Tests
- AcoustID Response Parser Tests
- Like Request/Response Schemas
- Streaming Endpoint
- Auth Token Issue/Refresh Flow
- Generic Job/Result Store Protocol
- Remote Library Materialization
- CI Docker Publish Workflow
- User Scrobbling Settings
- Domain Invariants (dedup, manual overwrite, offline tags)
- Alembic Migration Environment
- Cover Art Archive Client
- Health Endpoint Smoke Tests
- ASGI Middleware Protocol
- File Hashing Utilities
- Package: app.api
- Package: app.api.schemas
- Package: app.application
- Package: app.core
- Package: app.domain
- Package: app.infrastructure
- Package: metadata-enrichment adapters
- Package: source backends
- Package: storage adapters
- Package: app root (mcma-backend)
- Package: arq worker
- Package: arq tasks
- Config Conventions (doc)
- Subsonic Adapter Convention (doc)
- DB Session Convention (doc)
- Health Convention (doc)
- Invariant: Graceful Degradation
- Invariant: Likes Are Append-Only
- Invariant: Stable Track content_id
- Logging Convention (doc)
- Python 3.14 Lazy Annotations Note
- App-Passwords Mechanism (doc)
- Local Dev Setup (doc)
- Tooling Section (doc)
- app/application — use cases / services
- Composition roots (app/main.py, app/api/deps.py)
- app/core — cross-cutting concerns
- app/domain — pure business core
- Error handling convention (domain errors → HTTP in app/api/errors.py)
- Hexagonal architecture (ports & adapters)
- app/infrastructure — driven adapters
- Invariant: dedup on (source, source_id) and acoustid_fingerprint
- Invariant: no heavy work in the request cycle (goes to arq workers)
- Invariant: never overwrite metadata_status=manual
- Migrations convention (async, settings-driven Alembic)
- app/workers — arq background tasks
- Build (Docker) section
- Hexagonal architecture (ports & adapters) — README
- Database migrations (Alembic) section
- Subsonic API (/rest) section
- acoustid_trust_score (trust high-confidence AcoustID over junk tags)
- Offline tag reader (deterministic, always runs)
- scarlet_fire_otis_mcdonald.mp3 test fixture

## God Nodes (most connected - your core abstractions)
1. `NotFoundError` - 95 edges
2. `UserService` - 57 edges
3. `Track` - 50 edges
4. `AuthenticationError` - 49 edges
5. `TrackRepository` - 49 edges
6. `SourceInfo` - 49 edges
7. `MetadataEnrichmentService` - 47 edges
8. `DownloadResult` - 47 edges
9. `get_settings()` - 46 edges
10. `session_scope()` - 45 edges

## Surprising Connections (you probably didn't know these)
- `test_id_malformed_rejected()` --indirect_call--> `NotFoundError`  [INFERRED]
  tests/test_subsonic_security.py → app/domain/errors.py
- `test_id_wrong_prefix_rejected()` --indirect_call--> `NotFoundError`  [INFERRED]
  tests/test_subsonic_security.py → app/domain/errors.py
- `FakeAcoustId` --uses--> `MetadataEnrichmentService`  [INFERRED]
  tests/test_metadata_service.py → app/application/metadata_service.py
- `FakeAlbumRepo` --uses--> `MetadataEnrichmentService`  [INFERRED]
  tests/test_metadata_service.py → app/application/metadata_service.py
- `FakeArtistRepo` --uses--> `MetadataEnrichmentService`  [INFERRED]
  tests/test_metadata_service.py → app/application/metadata_service.py

## Import Cycles
- None detected.

## Hyperedges (group relationships)
- **Cross-cutting conventions (errors, config, logging, db sessions, migrations, health)** — claude_error_handling_convention, claude_config_convention, claude_logging_convention, claude_db_sessions_convention, claude_migrations_convention, claude_health_convention [EXTRACTED 1.00]
- **Non-negotiable domain invariants (for future sync + ML)** — claude_invariant_likes_event_log, claude_invariant_track_id_stable, claude_invariant_dedup, claude_invariant_graceful_degradation, claude_invariant_no_manual_overwrite, claude_invariant_no_heavy_work_in_request, claude_invariant_subsonic_compatibility [EXTRACTED 1.00]
- **Hexagonal architecture layers (domain/application/infrastructure/api/core/workers)** — claude_domain_layer, claude_application_layer, claude_infrastructure_layer, claude_api_layer, claude_core_layer, claude_workers_layer [EXTRACTED 1.00]

## Communities (133 total, 44 thin omitted)

### Community 0 - "Storage Backend & Disk Usage"
Cohesion: 0.05
Nodes (54): DiskUsage, ObjectStat, Value objects for file storage., Capacity of the volume backing the media store. ``None`` for backends     (e.g., File storage operation failed., StorageError, Capacity of the volume backing the store, or ``None`` when the         backend h, LocalFileStorage (+46 more)

### Community 1 - "Auth Schemas & Tokens"
Cohesion: 0.07
Nodes (59): LoginRequest, BaseModel, Auth request/response schemas. Tokens are returned in the body (the client store, RefreshRequest, RegisterRequest, TokenResponse, BaseModel, Schemas for Subsonic app-password self-service (native /api/v1 surface).  The Su (+51 more)

### Community 2 - "Error Mapping & Search Schemas"
Cohesion: 0.07
Nodes (39): _is_subsonic(), FastAPI, Maps domain exceptions to HTTP responses. The only place that knows both.  Two s, register_exception_handlers(), ExternalSearchResponse, ExternalSearchResultOut, BaseModel, Flat list of hits across one or more searchable sources, plus the names of     s (+31 more)

### Community 3 - "Download Service Orchestration"
Cohesion: 0.07
Nodes (20): DownloadRequest, EnrichEnqueuer, DownloadService — request external downloads and import their results.  Two role, Outcome of asking for a download.      Exactly one of the three states holds: th, EnrichEnqueuer, Path, Protocol, UploadService — handles user file uploads. (+12 more)

### Community 4 - "Playlist Schemas & API"
Cohesion: 0.20
Nodes (28): PlaylistAddTrack, PlaylistCreate, PlaylistOut, PlaylistReorder, PlaylistUpdate, BaseModel, Playlist request/response schemas., add_playlist_track() (+20 more)

### Community 5 - "Album Repository"
Cohesion: 0.06
Nodes (11): AlbumRepository, DownloadJobRepository, LikeRepository, PlaylistRepository, datetime, UUID, Resolve/create an album bound to a remote ``(source, source_id)``         (lazy, Persistence for download jobs (plan §6.1). Drives the §A5 download manager     a (+3 more)

### Community 6 - "ORM Base & Models"
Cohesion: 0.10
Nodes (31): Base, Declarative base with a fixed naming convention.  The naming convention makes Al, Base for all ORM models. Import models so Alembic sees their metadata., ORM model for albums., ORM model for artists., ORM model for download jobs (plan §6.1).  Tracks a queued download through its l, LikeValue, LyricsStatus (+23 more)

### Community 7 - "Correlation ID Middleware & Config"
Cohesion: 0.12
Nodes (17): CorrelationIdMiddleware, HTTP middleware: bind a correlation id and log each request., Pure-ASGI middleware: reuse inbound ``X-Correlation-Id`` or mint one,     bind i, app_version(), User-Agent sent to MusicBrainz/AcoustID: ``MCMA/<version> ( <contact> )``., _add_correlation_id(), configure_logging(), create_app() (+9 more)

### Community 8 - "Auth Services (native + Subsonic)"
Cohesion: 0.09
Nodes (42): EnrichmentResult, AcoustIdClient, AudioFingerprinter, AudioTagReader, CoverArtExtractor, CoverArtProvider, FetchableSource, HistoryRepository (+34 more)

### Community 9 - "Audio Tags & Metadata Test Fakes"
Cohesion: 0.15
Nodes (28): AudioTags, Embedded tags read from the file itself (ID3 / Vorbis / MP4 …).      Every field, _cover_service(), FakeAlbumRepo, FakeArtistRepo, FakeCoverExtractor, FakeCoverProvider, FakeTagReader (+20 more)

### Community 10 - "YouTube Source Backend"
Cohesion: 0.08
Nodes (32): One hit from a searchable source (plan §5), shown on the discover screen.      `, SearchResult, Which backend imported a track. Drives ``is_replaceable`` (plan §6.6)., TrackSource, _default_download(), _default_search(), _libs_available(), Any (+24 more)

### Community 11 - "Dependency Wiring (deps.py)"
Cohesion: 0.11
Nodes (29): get_album_repository(), get_artist_repository(), get_auth_service(), get_download_service(), get_history_repository(), get_like_repository(), get_metadata_service(), get_password_hasher() (+21 more)

### Community 12 - "Library Stats & Track Availability"
Cohesion: 0.13
Nodes (18): FormatBreakdown, LibraryStats, Per-container-format slice of the library (e.g. ``flac`` → 312 tracks)., Aggregate facts about everything the instance has stored. Computed from     the, Track, Whether a track's audio is on local storage or still a remote placeholder     (p, TrackAvailability, TrackModel (+10 more)

### Community 13 - "Library Import Service"
Cohesion: 0.12
Nodes (19): ImportSummary, LibraryImportService, UUID, LibraryImportService — imports files discovered by an indexable source.  Batch s, Source-backend value objects — framework-free.  A *source* is a place tracks com, A single importable file discovered by an indexable source.      ``source_id`` i, SourceFile, ``local`` source — indexes audio files from a mounted folder.  Walks a configure (+11 more)

### Community 14 - "Subsonic Response Envelope"
Cohesion: 0.12
Nodes (30): _build_xml(), _is_json(), Any, Element, Response, The Subsonic response envelope — one serializer, two wire formats.  Every Subson, A ``status="failed"`` envelope carrying a Subsonic ``<error>``., Recursively drop ``None`` values so JSON output matches XML (no empty attrs). (+22 more)

### Community 15 - "Chromaprint Fingerprinting"
Cohesion: 0.09
Nodes (24): AcoustIdHttpClient, Implements :class:`app.domain.ports.AcoustIdClient`., FpcalcFingerprinter, Path, FpcalcFingerprinter — Chromaprint fingerprint via the ``fpcalc`` binary.  ``fpca, Implements :class:`app.domain.ports.AudioFingerprinter`., MutagenTagReader, Implements :class:`app.domain.ports.AudioTagReader`. (+16 more)

### Community 16 - "Album/Search Response Schemas"
Cohesion: 0.12
Nodes (33): AlbumOut, BaseModel, Album request/response schemas., ArtistOut, BaseModel, Artist request/response schemas., PagedResponse, BaseModel (+25 more)

### Community 17 - "Pagination & Likes Endpoints"
Cohesion: 0.13
Nodes (39): MaterializeResponse, MetadataApply, MetadataMatch, MetadataMatchesOut, BaseModel, Track request/response schemas., One AcoustID candidate for the metadata editor's match picker (§A7)., Manual edits / accepted match applied via ``PUT /tracks/{id}/metadata``.      Se (+31 more)

### Community 18 - "Metadata Enrichment Service"
Cohesion: 0.11
Nodes (11): _first_int(), MetadataEnrichmentService, _opt_str(), UUID, MetadataEnrichmentService — the §6.2 pipeline orchestrator.  Order (tag-first):, Explain a ``failed`` (no-identity) run in terms a user can act on:         which, AcoustID candidates for the metadata editor's match picker (§A7).          Read-, Fill in an album cover when it has none. Source order mirrors the         tag-fi (+3 more)

### Community 19 - "Subsonic ID Encoding"
Cohesion: 0.13
Nodes (29): Subsonic annotation endpoints: star/unstar, rating, scrobble.  * ``star``/``unst, decode_album(), decode_artist(), _decode_as(), decode_track(), encode(), encode_track(), IdKind (+21 more)

### Community 20 - "Track & Artist Domain Entities"
Cohesion: 0.10
Nodes (17): Schemas for searching external (fetch) sources — the §A4 discover screen., Artist, Track and Artist domain entities., Resolve/create an artist bound to a remote ``(source, source_id)``         (lazy, ArtistModel, AsyncSession, UUID, Artist repository — adapter over ``AsyncSession``. (+9 more)

### Community 21 - "Source Port Protocols"
Cohesion: 0.18
Nodes (11): Playlist, Playlist domain entity., PlaylistModel, PlaylistTrackModel, A track's membership in a playlist.      ``position`` is a float so a track can, AsyncSession, UUID, Playlist repository — adapter over ``AsyncSession``. (+3 more)

### Community 22 - "User Management Service"
Cohesion: 0.11
Nodes (36): AuthService, _hash_token(), UUID, Authentication use cases: login, token refresh (rotation), logout, and access-to, At-rest hash of a refresh token. A signed JWT is high-entropy, so a fast     SHA, User-management use cases: admin CRUD plus self-service password change.  Deleti, UserService, _cmd_create_admin() (+28 more)

### Community 23 - "Metadata Enrichment Value Objects"
Cohesion: 0.17
Nodes (10): Domain entities and value objects — pure, framework-free., Fingerprint, Value objects for the metadata-enrichment pipeline (plan §6.2).  Pure data carri, Chromaprint fingerprint plus the decoded duration (both needed by AcoustID)., A single AcoustID result, flattened to the fields enrichment cares about.      `, RecordingMatch, _parse_matches(), _parse_one() (+2 more)

### Community 24 - "DB Session & Health Checks"
Cohesion: 0.16
Nodes (17): _check_db(), _check_ml(), _check_redis(), health(), HealthResponse, BaseModel, Response, Health & readiness endpoints — used by compose healthchecks and the admin UI.  * (+9 more)

### Community 25 - "Download Service Tests"
Cohesion: 0.16
Nodes (14): DownloadService, FakeArtistRepo, FakeJobRepo, FakeStorage, FakeTrackRepo, Path, UUID, Unit tests for DownloadService — DB-free, in-memory fakes. (+6 more)

### Community 26 - "Download Job Domain Entity"
Cohesion: 0.13
Nodes (10): DownloadJob, Download job domain entity (plan §6.1).  A queued fetch from an external source,, An unfinished (queued/downloading/enriching) job for the same item, if         a, DownloadJobModel, DownloadStatus, Lifecycle of a download job (plan §6.1)., datetime, UUID (+2 more)

### Community 27 - "Credentials & User Repository"
Cohesion: 0.10
Nodes (20): get_current_superuser(), get_current_user(), get_streaming_user(), AuthServiceDep, CurrentUser, Authenticate a stream request.      The browser ``<audio>`` element cannot send, Credentials, User entity.  Admin is a single ``is_superuser`` flag — no role system in Phase (+12 more)

### Community 28 - "Streaming Auth Dependencies"
Cohesion: 0.31
Nodes (4): UUID, Admin-driven password reset. Revokes all sessions., Soft delete: disable the account, keep the row for referential history., Self-service change: verify the current password first.

### Community 29 - "Subsonic Browsing Endpoints"
Cohesion: 0.26
Nodes (26): _albums_for_artist(), _artists_index(), _decorate_albums(), get_album(), get_album_list(), get_album_list2(), get_artist(), get_artists() (+18 more)

### Community 30 - "Remote Library Service Tests"
Cohesion: 0.21
Nodes (17): RemoteLibraryService, Input is well-formed but violates a business rule., ValidationError, FakeArtistRepo, FakeJobRepo, FakeTrackRepo, _local_track(), UUID (+9 more)

### Community 31 - "Worker Session Scope & Download Task"
Cohesion: 0.21
Nodes (24): Transactional session for workers/scripts: commit on success, rollback on error., session_scope(), AsyncSession, SqlAlchemyDownloadJobRepository, build_source_registry(), download_track(), _handle_failure(), _import_result() (+16 more)

### Community 33 - "Album Domain & Cover Value Object"
Cohesion: 0.17
Nodes (10): Album, AlbumModel, AsyncSession, UUID, Album repository — adapter over ``AsyncSession``., Resolve an album by ``(title, artist_id)``, creating it if absent.         Backf, Resolve an album by ``(source, source_id)`` first (re-browse/save         dedup), SqlAlchemyAlbumRepository (+2 more)

### Community 34 - "Downloads API Tests"
Cohesion: 0.15
Nodes (19): MonkeyPatch, api(), _db_reachable(), FakeFetchSource, _login(), Any, AsyncClient, Path (+11 more)

### Community 35 - "Subsonic Search Encoding"
Cohesion: 0.14
Nodes (22): encode_album(), encode_artist(), Subsonic-compatible API layer mounted at /rest., AlbumRepoDep, ArtistRepoDep, ge, le, Query (+14 more)

### Community 36 - "In-Memory Auth Repository Fakes"
Cohesion: 0.13
Nodes (8): InMemoryRefreshTokenRepository, InMemoryUserRepository, datetime, UUID, In-memory port implementations for fast, DB-free unit tests., _Stored, _Token, env()

### Community 37 - "Storage Stats Response Schemas"
Cohesion: 0.15
Nodes (20): DiskUsageOut, FormatBreakdownOut, GenreCountOut, BaseModel, Storage / library statistics response schemas (§A6)., Everything the Storage screen needs in a single call., StorageStatsOut, get_broken_files() (+12 more)

### Community 38 - "Subsonic App-Password Crypto"
Cohesion: 0.19
Nodes (10): generate_subsonic_password(), A fresh, high-entropy Subsonic app-password (url-safe, ~24 chars)., Unit tests for Subsonic crypto + id helpers (no DB, no network)., The decrypted app-password must reproduce a client's t=md5(password+salt)., test_cipher_roundtrip(), test_cipher_token_then_md5_matches(), test_cipher_wrong_key_fails(), test_generate_subsonic_password_is_long_and_unique() (+2 more)

### Community 39 - "Artist Schemas & Endpoints"
Cohesion: 0.19
Nodes (14): enqueue(), enqueue_download(), enqueue_enrich(), enqueue_materialize(), Any, UUID, Enqueue helper — submit a job to the arq queue from the request cycle.  A short-, Enqueue ``function`` by name, returning the job id. Raises     :class:`Dependenc (+6 more)

### Community 40 - "Download Request/Response Schemas"
Cohesion: 0.23
Nodes (17): DownloadCreate, DownloadCreateResponse, DownloadJobOut, BaseModel, Schemas for the download job endpoints (§A5 download manager)., Request to download an item discovered on a fetch source., Result of requesting a download.      ``already_in_library`` → the item was alre, cancel_download() (+9 more)

### Community 41 - "Settings & MusicBrainz User-Agent"
Cohesion: 0.16
Nodes (14): Settings, Argon2PasswordHasher, JwtTokenService, Security adapters: password hashing (argon2 via pwdlib) and JWT (pyjwt).  These, argon2id hasher with sensible defaults from pwdlib., Issues and verifies HS256 JWTs for access + refresh tokens.      TTLs come from, BaseSettings, Unit tests for the security adapters (no DB, no network). (+6 more)

### Community 42 - "Subsonic API Integration Tests"
Cohesion: 0.28
Nodes (18): _auth_params(), _login(), AsyncClient, Integration tests for the Subsonic /rest layer (happy path per endpoint group)., _seed_track(), _setup(), _subsonic_password(), test_get_album_list2() (+10 more)

### Community 43 - "Playlist Endpoints"
Cohesion: 0.31
Nodes (19): decode_playlist(), encode_playlist(), create_playlist(), delete_playlist(), get_playlist(), get_playlists(), _owned_playlist(), _playlist_dict() (+11 more)

### Community 44 - "Play History Domain & Repository"
Cohesion: 0.25
Nodes (9): PlayHistoryEntry, Play history domain entity — append-only scrobble log entry., PlayHistoryModel, AsyncSession, datetime, UUID, Play history repository — adapter over ``AsyncSession``., SqlAlchemyHistoryRepository (+1 more)

### Community 45 - "DB Engine Lifecycle"
Cohesion: 0.17
Nodes (17): dispose_engine(), get_engine(), get_sessionmaker(), AsyncSession, Async engine + session factory, created lazily from settings.  The engine is pro, Dispose the pooled engine on shutdown. Safe to call if never initialized., Database adapter: declarative base, async engine, session factory., async_sessionmaker (+9 more)

### Community 46 - "Shared Query Param Annotations"
Cohesion: 0.31
Nodes (13): ge, HistoryRepoDep, le, LikeRepoDep, Query, Response, SubsonicFormat, SubsonicUser (+5 more)

### Community 47 - "Local Folder Source Backend"
Cohesion: 0.21
Nodes (12): LocalFolderSource, Path, Implements :class:`app.domain.ports.IndexableSource`., Path, Unit tests for the local-folder source + registry (no DB, no network)., _settings(), test_info_reports_kind_and_availability(), test_is_available_false_when_missing() (+4 more)

### Community 48 - "Track Metadata Match Schemas"
Cohesion: 0.45
Nodes (13): _create_playlist(), _login(), Any, AsyncClient, Integration tests for the v1 playlist API.  Requires a reachable Postgres; skips, test_add_track_idempotent(), test_playlist_lifecycle(), test_remove_track() (+5 more)

### Community 49 - "Like Domain Entity (event log)"
Cohesion: 0.27
Nodes (8): Like, Like domain entity — append-only event log entry., LikeModel, AsyncSession, UUID, Like repository — adapter over ``AsyncSession``.  Likes are an append-only event, SqlAlchemyLikeRepository, _to_entity()

### Community 50 - "Auth API Integration Tests"
Cohesion: 0.24
Nodes (17): api(), _db_reachable(), _login(), AsyncClient, Integration tests for the auth + admin HTTP surface.  These require a reachable, test_admin_create_duplicate_conflicts(), test_admin_creates_user_and_nonadmin_forbidden(), test_deactivated_user_cannot_login() (+9 more)

### Community 51 - "Cover API Tests"
Cohesion: 0.30
Nodes (14): api(), _db_reachable(), _login(), AsyncClient, Path, UUID, Integration tests for the native cover-art endpoints.  Seeds an album with a sto, Create an artist + album (+ optional cover file) + track. Returns     ``(album_i (+6 more)

### Community 52 - "Upload/Stream API Tests"
Cohesion: 0.29
Nodes (14): api(), _db_reachable(), _login(), AsyncClient, Path, Integration tests for upload and streaming endpoints.  Requires a reachable Post, test_list_tracks_filters_by_source(), test_stream_full() (+6 more)

### Community 53 - "Tag Parsing Helpers"
Cohesion: 0.25
Nodes (10): _first(), _parse_track_number(), _parse_year(), Path, MutagenTagReader — reads embedded tags from a local audio file.  The offline fir, EasyXxx tags expose values as lists; take the first non-empty string., Unit tests for the mutagen tag-parsing helpers — pure, no files., test_first_takes_head_of_list() (+2 more)

### Community 54 - "Metadata API Tests"
Cohesion: 0.35
Nodes (13): api(), _db_reachable(), _login(), AsyncClient, Path, Integration tests for the metadata-editor endpoints (§A7, §1H).  Requires a reac, test_apply_metadata_not_found(), test_apply_metadata_partial_update() (+5 more)

### Community 55 - "Subsonic Auth Service Tests"
Cohesion: 0.15
Nodes (18): UUID, Symmetric encrypt/decrypt for the recoverable Subsonic app-password.      Subson, SubsonicPasswordCipher, _md5(), Unit tests for SubsonicAuthService — verification + app-password lifecycle.  DB-, _service_with_user(), test_authenticate_enc_password_success(), test_authenticate_inactive_user_fails() (+10 more)

### Community 56 - "Cover Art Serving"
Cohesion: 0.14
Nodes (16): _content_type_for(), StreamingResponse, UUID, Shared cover-art serving helper (presentation).  Streams a stored cover image fr, Stream a stored cover by its storage key. Raises ``NotFoundError`` if the     ob, The album that owns a track (cover lives on the album), or ``None``., resolve_album_for_track(), stream_cover() (+8 more)

### Community 57 - "Play History Schemas"
Cohesion: 0.24
Nodes (11): HistoryIn, HistoryOut, BaseModel, Play history request/response schemas., get_history(), CurrentUser, HistoryRepoDep, Response (+3 more)

### Community 58 - "Refresh Token Repository"
Cohesion: 0.27
Nodes (5): AsyncSession, datetime, UUID, Refresh-token repository — adapter implementing ``app.domain.ports.RefreshTokenR, SqlAlchemyRefreshTokenRepository

### Community 59 - "Radio Endpoints"
Cohesion: 0.20
Nodes (9): Native REST API, version 1. Aggregates feature routers under ``/api/v1``., next_radio_track(), Any, Radio / continuous-mix endpoints. Degrades gracefully when ML service is down., start_radio(), get_changes(), push_changes(), Any (+1 more)

### Community 60 - "Subsonic Legacy Password Decoding"
Cohesion: 0.23
Nodes (9): _decode_legacy_password(), _md5_hex(), UUID, SubsonicAuthService — app-password lifecycle + Subsonic auth verification.  The, Decode a Subsonic ``p`` param: ``enc:<hex>`` (hex-encoded) or plaintext., Resolve Subsonic query auth params to a domain :class:`User`.          Raises :c, Generate a fresh app-password, store it encrypted, return the plaintext., Return the current app-password, generating one on first access. (+1 more)

### Community 61 - "Management CLI"
Cohesion: 0.20
Nodes (4): PasswordHasher, True iff a row exists for ``jti`` that is neither revoked nor expired., Verify ``password`` against ``password_hash``. Returns         ``(is_valid, upda, RefreshTokenRepository

### Community 62 - "Sources API Tests"
Cohesion: 0.36
Nodes (9): api(), _db_reachable(), _login(), AsyncClient, Path, Integration tests for sources: enumeration + the real import path.  Requires a r, test_list_sources_includes_local(), test_local_import_creates_streamable_tracks() (+1 more)

### Community 64 - "Test DB Fixtures (conftest)"
Cohesion: 0.20
Nodes (11): _base_database_url(), client(), _create_test_db_if_missing(), _ensure_test_database(), AsyncClient, Shared test fixtures.  The ASGI app is driven in-process via httpx + asgi-lifesp, Resolve the DB URL the app *would* use, mirroring pydantic-settings     preceden, Return ``url`` with its database name swapped for ``name``. (+3 more)

### Community 65 - "Upload Response Schemas"
Cohesion: 0.22
Nodes (9): BaseModel, Schemas for upload responses., UploadResponse, CurrentUser, Local file upload endpoint., upload_file(), File, UploadFile (+1 more)

### Community 66 - "Cover Art Extraction (Vorbis/MP4)"
Cohesion: 0.23
Nodes (10): _decode_vorbis_picture(), _from_picture(), _front_or_first(), MutagenCoverExtractor, Any, Path, MutagenCoverExtractor — pulls embedded cover art from a local audio file.  The o, Prefer the front-cover picture (type 3), else the first available. (+2 more)

### Community 67 - "Storage Stats API Tests"
Cohesion: 0.35
Nodes (10): api(), _db_reachable(), _login(), AsyncClient, Path, Integration tests for the storage statistics endpoint (§A6).  Requires a reachab, test_storage_stats_counts_uploads(), test_storage_stats_empty_library() (+2 more)

### Community 68 - "AcoustID Response Parser Tests"
Cohesion: 0.42
Nodes (9): _parse_best_match(), _payload_with_results(), Unit tests for the AcoustID response parser — pure, no network., test_empty_results_returns_none(), test_error_status_returns_none(), test_non_dict_payload_returns_none(), test_parses_full_recording(), test_picks_highest_score() (+1 more)

### Community 69 - "Like Request/Response Schemas"
Cohesion: 0.25
Nodes (12): LikeEvent, LikeState, BaseModel, Like request/response schemas., add_like(), get_likes(), get_likes_state(), AlbumRepoDep (+4 more)

### Community 70 - "Streaming Endpoint"
Cohesion: 0.25
Nodes (8): alias, Header, StreamingResponse, StreamingServiceDep, StreamUser, UUID, Audio streaming endpoint — direct stream with Range support., stream_track()

### Community 71 - "Auth Token Issue/Refresh Flow"
Cohesion: 0.22
Nodes (3): FakeFingerprinter, FakeStorage, Path

### Community 72 - "Generic Job/Result Store Protocol"
Cohesion: 0.25
Nodes (3): UUID, Remove the job record. True mid-flight cancellation of an in-progress         yt, Store a freshly downloaded file and create a minimal ``pending`` track.

### Community 73 - "Remote Library Materialization"
Cohesion: 0.25
Nodes (6): MaterializeOutcome, UUID, RemoteLibraryService — save-to-library + materialize for remote browse hits (pla, Result of requesting materialization.      ``job`` is ``None`` when the track is, Persist a placeholder for a remote browse hit. Idempotent: a hit         already, Kick off (or report on) materializing a placeholder track.          Already-loca

### Community 74 - "CI Docker Publish Workflow"
Cohesion: 0.33
Nodes (7): Docker Buildx, dockerfiles/Dockerfile.prod, Gitea container registry, build job (Docker Build & Publish), cleanup job (Prune old image versions), KEEP_VERSIONS env (retention policy), push job (Docker Build & Publish)

### Community 75 - "User Scrobbling Settings"
Cohesion: 0.43
Nodes (6): get_scrobbling_settings(), get_settings(), Any, User settings endpoints, including scrobbling configuration., set_scrobbling_settings(), update_settings()

### Community 76 - "Domain Invariants (dedup, manual overwrite, offline tags)"
Cohesion: 0.18
Nodes (10): App-passwords, Architecture — hexagonal (ports & adapters), Build (Docker), Configuration, Database migrations (Alembic), Local dev (without Docker), mcma-backend, Sources & importing music (+2 more)

### Community 77 - "Alembic Migration Environment"
Cohesion: 0.13
Nodes (17): Alembic environment — async, settings-driven, model-aware.  The DB URL comes fro, _run_migrations(), run_migrations_online(), get_source_registry(), get_settings(), Application settings — single source of truth, sourced from environment.  Nothin, Cached settings singleton. Patch the cache in tests via ``get_settings.cache_cle, get_file_storage() (+9 more)

### Community 78 - "Cover Art Archive Client"
Cohesion: 0.21
Nodes (6): get_logger(), Structured logging via structlog.  Emits key=value (dev) or JSON (prod) with a p, CoverArtArchiveClient, CoverArtArchiveClient — fetches front cover art from the Cover Art Archive.  The, Implements :class:`app.domain.ports.CoverArtProvider`., FilteringBoundLogger

### Community 79 - "Health Endpoint Smoke Tests"
Cohesion: 0.47
Nodes (5): AsyncClient, Smoke tests for the health endpoints., test_correlation_id_echoed(), test_liveness_ok(), test_readiness_reports_checks()

### Community 80 - "ASGI Middleware Protocol"
Cohesion: 0.22
Nodes (7): Architecture — hexagonal (ports & adapters), Commands, Cross-cutting conventions, graphify, Non-negotiable domain invariants, Python 3.14 note, What this is

### Community 81 - "File Hashing Utilities"
Cohesion: 0.50
Nodes (3): Path, File hashing utilities., sha256_of_file()

### Community 110 - "App-Passwords Mechanism (doc)"
Cohesion: 0.29
Nodes (8): AlbumRepoDep, ArtistRepoDep, CurrentUser, SourceRegistryDep, TrackRepoDep, Search every available fetch source and merge the hits (§A4 discover).      A so, search(), search_library()

## Knowledge Gaps
- **32 isolated node(s):** `WorkerSettings`, `What this is`, `Commands`, `Cross-cutting conventions`, `Non-negotiable domain invariants` (+27 more)
  These have ≤1 connection - possible missing edges or undocumented components.
- **44 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.

## Suggested Questions
_Questions this graph is uniquely positioned to answer:_

- **Why does `NotFoundError` connect `Subsonic ID Encoding` to `Error Mapping & Search Schemas`, `Download Service Orchestration`, `Playlist Schemas & API`, `Auth Services (native + Subsonic)`, `Library Stats & Track Availability`, `Album/Search Response Schemas`, `Pagination & Likes Endpoints`, `Source Port Protocols`, `User Management Service`, `Download Service Tests`, `Credentials & User Repository`, `Streaming Auth Dependencies`, `Subsonic Browsing Endpoints`, `Remote Library Service Tests`, `Worker Session Scope & Download Task`, `Subsonic App-Password Crypto`, `Playlist Endpoints`, `Shared Query Param Annotations`, `Cover Art Serving`, `Play History Schemas`, `Subsonic Legacy Password Decoding`, `Generic Job/Result Store Protocol`, `Remote Library Materialization`?**
  _High betweenness centrality (0.117) - this node is a cross-community bridge._
- **Why does `get_settings()` connect `Alembic Migration Environment` to `Auth Schemas & Tokens`, `Downloads API Tests`, `Storage Stats API Tests`, `Correlation ID Middleware & Config`, `Artist Schemas & Endpoints`, `Settings & MusicBrainz User-Agent`, `Subsonic API Integration Tests`, `Dependency Wiring (deps.py)`, `DB Engine Lifecycle`, `Chromaprint Fingerprinting`, `Track Metadata Match Schemas`, `Auth API Integration Tests`, `Cover API Tests`, `Upload/Stream API Tests`, `Metadata API Tests`, `DB Session & Health Checks`, `Sources API Tests`, `Worker Session Scope & Download Task`?**
  _High betweenness centrality (0.069) - this node is a cross-community bridge._
- **Why does `UserService` connect `User Management Service` to `Downloads API Tests`, `Storage Stats API Tests`, `In-Memory Auth Repository Fakes`, `Album Repository`, `Subsonic API Integration Tests`, `Dependency Wiring (deps.py)`, `DB Engine Lifecycle`, `Track Metadata Match Schemas`, `Auth API Integration Tests`, `Subsonic ID Encoding`, `Cover API Tests`, `Upload/Stream API Tests`, `Metadata API Tests`, `Credentials & User Repository`, `Streaming Auth Dependencies`, `Management CLI`, `Sources API Tests`?**
  _High betweenness centrality (0.044) - this node is a cross-community bridge._
- **Are the 22 inferred relationships involving `NotFoundError` (e.g. with `IdKind` and `DownloadRequest`) actually correct?**
  _`NotFoundError` has 22 INFERRED edges - model-reasoned connections that need verification._
- **Are the 7 inferred relationships involving `UserService` (e.g. with `AlreadyExistsError` and `AuthenticationError`) actually correct?**
  _`UserService` has 7 INFERRED edges - model-reasoned connections that need verification._
- **Are the 25 inferred relationships involving `AuthenticationError` (e.g. with `AuthService` and `SubsonicAuthService`) actually correct?**
  _`AuthenticationError` has 25 INFERRED edges - model-reasoned connections that need verification._
- **What connects `Alembic environment — async, settings-driven, model-aware.  The DB URL comes fro`, `mcma-backend — self-hosted, offline-first music service.  Hexagonal (ports & ada`, `Driving adapter — FastAPI routers, schemas, dependency wiring.` to the rest of the system?**
  _376 weakly-connected nodes found - possible documentation gaps or missing edges._