libexhq/libex

1. What this service is

Libex is a Python API service that fronts Audible metadata. The core architecture is a FastAPI application that accepts book/author/series/narrator/search requests, fetches fresh data from Audible when needed, persists successful responses in PostgreSQL, and exposes a separate set of endpoints that query the local library only.

2. Primary request path

Most public endpoints follow the same flow: HTTP request → route layer with Pydantic schemas → service layer → cache/database lookup → Audible fetch if needed → normalize/enrich response → write to PostgreSQL → return response. That “fetch fresh, then persist” pattern is central to the design.

3. API boundary and routing

app/api/routes is organized by resource: books, authors, series, narrators, search, db, internal, and health/db utility routes. The route layer is the external contract and also handles compatibility details like region-prefixed search paths for Audiobookshelf and legacy endpoint aliases.

4. Audible integration boundary

app/services/audible contains the outbound integration with Audible. It is split by concern (client, books, authors, series, search) so the API layer does not talk to Audible directly. This is the main external dependency for live metadata, and it is the source of truth when data is requested.

5. Persistent data layer

app/db defines the relational model, async session management, and base metadata. PostgreSQL is the only backing datastore. The schema stores books, authors, series, narrators, genres, pivots/relationships, cache entries, and enrichment fields such as narrator profile metadata, plans, and virtual voice flags.

6. Read/write separation

app/services/db/reader.py and writer.py separate query logic from mutation logic. Readers power the /db/* endpoints and fallback lookup paths; writers persist freshly fetched Audible objects and related relationships. This boundary makes it easier to reason about “local library query” versus “ingest/update” behavior.

7. Cache subsystem

app/services/cache/manager.py implements an application-level cache backed by PostgreSQL, not Redis. Cache behavior is configurable via TTL and enable/disable flags. It sits between request handling and external fetches to reduce repeated Audible calls, but the local database remains the durable record even after cache expiry.

8. Background ingestion / seeding

app/services/seeder.py supports a background expansion process that walks relationships and discovers additional content over time. It is controlled by environment flags and intervals, and it uses the same Audible and database services as the request path. The internal API route likely provides a protected way to trigger or manage this behavior.

9. Cross-cutting concerns

app/core contains configuration, middleware, logging, exception handling, and shared utilities. These modules define the operational envelope around the API: environment-driven config, request/response middleware, structured logging, and consistent API error mapping.

10. Schema evolution and deployments

The repository is migration-driven with Alembic under migrations/, indicating a stable relational schema that evolves over time. The Dockerfile, docker-compose.yml, and GitHub Actions workflows show that the service is meant to run as a containerized API with PostgreSQL, with CI covering tests and publication.

11. Data enrichment

Narrator records are not just mirrored from Audible; they are augmented with external profile data from NarratorList/AussieNarrator when available. That enrichment is persisted and then exposed through the DB/narrator endpoints, adding a secondary metadata source to the main Audible pipeline.

12. Testing boundaries

The tests/ tree mirrors the main subsystems: API routes, services, cache behavior, DB reader/writer, exceptions, and health checks. That structure reflects the architecture: contract tests at the HTTP layer, unit tests around service orchestration, and lower-level tests for persistence and utilities.