TAKE-RFC-001 — Koder Take Architecture Overview

• Status: Draft
• Date: 2026-04-27
• Scope: Architecture for Koder Take, the Koder Stack's flagship cinéfilo social network (films, series, documentaries, anime, stand-up).
• Related RFCs: id-RFC-006-identity-service.md, recsys-RFC-001 (in services/ai/recsys/docs/rfcs/), kdb-RFC-014-graph-and-timeseries.md

Summary

Koder Take is the consumer-facing product slot for the audiovisual social network vertical of the Suite. It is the Letterboxd / Trakt / TVTime equivalent inside the Koder Stack — a diary, rating system, list builder, and recommendation engine for everything narrative on a screen. This RFC defines the architecture and the seams against existing Koder modules (Play, Tune, Cine, recsys, kdb, id, billing) so implementation tickets can be opened with confidence.

Two assertions shape the design:

1. Take is a separate product, not a feature of Cine. Cine is a B2B engine for cinema operations (tickets, programming, concession). Take is a B2C social product. They share identity (Koder ID), catalog (kdb-backed), and integrate via well-defined seams (Cine ticket purchase → Take diary entry), but they ship independently, brand independently, and reach independently.
2. Take consumes ai/recsys; it does not own a recommender. Recommendations are computed by ai/recsys (the same engine that powers Play and Tune). Take's job is the interface to the recommender (rating capture, multi-aspect "similar to" anchoring, filter UX, score breakdown display) and the social graph that feeds collaborative-filtering signals.

Motivation

The Koder Stack ships two consumption surfaces for video content — Koder Play (web/mobile streaming) and Koder Tune (Smart TV player) — and a B2B operations engine for theatrical cinema (Koder Cine). What is missing is the personal layer: where the user records what they watched, rates it, builds lists, follows critics, and asks "what should I watch tonight?". Without that layer:

• Play and Tune watch sessions produce engagement signal but no expressed preference (joinha/estrelas) — weakening the recommender.
• Users have nowhere to log films watched outside the Koder Stack (cinema, Netflix, DVD), making any Koder recommender blind to ~80% of their actual viewing history.
• Cine has no way to enrich a ticket purchase with social context (reviews, "people who saw this also saw…", critic recommendations).
• The Koder ID social graph has no audiovisual edge type, so the network effect of "follow what your friends watch" can never form.

Letterboxd has demonstrated that this product, done with cinéfilo respect, retains users at engagement rates rivaling general-purpose social networks. There is no reason the Koder Stack should ship without it.

Product surface (v1)

Core flows

Differentiation

The features the team committed to in the design conversation that don't exist in Letterboxd / Trakt today:

1. Multi-aspect "similar to" anchoring — user not only picks anchor titles but specifies what kind of similarity they want (action, tone, pacing, theme, protagonist archetype) and can supply negative anchors ("similar to Bourne but no torture"). Implemented as weighted slots over the recsys embedding space.
2. Score breakdown transparency — every title page and recommendation card shows RT / IMDb / Letterboxd / Take separately. No collapsed single number, ever. Cinéfilos want to see divergence; this is a brand-defining choice.
3. Trailer in recommendations — every suggested title surfaces its official trailer with both audio tracks (original/subtitled and dubbed), side by side. Audio language is a first-class field in the catalog.
4. Native cross-product wiring — Play/Tune auto-mark watched at ≥90% / abandoned at <15%; Cine ticket purchase pre-populates a diary entry; the same Koder ID is the social account.

Architecture

Block diagram

graph TD
  subgraph Apps[Apps layer]
    Mobile[suite/take/app/mobile<br/>Flutter — iOS + Android]
    Desktop[suite/take/app/desktop<br/>Flutter — Linux + Windows + macOS]
    Site[suite/take/site<br/>Landing page]
  end

  subgraph Platform[Take backend]
    Take[suite/take/platform<br/>Go SaaS<br/>diary · ratings · lists · social graph]
  end

  subgraph Sources[Content sources]
    Play[suite/play<br/>Streaming]
    Tune[suite/tune<br/>Smart TV]
    Cine[suite/cine<br/>Cinema tickets]
  end

  subgraph AI[AI layer]
    Recsys[ai/recsys<br/>Recommender]
    Runtime[ai/runtime<br/>Embeddings + LLM]
  end

  subgraph Foundation
    ID[foundation/id<br/>Koder ID]
    Billing[foundation/billing<br/>Premium tier]
    Reporter[foundation/reporter<br/>Error reporting]
  end

  subgraph Data
    KDB[data/kdb<br/>Catalog · ratings · diary · social graph]
    Search[data/search<br/>Title / person / list search]
    Blob[data/blob<br/>User-uploaded posters / list covers]
  end

  subgraph External[External catalogs]
    TMDb[TMDb API<br/>metadata · cast · crew · trailers]
    Trakt[Trakt API<br/>aggregate watch data]
    JustWatch[JustWatch API<br/>where-to-watch]
  end

  Mobile --> Take
  Desktop --> Take
  Site --> Take

  Play -.end-of-video signal.-> Take
  Tune -.end-of-video signal.-> Take
  Cine -.ticket purchase.-> Take

  Take --> Recsys
  Recsys --> Runtime
  Take --> ID
  Take --> Billing
  Take --> Reporter
  Take --> KDB
  Take --> Search
  Take --> Blob

  Take -.metadata sync.-> TMDb
  Take -.aggregate ratings.-> Trakt
  Take -.where-to-watch.-> JustWatch

