Almagest

Content-Based Similarity

For any item in the catalog, Almagest scores every other item across multiple signals and returns the strongest matches. The scoring weights shared people highest — if two movies share a director or two books share an author, that's a strong connection. Shared genres, year proximity, and media type each add additional signal.

Cross-Media Relations

Beyond similarity scoring, Almagest maintains explicit typed relationships between media items. These are discovered automatically through knowledge graph queries and AI-assisted detection, then stored as first-class links in the catalog.

A user looking at "The Lord of the Rings" (book) is one click away from the film trilogy, the animated adaptation, the TV series prequel, and the author's other works — all linked automatically.

Random Discovery

Sometimes the best recommendation is a surprise. The random discovery endpoint returns items the user would never have searched for, optionally filtered by type or genre. With 43 million items in the catalog, there's always something new to find.

Collection Trackers

Track what you own, what you've read or watched, and what's missing from a series. The catalog handles identity and completeness so the app can focus on the experience.

Recommendation Engines

Build personalized suggestions on top of clean, cross-referenced metadata. Know that a user who liked the book will probably want to know about the film.

Family Libraries

Shared catalogs where family members track their own media across formats. One family's books, movies, and shows in a single organized view.

Discovery Tools

Search across media types to find everything related to a topic, creator, or franchise. The cross-media linking makes exploration natural.

Worker

Background process that ingests metadata, runs AI cleaning pipelines, detects series relationships, and selects cover art

Catalog Database

PostgreSQL stores the canonical catalog with full-text search, relationship graphs, and change history

API Server

Go HTTP server exposes the catalog via RESTful endpoints with search, filtering, and pagination

GET /api/v1/search?q=tolkien&limit=3

{
  "hits": [
    { "id": "48846224", "type": "book", "title": "Tolkien" },
    { "id": "50388879", "type": "book", "title": "Tolkien" },
    { "id": "50718028", "type": "book", "title": "Tolkien" }
  ],
  "total": 376,
  "facets": {
    "type": { "book": 358, "movie": 18 },
    "genres": { "Fantasy": 9, "Fiction": 18, "Biography": 17, ... }
  },
  "processing_time_ms": 294
}

GET /api/v1/autocomplete?q=dark+kni&limit=3

{
  "query": "dark kni",
  "suggestions": [
    { "id": "48832461", "type": "book", "title": "Dark Knight Color by Number" },
    { "id": "49103633", "type": "book", "title": "Dark Knight Returns (Batman" },
    { "id": "49284820", "type": "book", "title": "Dark Knights" }
  ]
}

GET /api/v1/media?type=movie&genre=sci-fi&limit=3

{
  "data": [
    {
      "id": 73905792, "type": "movie",
      "title": "Alien Nation: Body and Soul",
      "year": 1995,
      "cover_path": "media/a1/33/a133ad37...jpg"
    },
    {
      "id": 73905793, "type": "movie",
      "title": "Alien Nation: Dark Horizon",
      "year": 1994,
      "cover_path": "media/b4/72/b472d4ad...jpg"
    },
    {
      "id": 73905794, "type": "movie",
      "title": "Alien Nation: Millennium",
      "year": 1996,
      "cover_path": "media/1b/4a/1b4a0ebd...jpg"
    }
  ],
  "total": 19, "limit": 3, "offset": 0
}

GET /api/v1/series/search?q=harry+potter

{
  "data": [
    { "id": 1543, "title": "Harry Potter", "media_count": 1 },
    { "id": 384, "title": "Harry Potter (canon divergent fan fiction)", "media_count": 1 }
  ],
  "query": "harry potter"
}