Data model (kdb collections)

All collections are tenant-scoped to the take tenant in Koder ID. Cross-tenant queries (e.g., showing aggregate "Take rating") are computed by take/platform and cached, never queried from the app directly.

Service boundaries

api/discover is the most interesting: it is a thin wrapper over ai/recsys. The ranking, embedding lookup, and collaborative filtering all happen in recsys; Take only assembles the request (user context + filters + anchors + aspects) and renders the response (with score breakdown + trailer URLs).

"Similar to" — implementation sketch

The flagship differentiator. Implementation across two recsys primitives:

1. Embedding centroid + nearest-neighbor — for each anchor title, fetch its embedding from recsys (computed via ai/runtime). Take user-supplied weights per aspect (action / tone / pacing / theme / protagonist) to project the embedding into a sub-space. Compute the centroid of all anchor projections. Negative anchors subtract their projected vector from the centroid. ANN over the catalog returns N candidates.
2. Collaborative filtering rerank — recsys reranks the N candidates using "users who rated all anchors highly also rated X highly" signal. Final rank is a weighted blend (default 60% content embedding, 40% collaborative; user-tunable in advanced mode).

Tickets ai/recsys#similar-anchored and ai/recsys#similar-aspect-projection will be opened against lock-koder-play once it archives.

External catalog ingestion

The strict ToS posture is deliberate. The product cannot ship if it violates RT or IMDb terms; instead, the score breakdown panel labels each source clearly and falls back to "—" when data is unavailable.

Cross-product seams

All seams are event-driven via data/mq — no synchronous coupling. If a downstream module is offline, the event queues; nothing on the user-facing path of the source product breaks.

Identity, billing, privacy

Identity

Take is a tenant in Koder ID (tenant: take). The Koder Person becomes a Take account on first login; profile data (display name, avatar) syncs from foundation/id. Username allocation follows policies/username-allocation.kmd.

Billing

Take v1 is free with optional premium (take.koder.dev/premium):

Subscription managed by foundation/billing. No ads served to users in EUUK pending GDPR review (see `policiessecurity.kmd`).

Privacy

• Ratings are public by default but each one can be marked private at capture time.
• Diary entries are followers-only by default.
• "Already watched" status is never public — it leaks too much about taste and habits.
• Following is symmetric-visible (you can see who follows you, and vice versa) — no shadow follows.
• Letterboxd CSV imports must be opt-in per import (no auto-publishing).

Phase plan

Phase 1 + Phase 0 can ship under lock-koder-take. Phases 2+ are coordinated with the relevant cross-module locks.

Open questions (resolved later, not blocking RFC ratification)

1. Episode-level "watched" granularity — RESOLVED 2026-05-14 (take#019): bitmap wins. Benchmark on internal/storage/watch_bench_test.go shows bitmap is 102× faster on bulk-mark (200ep series), 136× faster on SeriesRollup, and 144–185× smaller in bytes at the typical (200ep / 30 series) and heavy (2000ep / 80 series) RFC profiles. Sparse-list shipped first as #006's MVP (working code now); migration to bitmap is gated on a separate impl ticket (rolling backfill + read-side fallback during the window). Bitmap entry loses per-episode source (records source at the series level); accepted as worst-case loss because the same series tends to be consumed via the same source. Bench artifact: tests/bench/episode_watch_bench_test.go (in internal/storage/).
2. Aspect projection vector basis — the multi-aspect "similar to" feature requires a fixed basis of aspects (action, tone, pacing, theme, archetype). Whether to use a hand-curated set of 5 vs 10 vs 20 is a recsys decision; ticket recsys#similar-aspect-basis.
3. Ad provider — foundation/ads (built for Play) or third-party? Defer to Phase 5.
4. Letterboxd CSV format support — do we ingest only the official export, or also third-party Letterboxd archive tools? Defer to Phase 5.

Refs

• products/horizontal/take/README.md — product README
• products/horizontal/take/koder.toml — config
• docs/stack/modules/take.md — Stack deep-dive (companion document)
• docs/stack/engine-product-pattern.md — engine-vs-product distinction (Take is a product; recsys is its engine)
• meta/docs/stack/specs/naming/brand-score.kmd — Brand score 85 (Great) for "Take"