docs: update project description to reflect current scope

- add federate_reviews + federate_watchlist to UserSettings (default true)
- new UserFederationSettingsQuery port with FederationFlags struct
- remove get_user_federate_goals from LocalApContentQuery
- gate ReviewLogged, ReviewUpdated, WatchlistEntryAdded, on_poster_synced on flags
- goals gating migrated to UserFederationSettingsQuery
- ReviewDeleted and WatchlistEntryRemoved ungated (tombstones always fire)
- sqlite + postgres migrations and adapter impls
- settings API and SPA toggles

.cargo/config.toml

@@ -0,0 +1,5 @@
+[env]
+SQLX_OFFLINE = "true"
+
+[registries.gitea]
+index = "sparse+https://git.gabrielkaszewski.dev/api/packages/GKaszewski/cargo/"

.dockerignore

@@ -0,0 +1,13 @@
+target/
+.git/
+.env
+*.db
+*.db-shm
+*.db-wal
+# .cargo and .sqlx are needed at build time (SQLX_OFFLINE mode)
+docs/
+dev.db
+spa/node_modules/
+spa/dist/
+spa/.env
+spa/.env.local

.env.example

@@ -0,0 +1,55 @@
+# ── Required ──────────────────────────────────────────────────
+
+# Database (SQLite — file auto-created on first run)
+DATABASE_URL=sqlite:///data/movies.db
+
+# Authentication
+JWT_SECRET=change-me-to-a-random-string
+
+# Movie metadata — one of these is required (TMDB preferred)
+# TMDB_API_KEY=your-tmdb-key
+OMDB_API_KEY=your-omdb-key
+
+# ── Recommended ──────────────────────────────────────────────
+
+# Public URL (used for ActivityPub federation and canonical links)
+BASE_URL=https://yourdomain.example.com
+
+# Enable sign-ups (default: false — set true so you can register)
+ALLOW_REGISTRATION=true
+
+# ── Image Storage (defaults to local filesystem) ─────────────
+
+# IMAGE_STORAGE_BACKEND=local    # default
+# IMAGE_STORAGE_PATH=./images    # default
+
+# S3-compatible alternative (MinIO, AWS S3, etc.):
+# IMAGE_STORAGE_BACKEND=s3
+# MINIO_ENDPOINT=http://localhost:9000
+# MINIO_BUCKET=posters
+# MINIO_REGION=minio
+# MINIO_ACCESS_KEY_ID=minioadmin
+# MINIO_SECRET_ACCESS_KEY=minioadmin
+
+# ── Optional ─────────────────────────────────────────────────
+
+# TMDb enrichment (cast, crew, genres — separate from search metadata above)
+# TMDB_API_KEY=your-tmdb-key
+
+# Image conversion (converts uploaded posters to AVIF or WebP)
+# IMAGE_CONVERSION_ENABLED=false
+# IMAGE_CONVERSION_FORMAT=avif
+
+# Server
+# HOST=0.0.0.0
+# PORT=3000
+# RATE_LIMIT=60
+# SECURE_COOKIES=true
+# RUST_LOG=presentation=info,tower_http=info,worker=info
+
+# CORS (for SPA development only)
+# CORS_ORIGINS=http://localhost:5173
+
+# Event bus — "db" (default, uses same database) or "nats"
+# EVENT_BUS_BACKEND=db
+# NATS_URL=nats://localhost:4222

.gitea/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  ci:
+    name: Check / Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+      - name: fmt
+        run: cargo fmt --all -- --check
+
+      - name: clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: test
+        run: cargo test

.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: 1
+
+jobs:
+  ci:
+    name: Check / Test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+
+      - name: Cache cargo
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: ${{ runner.os }}-cargo-
+
+      - name: fmt
+        run: cargo fmt --all -- --check
+
+      - name: clippy
+        run: cargo clippy --all-targets -- -D warnings
+
+      - name: test
+        run: cargo test
+
+  docker:
+    name: Build & Push Docker Image
+    runs-on: ubuntu-latest
+    needs: ci
+    if: github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha,prefix=
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: FEATURES=sqlite,sqlite-federation

.gitignore

@@ -6,3 +6,14 @@
 
 .env
 .env.prod
+
+*.db
+*db-shm
+*db-wal
+
+.worktrees/
+.superpowers/
+docs/
+
+imgs/
+.sqlx/

CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+Thanks for your interest in Movies Diary! This is a personal project but contributions are welcome — bug fixes, new features, docs improvements, or picking up the deprecated TUI.
+
+## Getting started
+
+1. Fork and clone the repo
+2. Copy `.env.example` to `.env` and fill in at least `JWT_SECRET` and `OMDB_API_KEY`
+3. Install Rust (stable, 2024 edition) and Bun (for the SPA)
+4. Run the backend and worker:
+
+```bash
+cargo run -p presentation   # HTTP server on :3000
+cargo run -p worker          # event worker (separate terminal)
+```
+
+5. Run the SPA dev server:
+
+```bash
+cd spa && bun install && bun run dev
+```
+
+## Before submitting a PR
+
+```bash
+make           # runs fmt-check + clippy + test
+```
+
+Or individually:
+
+```bash
+cargo fmt --check
+cargo clippy -- -D warnings
+cargo test
+cd spa && bunx tsc --noEmit
+```
+
+All four must pass. PRs with clippy warnings or failing tests won't be merged.
+
+## Architecture
+
+The project follows hexagonal (ports & adapters) architecture. See `architecture.mmd` for the full diagram.
+
+**Key rules:**
+- Presentation handlers never touch repositories directly — all domain logic goes through use cases in the `application` crate
+- Application use cases return raw domain data — URL formatting, date display, and view model assembly belong in presentation mappers (`presentation/src/mappers/`)
+- Use cases called from presentation handlers take `&AppContext`. Functions called from adapter event handlers take individual `Arc<dyn Trait>` params to keep adapter dependencies explicit
+
+```
+domain         → pure types, traits (ports), zero deps
+application    → use cases, orchestration
+presentation   → Axum handlers, routes, OpenAPI
+worker         → event consumer, background jobs
+adapters/*     → implements domain ports (sqlite, postgres, AP, etc.)
+spa/           → React SPA (TanStack Router + shadcn/ui)
+```
+
+### Adding a new feature
+
+1. **Domain first** — models in `domain/src/models/`, ports in `ports.rs`, events in `events.rs`
+2. **Adapters** — implement ports in both `sqlite` and `postgres` adapters, add migration
+3. **Application** — use cases in `application/src/<domain>/`, wire into `context.rs`
+4. **API types** — DTOs in `api-types/src/`
+5. **Presentation** — handler file in `handlers/<domain>.rs`, routes in `routes.rs`
+6. **SPA** — API client in `spa/src/lib/api/`, hook in `spa/src/hooks/`, components
+7. **Classic HTML** — Askama template + CSS in `static/style.css`
+
+### Database adapters
+
+Both SQLite and PostgreSQL are supported. If you add a migration or repository, implement it for both. The postgres adapter uses `$1, $2` params and `TIMESTAMPTZ`; SQLite uses `?` and text datetimes.
+
+### Federation (ActivityPub)
+
+Federation is feature-gated (`#[cfg(feature = "federation")]`). If your feature should federate, add domain events, handle them in `activitypub/src/event_handler.rs`, and create an AP object + inbound handler.
+
+## Code style
+
+- No comments unless the *why* is non-obvious
+- Concise commit messages
+- One feature per PR — don't bundle unrelated changes
+- Follow existing patterns (check a similar feature for reference)
+
+## Areas seeking help
+
+- **TUI** (`crates/tui`) — deprecated, needs a maintainer to bring it up to feature parity
+- **Tests** — the domain and application crates have 400+ unit tests; integration tests for the presentation layer are welcome
+- **Docs** — API usage examples, deployment guides

Cargo.toml

@@ -1,18 +1,45 @@
 [workspace]
 members = [
     "crates/adapters/auth",
+    "crates/adapters/event-publisher",
     "crates/adapters/metadata",
+    "crates/adapters/poster-fetcher",
+    "crates/adapters/object-storage",
+    "crates/adapters/poster-sync",
     "crates/adapters/rss",
     "crates/adapters/sqlite",
+    "crates/adapters/postgres",
+    "crates/adapters/sqlite-federation",
+    "crates/adapters/postgres-federation",
+    "crates/adapters/sqlite-event-queue",
+    "crates/adapters/postgres-event-queue",
+    "crates/adapters/template-askama",
+    "crates/adapters/activitypub",
+    "crates/adapters/export",
+    "crates/adapters/event-payload",
+    "crates/adapters/nats",
+    "crates/api-types",
     "crates/application",
-    "crates/common",
+    "crates/adapters/tmdb-enrichment",
+    "crates/adapters/image-converter",
     "crates/domain",
     "crates/presentation",
+    "crates/tui",
+    "crates/worker",
+    "crates/adapters/importer",
+    "crates/adapters/jellyfin",
+    "crates/adapters/plex",
+    "crates/adapters/sqlite-search",
+    "crates/adapters/postgres-search",
 ]
 resolver = "2"
 
 [workspace.dependencies]
-tokio = { version = "1.0", features = ["full"] }
+tokio = { version = "1.0", features = ["macros", "net", "rt", "rt-multi-thread", "sync", "time"] }
+bytes = "1"
+futures = "0.3"
+async-stream = "0.3"
+dotenvy = "0.15"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 anyhow = "1.0"
@@ -20,14 +47,54 @@ thiserror = "2.0"
 tracing = "0.1"
 tracing-subscriber = { version = "0.3.23", features = ["env-filter"] }
 async-trait = "0.1"
-uuid = { version = "1.23.0", features = ["v4", "serde"] }
+uuid = { version = "1.23.0", features = ["v4", "v5", "serde"] }
 chrono = { version = "0.4", features = ["serde"] }
+sqlx = { version = "0.8.6", features = [
+    "runtime-tokio-rustls",
+    "sqlite",
+    "uuid",
+] }
+rand = "0.9"
+reqwest = { version = "0.13", features = ["json", "query"] }
+sha2 = "0.10"
+hex = "0.4"
+object_store = { version = "0.11", features = ["aws"] }
+axum = { version = "0.8.8", features = ["macros", "multipart"] }
+csv = "1"
 
+api-types = { path = "crates/api-types" }
 domain = { path = "crates/domain" }
-common = { path = "crates/common" }
+tmdb-enrichment = { path = "crates/adapters/tmdb-enrichment" }
 application = { path = "crates/application" }
 presentation = { path = "crates/presentation" }
 auth = { path = "crates/adapters/auth" }
 metadata = { path = "crates/adapters/metadata" }
+poster-fetcher = { path = "crates/adapters/poster-fetcher" }
+object-storage = { path = "crates/adapters/object-storage" }
+poster-sync = { path = "crates/adapters/poster-sync" }
+event-publisher = { path = "crates/adapters/event-publisher" }
 rss = { path = "crates/adapters/rss" }
+export = { path = "crates/adapters/export" }
 sqlite = { path = "crates/adapters/sqlite" }
+sqlite-federation = { path = "crates/adapters/sqlite-federation" }
+postgres = { path = "crates/adapters/postgres" }
+postgres-federation = { path = "crates/adapters/postgres-federation" }
+template-askama = { path = "crates/adapters/template-askama" }
+activitypub = { path = "crates/adapters/activitypub" }
+event-payload = { path = "crates/adapters/event-payload" }
+nats = { path = "crates/adapters/nats" }
+sqlite-event-queue = { path = "crates/adapters/sqlite-event-queue" }
+postgres-event-queue = { path = "crates/adapters/postgres-event-queue" }
+importer = { path = "crates/adapters/importer" }
+jellyfin = { path = "crates/adapters/jellyfin" }
+plex = { path = "crates/adapters/plex" }
+image-converter = { path = "crates/adapters/image-converter" }
+sqlite-search = { path = "crates/adapters/sqlite-search" }
+postgres-search = { path = "crates/adapters/postgres-search" }
+
+[profile.dev]
+debug = 1                    # line tables only — still debuggable, much faster linking
+split-debuginfo = "unpacked" # macOS: skip dsymutil on every link
+
+[profile.dev.package."*"]
+opt-level = 2                # compile deps faster at runtime; paid once, cached after

Dockerfile

@@ -0,0 +1,95 @@
+# ----- spa -----
+FROM node:22-slim AS spa-builder
+WORKDIR /spa
+COPY spa/package.json spa/package-lock.json ./
+RUN npm ci
+COPY spa/ .
+RUN npm run build
+
+# ----- build -----
+FROM rust:slim-bookworm AS builder
+
+WORKDIR /build
+
+# Cache dependency compilation separately from source
+COPY Cargo.toml Cargo.lock ./
+COPY .cargo ./.cargo
+COPY crates/adapters/activitypub/Cargo.toml       crates/adapters/activitypub/Cargo.toml
+COPY crates/adapters/auth/Cargo.toml              crates/adapters/auth/Cargo.toml
+COPY crates/adapters/event-payload/Cargo.toml     crates/adapters/event-payload/Cargo.toml
+COPY crates/adapters/event-publisher/Cargo.toml   crates/adapters/event-publisher/Cargo.toml
+COPY crates/adapters/nats/Cargo.toml              crates/adapters/nats/Cargo.toml
+COPY crates/adapters/metadata/Cargo.toml          crates/adapters/metadata/Cargo.toml
+COPY crates/adapters/poster-fetcher/Cargo.toml    crates/adapters/poster-fetcher/Cargo.toml
+COPY crates/adapters/object-storage/Cargo.toml     crates/adapters/object-storage/Cargo.toml
+COPY crates/adapters/poster-sync/Cargo.toml       crates/adapters/poster-sync/Cargo.toml
+COPY crates/adapters/export/Cargo.toml            crates/adapters/export/Cargo.toml
+COPY crates/adapters/importer/Cargo.toml          crates/adapters/importer/Cargo.toml
+COPY crates/adapters/jellyfin/Cargo.toml          crates/adapters/jellyfin/Cargo.toml
+COPY crates/adapters/plex/Cargo.toml              crates/adapters/plex/Cargo.toml
+COPY crates/adapters/rss/Cargo.toml               crates/adapters/rss/Cargo.toml
+COPY crates/adapters/sqlite/Cargo.toml              crates/adapters/sqlite/Cargo.toml
+COPY crates/adapters/sqlite-federation/Cargo.toml   crates/adapters/sqlite-federation/Cargo.toml
+COPY crates/adapters/sqlite-event-queue/Cargo.toml  crates/adapters/sqlite-event-queue/Cargo.toml
+COPY crates/adapters/postgres/Cargo.toml            crates/adapters/postgres/Cargo.toml
+COPY crates/adapters/postgres-federation/Cargo.toml crates/adapters/postgres-federation/Cargo.toml
+COPY crates/adapters/postgres-event-queue/Cargo.toml crates/adapters/postgres-event-queue/Cargo.toml
+COPY crates/adapters/template-askama/Cargo.toml   crates/adapters/template-askama/Cargo.toml
+COPY crates/api-types/Cargo.toml                  crates/api-types/Cargo.toml
+COPY crates/application/Cargo.toml                crates/application/Cargo.toml
+COPY crates/adapters/tmdb-enrichment/Cargo.toml   crates/adapters/tmdb-enrichment/Cargo.toml
+COPY crates/domain/Cargo.toml                     crates/domain/Cargo.toml
+COPY crates/presentation/Cargo.toml               crates/presentation/Cargo.toml
+COPY crates/tui/Cargo.toml                        crates/tui/Cargo.toml
+COPY crates/adapters/image-converter/Cargo.toml   crates/adapters/image-converter/Cargo.toml
+COPY crates/adapters/sqlite-search/Cargo.toml     crates/adapters/sqlite-search/Cargo.toml
+COPY crates/adapters/postgres-search/Cargo.toml   crates/adapters/postgres-search/Cargo.toml
+COPY crates/worker/Cargo.toml                     crates/worker/Cargo.toml
+
+# Stub every crate so cargo can resolve and fetch deps
+RUN find crates -name "Cargo.toml" | sed 's|/Cargo.toml||' | \
+    xargs -I{} sh -c 'mkdir -p {}/src && echo "fn main(){}" > {}/src/main.rs && echo "" > {}/src/lib.rs'
+
+# libwebp-dev: required at build time by the `webp` crate (C bindings)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libwebp-dev \
+    pkg-config \
+ && rm -rf /var/lib/apt/lists/*
+
+RUN cargo fetch
+
+# Now copy real sources (invalidates cache only on source changes)
+COPY crates ./crates
+
+# All sqlx queries use the runtime API (no query! macros), so no database
+# or .sqlx cache is needed at compile time.
+#
+# To build with PostgreSQL backend instead:
+#   --build-arg FEATURES=postgres,postgres-federation
+# To add NATS support (EVENT_BUS_BACKEND=nats):
+#   --build-arg FEATURES=sqlite,sqlite-federation,nats
+ARG FEATURES=sqlite,sqlite-federation
+RUN cargo build --release -p presentation -p worker --no-default-features --features "${FEATURES}"
+
+# ----- runtime -----
+FROM debian:bookworm-slim
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates \
+    wget \
+    libwebp7 \
+    fonts-dejavu-core \
+ && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+COPY --from=builder /build/target/release/presentation ./presentation
+COPY --from=builder /build/target/release/worker ./worker
+COPY static ./static
+COPY --from=spa-builder /spa/dist ./spa/dist
+
+EXPOSE 3000
+
+ENV RUST_LOG=presentation=info,tower_http=info
+
+CMD ["./presentation"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Kaszewski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,37 @@
+.DEFAULT_GOAL := check
+
+# Run the full local check suite — same order as CI would.
+check: fmt-check clippy test check-appcontext
+	@echo "✅ All checks passed"
+
+# Enforce that no application use case imports AppContext (god-object guard).
+check-appcontext:
+	@if grep -rn "AppContext" crates/application/src --include="*.rs" | grep -q .; then \
+	    echo "❌ AppContext found in application crate:"; \
+	    grep -rn "AppContext" crates/application/src --include="*.rs"; \
+	    exit 1; \
+	fi
+	@echo "✅ No AppContext in application crate"
+
+# Apply rustfmt to all files.
+fmt:
+	cargo fmt
+
+# Check formatting without modifying files (CI-safe).
+fmt-check:
+	cargo fmt --check
+
+# Run Clippy and treat warnings as errors.
+clippy:
+	cargo clippy -- -D warnings
+
+# Run the test suite.
+test:
+	cargo test
+
+# Apply fmt + clippy auto-fixes in one shot.
+fix:
+	cargo fmt
+	cargo clippy --fix --allow-dirty --allow-staged
+
+.PHONY: check fmt fmt-check clippy test fix

README.md

@@ -0,0 +1,305 @@
+# Movies Diary
+
+A self-hosted movie diary built in Rust. Ships a classic server-rendered HTML interface (no JavaScript) alongside a full React SPA, both backed by the same REST API. Federates over ActivityPub so reviews reach the Fediverse. Supports Jellyfin and Plex auto-import, full-text search, annual wrap-ups, goals, and bulk import from Letterboxd, IMDb, and other sources. Runs on SQLite or PostgreSQL.
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Built with Rust](https://img.shields.io/badge/built_with-Rust-orange.svg?logo=rust)](https://www.rust-lang.org/)
+[![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white)](https://hub.docker.com/)
+[![ActivityPub](https://img.shields.io/badge/ActivityPub-federated-5b5ea6)](https://activitypub.rocks/)
+[![SQLite](https://img.shields.io/badge/database-SQLite%20%7C%20PostgreSQL-003B57?logo=sqlite&logoColor=white)](https://www.sqlite.org/)
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Screenshots](#screenshots)
+- [Architecture](#architecture)
+- [Prerequisites](#prerequisites)
+- [Configuration](#configuration)
+- [Run](#run)
+- [API](#api)
+- [SPA](#spa)
+- [Development](#development)
+- [Test](#test)
+- [Docker](#docker)
+- [Media Server Integration](#media-server-integration)
+- [Annual Wrap-Up](#annual-wrap-up)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Quick Start
+
+The fastest way to run Movies Diary is via Docker Compose:
+
+```bash
+cp .env.example .env
+# Set JWT_SECRET and OMDB_API_KEY (or TMDB_API_KEY) in .env
+docker compose up -d
+```
+
+Open `http://localhost:3000`. The HTTP server and background worker start together; data is persisted in a Docker volume.
+
+---
+
+## Features
+
+- Log movies with a TMDB/OMDb ID or manual title/year/director, with a 0–5 rating
+- Immutable append-only viewing ledger (tracks re-watches)
+- Background poster fetching and storage (local filesystem or S3-compatible)
+- Movie enrichment via TMDb — full cast, crew, genres, keywords, runtime, budget/revenue, ratings; fetched automatically on movie discovery and refreshed every 30 days; exposed via `GET /api/v1/movies/{id}/profile`
+- Full-text search across movies and people via `GET /api/v1/search` — free-text query plus structured filters (genre, year, person, department, language); backed by SQLite FTS5 or PostgreSQL tsvector + GIN indexes
+- People as first-class entities — browse by person via `GET /api/v1/people/{id}` and full credit history via `GET /api/v1/people/{id}/credits`; index populated automatically during TMDb enrichment
+- RSS/Atom feed for public subscription (global and per-user)
+- JWT authentication via cookie (HTML) or Bearer token (REST API)
+- ActivityPub federation — follow/unfollow remote users, accept/reject/remove followers, federated reviews broadcast as `Note` objects with `#MoviesDiary` + `#MovieTitle` hashtags, paginated outbox, boost/Announce tracking, NodeInfo discovery endpoint, shared inbox delivery, actor profile sync (bio, avatar, discoverable)
+- Federation moderation — instance-level domain blocking (admin-managed), per-user actor blocking with `Block` activity, delivery filter excludes blocked actors and blocked-domain inboxes
+- Watchlist — add movies to watch later, per-user; federated watchlist entries visible for remote actors
+- User profiles — display name, bio, avatar, banner, custom profile fields; editable via HTML settings page or REST API
+- Jellyfin/Plex auto-import — media server sends a webhook on playback stop, movies land in a watch queue; review and confirm with a rating to create diary entries; per-user webhook tokens with SHA-256 auth; setup UI at `/settings/integrations`
+- Annual Wrap-Up — Spotify Wrapped for movies: per-user and instance-wide year-in-review with stats (top directors, actors, genres, rating distribution, watch time, rewatches, budget analysis), shareable HTML page at `/wrapups/{user_id}/{year}`; admin-triggered or auto-generated in January
+- Goals — set a "watch N movies in YEAR" target with a progress bar; progress computed from existing reviews (backwards compatible); per-user federation toggle in settings; displayed on profile (SPA: interactive with create/edit/delete, classic HTML: read-only glassmorphic card)
+- CSV and JSON diary export
+- File importer: upload CSV, TSV, JSON, or XLSX from any source (Letterboxd, IMDb, etc.), map columns to domain fields via a step-by-step wizard or REST API, save mapping profiles for repeat imports
+- REST API v1 (`/api/v1/`) with full feature parity with the HTML interface
+- OpenAPI documentation at `/docs` (Swagger UI) and `/scalar` (Scalar)
+- CSRF protection on all HTML form routes (double-submit cookie, defense-in-depth on top of `SameSite=Strict`)
+- Per-IP rate limiting via token bucket (production-grade, backed by `axum-governor`)
+- Single-page app at `/app/` — React + TanStack Router + shadcn/ui, built with Vite, served from the backend with client-side routing fallback
+- Terminal UI client (`crates/tui`, deprecated) for logging reviews, bulk CSV import, and diary browsing
+
+## Screenshots
+
+> SPA at `/app/` — React + TanStack Router + shadcn/ui
+
+| Feed | Movie | Person |
+|------|-------|--------|
+| ![Feed](screenshots/feed.jpeg) | ![Movie detail](screenshots/movie.jpeg) | ![Person detail](screenshots/person.jpeg) |
+
+| Profile | Wrap-Up | Wrap-Up card |
+|---------|---------|--------------|
+| ![Profile](screenshots/profile.jpeg) | ![Wrap-Up stats](screenshots/wrapup-stats.jpeg) | ![Wrap-Up shareable card](screenshots/wrapup-card.jpeg) |
+
+## Architecture
+
+Hexagonal (Ports & Adapters) with Domain-Driven Design:
+
+```
+api-types           — shared REST API request/response DTOs (Serialize/Deserialize + utoipa schemas); used by presentation and tui
+domain              — pure types and trait definitions, no external deps
+application         — use cases (commands + queries), business logic orchestration; handlers delegate here for all domain logic
+presentation        — Axum HTTP router, OpenAPI spec assembly, Swagger UI + Scalar serving, composition root for the HTTP process
+worker              — standalone worker binary (event consumer, poster sync, federation)
+adapters/
+  auth                 — JWT issuance and validation (Argon2 passwords)
+  sqlite               — SQLite repository + connection factory
+  postgres             — PostgreSQL repository + connection factory
+  metadata             — TMDB / OMDb HTTP client
+  poster-fetcher       — downloads poster images
+  image-storage        — stores images (posters + user avatars) on local filesystem or S3-compatible storage
+  poster-sync          — event handler: triggers poster fetch+store on MovieDiscovered
+  image-converter      — optional background worker: converts stored images to AVIF or WebP; backfills existing images via a 24h periodic job
+  tmdb-enrichment      — event handler: fetches full movie profile (cast, crew, genres, keywords, box office) from TMDb on MovieEnrichmentRequested; resolves IMDb IDs automatically
+  template-askama      — Askama HTML rendering
+  rss                  — RSS/Atom feed generation
+  export               — CSV and JSON diary serialization
+  importer             — CSV/TSV/JSON/XLSX parser and column mapper for bulk import
+  jellyfin             — Jellyfin webhook payload parser (MediaServerParser adapter)
+  plex                 — Plex webhook payload parser (MediaServerParser adapter; requires Plex Pass)
+  event-payload        — shared event serialization DTOs (used by all event bus adapters)
+  sqlite-event-queue   — durable polling event queue backed by SQLite
+  postgres-event-queue — durable polling event queue backed by PostgreSQL
+  nats                 — NATS Core / JetStream event publisher and consumer
+  event-publisher      — in-memory event channel (used in tests)
+  activitypub          — ActivityPub federation adapter (follow, inbox/outbox, actor); delegates to k-ap for protocol internals
+  sqlite-search        — SQLite FTS5 implementation of SearchPort + SearchCommand
+  postgres-search      — PostgreSQL tsvector + GIN implementation of SearchPort + SearchCommand
+  sqlite-federation    — SQLite-backed federation repository
+  postgres-federation  — PostgreSQL-backed federation repository
+tui                 — terminal UI client (ratatui); shares api-types with presentation for typed API access
+spa/                — React SPA (TanStack Router + shadcn/ui + Vite); served at /app/ by the backend
+```
+
+## Prerequisites
+
+- Rust (stable, 2024 edition)
+- SQLite
+- Poster storage: local filesystem (zero deps) or an S3-compatible object store (e.g. MinIO)
+- An [OMDb API key](https://www.omdbapi.com/apikey.aspx)
+
+## Configuration
+
+Copy `.env.example` to `.env` and set the values below. Required fields must be set before the server will start.
+
+| Variable | Default | Required | Description |
+|---|---|---|---|
+| `DATABASE_URL` | `sqlite://movies.db` | Yes | SQLite or PostgreSQL connection string |
+| `JWT_SECRET` | — | Yes | Secret for JWT signing — use a long random string |
+| `OMDB_API_KEY` | — | Yes | [OMDb](https://www.omdbapi.com/apikey.aspx) key for movie metadata |
+| `TMDB_API_KEY` | — | No | [TMDb](https://www.themoviedb.org/settings/api) key — enables cast, crew, genres, enrichment |
+| `BASE_URL` | — | Yes | Public URL of your instance (used for ActivityPub actor URLs) |
+| `IMAGE_STORAGE_BACKEND` | `local` | No | `local` or `s3` |
+| `IMAGE_STORAGE_PATH` | `./images` | No | Path for local image storage |
+| `MINIO_ENDPOINT` | — | S3 only | S3-compatible endpoint (e.g. `http://localhost:9000`) |
+| `MINIO_BUCKET` | — | S3 only | Bucket name |
+| `MINIO_REGION` | — | S3 only | Region (e.g. `minio`) |
+| `MINIO_ACCESS_KEY_ID` | — | S3 only | Access key ID |
+| `MINIO_SECRET_ACCESS_KEY` | — | S3 only | Secret access key |
+| `IMAGE_CONVERSION_ENABLED` | `false` | No | Convert stored images to AVIF or WebP |
+| `IMAGE_CONVERSION_FORMAT` | `avif` | No | `avif` or `webp` |
+| `HOST` | `0.0.0.0` | No | Bind address |
+| `PORT` | `3000` | No | HTTP port |
+| `RATE_LIMIT` | `60` | No | Requests per minute per IP |
+| `ALLOW_REGISTRATION` | `true` | No | Set `false` to disable new sign-ups |
+| `SECURE_COOKIES` | `true` | No | Must be `true` when serving over HTTPS |
+| `RUST_LOG` | — | No | Log verbosity (e.g. `presentation=info,worker=info`) |
+| `CORS_ORIGINS` | `*` | No | Comma-separated allowed origins for SPA dev |
+| `EVENT_BUS_BACKEND` | `db` | No | `db` (default) or `nats` |
+| `NATS_URL` | — | NATS only | NATS connection URL (e.g. `nats://localhost:4222`) |
+
+The `worker` binary must run alongside `presentation` to process events:
+
+```bash
+cargo run -p worker
+```
+
+## Run
+
+```bash
+cargo run -p presentation   # HTTP server (0.0.0.0:3000)
+cargo run -p worker         # event worker (poster sync, in a separate terminal)
+```
+
+The worker polls the event queue and must run alongside the presentation to process background tasks like poster fetching. Both processes share the same database.
+
+## API
+
+All REST endpoints are under `/api/v1/`. Authentication uses `Authorization: Bearer <token>` obtained from `POST /api/v1/auth/login`.
+
+Interactive API documentation is available at runtime:
+
+- **Swagger UI** — `http://localhost:3000/docs`
+- **Scalar** — `http://localhost:3000/scalar`
+
+An [Insomnia](https://insomnia.rest/) collection covering all endpoints is included at [`movies-diary.insomnia.json`](movies-diary.insomnia.json). Import it via **File → Import**, set `base_url` and `token` in the environment, and you're ready to go.
+
+## SPA
+
+The single-page app lives in `spa/` and is served at `/app/` by the backend. For local development:
+
+```bash
+cd spa && bun install && bun run dev   # http://localhost:5173/app/
+```
+
+Set `CORS_ORIGINS=http://localhost:5173` in the backend `.env` to allow cross-origin API calls during development.
+
+For production, `bun run build` outputs to `spa/dist/` which the backend serves statically (included in Docker image automatically).
+
+## Terminal UI (deprecated)
+
+> **Note:** The TUI was an experiment with ratatui and is no longer actively maintained. It may not support newer features (goals, watchlist, federation, etc.). Contributions welcome — if you'd like to maintain it, open a PR.
+
+```bash
+cargo run -p tui
+```
+
+Supports review logging, bulk CSV import, and diary browsing.
+
+## Development
+
+A `Makefile` wraps the most common dev commands:
+
+```bash
+make           # default: fmt-check + clippy + test (same order as CI)
+make fix       # auto-apply fmt + clippy fixes
+make fmt       # apply rustfmt
+make clippy    # clippy with -D warnings
+make test      # cargo test
+```
+
+## Test
+
+```bash
+cargo test                    # full workspace (requires DATABASE_URL for sqlx offline checks)
+cargo test -p application     # business logic tests only — no database required
+cargo test -p domain          # domain model + value object tests
+cargo llvm-cov -p application -p domain   # line coverage report (requires cargo-llvm-cov)
+```
+
+The `application` and `domain` crates have 400+ unit tests covering all use case modules (auth, diary, goals, import, integrations, movies, person, search, users, watchlist, wrapup) backed by in-memory fakes from `domain`'s `test-helpers` feature. These run without a database and are the fastest feedback loop for business logic changes.
+
+## Docker
+
+### Quick start
+
+```bash
+cp .env.example .env
+# Edit .env — set JWT_SECRET and OMDB_API_KEY (or TMDB_API_KEY)
+docker compose up -d
+```
+
+This builds and starts the HTTP server (port 3000) and event worker. Data is persisted in a Docker volume.
+
+### Manual docker run
+
+The image contains both `presentation` and `worker` binaries. Run them as separate containers sharing the same data volume:
+
+```bash
+docker build -t movies-diary .
+
+docker run -p 3000:3000 --env-file .env -v movies-diary-data:/data movies-diary
+docker run --env-file .env -v movies-diary-data:/data --entrypoint ./worker movies-diary
+```
+
+Build for PostgreSQL: `--build-arg FEATURES=postgres,postgres-federation`
+
+## Media Server Integration
+
+Auto-log movies you finish watching. Go to `/settings/integrations` to generate a webhook token, then configure your media server.
+
+### Jellyfin
+
+1. Install the **Webhook** plugin (Dashboard > Plugins > Catalog)
+2. Add a **Generic** destination:
+   - **URL**: `https://yourdomain.example.com/api/v1/webhooks/jellyfin`
+   - **Header**: `Authorization` = `Bearer <your-token>`
+   - **Send All Properties**: enabled
+   - **Notification Type**: Playback Stop only
+   - **Item Type**: Movies only
+
+### Plex (requires Plex Pass)
+
+1. Go to Settings > Webhooks in your Plex server
+2. Add webhook URL: `https://yourdomain.example.com/api/v1/webhooks/plex`
+3. Plex does not support custom headers natively — pass the token as a query param: `https://yourdomain.example.com/api/v1/webhooks/plex?token=<your-token>`
+
+Movies you finish watching appear in your watch queue at `/watch-queue` — rate and confirm to add to your diary.
+
+## Annual Wrap-Up
+
+Generate a year-in-review summary for any user — top directors, actors, genres, rating distribution, total watch time, rewatch stats, and more. Available as a shareable HTML page.
+
+**Generate via API** (admin only):
+```bash
+curl -X POST http://localhost:3000/api/v1/wrapups/generate \
+  -H "Authorization: Bearer <admin-token>" \
+  -H "Content-Type: application/json" \
+  -d '{"user_id": "<uuid>", "start_date": "2025-01-01", "end_date": "2026-01-01"}'
+```
+
+Omit `user_id` for a global instance wrap-up. The worker computes stats in the background — poll `GET /api/v1/wrapups/{id}` for status.
+
+**View:** `http://localhost:3000/wrapups/{user_id}/2025` (public, no login required)
+
+**Auto-generate:** The worker runs a daily job in January that generates wrap-ups for all users with reviews in the previous year.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, architecture overview, and PR guidelines.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

architecture.mmd

@@ -0,0 +1,140 @@
+---
+title: Movies Diary — Hexagonal Architecture
+---
+graph TB
+    subgraph Binaries["Binaries (Composition Root)"]
+        WEB["presentation<br/><i>Axum web server</i><br/>Routes, Handlers, Mappers"]
+        WORKER["worker<br/><i>Event consumer</i><br/>Concurrent dispatch, graceful shutdown"]
+        TUI["tui<br/><i>Terminal UI</i>"]
+    end
+
+    subgraph Application["Application Layer"]
+        direction TB
+        CTX["AppContext<br/><i>Repositories + Services</i>"]
+        APP_PORTS["ReviewLogger<br/><i>application-layer port</i>"]
+        subgraph UseCases["Use Cases"]
+            UC_AUTH["auth<br/>login, register"]
+            UC_DIARY["diary<br/>log_review, get_diary,<br/>get_activity_feed, export"]
+            UC_MOVIES["movies<br/>get_movies, get_movie_profile,<br/>enrich_movie, request_enrichment,<br/>sync_poster, reindex_search"]
+            UC_IMPORT["import<br/>create_session, apply_mapping,<br/>execute, profiles"]
+            UC_USERS["users<br/>get_users, get_profile,<br/>update_profile"]
+            UC_WATCHLIST["watchlist<br/>add, remove, get"]
+            UC_WRAPUP["wrapup<br/>generate, compute,<br/>list, delete"]
+            UC_GOALS["goals<br/>create, update, delete,<br/>get, list"]
+            UC_INTEGRATIONS["integrations<br/>webhooks, watch_queue,<br/>confirm, dismiss"]
+            UC_SEARCH["search<br/>execute"]
+            UC_PERSON["person<br/>get, get_credits"]
+        end
+        subgraph EventHandlers["Event Handlers"]
+            EH_ENRICH["EnrichmentHandler"]
+            EH_DISCOVER["MovieDiscoveryIndexer"]
+            EH_CLEANUP["SearchCleanupHandler"]
+            EH_REINDEX["SearchReindexHandler"]
+            EH_WRAPUP["WrapUpEventHandler"]
+        end
+        subgraph Jobs["Periodic Jobs"]
+            JOB_IMPORT["ImportSessionCleanup"]
+            JOB_WATCH["WatchEventCleanup"]
+            JOB_STALE["EnrichmentStaleness"]
+            JOB_WRAPGEN["WrapUpAutoGenerate"]
+        end
+        WORKER_SVC["WorkerService<br/><i>Semaphore(8), JoinSet,<br/>shutdown signal</i>"]
+    end
+
+    subgraph Domain["Domain Layer (0 dependencies)"]
+        direction TB
+        subgraph Models["Models"]
+            M_MOVIE["Movie, MovieSummary,<br/>MovieProfile"]
+            M_REVIEW["Review, DiaryEntry,<br/>FeedEntry"]
+            M_USER["User, UserSummary"]
+            M_PERSON["Person, PersonId,<br/>PersonCredits"]
+            M_WATCHLIST["WatchlistEntry,<br/>WatchEvent"]
+            M_GOAL["Goal, GoalWithProgress,<br/>UserSettings, RemoteGoalEntry"]
+            M_WRAPUP["WrapUpReport,<br/>MovieRef, PersonStat"]
+            M_SEARCH["SearchQuery,<br/>SearchResults"]
+        end
+        subgraph Ports["Port Traits (Interfaces)"]
+            P_REPOS["MovieRepository<br/>ReviewRepository<br/>DiaryRepository<br/>UserRepository<br/>WatchlistRepository<br/>WatchEventRepository<br/>WebhookTokenRepository<br/>ImportSessionRepository<br/>MovieProfileRepository<br/>WrapUpRepository<br/>GoalRepository<br/>UserSettingsRepository"]
+            P_SERVICES["AuthService<br/>MetadataClient<br/>PosterFetcherClient<br/>ObjectStorage<br/>EventPublisher<br/>EventConsumer<br/>PasswordHasher<br/>DiaryExporter<br/>DocumentParser"]
+            P_SEARCH["SearchPort<br/>SearchCommand<br/>PersonQuery<br/>PersonCommand"]
+            P_FEDERATION["SocialQueryPort<br/>LocalApContentQuery<br/>RemoteWatchlistRepository<br/>RemoteGoalRepository"]
+        end
+        subgraph DomainServices["Services (pure, no I/O)"]
+            DS_WRAPUP["WrapUpAnalyzer<br/><i>build_report, compute_*</i>"]
+            DS_REVIEW["ReviewHistoryAnalyzer<br/><i>rating_trend</i>"]
+        end
+        EVENTS["DomainEvent enum<br/><i>ReviewLogged, MovieDiscovered,<br/>GoalCreated, GoalUpdated,<br/>SearchReindexRequested, ...</i>"]
+        VO["Value Objects<br/><i>MovieId, UserId, Rating,<br/>Email, Username, Password, ...</i>"]
+    end
+
+    subgraph ApiTypes["api-types (0 domain deps)"]
+        DTO["DTOs<br/><i>MovieDto, ReviewDto,<br/>FeedEntryDto, UserSummaryDto,<br/>CastMemberDto, ...</i>"]
+    end
+
+    subgraph Adapters["Adapters (implement Port Traits)"]
+        direction TB
+        subgraph Storage["Storage"]
+            A_SQLITE["sqlite<br/><i>SQLite repos</i>"]
+            A_PG["postgres<br/><i>PostgreSQL repos</i>"]
+            A_SQLITE_SEARCH["sqlite-search<br/><i>FTS5</i>"]
+            A_PG_SEARCH["postgres-search<br/><i>tsvector/GIN</i>"]
+            A_OBJ["object-storage<br/><i>S3 / filesystem</i>"]
+        end
+        subgraph Messaging["Messaging"]
+            A_NATS["nats<br/><i>JetStream / Core</i>"]
+            A_PG_QUEUE["postgres-event-queue<br/><i>Polling, dead-letter</i>"]
+            A_PAYLOAD["event-payload<br/><i>Serde (de)serialization</i>"]
+        end
+        subgraph External["External Services"]
+            A_METADATA["metadata<br/><i>TMDB search/details</i>"]
+            A_TMDB["tmdb-enrichment<br/><i>Credits, keywords, cast</i>"]
+            A_POSTER["poster-fetcher<br/><i>TMDB image download</i>"]
+            A_AUTH["auth<br/><i>JWT tokens</i>"]
+        end
+        subgraph Federation["Federation (feature-gated)"]
+            A_AP["activitypub<br/><i>k_ap library</i>"]
+            A_SQLITE_FED["sqlite-federation"]
+            A_PG_FED["postgres-federation"]
+        end
+        subgraph Media["Media Processing"]
+            A_IMG["image-converter<br/><i>AVIF/WebP</i>"]
+            A_POSTER_SYNC["poster-sync"]
+        end
+        subgraph Presentation["Presentation Helpers"]
+            A_TEMPLATE["template-askama<br/><i>HTML templates</i>"]
+            A_RSS["rss<br/><i>Feed generation</i>"]
+            A_EXPORT["export<br/><i>CSV/JSON diary</i>"]
+            A_IMPORT["importer<br/><i>CSV/JSON/XLSX parser</i>"]
+        end
+        subgraph Webhooks["Webhook Parsers"]
+            A_JELLYFIN["jellyfin"]
+            A_PLEX["plex"]
+        end
+    end
+
+    %% Dependency arrows
+    WEB -->|"uses"| Application
+    WEB -->|"maps to"| ApiTypes
+    WORKER -->|"uses"| Application
+
+    Application -->|"depends on"| Domain
+    UC_WRAPUP -->|"delegates to"| DS_WRAPUP
+
+    Adapters -.->|"implements"| Ports
+
+    %% Key data flows
+    WEB ===|"HTTP"| DTO
+    WORKER ===|"Events"| EVENTS
+
+    classDef domain fill:#1a1a2e,stroke:#e94560,color:#fff
+    classDef app fill:#16213e,stroke:#0f3460,color:#fff
+    classDef adapter fill:#0f3460,stroke:#533483,color:#fff
+    classDef binary fill:#533483,stroke:#e94560,color:#fff
+    classDef api fill:#2a2a4a,stroke:#e94560,color:#fff
+
+    class Domain domain
+    class DomainServices domain
+    class Application app
+    class Adapters adapter
+    class Binaries binary
+    class ApiTypes api

crates/adapters/activitypub/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "activitypub"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+k-ap = { version = "0.4.0", registry = "gitea" }
+domain = { workspace = true }
+axum = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+uuid = { workspace = true }
+chrono = { workspace = true }
+anyhow = { workspace = true }
+tracing = { workspace = true }
+async-trait = { workspace = true }
+
+url = { version = "2", features = ["serde"] }
+ammonia = "4"

crates/adapters/activitypub/src/composite_handler.rs

@@ -0,0 +1,122 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use chrono::{DateTime, Utc};
+use k_ap::{ApContentReader, ApObjectHandler};
+use url::Url;
+
+use crate::{
+    goal_handler::GoalObjectHandler, review_handler::ReviewObjectHandler,
+    watchlist_handler::WatchlistObjectHandler,
+};
+
+pub struct CompositeObjectHandler {
+    pub review: Arc<ReviewObjectHandler>,
+    pub watchlist: Arc<WatchlistObjectHandler>,
+    pub goal: Arc<GoalObjectHandler>,
+}
+
+#[async_trait]
+impl ApContentReader for CompositeObjectHandler {
+    async fn get_local_objects_page(
+        &self,
+        user_id: uuid::Uuid,
+        before: Option<DateTime<Utc>>,
+        limit: usize,
+    ) -> anyhow::Result<Vec<(Url, serde_json::Value, DateTime<Utc>)>> {
+        self.review
+            .get_local_objects_page(user_id, before, limit)
+            .await
+    }
+
+    async fn count_local_posts(&self) -> anyhow::Result<u64> {
+        self.review.count_local_posts().await
+    }
+}
+
+#[async_trait]
+impl ApObjectHandler for CompositeObjectHandler {
+    async fn on_create(
+        &self,
+        ap_id: &Url,
+        actor_url: &Url,
+        object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        let is_watchlist = object.get("watchlistEntry").and_then(|v| v.as_bool()) == Some(true)
+            || (object.get("movieTitle").is_some() && object.get("rating").is_none());
+        let is_goal = object.get("goal").and_then(|v| v.as_bool()) == Some(true);
+        if object.get("rating").is_some() {
+            self.review.on_create(ap_id, actor_url, object).await
+        } else if is_goal {
+            self.goal.on_create(ap_id, actor_url, object).await
+        } else if is_watchlist {
+            self.watchlist.on_create(ap_id, actor_url, object).await
+        } else {
+            tracing::warn!(ap_id = %ap_id, "ignoring Create for unknown object type");
+            Ok(())
+        }
+    }
+
+    async fn on_update(
+        &self,
+        ap_id: &Url,
+        actor_url: &Url,
+        object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        let is_goal = object.get("goal").and_then(|v| v.as_bool()) == Some(true);
+        if object.get("rating").is_some() {
+            self.review.on_update(ap_id, actor_url, object).await
+        } else if is_goal {
+            self.goal.on_update(ap_id, actor_url, object).await
+        } else {
+            Ok(())
+        }
+    }
+
+    async fn on_delete(&self, ap_id: &Url, actor_url: &Url) -> anyhow::Result<()> {
+        self.review.on_delete(ap_id, actor_url).await?;
+        self.watchlist.on_delete(ap_id, actor_url).await?;
+        self.goal.on_delete(ap_id, actor_url).await?;
+        Ok(())
+    }
+
+    async fn on_actor_removed(&self, actor_url: &Url) -> anyhow::Result<()> {
+        self.review.on_actor_removed(actor_url).await?;
+        self.watchlist.on_actor_removed(actor_url).await?;
+        self.goal.on_actor_removed(actor_url).await?;
+        Ok(())
+    }
+
+    async fn on_like(&self, _object_url: &Url, _actor_url: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_announce_received(
+        &self,
+        _object_url: &Url,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_announce_of_remote(
+        &self,
+        _object_url: &Url,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_unlike(&self, _object_url: &Url, _actor_url: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_mention(
+        &self,
+        _thought_ap_id: &Url,
+        _mentioned_user_uuid: uuid::Uuid,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+}

crates/adapters/activitypub/src/event_handler.rs

@@ -0,0 +1,503 @@
+use async_trait::async_trait;
+use chrono::Datelike;
+use domain::ports::EventHandler;
+use domain::{
+    errors::DomainError,
+    events::DomainEvent,
+    ports::{LocalApContentQuery, UserFederationSettingsQuery},
+    value_objects::{MovieId, ReviewId, UserId},
+};
+use std::sync::Arc;
+
+use k_ap::{ActivityPubService, ApVisibility};
+
+use crate::objects::{goal_to_ap_object, review_to_ap_object};
+use crate::urls::{actor_url, goal_url, review_url};
+
+pub struct ActivityPubEventHandler {
+    ap_service: Arc<ActivityPubService>,
+    content_query: Arc<dyn LocalApContentQuery>,
+    federation_settings: Arc<dyn UserFederationSettingsQuery>,
+    base_url: String,
+}
+
+impl ActivityPubEventHandler {
+    pub fn new(
+        ap_service: Arc<ActivityPubService>,
+        content_query: Arc<dyn LocalApContentQuery>,
+        federation_settings: Arc<dyn UserFederationSettingsQuery>,
+        base_url: String,
+    ) -> Self {
+        Self {
+            ap_service,
+            content_query,
+            federation_settings,
+            base_url,
+        }
+    }
+}
+
+#[async_trait]
+impl EventHandler for ActivityPubEventHandler {
+    async fn handle(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        match event {
+            DomainEvent::ReviewLogged {
+                review_id, user_id, ..
+            } => self
+                .on_review_logged(user_id, review_id)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::ReviewUpdated {
+                review_id, user_id, ..
+            } => self
+                .on_review_updated(user_id, review_id)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::ReviewDeleted { review_id, user_id } => self
+                .on_review_deleted(user_id, review_id)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::UserUpdated { user_id } => self
+                .ap_service
+                .broadcast_actor_update(user_id.value())
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::WatchlistEntryAdded {
+                user_id,
+                movie_id,
+                movie_title,
+                release_year,
+                external_metadata_id,
+                added_at,
+            } => self
+                .on_watchlist_added(
+                    user_id,
+                    movie_id,
+                    movie_title,
+                    *release_year,
+                    external_metadata_id,
+                    added_at,
+                )
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::WatchlistEntryRemoved { user_id, movie_id } => self
+                .on_watchlist_removed(user_id, movie_id)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::FederationDeliveryRequested {
+                inbox_url,
+                activity_json,
+                signing_actor_id,
+            } => {
+                let inbox: url::Url = inbox_url
+                    .parse()
+                    .map_err(|e| DomainError::InfrastructureError(format!("bad inbox URL: {e}")))?;
+                let activity: serde_json::Value =
+                    serde_json::from_str(activity_json).map_err(|e| {
+                        DomainError::InfrastructureError(format!("bad activity JSON: {e}"))
+                    })?;
+                self.ap_service
+                    .deliver_to_inbox(inbox, activity, *signing_actor_id)
+                    .await
+                    .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+            }
+            DomainEvent::PosterSynced { movie_id } => self
+                .on_poster_synced(movie_id)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::GoalCreated {
+                user_id,
+                year,
+                target_count,
+                ..
+            } => self
+                .broadcast_goal(user_id, *year, *target_count, true)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::GoalUpdated {
+                user_id,
+                year,
+                target_count,
+                ..
+            } => self
+                .broadcast_goal(user_id, *year, *target_count, false)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            DomainEvent::GoalDeleted { user_id, year, .. } => self
+                .on_goal_deleted(user_id, *year)
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+            _ => Ok(()),
+        }
+    }
+}
+
+impl ActivityPubEventHandler {
+    async fn on_review_logged(&self, user_id: &UserId, review_id: &ReviewId) -> anyhow::Result<()> {
+        let flags = self
+            .federation_settings
+            .get_federation_flags(user_id)
+            .await
+            .unwrap_or(domain::ports::FederationFlags {
+                goals: true,
+                reviews: true,
+                watchlist: true,
+            });
+        if !flags.reviews {
+            return Ok(());
+        }
+
+        let review = match self.content_query.get_review_by_id(review_id).await? {
+            Some(r) => r,
+            None => return Ok(()),
+        };
+
+        let ap_id = review_url(&self.base_url, review_id);
+        let actor = actor_url(&self.base_url, user_id.value());
+
+        let movie = self
+            .content_query
+            .get_movie_by_id(review.movie_id())
+            .await
+            .ok()
+            .flatten();
+        let movie_title = movie
+            .as_ref()
+            .map(|m| m.title().value().to_string())
+            .unwrap_or_else(|| "Unknown".to_string());
+        let release_year = movie
+            .as_ref()
+            .map(|m| m.release_year().value())
+            .unwrap_or(0);
+        let poster_url = movie
+            .as_ref()
+            .and_then(|m| m.poster_path())
+            .map(|p| format!("{}/images/{}", self.base_url, p.value()));
+
+        let obj = review_to_ap_object(
+            &review,
+            ap_id.clone(),
+            actor,
+            movie_title,
+            release_year,
+            poster_url,
+            &self.base_url,
+        );
+        let json = serde_json::to_value(obj)?;
+
+        self.ap_service
+            .broadcast_create_note(user_id.value(), json, ApVisibility::Public, vec![])
+            .await?;
+
+        let year = review.watched_at().year() as u16;
+        self.broadcast_goal_progress_update(user_id, year).await?;
+
+        Ok(())
+    }
+
+    async fn on_review_updated(
+        &self,
+        user_id: &UserId,
+        review_id: &ReviewId,
+    ) -> anyhow::Result<()> {
+        let flags = self
+            .federation_settings
+            .get_federation_flags(user_id)
+            .await
+            .unwrap_or(domain::ports::FederationFlags {
+                goals: true,
+                reviews: true,
+                watchlist: true,
+            });
+        if !flags.reviews {
+            return Ok(());
+        }
+
+        let review = match self.content_query.get_review_by_id(review_id).await? {
+            Some(r) => r,
+            None => return Ok(()),
+        };
+
+        let ap_id = review_url(&self.base_url, review_id);
+        let actor = actor_url(&self.base_url, user_id.value());
+
+        let movie = self
+            .content_query
+            .get_movie_by_id(review.movie_id())
+            .await
+            .ok()
+            .flatten();
+        let movie_title = movie
+            .as_ref()
+            .map(|m| m.title().value().to_string())
+            .unwrap_or_else(|| "Unknown".to_string());
+        let release_year = movie
+            .as_ref()
+            .map(|m| m.release_year().value())
+            .unwrap_or(0);
+        let poster_url = movie
+            .as_ref()
+            .and_then(|m| m.poster_path())
+            .map(|p| format!("{}/images/{}", self.base_url, p.value()));
+
+        let obj = review_to_ap_object(
+            &review,
+            ap_id,
+            actor,
+            movie_title,
+            release_year,
+            poster_url,
+            &self.base_url,
+        );
+        let json = serde_json::to_value(obj)?;
+
+        self.ap_service
+            .broadcast_update_note(user_id.value(), json, ApVisibility::Public, vec![])
+            .await?;
+
+        Ok(())
+    }
+
+    async fn on_review_deleted(
+        &self,
+        user_id: &UserId,
+        review_id: &ReviewId,
+    ) -> anyhow::Result<()> {
+        let ap_id = review_url(&self.base_url, review_id);
+        self.ap_service
+            .broadcast_delete_to_followers(user_id.value(), ap_id)
+            .await?;
+        Ok(())
+    }
+
+    async fn on_watchlist_added(
+        &self,
+        user_id: &UserId,
+        movie_id: &domain::value_objects::MovieId,
+        movie_title: &str,
+        release_year: u16,
+        external_metadata_id: &Option<String>,
+        added_at: &chrono::NaiveDateTime,
+    ) -> anyhow::Result<()> {
+        let flags = self
+            .federation_settings
+            .get_federation_flags(user_id)
+            .await
+            .unwrap_or(domain::ports::FederationFlags {
+                goals: true,
+                reviews: true,
+                watchlist: true,
+            });
+        if !flags.watchlist {
+            return Ok(());
+        }
+
+        use crate::urls::watchlist_entry_url;
+        let ap_id = watchlist_entry_url(&self.base_url, user_id.value(), movie_id.value());
+        let actor = actor_url(&self.base_url, user_id.value());
+
+        let poster_url = self
+            .content_query
+            .get_movie_by_id(movie_id)
+            .await
+            .ok()
+            .flatten()
+            .and_then(|m| {
+                m.poster_path()
+                    .map(|p| format!("{}/images/{}", self.base_url, p.value()))
+            });
+
+        let added_at_utc =
+            chrono::DateTime::<chrono::Utc>::from_naive_utc_and_offset(*added_at, chrono::Utc);
+        let obj = crate::objects::watchlist_to_ap_object(crate::objects::WatchlistApInput {
+            ap_id: ap_id.clone(),
+            actor_url: actor,
+            movie_title: movie_title.to_string(),
+            release_year,
+            external_metadata_id: external_metadata_id.clone(),
+            poster_url,
+            added_at: added_at_utc,
+            base_url: self.base_url.clone(),
+        });
+        let json = serde_json::to_value(obj)?;
+
+        self.ap_service
+            .broadcast_create_note(user_id.value(), json, ApVisibility::Public, vec![])
+            .await?;
+        Ok(())
+    }
+
+    async fn on_watchlist_removed(
+        &self,
+        user_id: &UserId,
+        movie_id: &domain::value_objects::MovieId,
+    ) -> anyhow::Result<()> {
+        use crate::urls::watchlist_entry_url;
+        let ap_id = watchlist_entry_url(&self.base_url, user_id.value(), movie_id.value());
+        self.ap_service
+            .broadcast_delete_to_followers(user_id.value(), ap_id)
+            .await?;
+        Ok(())
+    }
+
+    async fn on_poster_synced(&self, movie_id: &MovieId) -> anyhow::Result<()> {
+        let entries = self
+            .content_query
+            .get_local_reviews_for_movie(movie_id)
+            .await?;
+
+        let movie = self.content_query.get_movie_by_id(movie_id).await?;
+        let movie = match movie {
+            Some(m) => m,
+            None => return Ok(()),
+        };
+        let poster_url = movie
+            .poster_path()
+            .map(|p| format!("{}/images/{}", self.base_url, p.value()));
+
+        for entry in entries {
+            let review = entry.review();
+            let user_id = review.user_id();
+
+            let flags = self
+                .federation_settings
+                .get_federation_flags(user_id)
+                .await
+                .unwrap_or(domain::ports::FederationFlags {
+                    goals: true,
+                    reviews: true,
+                    watchlist: true,
+                });
+            if !flags.reviews {
+                continue;
+            }
+
+            let ap_id = review_url(&self.base_url, review.id());
+            let actor = actor_url(&self.base_url, user_id.value());
+
+            let obj = review_to_ap_object(
+                review,
+                ap_id,
+                actor,
+                movie.title().value().to_string(),
+                movie.release_year().value(),
+                poster_url.clone(),
+                &self.base_url,
+            );
+            let json = serde_json::to_value(obj)?;
+
+            self.ap_service
+                .broadcast_update_note(user_id.value(), json, ApVisibility::Public, vec![])
+                .await?;
+        }
+
+        Ok(())
+    }
+
+    async fn broadcast_goal_progress_update(
+        &self,
+        user_id: &UserId,
+        year: u16,
+    ) -> anyhow::Result<()> {
+        let flags = self
+            .federation_settings
+            .get_federation_flags(user_id)
+            .await
+            .unwrap_or(domain::ports::FederationFlags {
+                goals: true,
+                reviews: true,
+                watchlist: true,
+            });
+        if !flags.goals {
+            return Ok(());
+        }
+        let Some((goal, current)) = self
+            .content_query
+            .get_goal_with_progress(user_id, year)
+            .await
+            .ok()
+            .flatten()
+        else {
+            return Ok(());
+        };
+        let ap_id = goal_url(&self.base_url, user_id.value(), year);
+        let actor = actor_url(&self.base_url, user_id.value());
+        let obj = goal_to_ap_object(
+            ap_id,
+            actor,
+            year,
+            goal.target_count(),
+            current,
+            &self.base_url,
+        );
+        let json = serde_json::to_value(obj)?;
+        self.ap_service
+            .broadcast_update_note(user_id.value(), json, ApVisibility::Public, vec![])
+            .await?;
+        Ok(())
+    }
+
+    async fn broadcast_goal(
+        &self,
+        user_id: &UserId,
+        year: u16,
+        target_count: u32,
+        is_create: bool,
+    ) -> anyhow::Result<()> {
+        let flags = self
+            .federation_settings
+            .get_federation_flags(user_id)
+            .await
+            .unwrap_or(domain::ports::FederationFlags {
+                goals: true,
+                reviews: true,
+                watchlist: true,
+            });
+        if !flags.goals {
+            return Ok(());
+        }
+        let current = self
+            .content_query
+            .get_goal_with_progress(user_id, year)
+            .await
+            .ok()
+            .flatten()
+            .map(|(_, c)| c)
+            .unwrap_or(0);
+
+        let ap_id = goal_url(&self.base_url, user_id.value(), year);
+        let actor = actor_url(&self.base_url, user_id.value());
+        let obj = goal_to_ap_object(ap_id, actor, year, target_count, current, &self.base_url);
+        let json = serde_json::to_value(obj)?;
+        if is_create {
+            self.ap_service
+                .broadcast_create_note(user_id.value(), json, ApVisibility::Public, vec![])
+                .await?;
+        } else {
+            self.ap_service
+                .broadcast_update_note(user_id.value(), json, ApVisibility::Public, vec![])
+                .await?;
+        }
+        Ok(())
+    }
+
+    async fn on_goal_deleted(&self, user_id: &UserId, year: u16) -> anyhow::Result<()> {
+        let flags = self
+            .federation_settings
+            .get_federation_flags(user_id)
+            .await
+            .unwrap_or(domain::ports::FederationFlags {
+                goals: true,
+                reviews: true,
+                watchlist: true,
+            });
+        if !flags.goals {
+            return Ok(());
+        }
+        let ap_id = goal_url(&self.base_url, user_id.value(), year);
+        self.ap_service
+            .broadcast_delete_to_followers(user_id.value(), ap_id)
+            .await?;
+        Ok(())
+    }
+}

crates/adapters/activitypub/src/federation_event_bridge.rs

@@ -0,0 +1,54 @@
+use std::sync::Arc;
+
+use domain::events::DomainEvent;
+use domain::value_objects::UserId;
+use k_ap::FederationEvent;
+
+pub struct FederationEventBridge {
+    domain_publisher: Arc<dyn domain::ports::EventPublisher>,
+}
+
+impl FederationEventBridge {
+    pub fn new(domain_publisher: Arc<dyn domain::ports::EventPublisher>) -> Self {
+        Self { domain_publisher }
+    }
+}
+
+#[async_trait::async_trait]
+impl k_ap::EventPublisher for FederationEventBridge {
+    async fn publish(&self, event: FederationEvent) -> anyhow::Result<()> {
+        match event {
+            FederationEvent::BackfillRequested {
+                owner_user_id,
+                follower_inbox_url,
+            } => self
+                .domain_publisher
+                .publish(&DomainEvent::BackfillFollower {
+                    owner_user_id: UserId::from_uuid(owner_user_id),
+                    follower_inbox_url,
+                })
+                .await
+                .map_err(|e| anyhow::anyhow!(e.to_string())),
+            FederationEvent::DeliveryRequested {
+                inbox,
+                activity,
+                signing_actor_id,
+            } => {
+                let json = serde_json::to_string(&activity)
+                    .map_err(|e| anyhow::anyhow!("serialize activity: {e}"))?;
+                self.domain_publisher
+                    .publish(&DomainEvent::FederationDeliveryRequested {
+                        inbox_url: inbox.to_string(),
+                        activity_json: json,
+                        signing_actor_id,
+                    })
+                    .await
+                    .map_err(|e| anyhow::anyhow!(e.to_string()))
+            }
+            FederationEvent::DeliveryFailed { inbox, error, .. } => {
+                tracing::warn!(inbox = %inbox, error = %error, "federation delivery failed permanently");
+                Ok(())
+            }
+        }
+    }
+}

crates/adapters/activitypub/src/goal_handler.rs

@@ -0,0 +1,95 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use domain::{models::RemoteGoalEntry, ports::RemoteGoalRepository};
+use k_ap::ApObjectHandler;
+use url::Url;
+
+use crate::objects::GoalObject;
+
+pub struct GoalObjectHandler {
+    pub remote_goal_repo: Arc<dyn RemoteGoalRepository>,
+}
+
+#[async_trait]
+impl ApObjectHandler for GoalObjectHandler {
+    async fn on_create(
+        &self,
+        ap_id: &Url,
+        actor_url: &Url,
+        object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        let obj: GoalObject = match serde_json::from_value(object) {
+            Ok(o) => o,
+            Err(e) => {
+                tracing::warn!(ap_id = %ap_id, "ignoring malformed goal Create: {}", e);
+                return Ok(());
+            }
+        };
+        let entry = RemoteGoalEntry {
+            ap_id: ap_id.as_str().to_string(),
+            actor_url: actor_url.as_str().to_string(),
+            year: obj.goal_year,
+            target_count: obj.goal_target,
+            current_count: obj.goal_current,
+            received_at: chrono::Utc::now(),
+        };
+        self.remote_goal_repo.save(entry).await?;
+        tracing::info!(ap_id = %ap_id, year = obj.goal_year, "saved remote goal");
+        Ok(())
+    }
+
+    async fn on_update(
+        &self,
+        ap_id: &Url,
+        actor_url: &Url,
+        object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        let obj: GoalObject = match serde_json::from_value(object) {
+            Ok(o) => o,
+            Err(e) => {
+                tracing::warn!(ap_id = %ap_id, "ignoring malformed goal Update: {}", e);
+                return Ok(());
+            }
+        };
+        if obj.attributed_to != *actor_url {
+            anyhow::bail!("goal Update actor does not match object attributed_to");
+        }
+        self.remote_goal_repo
+            .update_by_ap_id(ap_id.as_str(), obj.goal_target, obj.goal_current)
+            .await?;
+        tracing::info!(ap_id = %ap_id, "updated remote goal progress");
+        Ok(())
+    }
+
+    async fn on_delete(&self, ap_id: &Url, actor_url: &Url) -> anyhow::Result<()> {
+        self.remote_goal_repo
+            .remove_by_ap_id(ap_id.as_str(), actor_url.as_str())
+            .await?;
+        tracing::info!(ap_id = %ap_id, "removed remote goal");
+        Ok(())
+    }
+
+    async fn on_actor_removed(&self, actor_url: &Url) -> anyhow::Result<()> {
+        self.remote_goal_repo
+            .remove_all_by_actor(actor_url.as_str())
+            .await?;
+        Ok(())
+    }
+
+    async fn on_like(&self, _: &Url, _: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn on_announce_received(&self, _: &Url, _: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn on_announce_of_remote(&self, _: &Url, _: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn on_unlike(&self, _: &Url, _: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn on_mention(&self, _: &Url, _: uuid::Uuid, _: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+}

crates/adapters/activitypub/src/lib.rs

@@ -0,0 +1,143 @@
+pub mod composite_handler;
+pub mod event_handler;
+pub mod federation_event_bridge;
+pub mod goal_handler;
+pub mod objects;
+pub mod port;
+pub mod remote_review_repository;
+pub mod review_handler;
+pub(crate) mod urls;
+pub mod user_adapter;
+pub mod watchlist_handler;
+
+pub const INSTANCE_ACTOR_ID: uuid::Uuid =
+    uuid::Uuid::from_bytes([0, 0, 0, 0, 0, 0, 0x40, 0, 0x80, 0, 0, 0, 0, 0, 0, 0]);
+
+// Re-export the generic base types that callers need
+pub use k_ap::{
+    ActivityPubService, ActivityRepository, ActorRepository, ApContentReader, ApFederationConfig,
+    ApObjectHandler, ApUser, ApUserRepository, BlocklistRepository, FederationData,
+    FollowRepository, Follower, FollowerStatus, FollowingStatus, RemoteActor,
+};
+
+pub use event_handler::ActivityPubEventHandler;
+pub use port::{ActivityPubPort, NoopActivityPubService};
+pub use remote_review_repository::RemoteReviewRepository;
+pub use review_handler::ReviewObjectHandler;
+pub use user_adapter::DomainUserRepoAdapter;
+
+pub type FederationRepos = (
+    std::sync::Arc<dyn ActivityRepository>,
+    std::sync::Arc<dyn FollowRepository>,
+    std::sync::Arc<dyn ActorRepository>,
+    std::sync::Arc<dyn BlocklistRepository>,
+    std::sync::Arc<dyn domain::ports::SocialQueryPort>,
+    std::sync::Arc<dyn RemoteReviewRepository>,
+    std::sync::Arc<dyn domain::ports::RemoteWatchlistRepository>,
+);
+
+pub struct ActivityPubWire {
+    pub service: std::sync::Arc<dyn ActivityPubPort>,
+    pub router: axum::Router,
+    pub event_handler: std::sync::Arc<dyn domain::ports::EventHandler>,
+}
+
+pub struct ActivityPubDeps {
+    pub activity_repo: std::sync::Arc<dyn ActivityRepository>,
+    pub follow_repo: std::sync::Arc<dyn FollowRepository>,
+    pub actor_repo: std::sync::Arc<dyn ActorRepository>,
+    pub blocklist_repo: std::sync::Arc<dyn BlocklistRepository>,
+    pub review_store: std::sync::Arc<dyn RemoteReviewRepository>,
+    pub remote_watchlist_repo: std::sync::Arc<dyn domain::ports::RemoteWatchlistRepository>,
+    pub remote_goal_repo: std::sync::Arc<dyn domain::ports::RemoteGoalRepository>,
+    pub local_ap_content: std::sync::Arc<dyn domain::ports::LocalApContentQuery>,
+    pub user_repo: std::sync::Arc<dyn domain::ports::UserRepository>,
+    pub federation_settings: std::sync::Arc<dyn domain::ports::UserFederationSettingsQuery>,
+    pub base_url: String,
+    pub allow_registration: bool,
+    pub event_publisher: std::sync::Arc<dyn domain::ports::EventPublisher>,
+}
+
+pub async fn wire(deps: ActivityPubDeps) -> anyhow::Result<ActivityPubWire> {
+    let ActivityPubDeps {
+        activity_repo,
+        follow_repo,
+        actor_repo,
+        blocklist_repo,
+        review_store,
+        remote_watchlist_repo,
+        remote_goal_repo,
+        local_ap_content,
+        user_repo,
+        federation_settings,
+        base_url,
+        allow_registration,
+        event_publisher,
+    } = deps;
+    let review_handler = std::sync::Arc::new(ReviewObjectHandler {
+        content_query: std::sync::Arc::clone(&local_ap_content),
+        review_store,
+        base_url: base_url.clone(),
+    });
+    let watchlist_handler = std::sync::Arc::new(watchlist_handler::WatchlistObjectHandler {
+        remote_watchlist_repo,
+        content_query: std::sync::Arc::clone(&local_ap_content),
+        base_url: base_url.clone(),
+    });
+    let goal_handler = std::sync::Arc::new(goal_handler::GoalObjectHandler { remote_goal_repo });
+    let composite = std::sync::Arc::new(composite_handler::CompositeObjectHandler {
+        review: review_handler,
+        watchlist: watchlist_handler,
+        goal: goal_handler,
+    });
+
+    let federation_debug = std::env::var("FEDERATION_DEBUG")
+        .map(|v| v == "true" || v == "1")
+        .unwrap_or(false);
+
+    if federation_debug {
+        tracing::warn!(
+            "federation running in DEBUG mode — PermissiveVerifier active, \
+             no URL/signature validation. Do NOT use in production."
+        );
+    }
+
+    let fed_event_bridge = std::sync::Arc::new(
+        federation_event_bridge::FederationEventBridge::new(event_publisher),
+    );
+
+    let concrete = std::sync::Arc::new(
+        ActivityPubService::builder(base_url.clone())
+            .activity_repo(activity_repo)
+            .follow_repo(follow_repo)
+            .actor_repo(actor_repo)
+            .blocklist_repo(blocklist_repo)
+            .user_repo(std::sync::Arc::new(DomainUserRepoAdapter::new(
+                user_repo,
+                base_url.clone(),
+            )))
+            .signed_fetch_actor_id(INSTANCE_ACTOR_ID)
+            .content_reader(composite.clone() as std::sync::Arc<dyn ApContentReader>)
+            .object_handler(composite as std::sync::Arc<dyn ApObjectHandler>)
+            .event_publisher(fed_event_bridge)
+            .allow_registration(allow_registration)
+            .software_name("movies-diary")
+            .debug(federation_debug)
+            .build()
+            .await?,
+    );
+
+    let router = concrete.router();
+    let event_handler = std::sync::Arc::new(ActivityPubEventHandler::new(
+        std::sync::Arc::clone(&concrete),
+        local_ap_content,
+        federation_settings,
+        base_url,
+    )) as std::sync::Arc<dyn domain::ports::EventHandler>;
+
+    Ok(ActivityPubWire {
+        service: concrete as std::sync::Arc<dyn ActivityPubPort>,
+        router,
+        event_handler,
+    })
+}

crates/adapters/activitypub/src/objects.rs

@@ -0,0 +1,254 @@
+use chrono::{DateTime, Utc};
+use k_ap::AS_PUBLIC;
+use k_ap::NoteType;
+use serde::{Deserialize, Serialize};
+use url::Url;
+
+use domain::models::Review;
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+pub struct ApHashtag {
+    #[serde(rename = "type")]
+    pub(crate) kind: String,
+    pub(crate) href: Url,
+    pub(crate) name: String,
+}
+
+pub(crate) fn normalize_hashtag(title: &str) -> String {
+    title.chars().filter(|c| c.is_alphanumeric()).collect()
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ReviewObject {
+    #[serde(rename = "type")]
+    pub(crate) kind: NoteType,
+    pub(crate) id: Url,
+    pub(crate) attributed_to: Url,
+    pub(crate) content: String,
+    pub(crate) published: DateTime<Utc>,
+    pub(crate) movie_title: String,
+    #[serde(default)]
+    pub(crate) release_year: u16,
+    #[serde(default)]
+    pub(crate) poster_url: Option<String>,
+    pub(crate) rating: u8,
+    pub(crate) comment: Option<String>,
+    pub(crate) watched_at: DateTime<Utc>,
+    #[serde(default)]
+    pub(crate) tag: Vec<ApHashtag>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub(crate) to: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub(crate) cc: Vec<String>,
+}
+
+/// Serialize a local Review into a ReviewObject for AP delivery.
+/// Takes movie metadata explicitly since the handler fetches it separately.
+pub fn review_to_ap_object(
+    review: &Review,
+    ap_id: Url,
+    actor_url: Url,
+    movie_title: String,
+    release_year: u16,
+    poster_url: Option<String>,
+    base_url: &str,
+) -> ReviewObject {
+    let stars: String = "\u{2B50}".repeat(review.rating().value() as usize);
+    let comment_text = review.comment().map(|c| c.value().to_string());
+    let year_str = if release_year > 0 {
+        format!(" ({})", release_year)
+    } else {
+        String::new()
+    };
+    let watched_str = format!("Watched: {}", review.watched_at().format("%b %-d, %Y"));
+    let content = match &comment_text {
+        Some(c) => format!(
+            "{} {}{}\n{}\n{}",
+            stars, movie_title, year_str, c, watched_str
+        ),
+        None => format!("{} {}{}\n{}", stars, movie_title, year_str, watched_str),
+    };
+
+    let normalized = normalize_hashtag(&movie_title);
+    let tag = vec![
+        ApHashtag {
+            kind: "Hashtag".to_string(),
+            href: Url::parse(&format!("{}/tags/moviesdiary", base_url)).expect("valid base_url"),
+            name: "#MoviesDiary".to_string(),
+        },
+        ApHashtag {
+            kind: "Hashtag".to_string(),
+            href: Url::parse(&format!("{}/tags/{}", base_url, normalized.to_lowercase()))
+                .expect("valid base_url"),
+            name: format!("#{}", normalized),
+        },
+    ];
+
+    ReviewObject {
+        kind: NoteType::default(),
+        id: ap_id,
+        attributed_to: actor_url.clone(),
+        content,
+        published: DateTime::from_naive_utc_and_offset(*review.created_at(), Utc),
+        movie_title,
+        release_year,
+        poster_url,
+        rating: review.rating().value(),
+        comment: comment_text,
+        watched_at: DateTime::from_naive_utc_and_offset(*review.watched_at(), Utc),
+        tag,
+        to: vec![AS_PUBLIC.to_string()],
+        cc: vec![format!("{}/followers", actor_url)],
+    }
+}
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct WatchlistObject {
+    #[serde(rename = "type")]
+    pub(crate) kind: NoteType,
+    pub(crate) id: Url,
+    pub(crate) attributed_to: Url,
+    pub(crate) content: String,
+    pub(crate) published: chrono::DateTime<chrono::Utc>,
+    pub(crate) movie_title: String,
+    #[serde(default)]
+    pub(crate) release_year: u16,
+    #[serde(default)]
+    pub(crate) external_metadata_id: Option<String>,
+    #[serde(default)]
+    pub(crate) poster_url: Option<String>,
+    #[serde(default)]
+    pub(crate) tag: Vec<ApHashtag>,
+    /// Discriminator so Movies Diary instances distinguish this from a review Note.
+    /// Non-Movies-Diary apps ignore unknown fields.
+    #[serde(default)]
+    pub(crate) watchlist_entry: bool,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub(crate) to: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub(crate) cc: Vec<String>,
+}
+
+pub struct WatchlistApInput {
+    pub ap_id: Url,
+    pub actor_url: Url,
+    pub movie_title: String,
+    pub release_year: u16,
+    pub external_metadata_id: Option<String>,
+    pub poster_url: Option<String>,
+    pub added_at: chrono::DateTime<chrono::Utc>,
+    pub base_url: String,
+}
+
+pub fn watchlist_to_ap_object(input: WatchlistApInput) -> WatchlistObject {
+    let WatchlistApInput {
+        ap_id,
+        actor_url,
+        movie_title,
+        release_year,
+        external_metadata_id,
+        poster_url,
+        added_at,
+        base_url,
+    } = input;
+    let year_str = if release_year > 0 {
+        format!(" ({})", release_year)
+    } else {
+        String::new()
+    };
+    let content = format!("📋 {}{} — want to watch", movie_title, year_str);
+    let normalized = normalize_hashtag(&movie_title);
+    let tag = vec![
+        ApHashtag {
+            kind: "Hashtag".to_string(),
+            href: Url::parse(&format!("{}/tags/moviesdiary", base_url)).expect("valid base_url"),
+            name: "#MoviesDiary".to_string(),
+        },
+        ApHashtag {
+            kind: "Hashtag".to_string(),
+            href: Url::parse(&format!("{}/tags/{}", base_url, normalized.to_lowercase()))
+                .expect("valid base_url"),
+            name: format!("#{}", normalized),
+        },
+    ];
+
+    WatchlistObject {
+        kind: NoteType::default(),
+        id: ap_id,
+        attributed_to: actor_url.clone(),
+        content,
+        published: added_at,
+        movie_title,
+        release_year,
+        external_metadata_id,
+        poster_url,
+        tag,
+        watchlist_entry: true,
+        to: vec![AS_PUBLIC.to_string()],
+        cc: vec![format!("{}/followers", actor_url)],
+    }
+}
+
+// ── Goal object ──────────────────────────────────────────────────────────────
+
+#[derive(Debug, Clone, Deserialize, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct GoalObject {
+    #[serde(rename = "type")]
+    pub(crate) kind: NoteType,
+    pub(crate) id: Url,
+    pub(crate) attributed_to: Url,
+    pub(crate) content: String,
+    pub(crate) published: chrono::DateTime<chrono::Utc>,
+    pub(crate) goal_year: u16,
+    pub(crate) goal_target: u32,
+    pub(crate) goal_current: u32,
+    #[serde(default)]
+    pub(crate) goal: bool,
+    #[serde(default)]
+    pub(crate) tag: Vec<ApHashtag>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub(crate) to: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub(crate) cc: Vec<String>,
+}
+
+pub fn goal_to_ap_object(
+    ap_id: Url,
+    actor_url: Url,
+    year: u16,
+    target: u32,
+    current: u32,
+    base_url: &str,
+) -> GoalObject {
+    let content = format!(
+        "🎯 Goal: Watch {} movies in {} ({}/{})",
+        target, year, current, target
+    );
+    let tag = vec![ApHashtag {
+        kind: "Hashtag".to_string(),
+        href: Url::parse(&format!("{}/tags/moviesdiary", base_url)).expect("valid base_url"),
+        name: "#MoviesDiary".to_string(),
+    }];
+
+    GoalObject {
+        kind: NoteType::default(),
+        id: ap_id,
+        attributed_to: actor_url.clone(),
+        content,
+        published: chrono::Utc::now(),
+        goal_year: year,
+        goal_target: target,
+        goal_current: current,
+        goal: true,
+        tag,
+        to: vec![AS_PUBLIC.to_string()],
+        cc: vec![format!("{}/followers", actor_url)],
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/objects.rs"]
+mod tests;

crates/adapters/activitypub/src/port.rs

@@ -0,0 +1,210 @@
+use async_trait::async_trait;
+use uuid::Uuid;
+
+use k_ap::{ActivityPubService, BlockedDomain, RemoteActor};
+
+#[async_trait]
+pub trait ActivityPubPort: Send + Sync {
+    async fn actor_json(&self, user_id: &str) -> anyhow::Result<String>;
+    async fn count_following(&self, local_user_id: Uuid) -> anyhow::Result<usize>;
+    async fn count_accepted_followers(&self, local_user_id: Uuid) -> anyhow::Result<usize>;
+    async fn get_pending_followers(&self, local_user_id: Uuid) -> anyhow::Result<Vec<RemoteActor>>;
+    async fn follow(&self, local_user_id: Uuid, handle: &str) -> anyhow::Result<()>;
+    async fn unfollow(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()>;
+    async fn accept_follower(
+        &self,
+        local_user_id: Uuid,
+        remote_actor_url: &str,
+    ) -> anyhow::Result<()>;
+    async fn reject_follower(
+        &self,
+        local_user_id: Uuid,
+        remote_actor_url: &str,
+    ) -> anyhow::Result<()>;
+    async fn get_following(&self, local_user_id: Uuid) -> anyhow::Result<Vec<RemoteActor>>;
+    async fn get_accepted_followers(&self, local_user_id: Uuid)
+    -> anyhow::Result<Vec<RemoteActor>>;
+    async fn remove_follower(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()>;
+    async fn block_actor(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()>;
+    async fn unblock_actor(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()>;
+    async fn get_blocked_actors(&self, local_user_id: Uuid) -> anyhow::Result<Vec<RemoteActor>>;
+    async fn add_blocked_domain(&self, domain: &str, reason: Option<&str>) -> anyhow::Result<()>;
+    async fn remove_blocked_domain(&self, domain: &str) -> anyhow::Result<()>;
+    async fn get_blocked_domains(&self) -> anyhow::Result<Vec<BlockedDomain>>;
+    async fn import_remote_outbox(&self, outbox_url: &str, actor_url: &str) -> anyhow::Result<()>;
+    async fn followers_collection_json(
+        &self,
+        user_id: Uuid,
+        page: Option<u32>,
+    ) -> anyhow::Result<String>;
+    async fn following_collection_json(
+        &self,
+        user_id: Uuid,
+        page: Option<u32>,
+    ) -> anyhow::Result<String>;
+    async fn run_backfill_for_follower(
+        &self,
+        owner_user_id: Uuid,
+        follower_inbox_url: String,
+    ) -> anyhow::Result<()>;
+}
+
+#[async_trait]
+impl ActivityPubPort for ActivityPubService {
+    async fn actor_json(&self, user_id: &str) -> anyhow::Result<String> {
+        self.actor_json(user_id).await
+    }
+    async fn count_following(&self, local_user_id: Uuid) -> anyhow::Result<usize> {
+        self.count_following(local_user_id).await
+    }
+    async fn count_accepted_followers(&self, local_user_id: Uuid) -> anyhow::Result<usize> {
+        self.count_accepted_followers(local_user_id).await
+    }
+    async fn get_pending_followers(&self, local_user_id: Uuid) -> anyhow::Result<Vec<RemoteActor>> {
+        self.get_pending_followers(local_user_id).await
+    }
+    async fn follow(&self, local_user_id: Uuid, handle: &str) -> anyhow::Result<()> {
+        self.follow(local_user_id, handle).await
+    }
+    async fn unfollow(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()> {
+        self.unfollow(local_user_id, actor_url).await
+    }
+    async fn accept_follower(
+        &self,
+        local_user_id: Uuid,
+        remote_actor_url: &str,
+    ) -> anyhow::Result<()> {
+        self.accept_follower(local_user_id, remote_actor_url).await
+    }
+    async fn reject_follower(
+        &self,
+        local_user_id: Uuid,
+        remote_actor_url: &str,
+    ) -> anyhow::Result<()> {
+        self.reject_follower(local_user_id, remote_actor_url).await
+    }
+    async fn get_following(&self, local_user_id: Uuid) -> anyhow::Result<Vec<RemoteActor>> {
+        self.get_following(local_user_id).await
+    }
+    async fn get_accepted_followers(
+        &self,
+        local_user_id: Uuid,
+    ) -> anyhow::Result<Vec<RemoteActor>> {
+        self.get_accepted_followers(local_user_id).await
+    }
+    async fn remove_follower(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()> {
+        self.remove_follower(local_user_id, actor_url).await
+    }
+    async fn block_actor(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()> {
+        self.block_actor(local_user_id, actor_url).await
+    }
+    async fn unblock_actor(&self, local_user_id: Uuid, actor_url: &str) -> anyhow::Result<()> {
+        self.unblock_actor(local_user_id, actor_url).await
+    }
+    async fn get_blocked_actors(&self, local_user_id: Uuid) -> anyhow::Result<Vec<RemoteActor>> {
+        self.get_blocked_actors(local_user_id).await
+    }
+    async fn add_blocked_domain(&self, domain: &str, reason: Option<&str>) -> anyhow::Result<()> {
+        self.add_blocked_domain(domain, reason).await
+    }
+    async fn remove_blocked_domain(&self, domain: &str) -> anyhow::Result<()> {
+        self.remove_blocked_domain(domain).await
+    }
+    async fn get_blocked_domains(&self) -> anyhow::Result<Vec<BlockedDomain>> {
+        self.get_blocked_domains().await
+    }
+    async fn import_remote_outbox(&self, outbox_url: &str, actor_url: &str) -> anyhow::Result<()> {
+        self.import_remote_outbox(outbox_url, actor_url).await
+    }
+    async fn followers_collection_json(
+        &self,
+        user_id: Uuid,
+        page: Option<u32>,
+    ) -> anyhow::Result<String> {
+        self.followers_collection_json(user_id, page).await
+    }
+    async fn following_collection_json(
+        &self,
+        user_id: Uuid,
+        page: Option<u32>,
+    ) -> anyhow::Result<String> {
+        self.following_collection_json(user_id, page).await
+    }
+    async fn run_backfill_for_follower(
+        &self,
+        owner_user_id: Uuid,
+        follower_inbox_url: String,
+    ) -> anyhow::Result<()> {
+        self.run_backfill_for_follower(owner_user_id, follower_inbox_url)
+            .await
+    }
+}
+
+pub struct NoopActivityPubService;
+
+#[async_trait]
+impl ActivityPubPort for NoopActivityPubService {
+    async fn actor_json(&self, _: &str) -> anyhow::Result<String> {
+        Ok(String::new())
+    }
+    async fn count_following(&self, _: Uuid) -> anyhow::Result<usize> {
+        Ok(0)
+    }
+    async fn count_accepted_followers(&self, _: Uuid) -> anyhow::Result<usize> {
+        Ok(0)
+    }
+    async fn get_pending_followers(&self, _: Uuid) -> anyhow::Result<Vec<RemoteActor>> {
+        Ok(vec![])
+    }
+    async fn follow(&self, _: Uuid, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn unfollow(&self, _: Uuid, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn accept_follower(&self, _: Uuid, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn reject_follower(&self, _: Uuid, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn get_following(&self, _: Uuid) -> anyhow::Result<Vec<RemoteActor>> {
+        Ok(vec![])
+    }
+    async fn get_accepted_followers(&self, _: Uuid) -> anyhow::Result<Vec<RemoteActor>> {
+        Ok(vec![])
+    }
+    async fn remove_follower(&self, _: Uuid, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn block_actor(&self, _: Uuid, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn unblock_actor(&self, _: Uuid, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn get_blocked_actors(&self, _: Uuid) -> anyhow::Result<Vec<RemoteActor>> {
+        Ok(vec![])
+    }
+    async fn add_blocked_domain(&self, _: &str, _: Option<&str>) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn remove_blocked_domain(&self, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn get_blocked_domains(&self) -> anyhow::Result<Vec<BlockedDomain>> {
+        Ok(vec![])
+    }
+    async fn import_remote_outbox(&self, _: &str, _: &str) -> anyhow::Result<()> {
+        Ok(())
+    }
+    async fn followers_collection_json(&self, _: Uuid, _: Option<u32>) -> anyhow::Result<String> {
+        Ok(String::new())
+    }
+    async fn following_collection_json(&self, _: Uuid, _: Option<u32>) -> anyhow::Result<String> {
+        Ok(String::new())
+    }
+    async fn run_backfill_for_follower(&self, _: Uuid, _: String) -> anyhow::Result<()> {
+        Ok(())
+    }
+}

crates/adapters/activitypub/src/remote_review_repository.rs

@@ -0,0 +1,30 @@
+use anyhow::Result;
+use async_trait::async_trait;
+use chrono::NaiveDateTime;
+use domain::models::Review;
+
+#[async_trait]
+pub trait RemoteReviewRepository: Send + Sync {
+    async fn save_remote_review(
+        &self,
+        review: &Review,
+        ap_id: &str,
+        movie_title: &str,
+        release_year: u16,
+        poster_url: Option<&str>,
+    ) -> Result<()>;
+
+    async fn delete_remote_review(&self, ap_id: &str, actor_url: &str) -> Result<()>;
+
+    async fn update_remote_review(
+        &self,
+        ap_id: &str,
+        actor_url: &str,
+        rating: u8,
+        comment: Option<&str>,
+        watched_at: NaiveDateTime,
+        poster_url: Option<&str>,
+    ) -> Result<()>;
+
+    async fn delete_by_actor(&self, actor_url: &str) -> Result<()>;
+}

crates/adapters/activitypub/src/review_handler.rs

@@ -0,0 +1,205 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use domain::{
+    models::ReviewSource,
+    ports::LocalApContentQuery,
+    value_objects::{Comment, MovieId, Rating, ReviewId, UserId},
+};
+use k_ap::{ApContentReader, ApObjectHandler};
+use url::Url;
+
+use crate::objects::{ReviewObject, review_to_ap_object};
+use crate::remote_review_repository::RemoteReviewRepository;
+use crate::urls::{actor_url, review_url};
+
+pub struct ReviewObjectHandler {
+    pub content_query: Arc<dyn LocalApContentQuery>,
+    pub review_store: Arc<dyn RemoteReviewRepository>,
+    pub base_url: String,
+}
+
+#[async_trait]
+impl ApContentReader for ReviewObjectHandler {
+    async fn get_local_objects_page(
+        &self,
+        user_id: uuid::Uuid,
+        before: Option<chrono::DateTime<chrono::Utc>>,
+        limit: usize,
+    ) -> anyhow::Result<Vec<(url::Url, serde_json::Value, chrono::DateTime<chrono::Utc>)>> {
+        let domain_user_id = UserId::from_uuid(user_id);
+        let before_naive = before.map(|dt| dt.naive_utc());
+        let entries = self
+            .content_query
+            .get_local_reviews_page(&domain_user_id, before_naive, limit)
+            .await
+            .map_err(|e| anyhow::anyhow!(e.to_string()))?;
+
+        let actor = actor_url(&self.base_url, user_id);
+        let mut results = Vec::new();
+        for entry in entries {
+            let review = entry.review();
+            let published =
+                chrono::DateTime::from_naive_utc_and_offset(*review.watched_at(), chrono::Utc);
+            let movie = entry.movie();
+            let ap_id = review_url(&self.base_url, review.id());
+            let poster_url = movie
+                .poster_path()
+                .map(|p| format!("{}/images/{}", self.base_url, p.value()));
+
+            let obj = review_to_ap_object(
+                review,
+                ap_id.clone(),
+                actor.clone(),
+                movie.title().value().to_string(),
+                movie.release_year().value(),
+                poster_url,
+                &self.base_url,
+            );
+            results.push((ap_id, serde_json::to_value(obj)?, published));
+        }
+        Ok(results)
+    }
+
+    async fn count_local_posts(&self) -> anyhow::Result<u64> {
+        self.content_query
+            .count_local_posts()
+            .await
+            .map_err(|e| anyhow::anyhow!(e.to_string()))
+    }
+}
+
+#[async_trait]
+impl ApObjectHandler for ReviewObjectHandler {
+    async fn on_create(
+        &self,
+        _ap_id: &Url,
+        _actor_url: &Url,
+        object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        let mut obj: ReviewObject = match serde_json::from_value(object) {
+            Ok(o) => o,
+            Err(e) => {
+                tracing::warn!("ignoring unrecognized Create object: {}", e);
+                return Ok(());
+            }
+        };
+        obj.movie_title = ammonia::clean(&obj.movie_title);
+        obj.comment = obj.comment.map(|c| ammonia::clean(&c));
+
+        let actor_url_str = obj.attributed_to.to_string();
+        let review_id = ReviewId::generate();
+        let movie_id = MovieId::from_uuid(uuid::Uuid::new_v5(
+            &uuid::Uuid::NAMESPACE_URL,
+            obj.movie_title.as_bytes(),
+        ));
+        let user_id = UserId::from_uuid(uuid::Uuid::new_v5(
+            &uuid::Uuid::NAMESPACE_URL,
+            actor_url_str.as_bytes(),
+        ));
+        let rating = Rating::new(obj.rating.min(5))?;
+        let comment = obj.comment.map(Comment::new).transpose()?;
+
+        let review = domain::models::Review::from_persistence(domain::models::PersistedReview {
+            id: review_id,
+            movie_id,
+            user_id,
+            rating,
+            comment,
+            watched_at: obj.watched_at.naive_utc(),
+            created_at: obj.published.naive_utc(),
+            source: ReviewSource::Remote {
+                actor_url: actor_url_str,
+            },
+        });
+
+        self.review_store
+            .save_remote_review(
+                &review,
+                obj.id.as_str(),
+                &obj.movie_title,
+                obj.release_year,
+                obj.poster_url.as_deref(),
+            )
+            .await?;
+
+        Ok(())
+    }
+
+    async fn on_update(
+        &self,
+        ap_id: &Url,
+        actor_url: &Url,
+        object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        let mut obj: ReviewObject = match serde_json::from_value(object) {
+            Ok(o) => o,
+            Err(_) => {
+                tracing::warn!(actor = %actor_url, "ignoring non-review Update activity");
+                return Ok(());
+            }
+        };
+        obj.movie_title = ammonia::clean(&obj.movie_title);
+        obj.comment = obj.comment.map(|c| ammonia::clean(&c));
+
+        if obj.attributed_to != *actor_url {
+            anyhow::bail!("update actor does not match object attributed_to");
+        }
+
+        self.review_store
+            .update_remote_review(
+                ap_id.as_str(),
+                actor_url.as_str(),
+                obj.rating.min(5),
+                obj.comment.as_deref(),
+                obj.watched_at.naive_utc(),
+                obj.poster_url.as_deref(),
+            )
+            .await?;
+
+        Ok(())
+    }
+
+    async fn on_delete(&self, ap_id: &Url, actor_url: &Url) -> anyhow::Result<()> {
+        self.review_store
+            .delete_remote_review(ap_id.as_str(), actor_url.as_str())
+            .await
+    }
+
+    async fn on_actor_removed(&self, actor_url: &Url) -> anyhow::Result<()> {
+        self.review_store.delete_by_actor(actor_url.as_str()).await
+    }
+
+    async fn on_like(&self, _object_url: &Url, _actor_url: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_announce_received(
+        &self,
+        _object_url: &Url,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_announce_of_remote(
+        &self,
+        _object_url: &Url,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_unlike(&self, _object_url: &Url, _actor_url: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_mention(
+        &self,
+        _thought_ap_id: &Url,
+        _mentioned_user_uuid: uuid::Uuid,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+}

crates/adapters/activitypub/src/tests/objects.rs

@@ -0,0 +1,97 @@
+use super::*;
+
+#[test]
+fn normalize_hashtag_strips_non_alphanumeric() {
+    assert_eq!(normalize_hashtag("The Dark Knight"), "TheDarkKnight");
+    assert_eq!(normalize_hashtag("Schindler's List"), "SchindlersList");
+    assert_eq!(
+        normalize_hashtag("2001: A Space Odyssey"),
+        "2001ASpaceOdyssey"
+    );
+}
+
+#[test]
+fn review_to_ap_object_includes_two_hashtags() {
+    use chrono::NaiveDateTime;
+    use domain::{
+        models::{PersistedReview, Review, ReviewSource},
+        value_objects::{MovieId, Rating, ReviewId, UserId},
+    };
+
+    let review = Review::from_persistence(PersistedReview {
+        id: ReviewId::generate(),
+        movie_id: MovieId::from_uuid(uuid::Uuid::new_v4()),
+        user_id: UserId::from_uuid(uuid::Uuid::new_v4()),
+        rating: Rating::new(4).unwrap(),
+        comment: None,
+        watched_at: NaiveDateTime::parse_from_str("2024-01-01 00:00:00", "%Y-%m-%d %H:%M:%S")
+            .unwrap(),
+        created_at: NaiveDateTime::parse_from_str("2024-01-01 00:00:00", "%Y-%m-%d %H:%M:%S")
+            .unwrap(),
+        source: ReviewSource::Local,
+    });
+    let obj = review_to_ap_object(
+        &review,
+        "https://example.com/reviews/1".parse().unwrap(),
+        "https://example.com/users/1".parse().unwrap(),
+        "Dune".to_string(),
+        2021,
+        None,
+        "https://example.com",
+    );
+    assert_eq!(obj.tag.len(), 2);
+    let names: Vec<&str> = obj.tag.iter().map(|t| t.name.as_str()).collect();
+    assert!(names.contains(&"#MoviesDiary"));
+    assert!(names.contains(&"#Dune"));
+}
+
+#[test]
+fn review_to_ap_object_has_public_addressing() {
+    use chrono::NaiveDateTime;
+    use domain::{
+        models::{PersistedReview, Review, ReviewSource},
+        value_objects::{MovieId, Rating, ReviewId, UserId},
+    };
+
+    let review = Review::from_persistence(PersistedReview {
+        id: ReviewId::generate(),
+        movie_id: MovieId::from_uuid(uuid::Uuid::new_v4()),
+        user_id: UserId::from_uuid(uuid::Uuid::new_v4()),
+        rating: Rating::new(3).unwrap(),
+        comment: None,
+        watched_at: NaiveDateTime::parse_from_str("2024-06-01 00:00:00", "%Y-%m-%d %H:%M:%S")
+            .unwrap(),
+        created_at: NaiveDateTime::parse_from_str("2024-06-01 00:00:00", "%Y-%m-%d %H:%M:%S")
+            .unwrap(),
+        source: ReviewSource::Local,
+    });
+    let actor_url: url::Url = "https://example.com/users/abc".parse().unwrap();
+    let obj = review_to_ap_object(
+        &review,
+        "https://example.com/reviews/1".parse().unwrap(),
+        actor_url.clone(),
+        "Dune".to_string(),
+        2021,
+        None,
+        "https://example.com",
+    );
+    assert_eq!(obj.to, vec!["https://www.w3.org/ns/activitystreams#Public"]);
+    assert_eq!(obj.cc, vec!["https://example.com/users/abc/followers"]);
+}
+
+#[test]
+fn watchlist_to_ap_object_has_public_addressing() {
+    let actor_url: url::Url = "https://example.com/users/abc".parse().unwrap();
+    let obj = watchlist_to_ap_object(WatchlistApInput {
+        ap_id: "https://example.com/watchlist/1".parse().unwrap(),
+        actor_url: actor_url.clone(),
+        movie_title: "Alien".to_string(),
+        release_year: 1979,
+        external_metadata_id: None,
+        poster_url: None,
+        added_at: chrono::Utc::now(),
+        base_url: "https://example.com".to_string(),
+    });
+    assert_eq!(obj.to, vec!["https://www.w3.org/ns/activitystreams#Public"]);
+    assert_eq!(obj.cc, vec!["https://example.com/users/abc/followers"]);
+}

crates/adapters/activitypub/src/urls.rs

@@ -0,0 +1,28 @@
+use domain::value_objects::ReviewId;
+use url::Url;
+
+/// Builds the canonical actor URL: `{base_url}/users/{user_id}`
+pub fn actor_url(base_url: &str, user_id: uuid::Uuid) -> Url {
+    Url::parse(&format!("{}/users/{}", base_url, user_id))
+        .expect("base_url is always a valid URL prefix")
+}
+
+/// Builds the canonical review URL: `{base_url}/reviews/{review_id}`
+pub fn review_url(base_url: &str, review_id: &ReviewId) -> Url {
+    Url::parse(&format!("{}/reviews/{}", base_url, review_id.value()))
+        .expect("base_url is always a valid URL prefix")
+}
+
+pub fn goal_url(base_url: &str, user_id: uuid::Uuid, year: u16) -> Url {
+    Url::parse(&format!("{}/users/{}/goals/{}", base_url, user_id, year))
+        .expect("base_url is always a valid URL prefix")
+}
+
+/// Builds the canonical watchlist entry URL: `{base_url}/users/{user_id}/watchlist/{movie_id}`
+pub fn watchlist_entry_url(base_url: &str, user_id: uuid::Uuid, movie_id: uuid::Uuid) -> Url {
+    Url::parse(&format!(
+        "{}/users/{}/watchlist/{}",
+        base_url, user_id, movie_id
+    ))
+    .expect("base_url is always a valid URL prefix")
+}

crates/adapters/activitypub/src/user_adapter.rs

@@ -0,0 +1,89 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use domain::{ports::UserRepository, value_objects::UserId};
+use k_ap::{ApProfileField, ApUser, ApUserRepository};
+use url::Url;
+
+pub struct DomainUserRepoAdapter {
+    pub repo: Arc<dyn UserRepository>,
+    pub base_url: String,
+}
+
+impl DomainUserRepoAdapter {
+    pub fn new(repo: Arc<dyn UserRepository>, base_url: String) -> Self {
+        Self { repo, base_url }
+    }
+
+    fn build_user(&self, u: &domain::models::User) -> ApUser {
+        let avatar_url = u
+            .avatar_path()
+            .and_then(|p| Url::parse(&format!("{}/images/{}", self.base_url, p)).ok());
+        let banner_url = u
+            .banner_path()
+            .and_then(|p| Url::parse(&format!("{}/images/{}", self.base_url, p)).ok());
+        let profile_url = Url::parse(&format!("{}/u/{}", self.base_url, u.username().value())).ok();
+        ApUser {
+            id: u.id().value(),
+            username: u.username().value().to_string(),
+            display_name: u.display_name().map(|s| s.to_string()),
+            bio: u.bio().map(|s| s.to_string()),
+            avatar_url,
+            banner_url,
+            also_known_as: u
+                .also_known_as()
+                .map(|s| vec![s.to_string()])
+                .unwrap_or_default(),
+            profile_url,
+            attachment: u
+                .profile_fields()
+                .iter()
+                .map(|f| ApProfileField {
+                    name: f.name.clone(),
+                    value: f.value.clone(),
+                })
+                .collect(),
+            manually_approves_followers: true,
+            discoverable: true,
+            actor_type: Default::default(),
+            featured_url: Url::parse(&format!(
+                "{}/users/{}/featured",
+                self.base_url,
+                u.id().value()
+            ))
+            .ok(),
+        }
+    }
+}
+
+#[async_trait]
+impl ApUserRepository for DomainUserRepoAdapter {
+    async fn find_by_id(&self, id: uuid::Uuid) -> anyhow::Result<Option<ApUser>> {
+        let user_id = UserId::from_uuid(id);
+        let user = match self.repo.find_by_id(&user_id).await? {
+            Some(u) => u,
+            None => return Ok(None),
+        };
+        Ok(Some(self.build_user(&user)))
+    }
+
+    async fn find_by_username(&self, username: &str) -> anyhow::Result<Option<ApUser>> {
+        use domain::value_objects::Username;
+        let uname =
+            Username::new(username.to_string()).map_err(|e| anyhow::anyhow!(e.to_string()))?;
+        let user = match self.repo.find_by_username(&uname).await? {
+            Some(u) => u,
+            None => return Ok(None),
+        };
+        Ok(Some(self.build_user(&user)))
+    }
+
+    async fn count_users(&self) -> anyhow::Result<usize> {
+        Ok(self
+            .repo
+            .list_with_stats()
+            .await
+            .map_err(|e| anyhow::anyhow!(e.to_string()))?
+            .len())
+    }
+}

crates/adapters/activitypub/src/watchlist_handler.rs

@@ -0,0 +1,106 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use domain::{
+    models::RemoteWatchlistEntry,
+    ports::{LocalApContentQuery, RemoteWatchlistRepository},
+};
+use k_ap::ApObjectHandler;
+use url::Url;
+
+use crate::objects::WatchlistObject;
+
+pub struct WatchlistObjectHandler {
+    pub remote_watchlist_repo: Arc<dyn RemoteWatchlistRepository>,
+    pub content_query: Arc<dyn LocalApContentQuery>,
+    pub base_url: String,
+}
+
+#[async_trait]
+impl ApObjectHandler for WatchlistObjectHandler {
+    async fn on_create(
+        &self,
+        ap_id: &Url,
+        actor_url: &Url,
+        object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        let mut obj: WatchlistObject = match serde_json::from_value(object) {
+            Ok(o) => o,
+            Err(e) => {
+                tracing::warn!(ap_id = %ap_id, "ignoring malformed watchlist Create: {}", e);
+                return Ok(());
+            }
+        };
+        obj.movie_title = ammonia::clean(&obj.movie_title);
+        let added_at = obj.published;
+        let entry = RemoteWatchlistEntry {
+            ap_id: ap_id.as_str().to_string(),
+            actor_url: actor_url.as_str().to_string(),
+            movie_title: obj.movie_title,
+            release_year: obj.release_year,
+            external_metadata_id: obj.external_metadata_id,
+            poster_url: obj.poster_url,
+            added_at,
+        };
+        self.remote_watchlist_repo.save(entry).await?;
+        tracing::info!(ap_id = %ap_id, "saved remote watchlist entry");
+        Ok(())
+    }
+
+    async fn on_update(
+        &self,
+        _ap_id: &Url,
+        _actor_url: &Url,
+        _object: serde_json::Value,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_delete(&self, ap_id: &Url, actor_url: &Url) -> anyhow::Result<()> {
+        self.remote_watchlist_repo
+            .remove_by_ap_id(ap_id.as_str(), actor_url.as_str())
+            .await?;
+        tracing::info!(ap_id = %ap_id, "removed remote watchlist entry");
+        Ok(())
+    }
+
+    async fn on_actor_removed(&self, actor_url: &Url) -> anyhow::Result<()> {
+        self.remote_watchlist_repo
+            .remove_all_by_actor(actor_url.as_str())
+            .await?;
+        Ok(())
+    }
+
+    async fn on_like(&self, _object_url: &Url, _actor_url: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_announce_received(
+        &self,
+        _object_url: &Url,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_announce_of_remote(
+        &self,
+        _object_url: &Url,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_unlike(&self, _object_url: &Url, _actor_url: &Url) -> anyhow::Result<()> {
+        Ok(())
+    }
+
+    async fn on_mention(
+        &self,
+        _thought_ap_id: &Url,
+        _mentioned_user_uuid: uuid::Uuid,
+        _actor_url: &Url,
+    ) -> anyhow::Result<()> {
+        Ok(())
+    }
+}

crates/adapters/auth/Cargo.toml

@@ -4,3 +4,12 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
+async-trait = { workspace = true }
+domain = { workspace = true }
+anyhow = { workspace = true }
+chrono = { workspace = true }
+uuid = { workspace = true }
+serde = { version = "1.0", features = ["derive"] }
+jsonwebtoken = "9"
+argon2 = { version = "0.5", features = ["std"] }
+rand_core = { version = "0.6", features = ["getrandom"] }

crates/adapters/auth/src/lib.rs

@@ -1,14 +1,118 @@
-pub fn add(left: u64, right: u64) -> u64 {
-    left + right
+use argon2::{
+    Argon2,
+    password_hash::{PasswordHasher as _, PasswordVerifier, SaltString},
+};
+use async_trait::async_trait;
+use chrono::{Duration, Utc};
+use jsonwebtoken::{DecodingKey, EncodingKey, Header, Validation, decode, encode};
+use rand_core::OsRng;
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+use domain::{
+    errors::DomainError,
+    ports::{AuthService, GeneratedToken, PasswordHasher},
+    value_objects::{PasswordHash, UserId},
+};
+
+pub struct AuthConfig {
+    secret: String,
+    ttl_seconds: u64,
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn it_works() {
-        let result = add(2, 2);
-        assert_eq!(result, 4);
+impl AuthConfig {
+    pub fn from_env() -> anyhow::Result<Self> {
+        let secret = std::env::var("JWT_SECRET")
+            .map_err(|_| anyhow::anyhow!("JWT_SECRET env var is required"))?;
+        if secret.is_empty() {
+            anyhow::bail!("JWT_SECRET must not be empty");
+        }
+        let ttl_seconds = std::env::var("JWT_TTL_SECONDS")
+            .ok()
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(900u64);
+        Ok(Self {
+            secret,
+            ttl_seconds,
+        })
     }
 }
+
+#[derive(Serialize, Deserialize)]
+struct Claims {
+    sub: String,
+    exp: u64,
+}
+
+pub struct JwtAuthService {
+    config: AuthConfig,
+}
+
+impl JwtAuthService {
+    pub fn new(config: AuthConfig) -> Self {
+        Self { config }
+    }
+}
+
+#[async_trait]
+impl AuthService for JwtAuthService {
+    async fn generate_token(&self, user_id: &UserId) -> Result<GeneratedToken, DomainError> {
+        let expires_at = Utc::now() + Duration::seconds(self.config.ttl_seconds as i64);
+        let claims = Claims {
+            sub: user_id.value().to_string(),
+            exp: expires_at.timestamp() as u64,
+        };
+        let token = encode(
+            &Header::default(),
+            &claims,
+            &EncodingKey::from_secret(self.config.secret.as_bytes()),
+        )
+        .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        Ok(GeneratedToken { token, expires_at })
+    }
+
+    async fn validate_token(&self, token: &str) -> Result<UserId, DomainError> {
+        let data = decode::<Claims>(
+            token,
+            &DecodingKey::from_secret(self.config.secret.as_bytes()),
+            &Validation::default(),
+        )
+        .map_err(|_| DomainError::Unauthorized("Invalid or expired token".into()))?;
+        let uuid = Uuid::parse_str(&data.claims.sub)
+            .map_err(|_| DomainError::Unauthorized("Invalid token subject".into()))?;
+        Ok(UserId::from_uuid(uuid))
+    }
+}
+
+pub struct Argon2PasswordHasher;
+
+#[async_trait]
+impl PasswordHasher for Argon2PasswordHasher {
+    async fn hash(&self, plain_password: &str) -> Result<PasswordHash, DomainError> {
+        let salt = SaltString::generate(&mut OsRng);
+        let hash = Argon2::default()
+            .hash_password(plain_password.as_bytes(), &salt)
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+            .to_string();
+        PasswordHash::new(hash).map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+
+    async fn verify(&self, plain_password: &str, hash: &PasswordHash) -> Result<bool, DomainError> {
+        let parsed = argon2::password_hash::PasswordHash::new(hash.value())
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        Ok(Argon2::default()
+            .verify_password(plain_password.as_bytes(), &parsed)
+            .is_ok())
+    }
+}
+
+pub fn create() -> anyhow::Result<(
+    std::sync::Arc<dyn domain::ports::AuthService>,
+    std::sync::Arc<dyn domain::ports::PasswordHasher>,
+)> {
+    let config = AuthConfig::from_env()?;
+    Ok((
+        std::sync::Arc::new(JwtAuthService::new(config)),
+        std::sync::Arc::new(Argon2PasswordHasher),
+    ))
+}

crates/adapters/event-payload/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "event-payload"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain = { workspace = true }
+serde = { workspace = true }
+chrono = { workspace = true }
+uuid = { workspace = true }
+serde_json = { workspace = true }

crates/adapters/event-payload/src/lib.rs

@@ -0,0 +1,526 @@
+use chrono::NaiveDateTime;
+use domain::{
+    errors::DomainError,
+    events::DomainEvent,
+    models::{ExternalPersonId, PersonId},
+    value_objects::{
+        ExternalMetadataId, GoalId, MovieId, PosterPath, Rating, ReviewId, UserId, WrapUpId,
+    },
+};
+use serde::{Deserialize, Serialize};
+use uuid::Uuid;
+
+#[derive(Debug, Serialize, Deserialize, PartialEq)]
+#[serde(tag = "type", content = "data")]
+pub enum EventPayload {
+    ReviewLogged {
+        review_id: String,
+        movie_id: String,
+        user_id: String,
+        rating: u8,
+        watched_at: i64,
+    },
+    ReviewUpdated {
+        review_id: String,
+        movie_id: String,
+        user_id: String,
+        rating: u8,
+        watched_at: i64,
+    },
+    MovieDiscovered {
+        movie_id: String,
+        external_metadata_id: String,
+    },
+    MovieDeleted {
+        movie_id: String,
+        poster_path: Option<String>,
+    },
+    UserUpdated {
+        user_id: String,
+    },
+    ReviewDeleted {
+        review_id: String,
+        user_id: String,
+    },
+    MovieEnrichmentRequested {
+        movie_id: String,
+        external_metadata_id: String,
+    },
+    ImageStored {
+        key: String,
+    },
+    WatchlistEntryAdded {
+        user_id: String,
+        movie_id: String,
+        movie_title: String,
+        release_year: u16,
+        external_metadata_id: Option<String>,
+        added_at: i64,
+    },
+    WatchlistEntryRemoved {
+        user_id: String,
+        movie_id: String,
+    },
+    FollowAccepted {
+        local_user_id: String,
+        remote_actor_url: String,
+        outbox_url: String,
+    },
+    BackfillFollower {
+        owner_user_id: String,
+        follower_inbox_url: String,
+    },
+    FederationDeliveryRequested {
+        inbox_url: String,
+        activity_json: String,
+        signing_actor_id: String,
+    },
+    WatchEventIngested {
+        user_id: String,
+        title: String,
+        source: String,
+    },
+    WrapUpRequested {
+        wrapup_id: String,
+        user_id: Option<String>,
+        start_date: String,
+        end_date: String,
+    },
+    WrapUpCompleted {
+        wrapup_id: String,
+    },
+    SearchReindexRequested,
+    PosterSynced {
+        movie_id: String,
+    },
+    GoalCreated {
+        goal_id: String,
+        user_id: String,
+        year: u16,
+        target_count: u32,
+    },
+    GoalUpdated {
+        goal_id: String,
+        user_id: String,
+        year: u16,
+        target_count: u32,
+    },
+    GoalDeleted {
+        goal_id: String,
+        user_id: String,
+        year: u16,
+    },
+    PersonEnrichmentRequested {
+        person_id: String,
+        external_person_id: String,
+    },
+}
+
+impl EventPayload {
+    pub fn event_type(&self) -> &'static str {
+        match self {
+            EventPayload::ReviewLogged { .. } => "ReviewLogged",
+            EventPayload::ReviewUpdated { .. } => "ReviewUpdated",
+            EventPayload::MovieDiscovered { .. } => "MovieDiscovered",
+            EventPayload::MovieDeleted { .. } => "MovieDeleted",
+            EventPayload::UserUpdated { .. } => "UserUpdated",
+            EventPayload::ReviewDeleted { .. } => "ReviewDeleted",
+            EventPayload::MovieEnrichmentRequested { .. } => "MovieEnrichmentRequested",
+            EventPayload::ImageStored { .. } => "ImageStored",
+            EventPayload::WatchlistEntryAdded { .. } => "WatchlistEntryAdded",
+            EventPayload::WatchlistEntryRemoved { .. } => "WatchlistEntryRemoved",
+            EventPayload::FollowAccepted { .. } => "FollowAccepted",
+            EventPayload::BackfillFollower { .. } => "BackfillFollower",
+            EventPayload::FederationDeliveryRequested { .. } => "FederationDeliveryRequested",
+            EventPayload::WatchEventIngested { .. } => "WatchEventIngested",
+            EventPayload::WrapUpRequested { .. } => "WrapUpRequested",
+            EventPayload::WrapUpCompleted { .. } => "WrapUpCompleted",
+            EventPayload::SearchReindexRequested => "SearchReindexRequested",
+            EventPayload::PosterSynced { .. } => "PosterSynced",
+            EventPayload::GoalCreated { .. } => "GoalCreated",
+            EventPayload::GoalUpdated { .. } => "GoalUpdated",
+            EventPayload::GoalDeleted { .. } => "GoalDeleted",
+            EventPayload::PersonEnrichmentRequested { .. } => "PersonEnrichmentRequested",
+        }
+    }
+}
+
+fn parse_uuid(s: &str, field: &str) -> Result<Uuid, DomainError> {
+    Uuid::parse_str(s).map_err(|e| DomainError::InfrastructureError(format!("{field}: {e}")))
+}
+
+fn parse_ts(ts: i64) -> Result<NaiveDateTime, DomainError> {
+    chrono::DateTime::from_timestamp(ts, 0)
+        .map(|dt| dt.naive_utc())
+        .ok_or_else(|| DomainError::InfrastructureError(format!("invalid timestamp: {ts}")))
+}
+
+impl From<&DomainEvent> for EventPayload {
+    fn from(event: &DomainEvent) -> Self {
+        match event {
+            DomainEvent::ReviewLogged {
+                review_id,
+                movie_id,
+                user_id,
+                rating,
+                watched_at,
+            } => EventPayload::ReviewLogged {
+                review_id: review_id.value().to_string(),
+                movie_id: movie_id.value().to_string(),
+                user_id: user_id.value().to_string(),
+                rating: rating.value(),
+                watched_at: watched_at.and_utc().timestamp(),
+            },
+            DomainEvent::ReviewUpdated {
+                review_id,
+                movie_id,
+                user_id,
+                rating,
+                watched_at,
+            } => EventPayload::ReviewUpdated {
+                review_id: review_id.value().to_string(),
+                movie_id: movie_id.value().to_string(),
+                user_id: user_id.value().to_string(),
+                rating: rating.value(),
+                watched_at: watched_at.and_utc().timestamp(),
+            },
+            DomainEvent::MovieDiscovered {
+                movie_id,
+                external_metadata_id,
+            } => EventPayload::MovieDiscovered {
+                movie_id: movie_id.value().to_string(),
+                external_metadata_id: external_metadata_id.value().to_owned(),
+            },
+            DomainEvent::MovieDeleted {
+                movie_id,
+                poster_path,
+            } => EventPayload::MovieDeleted {
+                movie_id: movie_id.value().to_string(),
+                poster_path: poster_path.as_ref().map(|p| p.value().to_string()),
+            },
+            DomainEvent::UserUpdated { user_id } => EventPayload::UserUpdated {
+                user_id: user_id.value().to_string(),
+            },
+            DomainEvent::ReviewDeleted { review_id, user_id } => EventPayload::ReviewDeleted {
+                review_id: review_id.value().to_string(),
+                user_id: user_id.value().to_string(),
+            },
+            DomainEvent::MovieEnrichmentRequested {
+                movie_id,
+                external_metadata_id,
+            } => EventPayload::MovieEnrichmentRequested {
+                movie_id: movie_id.value().to_string(),
+                external_metadata_id: external_metadata_id.value().to_string(),
+            },
+            DomainEvent::ImageStored { key } => EventPayload::ImageStored { key: key.clone() },
+            DomainEvent::WatchlistEntryAdded {
+                user_id,
+                movie_id,
+                movie_title,
+                release_year,
+                external_metadata_id,
+                added_at,
+            } => EventPayload::WatchlistEntryAdded {
+                user_id: user_id.value().to_string(),
+                movie_id: movie_id.value().to_string(),
+                movie_title: movie_title.clone(),
+                release_year: *release_year,
+                external_metadata_id: external_metadata_id.clone(),
+                added_at: added_at.and_utc().timestamp(),
+            },
+            DomainEvent::WatchlistEntryRemoved { user_id, movie_id } => {
+                EventPayload::WatchlistEntryRemoved {
+                    user_id: user_id.value().to_string(),
+                    movie_id: movie_id.value().to_string(),
+                }
+            }
+            DomainEvent::FollowAccepted {
+                local_user_id,
+                remote_actor_url,
+                outbox_url,
+            } => EventPayload::FollowAccepted {
+                local_user_id: local_user_id.value().to_string(),
+                remote_actor_url: remote_actor_url.clone(),
+                outbox_url: outbox_url.clone(),
+            },
+            DomainEvent::BackfillFollower {
+                owner_user_id,
+                follower_inbox_url,
+            } => EventPayload::BackfillFollower {
+                owner_user_id: owner_user_id.value().to_string(),
+                follower_inbox_url: follower_inbox_url.clone(),
+            },
+            DomainEvent::FederationDeliveryRequested {
+                inbox_url,
+                activity_json,
+                signing_actor_id,
+            } => EventPayload::FederationDeliveryRequested {
+                inbox_url: inbox_url.clone(),
+                activity_json: activity_json.clone(),
+                signing_actor_id: signing_actor_id.to_string(),
+            },
+            DomainEvent::WatchEventIngested {
+                user_id,
+                title,
+                source,
+            } => EventPayload::WatchEventIngested {
+                user_id: user_id.value().to_string(),
+                title: title.clone(),
+                source: source.clone(),
+            },
+            DomainEvent::WrapUpRequested {
+                wrapup_id,
+                user_id,
+                start_date,
+                end_date,
+            } => EventPayload::WrapUpRequested {
+                wrapup_id: wrapup_id.value().to_string(),
+                user_id: user_id.as_ref().map(|u| u.value().to_string()),
+                start_date: start_date.to_string(),
+                end_date: end_date.to_string(),
+            },
+            DomainEvent::WrapUpCompleted { wrapup_id } => EventPayload::WrapUpCompleted {
+                wrapup_id: wrapup_id.value().to_string(),
+            },
+            DomainEvent::SearchReindexRequested => EventPayload::SearchReindexRequested,
+            DomainEvent::PosterSynced { movie_id } => EventPayload::PosterSynced {
+                movie_id: movie_id.value().to_string(),
+            },
+            DomainEvent::GoalCreated {
+                goal_id,
+                user_id,
+                year,
+                target_count,
+            } => EventPayload::GoalCreated {
+                goal_id: goal_id.value().to_string(),
+                user_id: user_id.value().to_string(),
+                year: *year,
+                target_count: *target_count,
+            },
+            DomainEvent::GoalUpdated {
+                goal_id,
+                user_id,
+                year,
+                target_count,
+            } => EventPayload::GoalUpdated {
+                goal_id: goal_id.value().to_string(),
+                user_id: user_id.value().to_string(),
+                year: *year,
+                target_count: *target_count,
+            },
+            DomainEvent::GoalDeleted {
+                goal_id,
+                user_id,
+                year,
+            } => EventPayload::GoalDeleted {
+                goal_id: goal_id.value().to_string(),
+                user_id: user_id.value().to_string(),
+                year: *year,
+            },
+            DomainEvent::PersonEnrichmentRequested {
+                person_id,
+                external_person_id,
+            } => EventPayload::PersonEnrichmentRequested {
+                person_id: person_id.value().to_string(),
+                external_person_id: external_person_id.value().to_string(),
+            },
+        }
+    }
+}
+
+impl TryFrom<EventPayload> for DomainEvent {
+    type Error = DomainError;
+    fn try_from(payload: EventPayload) -> Result<Self, DomainError> {
+        match payload {
+            EventPayload::ReviewLogged {
+                review_id,
+                movie_id,
+                user_id,
+                rating,
+                watched_at,
+            } => Ok(DomainEvent::ReviewLogged {
+                review_id: ReviewId::from_uuid(parse_uuid(&review_id, "review_id")?),
+                movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                rating: Rating::new(rating)?,
+                watched_at: parse_ts(watched_at)?,
+            }),
+            EventPayload::ReviewUpdated {
+                review_id,
+                movie_id,
+                user_id,
+                rating,
+                watched_at,
+            } => Ok(DomainEvent::ReviewUpdated {
+                review_id: ReviewId::from_uuid(parse_uuid(&review_id, "review_id")?),
+                movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                rating: Rating::new(rating)?,
+                watched_at: parse_ts(watched_at)?,
+            }),
+            EventPayload::MovieDiscovered {
+                movie_id,
+                external_metadata_id,
+            } => Ok(DomainEvent::MovieDiscovered {
+                movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                external_metadata_id: ExternalMetadataId::new(external_metadata_id)?,
+            }),
+            EventPayload::MovieDeleted {
+                movie_id,
+                poster_path,
+            } => {
+                let movie_id = MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?);
+                let poster_path = poster_path
+                    .map(PosterPath::new)
+                    .transpose()
+                    .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+                Ok(DomainEvent::MovieDeleted {
+                    movie_id,
+                    poster_path,
+                })
+            }
+            EventPayload::UserUpdated { user_id } => Ok(DomainEvent::UserUpdated {
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+            }),
+            EventPayload::ReviewDeleted { review_id, user_id } => Ok(DomainEvent::ReviewDeleted {
+                review_id: ReviewId::from_uuid(parse_uuid(&review_id, "review_id")?),
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+            }),
+            EventPayload::MovieEnrichmentRequested {
+                movie_id,
+                external_metadata_id,
+            } => Ok(DomainEvent::MovieEnrichmentRequested {
+                movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                external_metadata_id: ExternalMetadataId::new(external_metadata_id)
+                    .map_err(|e| DomainError::InfrastructureError(e.to_string()))?,
+            }),
+            EventPayload::ImageStored { key } => Ok(DomainEvent::ImageStored { key }),
+            EventPayload::WatchlistEntryAdded {
+                user_id,
+                movie_id,
+                movie_title,
+                release_year,
+                external_metadata_id,
+                added_at,
+            } => Ok(DomainEvent::WatchlistEntryAdded {
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                movie_title,
+                release_year,
+                external_metadata_id,
+                added_at: parse_ts(added_at)?,
+            }),
+            EventPayload::WatchlistEntryRemoved { user_id, movie_id } => {
+                Ok(DomainEvent::WatchlistEntryRemoved {
+                    user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                    movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+                })
+            }
+            EventPayload::FollowAccepted {
+                local_user_id,
+                remote_actor_url,
+                outbox_url,
+            } => Ok(DomainEvent::FollowAccepted {
+                local_user_id: UserId::from_uuid(parse_uuid(&local_user_id, "local_user_id")?),
+                remote_actor_url,
+                outbox_url,
+            }),
+            EventPayload::BackfillFollower {
+                owner_user_id,
+                follower_inbox_url,
+            } => Ok(DomainEvent::BackfillFollower {
+                owner_user_id: UserId::from_uuid(parse_uuid(&owner_user_id, "owner_user_id")?),
+                follower_inbox_url,
+            }),
+            EventPayload::FederationDeliveryRequested {
+                inbox_url,
+                activity_json,
+                signing_actor_id,
+            } => Ok(DomainEvent::FederationDeliveryRequested {
+                inbox_url,
+                activity_json,
+                signing_actor_id: parse_uuid(&signing_actor_id, "signing_actor_id")?,
+            }),
+            EventPayload::WatchEventIngested {
+                user_id,
+                title,
+                source,
+            } => Ok(DomainEvent::WatchEventIngested {
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                title,
+                source,
+            }),
+            EventPayload::WrapUpRequested {
+                wrapup_id,
+                user_id,
+                start_date,
+                end_date,
+            } => {
+                let wid = parse_uuid(&wrapup_id, "wrapup_id")?;
+                let uid = user_id.map(|s| parse_uuid(&s, "user_id")).transpose()?;
+                let sd = chrono::NaiveDate::parse_from_str(&start_date, "%Y-%m-%d")
+                    .map_err(|e| DomainError::ValidationError(e.to_string()))?;
+                let ed = chrono::NaiveDate::parse_from_str(&end_date, "%Y-%m-%d")
+                    .map_err(|e| DomainError::ValidationError(e.to_string()))?;
+                Ok(DomainEvent::WrapUpRequested {
+                    wrapup_id: WrapUpId::from_uuid(wid),
+                    user_id: uid.map(UserId::from_uuid),
+                    start_date: sd,
+                    end_date: ed,
+                })
+            }
+            EventPayload::WrapUpCompleted { wrapup_id } => {
+                let wid = parse_uuid(&wrapup_id, "wrapup_id")?;
+                Ok(DomainEvent::WrapUpCompleted {
+                    wrapup_id: WrapUpId::from_uuid(wid),
+                })
+            }
+            EventPayload::SearchReindexRequested => Ok(DomainEvent::SearchReindexRequested),
+            EventPayload::PosterSynced { movie_id } => Ok(DomainEvent::PosterSynced {
+                movie_id: MovieId::from_uuid(parse_uuid(&movie_id, "movie_id")?),
+            }),
+            EventPayload::GoalCreated {
+                goal_id,
+                user_id,
+                year,
+                target_count,
+            } => Ok(DomainEvent::GoalCreated {
+                goal_id: GoalId::from_uuid(parse_uuid(&goal_id, "goal_id")?),
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                year,
+                target_count,
+            }),
+            EventPayload::GoalUpdated {
+                goal_id,
+                user_id,
+                year,
+                target_count,
+            } => Ok(DomainEvent::GoalUpdated {
+                goal_id: GoalId::from_uuid(parse_uuid(&goal_id, "goal_id")?),
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                year,
+                target_count,
+            }),
+            EventPayload::GoalDeleted {
+                goal_id,
+                user_id,
+                year,
+            } => Ok(DomainEvent::GoalDeleted {
+                goal_id: GoalId::from_uuid(parse_uuid(&goal_id, "goal_id")?),
+                user_id: UserId::from_uuid(parse_uuid(&user_id, "user_id")?),
+                year,
+            }),
+            EventPayload::PersonEnrichmentRequested {
+                person_id,
+                external_person_id,
+            } => Ok(DomainEvent::PersonEnrichmentRequested {
+                person_id: PersonId::from_uuid(parse_uuid(&person_id, "person_id")?),
+                external_person_id: ExternalPersonId::new(external_person_id),
+            }),
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/lib.rs"]
+mod tests;

crates/adapters/event-payload/src/tests/lib.rs

@@ -0,0 +1,101 @@
+use super::*;
+
+fn fixed_dt() -> NaiveDateTime {
+    chrono::DateTime::from_timestamp(1_700_000_000, 0)
+        .unwrap()
+        .naive_utc()
+}
+
+fn review_logged() -> DomainEvent {
+    DomainEvent::ReviewLogged {
+        review_id: ReviewId::from_uuid(Uuid::new_v4()),
+        movie_id: MovieId::from_uuid(Uuid::new_v4()),
+        user_id: UserId::from_uuid(Uuid::new_v4()),
+        rating: Rating::new(4).unwrap(),
+        watched_at: fixed_dt(),
+    }
+}
+
+fn review_updated() -> DomainEvent {
+    DomainEvent::ReviewUpdated {
+        review_id: ReviewId::from_uuid(Uuid::new_v4()),
+        movie_id: MovieId::from_uuid(Uuid::new_v4()),
+        user_id: UserId::from_uuid(Uuid::new_v4()),
+        rating: Rating::new(3).unwrap(),
+        watched_at: fixed_dt(),
+    }
+}
+
+fn movie_discovered() -> DomainEvent {
+    DomainEvent::MovieDiscovered {
+        movie_id: MovieId::from_uuid(Uuid::new_v4()),
+        external_metadata_id: ExternalMetadataId::new("tt1234567".into()).unwrap(),
+    }
+}
+
+fn round_trip(event: DomainEvent) {
+    let payload = EventPayload::from(&event);
+    let json = serde_json::to_string(&payload).expect("serialize");
+    let back: EventPayload = serde_json::from_str(&json).expect("deserialize");
+    let recovered = DomainEvent::try_from(back).expect("try_from");
+    assert_eq!(EventPayload::from(&event), EventPayload::from(&recovered));
+}
+
+#[test]
+fn round_trip_review_logged() {
+    round_trip(review_logged());
+}
+
+#[test]
+fn round_trip_review_updated() {
+    round_trip(review_updated());
+}
+
+#[test]
+fn round_trip_movie_discovered() {
+    round_trip(movie_discovered());
+}
+
+#[test]
+fn serialized_format_is_tagged() {
+    let payload = EventPayload::from(&movie_discovered());
+    let json = serde_json::to_string(&payload).unwrap();
+    assert!(json.contains(r#""type":"MovieDiscovered""#));
+    assert!(json.contains(r#""data":"#));
+}
+
+#[test]
+fn event_type_strings() {
+    assert_eq!(
+        EventPayload::from(&review_logged()).event_type(),
+        "ReviewLogged"
+    );
+    assert_eq!(
+        EventPayload::from(&review_updated()).event_type(),
+        "ReviewUpdated"
+    );
+    assert_eq!(
+        EventPayload::from(&movie_discovered()).event_type(),
+        "MovieDiscovered"
+    );
+}
+
+#[test]
+fn round_trip_image_stored() {
+    let event = DomainEvent::ImageStored {
+        key: "avatars/abc123".into(),
+    };
+    let payload = EventPayload::from(&event);
+    let json = serde_json::to_string(&payload).unwrap();
+    let back: EventPayload = serde_json::from_str(&json).unwrap();
+    let recovered = DomainEvent::try_from(back).unwrap();
+    assert_eq!(EventPayload::from(&event), EventPayload::from(&recovered));
+}
+
+#[test]
+fn image_stored_event_type() {
+    let payload = EventPayload::from(&DomainEvent::ImageStored {
+        key: "posters/x".into(),
+    });
+    assert_eq!(payload.event_type(), "ImageStored");
+}

crates/adapters/event-publisher/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "event-publisher"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain      = { workspace = true }
+async-trait = { workspace = true }
+tokio       = { workspace = true }
+futures     = { workspace = true }

crates/adapters/event-publisher/src/lib.rs

@@ -0,0 +1,92 @@
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::{AckHandle, DomainEvent, EventEnvelope},
+    ports::{EventConsumer, EventPublisher},
+};
+use futures::stream::{self, BoxStream};
+use std::sync::Arc;
+use tokio::sync::Mutex;
+use tokio::sync::mpsc;
+
+pub use domain::ports::EventHandler;
+
+pub struct EventPublisherConfig {
+    pub channel_buffer: usize,
+}
+
+impl EventPublisherConfig {
+    pub fn from_env() -> Self {
+        let channel_buffer = std::env::var("EVENT_CHANNEL_BUFFER")
+            .ok()
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(128);
+        Self { channel_buffer }
+    }
+}
+
+pub struct ChannelEventPublisher {
+    sender: mpsc::Sender<DomainEvent>,
+}
+
+#[async_trait]
+impl EventPublisher for ChannelEventPublisher {
+    async fn publish(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        self.sender
+            .send(event.clone())
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+}
+
+struct NoopAck;
+
+#[async_trait]
+impl AckHandle for NoopAck {
+    async fn ack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
+    async fn nack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
+}
+
+pub struct ChannelEventConsumer {
+    receiver: Arc<Mutex<mpsc::Receiver<DomainEvent>>>,
+}
+
+impl EventConsumer for ChannelEventConsumer {
+    fn consume(&self) -> BoxStream<'_, Result<EventEnvelope, DomainError>> {
+        let receiver = Arc::clone(&self.receiver);
+        Box::pin(stream::unfold(receiver, |rx| async move {
+            let event = rx.lock().await.recv().await?;
+            let envelope = EventEnvelope::new(event, Box::new(NoopAck));
+            Some((Ok(envelope), rx))
+        }))
+    }
+}
+
+pub struct NoopEventPublisher;
+
+#[async_trait]
+impl EventPublisher for NoopEventPublisher {
+    async fn publish(&self, _event: &DomainEvent) -> Result<(), DomainError> {
+        Ok(())
+    }
+}
+
+pub fn create_event_channel(
+    config: EventPublisherConfig,
+) -> (ChannelEventPublisher, ChannelEventConsumer) {
+    let (tx, rx) = mpsc::channel(config.channel_buffer);
+    (
+        ChannelEventPublisher { sender: tx },
+        ChannelEventConsumer {
+            receiver: Arc::new(Mutex::new(rx)),
+        },
+    )
+}
+
+#[cfg(test)]
+#[path = "tests/lib.rs"]
+mod tests;

crates/adapters/event-publisher/src/tests/lib.rs

@@ -0,0 +1,57 @@
+use super::*;
+use domain::{
+    events::DomainEvent,
+    value_objects::{ExternalMetadataId, MovieId},
+};
+use futures::StreamExt;
+
+fn movie_discovered() -> DomainEvent {
+    DomainEvent::MovieDiscovered {
+        movie_id: MovieId::generate(),
+        external_metadata_id: ExternalMetadataId::new("tt1234567".into()).unwrap(),
+    }
+}
+
+#[tokio::test]
+async fn consumer_yields_published_events() {
+    let config = EventPublisherConfig { channel_buffer: 8 };
+    let (publisher, consumer) = create_event_channel(config);
+
+    publisher.publish(&movie_discovered()).await.unwrap();
+    drop(publisher);
+
+    let mut stream = consumer.consume();
+    let envelope = stream.next().await.unwrap().unwrap();
+    assert!(matches!(
+        envelope.event,
+        DomainEvent::MovieDiscovered { .. }
+    ));
+    assert!(stream.next().await.is_none());
+}
+
+#[tokio::test]
+async fn consumer_yields_multiple_events_in_order() {
+    let config = EventPublisherConfig { channel_buffer: 8 };
+    let (publisher, consumer) = create_event_channel(config);
+
+    publisher.publish(&movie_discovered()).await.unwrap();
+    publisher.publish(&movie_discovered()).await.unwrap();
+    drop(publisher);
+
+    let mut stream = consumer.consume();
+    let first = stream.next().await.unwrap().unwrap();
+    let second = stream.next().await.unwrap().unwrap();
+    assert!(matches!(first.event, DomainEvent::MovieDiscovered { .. }));
+    assert!(matches!(second.event, DomainEvent::MovieDiscovered { .. }));
+    assert!(stream.next().await.is_none());
+}
+
+#[tokio::test]
+async fn stream_ends_when_publisher_dropped() {
+    let config = EventPublisherConfig { channel_buffer: 8 };
+    let (publisher, consumer) = create_event_channel(config);
+    drop(publisher);
+
+    let mut stream = consumer.consume();
+    assert!(stream.next().await.is_none());
+}

crates/adapters/export/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "export"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain = { workspace = true }
+async-trait = { workspace = true }
+serde_json = { workspace = true }
+chrono = { workspace = true }
+futures = { workspace = true }
+bytes = { workspace = true }
+async-stream = { workspace = true }
+
+[dev-dependencies]
+uuid = { workspace = true }
+tokio = { workspace = true }

crates/adapters/export/src/lib.rs

@@ -0,0 +1,111 @@
+use bytes::Bytes;
+use domain::{
+    errors::DomainError,
+    models::{DiaryEntry, ExportFormat},
+    ports::DiaryExporter,
+};
+use futures::stream::BoxStream;
+
+pub struct ExportAdapter;
+
+impl DiaryExporter for ExportAdapter {
+    fn stream_entries(
+        &self,
+        stream: BoxStream<'static, Result<DiaryEntry, DomainError>>,
+        format: ExportFormat,
+    ) -> BoxStream<'static, Result<Bytes, DomainError>> {
+        match format {
+            ExportFormat::Csv => stream_csv(stream),
+            ExportFormat::Json => stream_json(stream),
+        }
+    }
+}
+
+fn stream_csv(
+    entries: BoxStream<'static, Result<DiaryEntry, DomainError>>,
+) -> BoxStream<'static, Result<Bytes, DomainError>> {
+    use futures::StreamExt;
+    let header = futures::stream::once(async {
+        Ok(Bytes::from_static(
+            b"title,year,director,rating,comment,watched_at,external_metadata_id\n",
+        ))
+    });
+    let rows = entries.map(|r| r.map(|e| Bytes::from(csv_row(&e))));
+    Box::pin(header.chain(rows))
+}
+
+fn stream_json(
+    stream: BoxStream<'static, Result<DiaryEntry, DomainError>>,
+) -> BoxStream<'static, Result<Bytes, DomainError>> {
+    Box::pin(async_stream::stream! {
+        futures::pin_mut!(stream);
+        let mut is_first = true;
+        while let Some(r) = futures::StreamExt::next(&mut stream).await {
+            match r {
+                Err(e) => { yield Err(e); return; }
+                Ok(entry) => {
+                    let json = serde_json::to_string(&entry_to_json(&entry))
+                        .map_err(|e| DomainError::InfrastructureError(e.to_string()));
+                    let json = match json {
+                        Ok(s) => s,
+                        Err(e) => { yield Err(e); return; }
+                    };
+                    let prefix = if is_first { "[" } else { "," };
+                    is_first = false;
+                    yield Ok(Bytes::from(format!("{}{}", prefix, json)));
+                }
+            }
+        }
+        if is_first {
+            yield Ok(Bytes::from_static(b"[]"));
+        } else {
+            yield Ok(Bytes::from_static(b"]"));
+        }
+    })
+}
+
+fn csv_row(e: &DiaryEntry) -> String {
+    let title = csv_escape(e.movie().title().value());
+    let year = e.movie().release_year().value();
+    let director = e.movie().director().map(csv_escape).unwrap_or_default();
+    let rating = e.review().rating().value();
+    let comment = e
+        .review()
+        .comment()
+        .map(|c| csv_escape(c.value()))
+        .unwrap_or_default();
+    let watched_at = e.review().watched_at().format("%Y-%m-%d");
+    let ext_id = e
+        .movie()
+        .external_metadata_id()
+        .map(|id| id.value().to_string())
+        .unwrap_or_default();
+    format!(
+        "{},{},{},{},{},{},{}\n",
+        title, year, director, rating, comment, watched_at, ext_id
+    )
+}
+
+fn csv_escape(s: &str) -> String {
+    if s.contains(',') || s.contains('"') || s.contains('\n') {
+        format!("\"{}\"", s.replace('"', "\"\""))
+    } else {
+        s.to_string()
+    }
+}
+
+fn entry_to_json(e: &DiaryEntry) -> serde_json::Value {
+    serde_json::json!({
+        "title": e.movie().title().value(),
+        "year": e.movie().release_year().value(),
+        "director": e.movie().director(),
+        "rating": e.review().rating().value(),
+        "comment": e.review().comment().map(|c| c.value().to_string()),
+        "watched_at": e.review().watched_at().format("%Y-%m-%d").to_string(),
+        "external_metadata_id": e.movie().external_metadata_id().map(|id| id.value().to_string()),
+    })
+}
+
+#[cfg(test)]
+#[path = "tests/lib.rs"]
+mod tests;

crates/adapters/export/src/tests/lib.rs

@@ -0,0 +1,162 @@
+use super::ExportAdapter;
+use domain::{
+    models::{DiaryEntry, ExportFormat, Movie, Review},
+    ports::DiaryExporter,
+    value_objects::{ExternalMetadataId, MovieTitle, Rating, ReleaseYear},
+};
+
+async fn collect_stream(
+    stream: futures::stream::BoxStream<'static, Result<bytes::Bytes, domain::errors::DomainError>>,
+) -> Vec<u8> {
+    use futures::StreamExt;
+    let mut out = Vec::new();
+    futures::pin_mut!(stream);
+    while let Some(chunk) = stream.next().await {
+        out.extend_from_slice(&chunk.unwrap());
+    }
+    out
+}
+
+fn entry_stream(
+    entries: Vec<domain::models::DiaryEntry>,
+) -> futures::stream::BoxStream<
+    'static,
+    Result<domain::models::DiaryEntry, domain::errors::DomainError>,
+> {
+    Box::pin(futures::stream::iter(entries.into_iter().map(Ok)))
+}
+
+fn make_entry(
+    title: &str,
+    year: u16,
+    director: Option<&str>,
+    rating: u8,
+    comment: Option<&str>,
+) -> DiaryEntry {
+    make_entry_full(title, year, director, rating, comment, None)
+}
+
+fn make_entry_full(
+    title: &str,
+    year: u16,
+    director: Option<&str>,
+    rating: u8,
+    comment: Option<&str>,
+    external_id: Option<&str>,
+) -> DiaryEntry {
+    let movie = Movie::new(
+        external_id.map(|id| ExternalMetadataId::new(id.to_string()).unwrap()),
+        MovieTitle::new(title.to_string()).unwrap(),
+        ReleaseYear::new(year).unwrap(),
+        director.map(str::to_string),
+        None,
+    );
+    let user_id = domain::value_objects::UserId::from_uuid(uuid::Uuid::new_v4());
+    let review = Review::new(
+        movie.id().clone(),
+        user_id,
+        Rating::new(rating).unwrap(),
+        comment.map(|c| domain::value_objects::Comment::new(c.to_string()).unwrap()),
+        chrono::NaiveDate::from_ymd_opt(2024, 3, 15)
+            .unwrap()
+            .and_hms_opt(0, 0, 0)
+            .unwrap(),
+    )
+    .unwrap();
+    DiaryEntry::new(movie, review)
+}
+
+#[tokio::test]
+async fn csv_has_header_and_one_row() {
+    let adapter = ExportAdapter;
+    let entry = make_entry(
+        "Inception",
+        2010,
+        Some("Christopher Nolan"),
+        5,
+        Some("great"),
+    );
+    let bytes =
+        collect_stream(adapter.stream_entries(entry_stream(vec![entry]), ExportFormat::Csv)).await;
+    let text = String::from_utf8(bytes).unwrap();
+    assert!(
+        text.starts_with("title,year,director,rating,comment,watched_at,external_metadata_id\n")
+    );
+    assert!(text.contains("Inception"));
+    assert!(text.contains("2010"));
+    assert!(text.contains("Christopher Nolan"));
+    assert!(text.contains("5"));
+    assert!(text.contains("great"));
+    assert!(text.contains("2024-03-15"));
+}
+
+#[tokio::test]
+async fn csv_escapes_commas_in_title() {
+    let adapter = ExportAdapter;
+    let entry = make_entry("Tár, A Film", 2022, None, 4, None);
+    let bytes =
+        collect_stream(adapter.stream_entries(entry_stream(vec![entry]), ExportFormat::Csv)).await;
+    let text = String::from_utf8(bytes).unwrap();
+    assert!(text.contains("\"Tár, A Film\""));
+}
+
+#[tokio::test]
+async fn json_is_valid_array() {
+    let adapter = ExportAdapter;
+    let entry = make_entry("Dune", 2021, Some("Denis Villeneuve"), 5, None);
+    let bytes =
+        collect_stream(adapter.stream_entries(entry_stream(vec![entry]), ExportFormat::Json)).await;
+    let arr: Vec<serde_json::Value> = serde_json::from_slice(&bytes).unwrap();
+    assert_eq!(arr.len(), 1);
+    assert_eq!(arr[0]["title"], "Dune");
+    assert_eq!(arr[0]["year"], 2021);
+    assert_eq!(arr[0]["rating"], 5);
+    assert_eq!(arr[0]["comment"], serde_json::Value::Null);
+    assert_eq!(arr[0]["external_metadata_id"], serde_json::Value::Null);
+}
+
+#[tokio::test]
+async fn external_metadata_id_included_when_present() {
+    let adapter = ExportAdapter;
+    let entry = make_entry_full("Alien", 1979, None, 5, None, Some("tt0078748"));
+    let bytes =
+        collect_stream(adapter.stream_entries(entry_stream(vec![entry]), ExportFormat::Json)).await;
+    let arr: Vec<serde_json::Value> = serde_json::from_slice(&bytes).unwrap();
+    assert_eq!(arr[0]["external_metadata_id"], "tt0078748");
+
+    let bytes = collect_stream(adapter.stream_entries(
+        entry_stream(vec![make_entry_full(
+            "Alien",
+            1979,
+            None,
+            5,
+            None,
+            Some("tt0078748"),
+        )]),
+        ExportFormat::Csv,
+    ))
+    .await;
+    let text = String::from_utf8(bytes).unwrap();
+    assert!(text.contains("tt0078748"));
+}
+
+#[tokio::test]
+async fn empty_entries_returns_csv_header_only() {
+    let adapter = ExportAdapter;
+    let bytes =
+        collect_stream(adapter.stream_entries(entry_stream(vec![]), ExportFormat::Csv)).await;
+    let text = String::from_utf8(bytes).unwrap();
+    assert_eq!(
+        text,
+        "title,year,director,rating,comment,watched_at,external_metadata_id\n"
+    );
+}
+
+#[tokio::test]
+async fn empty_json_is_valid_empty_array() {
+    let adapter = ExportAdapter;
+    let bytes =
+        collect_stream(adapter.stream_entries(entry_stream(vec![]), ExportFormat::Json)).await;
+    let arr: Vec<serde_json::Value> = serde_json::from_slice(&bytes).unwrap();
+    assert!(arr.is_empty());
+}

crates/adapters/image-converter/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "image-converter"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+domain      = { workspace = true }
+async-trait = { workspace = true }
+anyhow      = { workspace = true }
+tracing     = { workspace = true }
+tokio       = { workspace = true }
+image       = { version = "0.25", default-features = false, features = ["jpeg", "png", "webp"] }
+ravif       = { version = "0.11", default-features = false }
+webp        = "0.3"
+
+[dev-dependencies]
+object-storage = { workspace = true }
+object_store = "0.11"
+uuid = { workspace = true }

crates/adapters/image-converter/src/backfill.rs

@@ -0,0 +1,55 @@
+use std::{sync::Arc, time::Duration};
+
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::DomainEvent,
+    ports::{EventPublisher, ImageRefQuery, PeriodicJob},
+};
+
+pub struct ConversionBackfillJob {
+    image_ref: Arc<dyn ImageRefQuery>,
+    event_publisher: Arc<dyn EventPublisher>,
+}
+
+impl ConversionBackfillJob {
+    pub fn new(
+        image_ref: Arc<dyn ImageRefQuery>,
+        event_publisher: Arc<dyn EventPublisher>,
+    ) -> Self {
+        Self {
+            image_ref,
+            event_publisher,
+        }
+    }
+}
+
+#[async_trait]
+impl PeriodicJob for ConversionBackfillJob {
+    fn interval(&self) -> Duration {
+        Duration::from_secs(60 * 60 * 24) // 24h
+    }
+
+    async fn run(&self) -> Result<(), DomainError> {
+        let keys = self.image_ref.list_keys().await?;
+
+        for key in keys {
+            if key.ends_with(".avif") || key.ends_with(".webp") {
+                continue;
+            }
+            if let Err(e) = self
+                .event_publisher
+                .publish(&DomainEvent::ImageStored { key: key.clone() })
+                .await
+            {
+                tracing::warn!("backfill: failed to emit ImageStored for {key}: {e}");
+            }
+        }
+
+        Ok(())
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/backfill.rs"]
+mod tests;

crates/adapters/image-converter/src/config.rs

@@ -0,0 +1,51 @@
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub enum Format {
+    Avif,
+    Webp,
+}
+
+impl Format {
+    pub fn extension(self) -> &'static str {
+        match self {
+            Format::Avif => ".avif",
+            Format::Webp => ".webp",
+        }
+    }
+}
+
+pub struct ConversionConfig {
+    pub format: Format,
+}
+
+impl ConversionConfig {
+    pub fn from_env() -> anyhow::Result<Option<Self>> {
+        Self::from_vars(
+            std::env::var("IMAGE_CONVERSION_ENABLED").ok().as_deref(),
+            std::env::var("IMAGE_CONVERSION_FORMAT").ok().as_deref(),
+        )
+    }
+
+    fn from_vars(enabled: Option<&str>, format: Option<&str>) -> anyhow::Result<Option<Self>> {
+        if enabled != Some("true") {
+            return Ok(None);
+        }
+
+        let format_str = format.ok_or_else(|| {
+            anyhow::anyhow!("IMAGE_CONVERSION_FORMAT required when IMAGE_CONVERSION_ENABLED=true")
+        })?;
+
+        let format = match format_str {
+            "avif" => Format::Avif,
+            "webp" => Format::Webp,
+            other => anyhow::bail!(
+                "Unknown IMAGE_CONVERSION_FORMAT: {other:?}. Valid values: avif, webp"
+            ),
+        };
+
+        Ok(Some(Self { format }))
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/config.rs"]
+mod tests;

crates/adapters/image-converter/src/handler.rs

@@ -0,0 +1,105 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::DomainEvent,
+    ports::{EventHandler, ImageRefCommand, ObjectStorage},
+};
+
+use crate::Format;
+
+pub struct ImageConversionHandler {
+    storage: Arc<dyn ObjectStorage>,
+    image_ref: Arc<dyn ImageRefCommand>,
+    format: Format,
+}
+
+impl ImageConversionHandler {
+    pub fn new(
+        storage: Arc<dyn ObjectStorage>,
+        image_ref: Arc<dyn ImageRefCommand>,
+        format: Format,
+    ) -> Self {
+        Self {
+            storage,
+            image_ref,
+            format,
+        }
+    }
+}
+
+#[async_trait]
+impl EventHandler for ImageConversionHandler {
+    async fn handle(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        let key = match event {
+            DomainEvent::ImageStored { key } => key.clone(),
+            _ => return Ok(()),
+        };
+
+        if key.ends_with(".avif") || key.ends_with(".webp") {
+            return Ok(());
+        }
+
+        let bytes = self.storage.get(&key).await?;
+        let format = self.format;
+
+        let converted = tokio::task::spawn_blocking(move || convert(bytes, format))
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+            .map_err(DomainError::InfrastructureError)?;
+
+        let ext = format.extension();
+        let new_key = format!("{key}{ext}");
+        self.storage.store(&new_key, &converted).await?;
+
+        if let Err(e) = self.image_ref.swap(&key, &new_key).await {
+            tracing::error!("swap failed for {key} → {new_key}: {e}");
+            return Err(e);
+        }
+
+        if let Err(e) = self.storage.delete(&key).await {
+            tracing::warn!("failed to delete old image key {key}: {e}");
+        }
+
+        tracing::info!("converted {key} → {new_key}");
+        Ok(())
+    }
+}
+
+fn convert(bytes: Vec<u8>, format: Format) -> Result<Vec<u8>, String> {
+    let img = image::load_from_memory(&bytes).map_err(|e| e.to_string())?;
+
+    match format {
+        Format::Avif => {
+            let rgba = img.to_rgba8();
+            let width = rgba.width() as usize;
+            let height = rgba.height() as usize;
+            let pixels: Vec<ravif::RGBA8> = rgba
+                .pixels()
+                .map(|p| ravif::RGBA8 {
+                    r: p.0[0],
+                    g: p.0[1],
+                    b: p.0[2],
+                    a: p.0[3],
+                })
+                .collect();
+            let result = ravif::Encoder::new()
+                .with_quality(80.0)
+                .with_speed(6)
+                .encode_rgba(ravif::Img::new(&pixels, width, height))
+                .map_err(|e| e.to_string())?;
+            Ok(result.avif_file.to_vec())
+        }
+        Format::Webp => {
+            let rgba = img.to_rgba8();
+            let (width, height) = (rgba.width(), rgba.height());
+            let encoder = webp::Encoder::from_rgba(rgba.as_raw(), width, height);
+            Ok(encoder.encode(80.0).to_vec())
+        }
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/handler.rs"]
+mod tests;

crates/adapters/image-converter/src/lib.rs

@@ -0,0 +1,41 @@
+mod backfill;
+mod config;
+mod handler;
+
+pub use backfill::ConversionBackfillJob;
+pub use config::{ConversionConfig, Format};
+pub use handler::ImageConversionHandler;
+
+use domain::ports::{
+    EventHandler, EventPublisher, ImageRefCommand, ImageRefQuery, ObjectStorage, PeriodicJob,
+};
+use std::sync::Arc;
+
+type ConversionPair = (Arc<dyn EventHandler>, Arc<dyn PeriodicJob>);
+
+pub fn build(
+    object_storage: Arc<dyn ObjectStorage>,
+    image_ref_command: Arc<dyn ImageRefCommand>,
+    image_ref_query: Arc<dyn ImageRefQuery>,
+    event_publisher: Arc<dyn EventPublisher>,
+) -> anyhow::Result<Option<ConversionPair>> {
+    let config = match ConversionConfig::from_env()? {
+        Some(c) => c,
+        None => return Ok(None),
+    };
+
+    let format = config.format;
+
+    let handler = Arc::new(ImageConversionHandler::new(
+        Arc::clone(&object_storage),
+        image_ref_command,
+        format,
+    )) as Arc<dyn EventHandler>;
+
+    let job = Arc::new(ConversionBackfillJob::new(
+        image_ref_query,
+        Arc::clone(&event_publisher),
+    )) as Arc<dyn PeriodicJob>;
+
+    Ok(Some((handler, job)))
+}

crates/adapters/image-converter/src/tests/backfill.rs

@@ -0,0 +1,85 @@
+use super::*;
+use std::sync::Mutex;
+
+struct MockImageRef {
+    keys: Vec<String>,
+}
+
+#[async_trait::async_trait]
+impl ImageRefQuery for MockImageRef {
+    async fn list_keys(&self) -> Result<Vec<String>, DomainError> {
+        Ok(self.keys.clone())
+    }
+}
+
+struct MockPublisher {
+    emitted: Mutex<Vec<String>>,
+}
+
+impl MockPublisher {
+    fn new() -> Arc<Self> {
+        Arc::new(Self {
+            emitted: Mutex::new(vec![]),
+        })
+    }
+
+    fn emitted(&self) -> Vec<String> {
+        self.emitted.lock().unwrap().clone()
+    }
+}
+
+#[async_trait::async_trait]
+impl EventPublisher for MockPublisher {
+    async fn publish(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        if let DomainEvent::ImageStored { key } = event {
+            self.emitted.lock().unwrap().push(key.clone());
+        }
+        Ok(())
+    }
+}
+
+#[tokio::test]
+async fn emits_image_stored_for_unconverted_keys() {
+    let image_ref = Arc::new(MockImageRef {
+        keys: vec!["avatars/u1".into(), "posters/m1".into()],
+    });
+    let publisher = MockPublisher::new();
+    let job =
+        ConversionBackfillJob::new(image_ref, Arc::clone(&publisher) as Arc<dyn EventPublisher>);
+
+    job.run().await.unwrap();
+
+    let mut emitted = publisher.emitted();
+    emitted.sort();
+    assert_eq!(emitted, vec!["avatars/u1", "posters/m1"]);
+}
+
+#[tokio::test]
+async fn skips_already_converted_keys() {
+    let image_ref = Arc::new(MockImageRef {
+        keys: vec![
+            "avatars/u1.avif".into(),
+            "posters/m1".into(),
+            "avatars/u2.webp".into(),
+        ],
+    });
+    let publisher = MockPublisher::new();
+    let job =
+        ConversionBackfillJob::new(image_ref, Arc::clone(&publisher) as Arc<dyn EventPublisher>);
+
+    job.run().await.unwrap();
+
+    assert_eq!(publisher.emitted(), vec!["posters/m1"]);
+}
+
+#[tokio::test]
+async fn empty_keys_emits_nothing() {
+    let image_ref = Arc::new(MockImageRef { keys: vec![] });
+    let publisher = MockPublisher::new();
+    let job =
+        ConversionBackfillJob::new(image_ref, Arc::clone(&publisher) as Arc<dyn EventPublisher>);
+
+    job.run().await.unwrap();
+
+    assert!(publisher.emitted().is_empty());
+}

crates/adapters/image-converter/src/tests/config.rs

@@ -0,0 +1,45 @@
+use super::*;
+
+#[test]
+fn disabled_by_default() {
+    assert!(ConversionConfig::from_vars(None, None).unwrap().is_none());
+    assert!(ConversionConfig::from_vars(Some("false"), None)
+        .unwrap()
+        .is_none());
+}
+
+#[test]
+fn enabled_avif() {
+    let cfg = ConversionConfig::from_vars(Some("true"), Some("avif"))
+        .unwrap()
+        .unwrap();
+    assert_eq!(cfg.format, Format::Avif);
+}
+
+#[test]
+fn enabled_webp() {
+    let cfg = ConversionConfig::from_vars(Some("true"), Some("webp"))
+        .unwrap()
+        .unwrap();
+    assert_eq!(cfg.format, Format::Webp);
+}
+
+#[test]
+fn unknown_format_is_error() {
+    assert!(ConversionConfig::from_vars(Some("true"), Some("gif")).is_err());
+}
+
+#[test]
+fn missing_format_when_enabled_is_error() {
+    assert!(ConversionConfig::from_vars(Some("true"), None).is_err());
+}
+
+#[test]
+fn avif_extension() {
+    assert_eq!(Format::Avif.extension(), ".avif");
+}
+
+#[test]
+fn webp_extension() {
+    assert_eq!(Format::Webp.extension(), ".webp");
+}

crates/adapters/image-converter/src/tests/handler.rs

@@ -0,0 +1,160 @@
+use super::*;
+use object_storage::ObjectStorageAdapter;
+use object_store::memory::InMemory;
+use std::sync::Mutex;
+
+struct MockImageRef {
+    swaps: Mutex<Vec<(String, String)>>,
+}
+
+impl MockImageRef {
+    fn new() -> Arc<Self> {
+        Arc::new(Self {
+            swaps: Mutex::new(vec![]),
+        })
+    }
+
+    fn swaps(&self) -> Vec<(String, String)> {
+        self.swaps.lock().unwrap().clone()
+    }
+}
+
+#[async_trait::async_trait]
+impl ImageRefCommand for MockImageRef {
+    async fn swap(&self, old: &str, new: &str) -> Result<(), DomainError> {
+        self.swaps.lock().unwrap().push((old.into(), new.into()));
+        Ok(())
+    }
+}
+
+fn in_memory_storage() -> Arc<ObjectStorageAdapter> {
+    Arc::new(ObjectStorageAdapter::new(Arc::new(InMemory::new())))
+}
+
+fn tiny_jpeg() -> Vec<u8> {
+    use image::{DynamicImage, ImageBuffer, Rgb};
+    let img = DynamicImage::ImageRgb8(ImageBuffer::from_pixel(4, 4, Rgb([200u8, 100, 50])));
+    let mut buf = std::io::Cursor::new(Vec::new());
+    img.write_to(&mut buf, image::ImageFormat::Jpeg).unwrap();
+    buf.into_inner()
+}
+
+#[tokio::test]
+async fn ignores_non_image_stored_events() {
+    let storage = in_memory_storage();
+    let image_ref = MockImageRef::new();
+    let handler = ImageConversionHandler::new(
+        Arc::clone(&storage) as Arc<dyn ObjectStorage>,
+        Arc::clone(&image_ref) as Arc<dyn ImageRefCommand>,
+        Format::Avif,
+    );
+
+    handler
+        .handle(&DomainEvent::UserUpdated {
+            user_id: domain::value_objects::UserId::from_uuid(uuid::Uuid::new_v4()),
+        })
+        .await
+        .unwrap();
+
+    assert!(image_ref.swaps().is_empty());
+}
+
+#[tokio::test]
+async fn skips_already_converted_avif_key() {
+    let storage = in_memory_storage();
+    storage
+        .store("avatars/u1.avif", &tiny_jpeg())
+        .await
+        .unwrap();
+    let image_ref = MockImageRef::new();
+    let handler = ImageConversionHandler::new(
+        Arc::clone(&storage) as Arc<dyn ObjectStorage>,
+        Arc::clone(&image_ref) as Arc<dyn ImageRefCommand>,
+        Format::Avif,
+    );
+
+    handler
+        .handle(&DomainEvent::ImageStored {
+            key: "avatars/u1.avif".into(),
+        })
+        .await
+        .unwrap();
+
+    assert!(image_ref.swaps().is_empty());
+}
+
+#[tokio::test]
+async fn skips_already_converted_webp_key() {
+    let storage = in_memory_storage();
+    storage
+        .store("posters/m1.webp", &tiny_jpeg())
+        .await
+        .unwrap();
+    let image_ref = MockImageRef::new();
+    let handler = ImageConversionHandler::new(
+        Arc::clone(&storage) as Arc<dyn ObjectStorage>,
+        Arc::clone(&image_ref) as Arc<dyn ImageRefCommand>,
+        Format::Webp,
+    );
+
+    handler
+        .handle(&DomainEvent::ImageStored {
+            key: "posters/m1.webp".into(),
+        })
+        .await
+        .unwrap();
+
+    assert!(image_ref.swaps().is_empty());
+}
+
+#[tokio::test]
+async fn converts_jpeg_to_avif_and_swaps_key() {
+    let storage = in_memory_storage();
+    storage.store("avatars/u1", &tiny_jpeg()).await.unwrap();
+    let image_ref = MockImageRef::new();
+    let handler = ImageConversionHandler::new(
+        Arc::clone(&storage) as Arc<dyn ObjectStorage>,
+        Arc::clone(&image_ref) as Arc<dyn ImageRefCommand>,
+        Format::Avif,
+    );
+
+    handler
+        .handle(&DomainEvent::ImageStored {
+            key: "avatars/u1".into(),
+        })
+        .await
+        .unwrap();
+
+    assert_eq!(
+        image_ref.swaps(),
+        vec![("avatars/u1".into(), "avatars/u1.avif".into())]
+    );
+    assert!(storage.get("avatars/u1.avif").await.is_ok());
+    // Old raw key deleted — fallback resolves to .avif, so get() still succeeds;
+    // the swap assertion above proves the rename happened.
+}
+
+#[tokio::test]
+async fn converts_jpeg_to_webp_and_swaps_key() {
+    let storage = in_memory_storage();
+    storage.store("avatars/u1", &tiny_jpeg()).await.unwrap();
+    let image_ref = MockImageRef::new();
+    let handler = ImageConversionHandler::new(
+        Arc::clone(&storage) as Arc<dyn ObjectStorage>,
+        Arc::clone(&image_ref) as Arc<dyn ImageRefCommand>,
+        Format::Webp,
+    );
+
+    handler
+        .handle(&DomainEvent::ImageStored {
+            key: "avatars/u1".into(),
+        })
+        .await
+        .unwrap();
+
+    assert_eq!(
+        image_ref.swaps(),
+        vec![("avatars/u1".into(), "avatars/u1.webp".into())]
+    );
+    assert!(storage.get("avatars/u1.webp").await.is_ok());
+}

crates/adapters/importer/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "importer"
+version = "0.1.0"
+edition = "2024"
+
+[features]
+xlsx = ["dep:calamine"]
+
+[dependencies]
+domain = { workspace = true }
+serde_json = { workspace = true }
+csv = { workspace = true }
+calamine = { version = "0.35", optional = true }

crates/adapters/importer/src/lib.rs

@@ -0,0 +1,32 @@
+mod mapper;
+mod parsers;
+
+use domain::{
+    models::{AnnotatedRow, FieldMapping, FileFormat, ImportError, ParsedFile},
+    ports::DocumentParser,
+};
+
+pub struct ImporterDocumentParser;
+
+impl DocumentParser for ImporterDocumentParser {
+    fn parse(&self, bytes: &[u8], format: FileFormat) -> Result<ParsedFile, ImportError> {
+        match format {
+            FileFormat::Csv => parsers::parse_csv(bytes),
+            FileFormat::Json => parsers::parse_json(bytes),
+            FileFormat::Xlsx => {
+                #[cfg(feature = "xlsx")]
+                {
+                    parsers::parse_xlsx(bytes)
+                }
+                #[cfg(not(feature = "xlsx"))]
+                {
+                    Err(ImportError::Xlsx("XLSX support not compiled in".into()))
+                }
+            }
+        }
+    }
+
+    fn apply_mapping(&self, file: &ParsedFile, mappings: &[FieldMapping]) -> Vec<AnnotatedRow> {
+        mapper::apply_mapping(file, mappings)
+    }
+}

crates/adapters/importer/src/mapper.rs

@@ -0,0 +1,85 @@
+use domain::models::{
+    AnnotatedRow, DomainField, FieldMapping, ImportRow, ParsedFile, RowResult, Transform,
+};
+
+pub fn apply_mapping(file: &ParsedFile, mappings: &[FieldMapping]) -> Vec<AnnotatedRow> {
+    file.rows
+        .iter()
+        .map(|row| {
+            let result = map_row(row, &file.columns, mappings);
+            AnnotatedRow {
+                result,
+                is_duplicate: false,
+            }
+        })
+        .collect()
+}
+
+fn map_row(row: &[String], columns: &[String], mappings: &[FieldMapping]) -> RowResult {
+    let mut import_row = ImportRow::default();
+    let mut errors = Vec::new();
+
+    for mapping in mappings {
+        let Some(col_idx) = columns.iter().position(|c| c == &mapping.source_column) else {
+            continue;
+        };
+        let raw_value = row.get(col_idx).map(|s| s.as_str()).unwrap_or("").trim();
+        if raw_value.is_empty() {
+            continue;
+        }
+        if let Some(value) = apply_transform(raw_value, &mapping.transform, &mut errors) {
+            set_field(&mut import_row, &mapping.domain_field, value);
+        }
+    }
+
+    if import_row.title.is_none() && import_row.external_metadata_id.is_none() {
+        errors.push("missing required field: title or external_metadata_id".into());
+    }
+    if import_row.rating.is_none() {
+        errors.push("missing required field: rating".into());
+    }
+    if import_row.watched_at.is_none() {
+        errors.push("missing required field: watched_at".into());
+    }
+
+    if errors.is_empty() {
+        RowResult::Valid(import_row)
+    } else {
+        let raw = columns
+            .iter()
+            .zip(row.iter())
+            .map(|(c, v)| (c.clone(), v.clone()))
+            .collect();
+        RowResult::Invalid { errors, raw }
+    }
+}
+
+fn apply_transform(value: &str, transform: &Transform, errors: &mut Vec<String>) -> Option<String> {
+    match transform {
+        Transform::Identity => Some(value.to_string()),
+        Transform::DateFormat(_) => Some(value.to_string()),
+        Transform::RatingScale(factor) => match value.parse::<f64>() {
+            Ok(n) => Some((n * factor).round().to_string()),
+            Err(_) => {
+                errors.push(format!("rating '{}' is not a number", value));
+                None
+            }
+        },
+    }
+}
+
+fn set_field(row: &mut ImportRow, field: &DomainField, value: String) {
+    match field {
+        DomainField::Title => row.title = Some(value),
+        DomainField::ReleaseYear => row.release_year = Some(value),
+        DomainField::Director => row.director = Some(value),
+        DomainField::Rating => row.rating = Some(value),
+        DomainField::WatchedAt => row.watched_at = Some(value),
+        DomainField::Comment => row.comment = Some(value),
+        DomainField::ExternalMetadataId => row.external_metadata_id = Some(value),
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/mapper.rs"]
+mod tests;

crates/adapters/importer/src/parsers/csv.rs

@@ -0,0 +1,48 @@
+use domain::models::{ImportError, ParsedFile};
+
+pub fn parse_csv(bytes: &[u8]) -> Result<ParsedFile, ImportError> {
+    if bytes.is_empty() {
+        return Err(ImportError::Empty);
+    }
+
+    let delimiter = detect_delimiter(bytes);
+    let mut rdr = csv::ReaderBuilder::new()
+        .delimiter(delimiter)
+        .from_reader(bytes);
+
+    let columns: Vec<String> = rdr
+        .headers()
+        .map_err(|e| ImportError::Csv(e.to_string()))?
+        .iter()
+        .map(|s| s.trim().to_string())
+        .collect();
+
+    if columns.is_empty() {
+        return Err(ImportError::NoHeader);
+    }
+
+    let rows: Vec<Vec<String>> = rdr
+        .records()
+        .map(|r| {
+            r.map_err(|e| ImportError::Csv(e.to_string())).map(|rec| {
+                let mut cells: Vec<String> = rec.iter().map(|f| f.trim().to_string()).collect();
+                cells.resize(columns.len(), String::new());
+                cells.truncate(columns.len());
+                cells
+            })
+        })
+        .collect::<Result<_, _>>()?;
+
+    if rows.is_empty() {
+        return Err(ImportError::Empty);
+    }
+
+    Ok(ParsedFile { columns, rows })
+}
+
+fn detect_delimiter(bytes: &[u8]) -> u8 {
+    let first_line = bytes.split(|&b| b == b'\n').next().unwrap_or(bytes);
+    let tabs = first_line.iter().filter(|&&b| b == b'\t').count();
+    let commas = first_line.iter().filter(|&&b| b == b',').count();
+    if tabs > commas { b'\t' } else { b',' }
+}

crates/adapters/importer/src/parsers/json.rs

@@ -0,0 +1,48 @@
+use domain::models::{ImportError, ParsedFile};
+use serde_json::Value;
+
+pub fn parse_json(bytes: &[u8]) -> Result<ParsedFile, ImportError> {
+    let value: Value =
+        serde_json::from_slice(bytes).map_err(|e| ImportError::Json(e.to_string()))?;
+
+    let arr = value
+        .as_array()
+        .ok_or_else(|| ImportError::Json("expected a JSON array".into()))?;
+
+    if arr.is_empty() {
+        return Err(ImportError::Empty);
+    }
+
+    let first = arr[0]
+        .as_object()
+        .ok_or_else(|| ImportError::Json("array elements must be objects".into()))?;
+    let columns: Vec<String> = first.keys().cloned().collect();
+
+    if columns.is_empty() {
+        return Err(ImportError::NoHeader);
+    }
+
+    let rows: Vec<Vec<String>> = arr
+        .iter()
+        .enumerate()
+        .map(|(idx, item)| {
+            let obj = item.as_object().ok_or_else(|| {
+                ImportError::Json(format!("element at index {} is not an object", idx))
+            })?;
+            Ok(columns
+                .iter()
+                .map(|col| obj.get(col).map(value_to_string).unwrap_or_default())
+                .collect())
+        })
+        .collect::<Result<_, ImportError>>()?;
+
+    Ok(ParsedFile { columns, rows })
+}
+
+fn value_to_string(v: &Value) -> String {
+    match v {
+        Value::String(s) => s.clone(),
+        Value::Null => String::new(),
+        other => other.to_string(),
+    }
+}

crates/adapters/importer/src/parsers/mod.rs

@@ -0,0 +1,13 @@
+mod csv;
+mod json;
+#[cfg(feature = "xlsx")]
+mod xlsx;
+
+pub use csv::parse_csv;
+pub use json::parse_json;
+#[cfg(feature = "xlsx")]
+pub use xlsx::parse_xlsx;
+
+#[cfg(test)]
+#[path = "tests.rs"]
+mod tests;

crates/adapters/importer/src/parsers/tests.rs

@@ -0,0 +1,37 @@
+use super::*;
+
+#[test]
+fn csv_parses_headers_and_rows() {
+    let data = b"title,rating,watched_at\nInception,5,2024-01-01\nDune,4,2024-02-15\n";
+    let file = parse_csv(data).unwrap();
+    assert_eq!(file.columns, vec!["title", "rating", "watched_at"]);
+    assert_eq!(file.rows.len(), 2);
+    assert_eq!(file.rows[0], vec!["Inception", "5", "2024-01-01"]);
+}
+
+#[test]
+fn csv_rejects_empty() {
+    assert!(parse_csv(b"").is_err());
+}
+
+#[test]
+fn tsv_parses_correctly() {
+    let data = b"title\trating\nInception\t5\n";
+    let file = parse_csv(data).unwrap();
+    assert_eq!(file.columns, vec!["title", "rating"]);
+    assert_eq!(file.rows[0], vec!["Inception", "5"]);
+}
+
+#[test]
+fn json_array_of_objects() {
+    let data = br#"[{"title":"Inception","rating":"5"},{"title":"Dune","rating":"4"}]"#;
+    let file = parse_json(data).unwrap();
+    assert_eq!(file.columns.len(), 2);
+    assert!(file.columns.contains(&"title".to_string()));
+    assert_eq!(file.rows.len(), 2);
+}
+
+#[test]
+fn json_empty_array_errors() {
+    assert!(parse_json(b"[]").is_err());
+}

crates/adapters/importer/src/parsers/xlsx.rs

@@ -0,0 +1,71 @@
+use calamine::{Data, Reader, Xlsx, open_workbook_from_rs};
+use domain::models::{ImportError, ParsedFile};
+use std::io::Cursor;
+
+pub fn parse_xlsx(bytes: &[u8]) -> Result<ParsedFile, ImportError> {
+    let cursor = Cursor::new(bytes);
+    let mut workbook: Xlsx<_> = open_workbook_from_rs(cursor)
+        .map_err(|e: calamine::XlsxError| ImportError::Xlsx(e.to_string()))?;
+
+    let sheet_name = workbook
+        .sheet_names()
+        .first()
+        .cloned()
+        .ok_or(ImportError::Empty)?;
+
+    let range = workbook
+        .worksheet_range(&sheet_name)
+        .map_err(|e| ImportError::Xlsx(e.to_string()))?;
+
+    let mut iter = range.rows();
+
+    let header = iter.next().ok_or(ImportError::NoHeader)?;
+    let columns: Vec<String> = header
+        .iter()
+        .map(|c| cell_to_string(c).trim().to_string())
+        .collect();
+
+    if columns.is_empty() {
+        return Err(ImportError::NoHeader);
+    }
+
+    let rows: Vec<Vec<String>> = iter
+        .map(|row| {
+            let mut cells: Vec<String> = row.iter().map(cell_to_string).collect();
+            cells.resize(columns.len(), String::new());
+            cells.truncate(columns.len());
+            cells
+        })
+        .collect();
+
+    if rows.is_empty() {
+        return Err(ImportError::Empty);
+    }
+
+    Ok(ParsedFile { columns, rows })
+}
+
+fn cell_to_string(cell: &Data) -> String {
+    match cell {
+        Data::String(s) => s.clone(),
+        Data::Float(f) => {
+            if f.fract() == 0.0 {
+                format!("{}", *f as i64)
+            } else {
+                format!("{}", f)
+            }
+        }
+        Data::Int(i) => i.to_string(),
+        Data::Bool(b) => b.to_string(),
+        Data::DateTime(dt) => {
+            // ExcelDateTime::to_ymd_hms_milli() works without the chrono feature.
+            let (year, month, day, _, _, _, _) = dt.to_ymd_hms_milli();
+            format!("{:04}-{:02}-{:02}", year, month, day)
+        }
+        Data::DateTimeIso(s) => s.clone(),
+        Data::DurationIso(s) => s.clone(),
+        Data::Empty | Data::Error(_) => String::new(),
+        // Fallback for unexpected calamine Data variants; renders as debug string
+        other => format!("{other:?}"),
+    }
+}

crates/adapters/importer/src/tests/mapper.rs

@@ -0,0 +1,158 @@
+use super::*;
+use domain::models::{DomainField, FieldMapping, ParsedFile, RowResult, Transform};
+
+fn sample_file() -> ParsedFile {
+    ParsedFile {
+        columns: vec!["Name".into(), "Stars".into(), "Date".into()],
+        rows: vec![
+            vec!["Inception".into(), "10".into(), "2024-01-15".into()],
+            vec!["Dune".into(), "8".into(), "2024-02-20".into()],
+            vec!["".into(), "3".into(), "2024-03-01".into()], // missing title → invalid
+        ],
+    }
+}
+
+fn full_mappings() -> Vec<FieldMapping> {
+    vec![
+        FieldMapping {
+            source_column: "Name".into(),
+            domain_field: DomainField::Title,
+            transform: Transform::Identity,
+        },
+        FieldMapping {
+            source_column: "Stars".into(),
+            domain_field: DomainField::Rating,
+            transform: Transform::RatingScale(0.5),
+        },
+        FieldMapping {
+            source_column: "Date".into(),
+            domain_field: DomainField::WatchedAt,
+            transform: Transform::Identity,
+        },
+    ]
+}
+
+#[test]
+fn maps_valid_rows() {
+    let results = apply_mapping(&sample_file(), &full_mappings());
+    assert_eq!(results.len(), 3);
+    // First two rows are valid
+    assert!(matches!(results[0].result, RowResult::Valid(_)));
+    assert!(matches!(results[1].result, RowResult::Valid(_)));
+    // is_duplicate defaults to false
+    assert!(!results[0].is_duplicate);
+}
+
+#[test]
+fn applies_rating_scale_transform() {
+    let results = apply_mapping(&sample_file(), &full_mappings());
+    if let RowResult::Valid(row) = &results[0].result {
+        // 10 * 0.5 = 5
+        assert_eq!(row.rating.as_deref(), Some("5"));
+    } else {
+        panic!("expected Valid");
+    }
+}
+
+#[test]
+fn marks_missing_required_fields_invalid() {
+    let results = apply_mapping(&sample_file(), &full_mappings());
+    // Row 2 has empty title
+    assert!(matches!(results[2].result, RowResult::Invalid { .. }));
+}
+
+#[test]
+fn ignores_unmapped_columns() {
+    let mappings = vec![FieldMapping {
+        source_column: "Name".into(),
+        domain_field: DomainField::Title,
+        transform: Transform::Identity,
+    }];
+    let file = ParsedFile {
+        columns: vec!["Name".into(), "Extra".into()],
+        rows: vec![vec!["Inception".into(), "ignored".into()]],
+    };
+    let results = apply_mapping(&file, &mappings);
+    assert_eq!(results.len(), 1);
+    // Missing rating and watched_at → invalid
+    assert!(matches!(results[0].result, RowResult::Invalid { .. }));
+}
+
+#[test]
+fn nonexistent_source_column_skipped() {
+    let mappings = vec![FieldMapping {
+        source_column: "DoesNotExist".into(),
+        domain_field: DomainField::Title,
+        transform: Transform::Identity,
+    }];
+    let file = ParsedFile {
+        columns: vec!["Name".into()],
+        rows: vec![vec!["Inception".into()]],
+    };
+    let results = apply_mapping(&file, &mappings);
+    // Column not found → field not set → invalid (missing title, rating, watched_at)
+    assert!(matches!(results[0].result, RowResult::Invalid { .. }));
+}
+
+#[test]
+fn collects_all_errors_not_just_first() {
+    let mappings = vec![
+        FieldMapping {
+            source_column: "Name".into(),
+            domain_field: DomainField::Title,
+            transform: Transform::Identity,
+        },
+        FieldMapping {
+            source_column: "Stars".into(),
+            domain_field: DomainField::Rating,
+            transform: Transform::RatingScale(0.5),
+        },
+        // no watched_at mapping
+    ];
+    let file = ParsedFile {
+        columns: vec!["Name".into(), "Stars".into()],
+        rows: vec![vec!["Inception".into(), "notanumber".into()]],
+    };
+    let results = apply_mapping(&file, &mappings);
+    if let RowResult::Invalid { errors, .. } = &results[0].result {
+        assert!(
+            errors.iter().any(|e| e.contains("not a number")),
+            "expected rating error, got: {:?}",
+            errors
+        );
+        assert!(
+            errors.iter().any(|e| e.contains("watched_at")),
+            "expected watched_at error, got: {:?}",
+            errors
+        );
+    } else {
+        panic!("expected Invalid");
+    }
+}
+
+#[test]
+fn non_numeric_rating_produces_error_in_row() {
+    let mappings = vec![
+        FieldMapping {
+            source_column: "Name".into(),
+            domain_field: DomainField::Title,
+            transform: Transform::Identity,
+        },
+        FieldMapping {
+            source_column: "Stars".into(),
+            domain_field: DomainField::Rating,
+            transform: Transform::RatingScale(0.5),
+        },
+        FieldMapping {
+            source_column: "Date".into(),
+            domain_field: DomainField::WatchedAt,
+            transform: Transform::Identity,
+        },
+    ];
+    let file = ParsedFile {
+        columns: vec!["Name".into(), "Stars".into(), "Date".into()],
+        rows: vec![vec!["Inception".into(), "five".into(), "2024-01-15".into()]],
+    };
+    let results = apply_mapping(&file, &mappings);
+    assert!(matches!(results[0].result, RowResult::Invalid { .. }));
+}

crates/adapters/jellyfin/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "jellyfin"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }

crates/adapters/jellyfin/src/lib.rs

@@ -0,0 +1,132 @@
+use domain::{errors::DomainError, models::ParsedPlaybackEvent, ports::MediaServerParser};
+use serde::Deserialize;
+
+pub struct JellyfinParser;
+
+impl MediaServerParser for JellyfinParser {
+    fn parse_playback_event(
+        &self,
+        body: &[u8],
+    ) -> Result<Option<ParsedPlaybackEvent>, DomainError> {
+        let payload: JellyfinPayload = serde_json::from_slice(body)
+            .map_err(|e| DomainError::ValidationError(format!("invalid Jellyfin payload: {e}")))?;
+
+        if payload.notification_type != "PlaybackStop" {
+            return Ok(None);
+        }
+
+        let item_type = payload.item_type.as_deref().unwrap_or("");
+        if item_type != "Movie" {
+            return Ok(None);
+        }
+
+        if !payload.played_to_completion.unwrap_or(false) {
+            return Ok(None);
+        }
+
+        let title = match payload.name {
+            Some(t) if !t.is_empty() => t,
+            _ => return Ok(None),
+        };
+
+        let tmdb_id = payload.provider_tmdb.map(|id| format!("tmdb:{id}"));
+        let imdb_id = payload.provider_imdb;
+
+        Ok(Some(ParsedPlaybackEvent {
+            title,
+            year: payload.year,
+            tmdb_id,
+            imdb_id,
+        }))
+    }
+}
+
+#[derive(Deserialize)]
+struct JellyfinPayload {
+    #[serde(rename = "NotificationType")]
+    notification_type: String,
+    #[serde(rename = "ItemType")]
+    item_type: Option<String>,
+    #[serde(rename = "Name")]
+    name: Option<String>,
+    #[serde(rename = "Year")]
+    year: Option<u16>,
+    #[serde(rename = "PlayedToCompletion")]
+    played_to_completion: Option<bool>,
+    #[serde(rename = "Provider_tmdb")]
+    provider_tmdb: Option<String>,
+    #[serde(rename = "Provider_imdb")]
+    provider_imdb: Option<String>,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_valid_playback_stop() {
+        let body = serde_json::json!({
+            "NotificationType": "PlaybackStop",
+            "ItemType": "Movie",
+            "Name": "Blade Runner",
+            "Year": 1982,
+            "PlayedToCompletion": true,
+            "Provider_tmdb": "78",
+            "Provider_imdb": "tt0083658"
+        });
+        let parser = JellyfinParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        let event = result.expect("should parse");
+        assert_eq!(event.title, "Blade Runner");
+        assert_eq!(event.year, Some(1982));
+        assert_eq!(event.tmdb_id, Some("tmdb:78".into()));
+        assert_eq!(event.imdb_id, Some("tt0083658".into()));
+    }
+
+    #[test]
+    fn ignores_non_movie() {
+        let body = serde_json::json!({
+            "NotificationType": "PlaybackStop",
+            "ItemType": "Episode",
+            "Name": "Some Episode",
+            "PlayedToCompletion": true
+        });
+        let parser = JellyfinParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn ignores_incomplete_playback() {
+        let body = serde_json::json!({
+            "NotificationType": "PlaybackStop",
+            "ItemType": "Movie",
+            "Name": "Blade Runner",
+            "PlayedToCompletion": false
+        });
+        let parser = JellyfinParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn ignores_playback_start() {
+        let body = serde_json::json!({
+            "NotificationType": "PlaybackStart",
+            "ItemType": "Movie",
+            "Name": "Blade Runner",
+            "PlayedToCompletion": false
+        });
+        let parser = JellyfinParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        assert!(result.is_none());
+    }
+}

crates/adapters/metadata/Cargo.toml

@@ -4,3 +4,8 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
+anyhow = { workspace = true }
+async-trait = { workspace = true }
+reqwest = { workspace = true }
+serde = { workspace = true }
+domain = { workspace = true }

crates/adapters/metadata/src/lib.rs

@@ -1,14 +1,78 @@
-pub fn add(left: u64, right: u64) -> u64 {
-    left + right
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    models::Movie,
+    ports::{MetadataClient, MetadataSearchCriteria},
+    value_objects::{ExternalMetadataId, MovieTitle, PosterUrl, ReleaseYear},
+};
+
+mod omdb;
+mod tmdb;
+
+pub(crate) struct ProviderMovie {
+    pub imdb_id: ExternalMetadataId,
+    pub title: MovieTitle,
+    pub release_year: ReleaseYear,
+    pub director: Option<String>,
+    pub poster_url: Option<PosterUrl>,
 }
 
-#[cfg(test)]
-mod tests {
-    use super::*;
+#[async_trait]
+pub(crate) trait MetadataProvider: Send + Sync {
+    async fn fetch(&self, criteria: &MetadataSearchCriteria) -> Result<ProviderMovie, DomainError>;
+}
 
-    #[test]
-    fn it_works() {
-        let result = add(2, 2);
-        assert_eq!(result, 4);
+pub struct MetadataClientImpl {
+    provider: Box<dyn MetadataProvider>,
+}
+
+impl MetadataClientImpl {
+    pub fn new_omdb(api_key: String) -> Self {
+        Self {
+            provider: Box::new(omdb::OmdbProvider::new(api_key)),
+        }
+    }
+
+    pub fn new_tmdb(api_key: String) -> Self {
+        Self {
+            provider: Box::new(tmdb::TmdbProvider::new(api_key)),
+        }
+    }
+}
+
+#[async_trait]
+impl MetadataClient for MetadataClientImpl {
+    async fn fetch_movie_metadata(
+        &self,
+        criteria: &MetadataSearchCriteria,
+    ) -> Result<Movie, DomainError> {
+        let pm = self.provider.fetch(criteria).await?;
+        Ok(Movie::new(
+            Some(pm.imdb_id),
+            pm.title,
+            pm.release_year,
+            pm.director,
+            None,
+        ))
+    }
+
+    async fn get_poster_url(
+        &self,
+        external_metadata_id: &ExternalMetadataId,
+    ) -> Result<Option<PosterUrl>, DomainError> {
+        let criteria = MetadataSearchCriteria::ImdbId(external_metadata_id.clone());
+        let pm = self.provider.fetch(&criteria).await?;
+        Ok(pm.poster_url)
+    }
+}
+
+pub fn create() -> anyhow::Result<std::sync::Arc<dyn domain::ports::MetadataClient>> {
+    use anyhow::Context;
+    if let Ok(key) = std::env::var("TMDB_API_KEY") {
+        Ok(std::sync::Arc::new(MetadataClientImpl::new_tmdb(key)))
+    } else {
+        let key = std::env::var("OMDB_API_KEY")
+            .context("either TMDB_API_KEY or OMDB_API_KEY must be set")?;
+        Ok(std::sync::Arc::new(MetadataClientImpl::new_omdb(key)))
     }
 }

crates/adapters/metadata/src/omdb.rs

@@ -0,0 +1,125 @@
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    ports::MetadataSearchCriteria,
+    value_objects::{ExternalMetadataId, MovieTitle, PosterUrl, ReleaseYear},
+};
+use serde::Deserialize;
+
+use crate::{MetadataProvider, ProviderMovie};
+
+pub(crate) struct OmdbProvider {
+    client: reqwest::Client,
+    api_key: String,
+    base_url: String,
+}
+
+impl OmdbProvider {
+    pub(crate) fn new(api_key: String) -> Self {
+        Self {
+            client: reqwest::Client::new(),
+            api_key,
+            base_url: "http://www.omdbapi.com/".to_string(),
+        }
+    }
+}
+
+#[derive(Deserialize)]
+struct OmdbResponse {
+    #[serde(rename = "Title")]
+    title: String,
+    #[serde(rename = "Year")]
+    year: String,
+    #[serde(rename = "Director")]
+    director: String,
+    #[serde(rename = "Poster")]
+    poster: String,
+    #[serde(rename = "imdbID")]
+    imdb_id: String,
+    #[serde(rename = "Response")]
+    response: String,
+    #[serde(rename = "Error")]
+    error: Option<String>,
+}
+
+#[async_trait]
+impl MetadataProvider for OmdbProvider {
+    async fn fetch(&self, criteria: &MetadataSearchCriteria) -> Result<ProviderMovie, DomainError> {
+        let mut url = reqwest::Url::parse(&self.base_url)
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+
+        {
+            let mut params = url.query_pairs_mut();
+            params.append_pair("apikey", &self.api_key);
+            match criteria {
+                MetadataSearchCriteria::ImdbId(id) => {
+                    params.append_pair("i", id.value());
+                }
+                MetadataSearchCriteria::Title { title, year } => {
+                    params.append_pair("t", title.value());
+                    if let Some(y) = year {
+                        params.append_pair("y", &y.value().to_string());
+                    }
+                }
+            }
+        }
+
+        let http_resp = self
+            .client
+            .get(url)
+            .send()
+            .await
+            .map_err(|e: reqwest::Error| DomainError::InfrastructureError(e.to_string()))?
+            .error_for_status()
+            .map_err(|e: reqwest::Error| DomainError::InfrastructureError(e.to_string()))?;
+
+        let resp: OmdbResponse = http_resp
+            .json()
+            .await
+            .map_err(|e: reqwest::Error| DomainError::InfrastructureError(e.to_string()))?;
+
+        if resp.response != "True" {
+            let msg = resp.error.unwrap_or_default();
+            return if msg.to_lowercase().contains("not found") {
+                Err(DomainError::NotFound(msg))
+            } else {
+                Err(DomainError::InfrastructureError(msg))
+            };
+        }
+
+        let year: u16 = resp
+            .year
+            .chars()
+            .take(4)
+            .collect::<String>()
+            .parse()
+            .map_err(|_| {
+                DomainError::InfrastructureError(format!("Unparseable year: {}", resp.year))
+            })?;
+
+        let imdb_id = ExternalMetadataId::new(resp.imdb_id)
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        let title = MovieTitle::new(resp.title)
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        let release_year =
+            ReleaseYear::new(year).map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+
+        let director = match resp.director.as_str() {
+            "N/A" | "" => None,
+            d => Some(d.to_string()),
+        };
+
+        let poster_url = match resp.poster.as_str() {
+            "N/A" | "" => None,
+            url => PosterUrl::new(url.to_string()).ok(),
+        };
+
+        Ok(ProviderMovie {
+            imdb_id,
+            title,
+            release_year,
+            director,
+            poster_url,
+        })
+    }
+}

crates/adapters/metadata/src/tmdb.rs

@@ -0,0 +1,175 @@
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    ports::MetadataSearchCriteria,
+    value_objects::{ExternalMetadataId, MovieTitle, PosterUrl, ReleaseYear},
+};
+use serde::Deserialize;
+
+use crate::{MetadataProvider, ProviderMovie};
+
+pub(crate) struct TmdbProvider {
+    client: reqwest::Client,
+    api_key: String,
+}
+
+impl TmdbProvider {
+    pub(crate) fn new(api_key: String) -> Self {
+        Self {
+            client: reqwest::Client::new(),
+            api_key,
+        }
+    }
+
+    fn base(&self, path: &str) -> String {
+        format!("https://api.themoviedb.org/3{}", path)
+    }
+
+    fn poster_url(&self, path: &str) -> Option<PosterUrl> {
+        if path.is_empty() || path == "null" {
+            return None;
+        }
+        PosterUrl::new(format!("https://image.tmdb.org/t/p/w500{}", path)).ok()
+    }
+
+    async fn get<T: for<'de> Deserialize<'de>>(
+        &self,
+        url: &str,
+        extra: &[(&str, &str)],
+    ) -> Result<T, DomainError> {
+        let mut req = self
+            .client
+            .get(url)
+            .query(&[("api_key", self.api_key.as_str())]);
+        for (k, v) in extra {
+            req = req.query(&[(k, v)]);
+        }
+        req.send()
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+            .error_for_status()
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+            .json::<T>()
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+
+    async fn fetch_details(&self, tmdb_id: u64) -> Result<ProviderMovie, DomainError> {
+        #[derive(Deserialize)]
+        struct CrewMember {
+            job: String,
+            name: String,
+        }
+        #[derive(Deserialize)]
+        struct Credits {
+            crew: Vec<CrewMember>,
+        }
+        #[derive(Deserialize)]
+        struct Details {
+            imdb_id: Option<String>,
+            title: String,
+            release_date: String, // "YYYY-MM-DD"
+            poster_path: Option<String>,
+            credits: Credits,
+        }
+
+        let url = self.base(&format!("/movie/{}", tmdb_id));
+        let d: Details = self.get(&url, &[("append_to_response", "credits")]).await?;
+
+        let year: u16 = d
+            .release_date
+            .split('-')
+            .next()
+            .and_then(|y| y.parse().ok())
+            .ok_or_else(|| {
+                DomainError::InfrastructureError(format!(
+                    "Unparseable release_date: {}",
+                    d.release_date
+                ))
+            })?;
+
+        // Prefer IMDB ID; fall back to "tmdb:{id}" so the record is still usable.
+        let raw_id = d
+            .imdb_id
+            .filter(|s| !s.is_empty())
+            .unwrap_or_else(|| format!("tmdb:{}", tmdb_id));
+
+        let imdb_id = ExternalMetadataId::new(raw_id)
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        let title = MovieTitle::new(d.title)
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        let release_year =
+            ReleaseYear::new(year).map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+
+        let director = d
+            .credits
+            .crew
+            .into_iter()
+            .find(|c| c.job == "Director")
+            .map(|c| c.name);
+
+        let poster_url = d.poster_path.as_deref().and_then(|p| self.poster_url(p));
+
+        Ok(ProviderMovie {
+            imdb_id,
+            title,
+            release_year,
+            director,
+            poster_url,
+        })
+    }
+}
+
+#[async_trait]
+impl MetadataProvider for TmdbProvider {
+    async fn fetch(&self, criteria: &MetadataSearchCriteria) -> Result<ProviderMovie, DomainError> {
+        let tmdb_id: u64 = match criteria {
+            MetadataSearchCriteria::ImdbId(id) => {
+                #[derive(Deserialize)]
+                struct FindResult {
+                    id: u64,
+                }
+                #[derive(Deserialize)]
+                struct FindResponse {
+                    movie_results: Vec<FindResult>,
+                }
+                let url = self.base(&format!("/find/{}", id.value()));
+                let resp: FindResponse = self.get(&url, &[("external_source", "imdb_id")]).await?;
+                resp.movie_results
+                    .into_iter()
+                    .next()
+                    .ok_or_else(|| {
+                        DomainError::NotFound(format!("TMDB: no movie for {}", id.value()))
+                    })?
+                    .id
+            }
+            MetadataSearchCriteria::Title { title, year } => {
+                #[derive(Deserialize)]
+                struct SearchResult {
+                    id: u64,
+                }
+                #[derive(Deserialize)]
+                struct SearchResponse {
+                    results: Vec<SearchResult>,
+                }
+                let url = self.base("/search/movie");
+                let mut extra = vec![("query", title.value())];
+                let year_str;
+                if let Some(y) = year {
+                    year_str = y.value().to_string();
+                    extra.push(("year", year_str.as_str()));
+                }
+                let resp: SearchResponse = self.get(&url, &extra).await?;
+                resp.results
+                    .into_iter()
+                    .next()
+                    .ok_or_else(|| {
+                        DomainError::NotFound(format!("TMDB: no results for '{}'", title.value()))
+                    })?
+                    .id
+            }
+        };
+
+        self.fetch_details(tmdb_id).await
+    }
+}

crates/adapters/nats/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "nats"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+async-nats = "0.48.0"
+
+domain = { workspace = true }
+event-payload = { workspace = true }
+async-trait = { workspace = true }
+anyhow = { workspace = true }
+tracing = { workspace = true }
+serde_json = { workspace = true }
+uuid = { workspace = true }
+chrono = { workspace = true }
+tokio = { workspace = true }
+futures = { workspace = true }

crates/adapters/nats/src/config.rs

@@ -0,0 +1,58 @@
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub enum NatsMode {
+    Core,
+    JetStream,
+}
+
+#[derive(Debug, Clone)]
+pub struct NatsConfig {
+    pub url: String,
+    pub mode: NatsMode,
+    pub subject_prefix: String,
+    pub stream_name: String,
+    pub consumer_name: String,
+}
+
+impl NatsConfig {
+    pub fn from_env() -> anyhow::Result<Self> {
+        Self::from_vars(
+            std::env::var("NATS_URL").ok().as_deref(),
+            std::env::var("NATS_MODE").ok().as_deref(),
+            std::env::var("NATS_SUBJECT_PREFIX").ok().as_deref(),
+            std::env::var("NATS_STREAM_NAME").ok().as_deref(),
+            std::env::var("NATS_CONSUMER_NAME").ok().as_deref(),
+        )
+    }
+
+    pub(crate) fn from_vars(
+        url: Option<&str>,
+        mode: Option<&str>,
+        subject_prefix: Option<&str>,
+        stream_name: Option<&str>,
+        consumer_name: Option<&str>,
+    ) -> anyhow::Result<Self> {
+        let url = url.ok_or_else(|| anyhow::anyhow!("NATS_URL is not set"))?;
+
+        let mode = match mode.unwrap_or("jetstream") {
+            "core" => NatsMode::Core,
+            "jetstream" => NatsMode::JetStream,
+            other => anyhow::bail!("unknown NATS_MODE: {other}"),
+        };
+
+        let subject_prefix = subject_prefix.unwrap_or("movies-diary.events").to_string();
+        let stream_name = stream_name.unwrap_or("MOVIES_DIARY_EVENTS").to_string();
+        let consumer_name = consumer_name.unwrap_or("worker").to_string();
+
+        Ok(Self {
+            url: url.to_string(),
+            mode,
+            subject_prefix,
+            stream_name,
+            consumer_name,
+        })
+    }
+}
+
+#[cfg(test)]
+#[path = "tests/config.rs"]
+mod tests;

crates/adapters/nats/src/consumer.rs

@@ -0,0 +1,214 @@
+use async_nats::{
+    Client,
+    jetstream::{self, consumer::pull, message::AckKind, stream::Config as StreamConfig},
+};
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::{AckHandle, DomainEvent, EventEnvelope},
+    ports::EventConsumer,
+};
+use futures::{
+    StreamExt,
+    stream::{self, BoxStream},
+};
+use std::sync::Arc;
+use tokio::sync::{Mutex, mpsc};
+
+use crate::{config::NatsConfig, payload::NatsEventPayload, subject::consumer_subject_filter};
+
+// ── JetStream ack handle ─────────────────────────────────────────────────────
+
+struct NatsJetStreamAckHandle {
+    message: async_nats::jetstream::Message,
+}
+
+#[async_trait]
+impl AckHandle for NatsJetStreamAckHandle {
+    async fn ack(&self) -> Result<(), DomainError> {
+        tracing::debug!(
+            "acknowledging message with sequence {}",
+            self.message.info().unwrap().stream_sequence
+        );
+
+        self.message
+            .ack()
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+
+    async fn nack(&self) -> Result<(), DomainError> {
+        tracing::debug!(
+            "negatively acknowledging message with sequence {}",
+            self.message.info().unwrap().stream_sequence
+        );
+
+        self.message
+            .ack_with(AckKind::Nak(None))
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+}
+
+// ── Core NATS ack handle (no-op) ─────────────────────────────────────────────
+
+struct NoopAck;
+
+#[async_trait]
+impl AckHandle for NoopAck {
+    async fn ack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
+    async fn nack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
+}
+
+// ── Envelope construction helpers ────────────────────────────────────────────
+
+fn decode_js(msg: async_nats::jetstream::Message) -> Result<EventEnvelope, DomainError> {
+    let payload: NatsEventPayload = serde_json::from_slice(&msg.payload)
+        .map_err(|e| DomainError::InfrastructureError(format!("deserialize: {e}")))?;
+    let event = DomainEvent::try_from(payload)?;
+    Ok(EventEnvelope::new(
+        event,
+        Box::new(NatsJetStreamAckHandle { message: msg }),
+    ))
+}
+
+fn decode_core(msg: async_nats::Message) -> Result<EventEnvelope, DomainError> {
+    let payload: NatsEventPayload = serde_json::from_slice(&msg.payload)
+        .map_err(|e| DomainError::InfrastructureError(format!("deserialize: {e}")))?;
+    let event = DomainEvent::try_from(payload)?;
+    Ok(EventEnvelope::new(event, Box::new(NoopAck)))
+}
+
+// ── Channel-bridge shared by both consumers ──────────────────────────────────
+
+type EnvelopeRx = Arc<Mutex<mpsc::Receiver<Result<EventEnvelope, DomainError>>>>;
+
+fn consume_from_rx(rx: EnvelopeRx) -> BoxStream<'static, Result<EventEnvelope, DomainError>> {
+    Box::pin(stream::unfold(rx, |rx| async move {
+        let item = rx.lock().await.recv().await?;
+        Some((item, rx))
+    }))
+}
+
+// ── JetStream consumer ────────────────────────────────────────────────────────
+
+pub struct NatsJetStreamConsumer {
+    rx: EnvelopeRx,
+}
+
+impl NatsJetStreamConsumer {
+    pub async fn create(cfg: &NatsConfig, client: Client) -> anyhow::Result<Self> {
+        let js = jetstream::new(client);
+
+        let stream = js
+            .get_or_create_stream(StreamConfig {
+                name: cfg.stream_name.clone(),
+                subjects: vec![consumer_subject_filter(&cfg.subject_prefix)],
+                max_messages: 100_000,
+                ..Default::default()
+            })
+            .await?;
+
+        let subject_filter = consumer_subject_filter(&cfg.subject_prefix);
+        let consumer = stream
+            .get_or_create_consumer(
+                cfg.consumer_name.as_str(),
+                pull::Config {
+                    durable_name: Some(cfg.consumer_name.clone()),
+                    filter_subject: subject_filter,
+                    ack_wait: std::time::Duration::from_secs(600),
+                    ..Default::default()
+                },
+            )
+            .await?;
+
+        let (tx, rx) = mpsc::channel(128);
+
+        tokio::spawn(async move {
+            loop {
+                let mut messages = match consumer.messages().await {
+                    Err(e) => {
+                        tracing::error!("failed to fetch messages: {}", e);
+
+                        let _ = tx
+                            .send(Err(DomainError::InfrastructureError(e.to_string())))
+                            .await;
+                        return;
+                    }
+                    Ok(m) => m,
+                };
+                while let Some(result) = messages.next().await {
+                    let envelope = result
+                        .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+                        .and_then(decode_js);
+
+                    if tx.send(envelope).await.is_err() {
+                        tracing::info!("consumer channel closed, stopping message processing");
+                        return;
+                    }
+
+                    tracing::debug!("message sent to consumer channel");
+                }
+                // messages() stream ended (fetch expired in strict mode) — restart
+            }
+        });
+
+        Ok(Self {
+            rx: Arc::new(Mutex::new(rx)),
+        })
+    }
+}
+
+impl EventConsumer for NatsJetStreamConsumer {
+    fn consume(&self) -> BoxStream<'_, Result<EventEnvelope, DomainError>> {
+        consume_from_rx(Arc::clone(&self.rx))
+    }
+}
+
+// ── Core NATS consumer ────────────────────────────────────────────────────────
+
+pub struct NatsCoreConsumer {
+    rx: EnvelopeRx,
+}
+
+impl NatsCoreConsumer {
+    pub async fn create(cfg: &NatsConfig, client: Client) -> anyhow::Result<Self> {
+        let subject = consumer_subject_filter(&cfg.subject_prefix);
+        let mut subscriber = client.subscribe(subject).await?;
+
+        let (tx, rx) = mpsc::channel(128);
+
+        tokio::spawn(async move {
+            while let Some(msg) = subscriber.next().await {
+                let envelope = decode_core(msg);
+
+                tracing::debug!("message received and decoded, sending to consumer channel");
+
+                if tx.send(envelope).await.is_err() {
+                    tracing::info!("consumer channel closed, stopping message processing");
+                    break;
+                }
+            }
+        });
+
+        Ok(Self {
+            rx: Arc::new(Mutex::new(rx)),
+        })
+    }
+}
+
+impl EventConsumer for NatsCoreConsumer {
+    fn consume(&self) -> BoxStream<'_, Result<EventEnvelope, DomainError>> {
+        consume_from_rx(Arc::clone(&self.rx))
+    }
+}
+
+fn _assert_send_sync() {
+    fn check<T: Send + Sync>() {}
+    check::<NatsJetStreamConsumer>();
+    check::<NatsCoreConsumer>();
+}

crates/adapters/nats/src/lib.rs

@@ -0,0 +1,52 @@
+mod config;
+mod consumer;
+mod payload;
+mod publisher;
+mod subject;
+
+pub use config::{NatsConfig, NatsMode};
+pub use consumer::{NatsCoreConsumer, NatsJetStreamConsumer};
+pub use publisher::NatsEventPublisher;
+
+use std::sync::Arc;
+
+use domain::ports::{EventConsumer, EventPublisher};
+
+pub async fn create_publisher(cfg: NatsConfig) -> anyhow::Result<Arc<dyn EventPublisher>> {
+    let client = async_nats::connect(&cfg.url).await?;
+    let publisher: Arc<dyn EventPublisher> = match cfg.mode {
+        NatsMode::Core => Arc::new(NatsEventPublisher::new_core(client, cfg.subject_prefix)),
+        NatsMode::JetStream => Arc::new(NatsEventPublisher::new_jetstream(
+            client,
+            cfg.subject_prefix,
+        )),
+    };
+
+    tracing::info!("NATS publisher created (mode: {:?})", cfg.mode);
+    Ok(publisher)
+}
+
+pub async fn create_channel(
+    cfg: NatsConfig,
+) -> anyhow::Result<(Arc<dyn EventPublisher>, Arc<dyn EventConsumer>)> {
+    let client = async_nats::connect(&cfg.url).await?;
+
+    let publisher: Arc<dyn EventPublisher> = match cfg.mode {
+        NatsMode::Core => Arc::new(NatsEventPublisher::new_core(
+            client.clone(),
+            cfg.subject_prefix.clone(),
+        )),
+        NatsMode::JetStream => Arc::new(NatsEventPublisher::new_jetstream(
+            client.clone(),
+            cfg.subject_prefix.clone(),
+        )),
+    };
+
+    let consumer: Arc<dyn EventConsumer> = match cfg.mode {
+        NatsMode::Core => Arc::new(NatsCoreConsumer::create(&cfg, client).await?),
+        NatsMode::JetStream => Arc::new(NatsJetStreamConsumer::create(&cfg, client).await?),
+    };
+
+    tracing::info!("NATS channel created (mode: {:?})", cfg.mode);
+    Ok((publisher, consumer))
+}

crates/adapters/nats/src/payload.rs

@@ -0,0 +1 @@
+pub use event_payload::EventPayload as NatsEventPayload;

crates/adapters/nats/src/publisher.rs

@@ -0,0 +1,60 @@
+use async_nats::{Client, jetstream};
+use async_trait::async_trait;
+use domain::{errors::DomainError, events::DomainEvent, ports::EventPublisher};
+
+use crate::{payload::NatsEventPayload, subject::event_to_subject};
+
+enum PublisherMode {
+    Core(Client),
+    JetStream(jetstream::Context),
+}
+
+pub struct NatsEventPublisher {
+    mode: PublisherMode,
+    subject_prefix: String,
+}
+
+impl NatsEventPublisher {
+    pub fn new_core(client: Client, subject_prefix: String) -> Self {
+        Self {
+            mode: PublisherMode::Core(client),
+            subject_prefix,
+        }
+    }
+
+    pub fn new_jetstream(client: Client, subject_prefix: String) -> Self {
+        Self {
+            mode: PublisherMode::JetStream(jetstream::new(client)),
+            subject_prefix,
+        }
+    }
+}
+
+#[async_trait]
+impl EventPublisher for NatsEventPublisher {
+    async fn publish(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        let subject = event_to_subject(&self.subject_prefix, event);
+        let payload = serde_json::to_vec(&NatsEventPayload::from(event))
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+
+        match &self.mode {
+            PublisherMode::Core(client) => client
+                .publish(subject, payload.into())
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+
+            PublisherMode::JetStream(js) => js
+                .publish(subject, payload.into())
+                .await
+                .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+                .await
+                .map(|_| ())
+                .map_err(|e| DomainError::InfrastructureError(e.to_string())),
+        }
+    }
+}
+
+fn _assert_send_sync() {
+    fn check<T: Send + Sync>() {}
+    check::<NatsEventPublisher>();
+}

crates/adapters/nats/src/subject.rs

@@ -0,0 +1,37 @@
+use domain::events::DomainEvent;
+
+pub fn event_to_subject(prefix: &str, event: &DomainEvent) -> String {
+    let suffix = match event {
+        DomainEvent::ReviewLogged { .. } => "review.logged",
+        DomainEvent::ReviewUpdated { .. } => "review.updated",
+        DomainEvent::ReviewDeleted { .. } => "review.deleted",
+        DomainEvent::MovieDiscovered { .. } => "movie.discovered",
+        DomainEvent::MovieDeleted { .. } => "movie.deleted",
+        DomainEvent::UserUpdated { .. } => "user.updated",
+        DomainEvent::MovieEnrichmentRequested { .. } => "movie.enrichment.requested",
+        DomainEvent::ImageStored { .. } => "image.stored",
+        DomainEvent::WatchlistEntryAdded { .. } => "watchlist.entry.added",
+        DomainEvent::WatchlistEntryRemoved { .. } => "watchlist.entry.removed",
+        DomainEvent::FollowAccepted { .. } => "follow.accepted",
+        DomainEvent::BackfillFollower { .. } => "backfill.follower",
+        DomainEvent::FederationDeliveryRequested { .. } => "federation.delivery.requested",
+        DomainEvent::WatchEventIngested { .. } => "watch.event.ingested",
+        DomainEvent::WrapUpRequested { .. } => "wrapup.requested",
+        DomainEvent::WrapUpCompleted { .. } => "wrapup.completed",
+        DomainEvent::SearchReindexRequested => "search.reindex.requested",
+        DomainEvent::PosterSynced { .. } => "poster.synced",
+        DomainEvent::GoalCreated { .. } => "goal.created",
+        DomainEvent::GoalUpdated { .. } => "goal.updated",
+        DomainEvent::GoalDeleted { .. } => "goal.deleted",
+        DomainEvent::PersonEnrichmentRequested { .. } => "person.enrichment.requested",
+    };
+    format!("{prefix}.{suffix}")
+}
+
+pub fn consumer_subject_filter(prefix: &str) -> String {
+    format!("{prefix}.>")
+}
+
+#[cfg(test)]
+#[path = "tests/subject.rs"]
+mod tests;

crates/adapters/nats/src/tests/config.rs

@@ -0,0 +1,30 @@
+use super::*;
+
+#[test]
+fn errors_without_nats_url() {
+    assert!(NatsConfig::from_vars(None, None, None, None, None).is_err());
+}
+
+#[test]
+fn defaults_with_only_url() {
+    let cfg = NatsConfig::from_vars(Some("nats://localhost:4222"), None, None, None, None).unwrap();
+    assert_eq!(cfg.url, "nats://localhost:4222");
+    assert_eq!(cfg.mode, NatsMode::JetStream);
+    assert_eq!(cfg.subject_prefix, "movies-diary.events");
+    assert_eq!(cfg.stream_name, "MOVIES_DIARY_EVENTS");
+    assert_eq!(cfg.consumer_name, "worker");
+}
+
+#[test]
+fn core_mode_parsed() {
+    let cfg =
+        NatsConfig::from_vars(Some("nats://test:4222"), Some("core"), None, None, None).unwrap();
+    assert_eq!(cfg.mode, NatsMode::Core);
+}
+
+#[test]
+fn invalid_mode_errors() {
+    assert!(
+        NatsConfig::from_vars(Some("nats://test:4222"), Some("kafka"), None, None, None).is_err()
+    );
+}

crates/adapters/nats/src/tests/subject.rs

@@ -0,0 +1,60 @@
+use super::*;
+use chrono::NaiveDateTime;
+use domain::value_objects::{ExternalMetadataId, MovieId, Rating, ReviewId, UserId};
+use uuid::Uuid;
+
+fn dt() -> NaiveDateTime {
+    chrono::DateTime::from_timestamp(1_700_000_000, 0)
+        .unwrap()
+        .naive_utc()
+}
+
+#[test]
+fn review_logged_subject() {
+    let event = DomainEvent::ReviewLogged {
+        review_id: ReviewId::from_uuid(Uuid::new_v4()),
+        movie_id: MovieId::from_uuid(Uuid::new_v4()),
+        user_id: UserId::from_uuid(Uuid::new_v4()),
+        rating: Rating::new(3).unwrap(),
+        watched_at: dt(),
+    };
+    assert_eq!(
+        event_to_subject("movies-diary.events", &event),
+        "movies-diary.events.review.logged"
+    );
+}
+
+#[test]
+fn review_updated_subject() {
+    let event = DomainEvent::ReviewUpdated {
+        review_id: ReviewId::from_uuid(Uuid::new_v4()),
+        movie_id: MovieId::from_uuid(Uuid::new_v4()),
+        user_id: UserId::from_uuid(Uuid::new_v4()),
+        rating: Rating::new(5).unwrap(),
+        watched_at: dt(),
+    };
+    assert_eq!(
+        event_to_subject("movies-diary.events", &event),
+        "movies-diary.events.review.updated"
+    );
+}
+
+#[test]
+fn movie_discovered_subject() {
+    let event = DomainEvent::MovieDiscovered {
+        movie_id: MovieId::from_uuid(Uuid::new_v4()),
+        external_metadata_id: ExternalMetadataId::new("tt0000001".into()).unwrap(),
+    };
+    assert_eq!(
+        event_to_subject("movies-diary.events", &event),
+        "movies-diary.events.movie.discovered"
+    );
+}
+
+#[test]
+fn consumer_subject_filter_appends_wildcard() {
+    assert_eq!(
+        consumer_subject_filter("movies-diary.events"),
+        "movies-diary.events.>"
+    );
+}

crates/adapters/object-storage/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "object-storage"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain = { workspace = true }
+anyhow = { workspace = true }
+async-trait = { workspace = true }
+tracing = { workspace = true }
+bytes = { workspace = true }
+futures = { workspace = true }
+object_store = { workspace = true }
+infer = "0.19.0"
+
+[dev-dependencies]
+tokio = { workspace = true }
+uuid = { workspace = true }

crates/adapters/object-storage/src/config.rs

@@ -0,0 +1,64 @@
+use anyhow::Context;
+use object_store::{ObjectStore, aws::AmazonS3Builder, local::LocalFileSystem};
+use std::sync::Arc;
+
+pub struct StorageConfig(Arc<dyn ObjectStore>);
+
+impl StorageConfig {
+    pub fn from_env() -> anyhow::Result<Self> {
+        let backend = std::env::var("IMAGE_STORAGE_BACKEND").unwrap_or_else(|_| "local".into());
+
+        let store: Arc<dyn ObjectStore> = match backend.as_str() {
+            "s3" => build_s3_store(
+                &std::env::var("MINIO_ENDPOINT").context("MINIO_ENDPOINT required")?,
+                &std::env::var("MINIO_ACCESS_KEY_ID").context("MINIO_ACCESS_KEY_ID required")?,
+                &std::env::var("MINIO_SECRET_ACCESS_KEY")
+                    .context("MINIO_SECRET_ACCESS_KEY required")?,
+                &std::env::var("MINIO_BUCKET").context("MINIO_BUCKET required")?,
+                &std::env::var("MINIO_REGION").unwrap_or_else(|_| "minio".to_string()),
+            )?,
+            "local" => build_local_store(
+                &std::env::var("IMAGE_STORAGE_PATH").unwrap_or_else(|_| "./images".into()),
+            )?,
+            other => {
+                anyhow::bail!("Unknown IMAGE_STORAGE_BACKEND: {other:?}. Valid values: s3, local")
+            }
+        };
+
+        Ok(Self(store))
+    }
+
+    pub fn build_store(self) -> Arc<dyn ObjectStore> {
+        self.0
+    }
+}
+
+fn build_s3_store(
+    endpoint: &str,
+    access_key_id: &str,
+    secret_access_key: &str,
+    bucket: &str,
+    region: &str,
+) -> anyhow::Result<Arc<dyn ObjectStore>> {
+    let store = AmazonS3Builder::new()
+        .with_endpoint(endpoint)
+        .with_access_key_id(access_key_id)
+        .with_secret_access_key(secret_access_key)
+        .with_bucket_name(bucket)
+        .with_region(region)
+        .with_allow_http(true)
+        .build()
+        .context("Failed to build S3/Minio store")?;
+    Ok(Arc::new(store))
+}
+
+fn build_local_store(path: &str) -> anyhow::Result<Arc<dyn ObjectStore>> {
+    std::fs::create_dir_all(path).context("Failed to create image storage directory")?;
+    let store = LocalFileSystem::new_with_prefix(path)
+        .context("Failed to initialise local file system store")?;
+    Ok(Arc::new(store))
+}
+
+#[cfg(test)]
+#[path = "tests/config.rs"]
+mod tests;

crates/adapters/object-storage/src/lib.rs

@@ -0,0 +1,139 @@
+mod config;
+pub use config::StorageConfig;
+
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::DomainEvent,
+    ports::{EventHandler, ObjectStorage},
+};
+use futures::StreamExt;
+use object_store::{ObjectStore, path::Path};
+use std::sync::Arc;
+
+pub struct ObjectStorageAdapter {
+    store: Arc<dyn ObjectStore>,
+}
+
+impl ObjectStorageAdapter {
+    pub fn new(store: Arc<dyn ObjectStore>) -> Self {
+        Self { store }
+    }
+
+    pub fn from_config(config: StorageConfig) -> Self {
+        Self::new(config.build_store())
+    }
+
+    async fn get_exact(&self, key: &str) -> Result<Vec<u8>, DomainError> {
+        let path = Path::from(key);
+        let result = self.store.get(&path).await.map_err(|e| match e {
+            object_store::Error::NotFound { .. } => DomainError::NotFound("Image not found".into()),
+            _ => DomainError::InfrastructureError(e.to_string()),
+        })?;
+        result
+            .bytes()
+            .await
+            .map(|b| b.to_vec())
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+    }
+}
+
+#[async_trait]
+impl ObjectStorage for ObjectStorageAdapter {
+    async fn store(&self, key: &str, image_bytes: &[u8]) -> Result<String, DomainError> {
+        let path = Path::from(key);
+        self.store
+            .put(&path, image_bytes.to_vec().into())
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        Ok(key.to_string())
+    }
+
+    async fn get(&self, key: &str) -> Result<Vec<u8>, DomainError> {
+        match self.get_exact(key).await {
+            Ok(bytes) => return Ok(bytes),
+            Err(DomainError::NotFound(_)) if !has_image_ext(key) => {}
+            Err(e) => return Err(e),
+        }
+        // Key may reference a pre-conversion path; try converted extensions.
+        for ext in [".webp", ".avif"] {
+            let candidate = format!("{key}{ext}");
+            if let Ok(bytes) = self.get_exact(&candidate).await {
+                return Ok(bytes);
+            }
+        }
+        Err(DomainError::NotFound("Image not found".into()))
+    }
+
+    async fn get_stream(
+        &self,
+        key: &str,
+    ) -> Result<futures::stream::BoxStream<'static, Result<bytes::Bytes, DomainError>>, DomainError>
+    {
+        let path = Path::from(key);
+        let result = self.store.get(&path).await.map_err(|e| match e {
+            object_store::Error::NotFound { .. } => DomainError::NotFound("not found".into()),
+            _ => DomainError::InfrastructureError(e.to_string()),
+        })?;
+        let stream = result.into_stream().map(|chunk| {
+            chunk
+                .map(|b| bytes::Bytes::from(b.to_vec()))
+                .map_err(|e| DomainError::InfrastructureError(e.to_string()))
+        });
+        Ok(Box::pin(stream))
+    }
+
+    async fn delete(&self, key: &str) -> Result<(), DomainError> {
+        let path = Path::from(key);
+        match self.store.delete(&path).await {
+            Ok(()) => Ok(()),
+            Err(object_store::Error::NotFound { .. }) => Ok(()),
+            Err(e) => Err(DomainError::InfrastructureError(e.to_string())),
+        }
+    }
+}
+
+fn has_image_ext(key: &str) -> bool {
+    key.ends_with(".webp")
+        || key.ends_with(".avif")
+        || key.ends_with(".png")
+        || key.ends_with(".jpg")
+        || key.ends_with(".jpeg")
+}
+
+pub struct ImageCleanupHandler {
+    object_storage: Arc<dyn ObjectStorage>,
+}
+
+impl ImageCleanupHandler {
+    pub fn new(object_storage: Arc<dyn ObjectStorage>) -> Self {
+        Self { object_storage }
+    }
+}
+
+#[async_trait]
+impl EventHandler for ImageCleanupHandler {
+    async fn handle(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        let poster_path = match event {
+            DomainEvent::MovieDeleted { poster_path, .. } => poster_path,
+            _ => return Ok(()),
+        };
+        let Some(path) = poster_path else {
+            return Ok(());
+        };
+        if let Err(e) = self.object_storage.delete(path.value()).await {
+            tracing::warn!("image cleanup failed for {}: {e}", path.value());
+        }
+        Ok(())
+    }
+}
+
+pub fn create() -> anyhow::Result<Arc<dyn ObjectStorage>> {
+    Ok(Arc::new(ObjectStorageAdapter::from_config(
+        StorageConfig::from_env()?,
+    )))
+}
+
+#[cfg(test)]
+#[path = "tests/lib.rs"]
+mod tests;

crates/adapters/object-storage/src/tests/config.rs

@@ -0,0 +1,17 @@
+use super::*;
+
+#[test]
+fn local_store_creates_dir_and_succeeds() {
+    let dir = std::env::temp_dir().join(format!("image_test_{}", uuid::Uuid::new_v4()));
+    let result = build_local_store(dir.to_str().unwrap());
+    assert!(result.is_ok(), "expected Ok, got: {:?}", result.err());
+    assert!(dir.exists(), "directory should have been created");
+}
+
+#[test]
+fn local_store_succeeds_if_dir_already_exists() {
+    let dir = std::env::temp_dir().join(format!("image_test_{}", uuid::Uuid::new_v4()));
+    std::fs::create_dir_all(&dir).unwrap();
+    let result = build_local_store(dir.to_str().unwrap());
+    assert!(result.is_ok());
+}

crates/adapters/object-storage/src/tests/lib.rs

@@ -0,0 +1,61 @@
+use super::*;
+use object_store::memory::InMemory;
+
+fn adapter() -> ObjectStorageAdapter {
+    ObjectStorageAdapter::new(Arc::new(InMemory::new()))
+}
+
+#[tokio::test]
+async fn store_and_retrieve_round_trip() {
+    let adapter = adapter();
+    let bytes = b"fake-image-bytes";
+    let path = adapter.store("posters/abc123", bytes).await.unwrap();
+    assert_eq!(path, "posters/abc123");
+    let retrieved = adapter.get("posters/abc123").await.unwrap();
+    assert_eq!(retrieved, bytes);
+}
+
+#[tokio::test]
+async fn get_missing_returns_not_found() {
+    let adapter = adapter();
+    let result = adapter.get("nonexistent").await;
+    assert!(matches!(result, Err(DomainError::NotFound(_))));
+}
+
+#[tokio::test]
+async fn delete_removes_key() {
+    let adapter = adapter();
+    adapter.store("avatars/user1", b"img").await.unwrap();
+    adapter.delete("avatars/user1").await.unwrap();
+    let result = adapter.get("avatars/user1").await;
+    assert!(matches!(result, Err(DomainError::NotFound(_))));
+}
+
+#[tokio::test]
+async fn delete_missing_returns_ok() {
+    let adapter = adapter();
+    assert!(adapter.delete("does-not-exist").await.is_ok());
+}
+
+#[tokio::test]
+async fn cleanup_handler_deletes_on_movie_deleted() {
+    use domain::{
+        events::DomainEvent,
+        value_objects::{MovieId, PosterPath},
+    };
+    let inner = Arc::new(adapter());
+    inner.store("some-uuid", b"img").await.unwrap();
+    let path = PosterPath::new("some-uuid".to_string()).unwrap();
+    let handler = ImageCleanupHandler::new(Arc::clone(&inner) as Arc<dyn ObjectStorage>);
+    handler
+        .handle(&DomainEvent::MovieDeleted {
+            movie_id: MovieId::from_uuid(uuid::Uuid::new_v4()),
+            poster_path: Some(path.clone()),
+        })
+        .await
+        .unwrap();
+    assert!(matches!(
+        inner.get("some-uuid").await,
+        Err(DomainError::NotFound(_))
+    ));
+}

crates/adapters/plex/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "plex"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }

crates/adapters/plex/src/lib.rs

@@ -0,0 +1,172 @@
+use domain::{errors::DomainError, models::ParsedPlaybackEvent, ports::MediaServerParser};
+use serde::Deserialize;
+
+pub struct PlexParser;
+
+impl MediaServerParser for PlexParser {
+    /// Plex sends multipart form data with a `payload` JSON field.
+    /// The caller must extract the JSON string from the multipart body
+    /// and pass it here as raw bytes.
+    fn parse_playback_event(
+        &self,
+        body: &[u8],
+    ) -> Result<Option<ParsedPlaybackEvent>, DomainError> {
+        let payload: PlexPayload = serde_json::from_slice(body)
+            .map_err(|e| DomainError::ValidationError(format!("invalid Plex payload: {e}")))?;
+
+        if payload.event != "media.scrobble" {
+            return Ok(None);
+        }
+
+        let metadata = match payload.metadata {
+            Some(m) => m,
+            None => return Ok(None),
+        };
+
+        if metadata.media_type != "movie" {
+            return Ok(None);
+        }
+
+        if metadata.title.is_empty() {
+            return Ok(None);
+        }
+
+        let mut tmdb_id = None;
+        let mut imdb_id = None;
+        for guid in &metadata.guids {
+            if let Some(id) = guid.id.strip_prefix("tmdb://") {
+                tmdb_id = Some(format!("tmdb:{id}"));
+            } else if let Some(id) = guid.id.strip_prefix("imdb://") {
+                imdb_id = Some(id.to_string());
+            }
+        }
+
+        Ok(Some(ParsedPlaybackEvent {
+            title: metadata.title,
+            year: metadata.year.map(|y| y as u16),
+            tmdb_id,
+            imdb_id,
+        }))
+    }
+}
+
+#[derive(Deserialize)]
+struct PlexPayload {
+    event: String,
+    #[serde(rename = "Metadata")]
+    metadata: Option<PlexMetadata>,
+}
+
+#[derive(Deserialize)]
+struct PlexMetadata {
+    #[serde(rename = "type")]
+    media_type: String,
+    title: String,
+    year: Option<i32>,
+    #[serde(rename = "Guid", default)]
+    guids: Vec<PlexGuid>,
+}
+
+#[derive(Deserialize)]
+struct PlexGuid {
+    id: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_movie_scrobble() {
+        let body = serde_json::json!({
+            "event": "media.scrobble",
+            "Metadata": {
+                "type": "movie",
+                "title": "Blade Runner",
+                "year": 1982,
+                "Guid": [
+                    {"id": "tmdb://78"},
+                    {"id": "imdb://tt0083658"}
+                ]
+            }
+        });
+        let parser = PlexParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        let event = result.expect("should parse");
+        assert_eq!(event.title, "Blade Runner");
+        assert_eq!(event.year, Some(1982));
+        assert_eq!(event.tmdb_id, Some("tmdb:78".into()));
+        assert_eq!(event.imdb_id, Some("tt0083658".into()));
+    }
+
+    #[test]
+    fn ignores_tv_episode() {
+        let body = serde_json::json!({
+            "event": "media.scrobble",
+            "Metadata": {
+                "type": "episode",
+                "title": "Pilot",
+                "grandparentTitle": "Breaking Bad",
+                "year": 2008,
+                "Guid": []
+            }
+        });
+        let parser = PlexParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn ignores_play_event() {
+        let body = serde_json::json!({
+            "event": "media.play",
+            "Metadata": {
+                "type": "movie",
+                "title": "Blade Runner",
+                "year": 1982,
+                "Guid": []
+            }
+        });
+        let parser = PlexParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn handles_no_guids() {
+        let body = serde_json::json!({
+            "event": "media.scrobble",
+            "Metadata": {
+                "type": "movie",
+                "title": "Some Indie Film",
+                "year": 2023
+            }
+        });
+        let parser = PlexParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        let event = result.expect("should parse");
+        assert_eq!(event.title, "Some Indie Film");
+        assert!(event.tmdb_id.is_none());
+        assert!(event.imdb_id.is_none());
+    }
+
+    #[test]
+    fn handles_missing_metadata() {
+        let body = serde_json::json!({
+            "event": "media.scrobble"
+        });
+        let parser = PlexParser;
+        let result = parser
+            .parse_playback_event(serde_json::to_vec(&body).unwrap().as_slice())
+            .unwrap();
+        assert!(result.is_none());
+    }
+}

crates/adapters/poster-fetcher/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "poster-fetcher"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+domain = { workspace = true }
+async-trait = { workspace = true }
+reqwest = { workspace = true }
+anyhow = { workspace = true }

crates/adapters/poster-fetcher/src/config.rs

@@ -0,0 +1,13 @@
+pub struct PosterFetcherConfig {
+    pub timeout_seconds: u64,
+}
+
+impl PosterFetcherConfig {
+    pub fn from_env() -> Self {
+        let timeout_seconds = std::env::var("POSTER_FETCH_TIMEOUT_SECONDS")
+            .ok()
+            .and_then(|v| v.parse().ok())
+            .unwrap_or(30);
+        Self { timeout_seconds }
+    }
+}

crates/adapters/poster-fetcher/src/lib.rs

@@ -0,0 +1,44 @@
+mod config;
+pub use config::PosterFetcherConfig;
+
+use std::time::Duration;
+
+use async_trait::async_trait;
+use domain::{errors::DomainError, ports::PosterFetcherClient, value_objects::PosterUrl};
+
+pub struct ReqwestPosterFetcher {
+    client: reqwest::Client,
+}
+
+impl ReqwestPosterFetcher {
+    pub fn new(config: PosterFetcherConfig) -> anyhow::Result<Self> {
+        let client = reqwest::Client::builder()
+            .timeout(Duration::from_secs(config.timeout_seconds))
+            .build()?;
+        Ok(Self { client })
+    }
+}
+
+#[async_trait]
+impl PosterFetcherClient for ReqwestPosterFetcher {
+    async fn fetch_poster_bytes(&self, poster_url: &PosterUrl) -> Result<Vec<u8>, DomainError> {
+        let bytes = self
+            .client
+            .get(poster_url.value())
+            .send()
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+            .error_for_status()
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?
+            .bytes()
+            .await
+            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+        Ok(bytes.to_vec())
+    }
+}
+
+pub fn create() -> anyhow::Result<std::sync::Arc<dyn domain::ports::PosterFetcherClient>> {
+    Ok(std::sync::Arc::new(ReqwestPosterFetcher::new(
+        PosterFetcherConfig::from_env(),
+    )?))
+}

crates/adapters/poster-sync/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "poster-sync"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+domain = { workspace = true }
+async-trait = { workspace = true }
+tracing = { workspace = true }
+tokio = { workspace = true }

crates/adapters/poster-sync/src/lib.rs

@@ -0,0 +1,164 @@
+use std::{sync::Arc, time::Duration};
+
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::DomainEvent,
+    ports::{
+        EventHandler, EventPublisher, MetadataClient, MovieRepository, ObjectStorage,
+        PosterFetcherClient,
+    },
+    value_objects::{ExternalMetadataId, MovieId, PosterPath},
+};
+
+pub struct PosterSyncHandler {
+    movie_repository: Arc<dyn MovieRepository>,
+    metadata_client: Arc<dyn MetadataClient>,
+    poster_fetcher: Arc<dyn PosterFetcherClient>,
+    object_storage: Arc<dyn ObjectStorage>,
+    event_publisher: Arc<dyn EventPublisher>,
+    max_retries: u32,
+}
+
+impl PosterSyncHandler {
+    pub fn new(
+        movie_repository: Arc<dyn MovieRepository>,
+        metadata_client: Arc<dyn MetadataClient>,
+        poster_fetcher: Arc<dyn PosterFetcherClient>,
+        object_storage: Arc<dyn ObjectStorage>,
+        event_publisher: Arc<dyn EventPublisher>,
+        max_retries: u32,
+    ) -> Self {
+        Self {
+            movie_repository,
+            metadata_client,
+            poster_fetcher,
+            object_storage,
+            event_publisher,
+            max_retries,
+        }
+    }
+
+    async fn sync(
+        &self,
+        movie_id: MovieId,
+        external_metadata_id: ExternalMetadataId,
+    ) -> Result<(), DomainError> {
+        let mut movie = match self.movie_repository.get_movie_by_id(&movie_id).await? {
+            Some(m) => m,
+            None => {
+                tracing::warn!("Sync cancelled: Movie {} not found", movie_id.value());
+                return Err(DomainError::NotFound("Movie not found".into()));
+            }
+        };
+
+        let poster_url = match self
+            .metadata_client
+            .get_poster_url(&external_metadata_id)
+            .await
+        {
+            Ok(Some(url)) => url,
+            Ok(None) => return Ok(()),
+            Err(e) => {
+                tracing::warn!("Failed to find poster URL: {:?}", e);
+                return Err(e);
+            }
+        };
+
+        let image_bytes = self.poster_fetcher.fetch_poster_bytes(&poster_url).await?;
+        let stored_path = self
+            .object_storage
+            .store(&movie_id.value().to_string(), &image_bytes)
+            .await?;
+        if let Err(e) = self
+            .event_publisher
+            .publish(&DomainEvent::ImageStored {
+                key: stored_path.clone(),
+            })
+            .await
+        {
+            tracing::warn!("failed to emit ImageStored for {stored_path}: {e}");
+        }
+        let poster_path = PosterPath::new(stored_path)?;
+
+        movie.update_poster(poster_path);
+        self.movie_repository.upsert_movie(&movie).await?;
+
+        if let Err(e) = self
+            .event_publisher
+            .publish(&DomainEvent::PosterSynced {
+                movie_id: movie.id().clone(),
+            })
+            .await
+        {
+            tracing::warn!(
+                "failed to emit PosterSynced for {}: {e}",
+                movie.id().value()
+            );
+        }
+
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl EventHandler for PosterSyncHandler {
+    async fn handle(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        let (movie_id, external_metadata_id) = match event {
+            DomainEvent::MovieDiscovered {
+                movie_id,
+                external_metadata_id,
+            } => (movie_id.value(), external_metadata_id.value().to_owned()),
+            DomainEvent::MovieEnrichmentRequested {
+                movie_id,
+                external_metadata_id,
+            } => {
+                // Only sync poster if the movie doesn't have one yet
+                let already_has_poster = self
+                    .movie_repository
+                    .get_movie_by_id(&MovieId::from_uuid(movie_id.value()))
+                    .await?
+                    .map(|m| m.poster_path().is_some())
+                    .unwrap_or(false);
+                if already_has_poster {
+                    return Ok(());
+                }
+                (movie_id.value(), external_metadata_id.value().to_owned())
+            }
+            _ => return Ok(()),
+        };
+
+        let movie_id = MovieId::from_uuid(movie_id);
+        let external_metadata_id = ExternalMetadataId::new(external_metadata_id)?;
+
+        let mut last_err: Option<DomainError> = None;
+        for attempt in 0..=self.max_retries {
+            match self
+                .sync(movie_id.clone(), external_metadata_id.clone())
+                .await
+            {
+                Ok(()) => return Ok(()),
+                Err(e) => {
+                    if attempt < self.max_retries {
+                        let delay = Duration::from_secs(2u64.pow(attempt));
+                        tracing::warn!(
+                            attempt = attempt + 1,
+                            max_attempts = self.max_retries + 1,
+                            delay_secs = delay.as_secs(),
+                            "poster sync failed, retrying: {e}"
+                        );
+                        tokio::time::sleep(delay).await;
+                    }
+                    last_err = Some(e);
+                }
+            }
+        }
+
+        let err = last_err.expect("loop runs at least once");
+        tracing::error!(
+            attempts = self.max_retries + 1,
+            "poster sync failed after all attempts: {err}"
+        );
+        Err(err)
+    }
+}

crates/adapters/postgres-event-queue/Cargo.toml

@@ -0,0 +1,15 @@
+[package]
+name = "postgres-event-queue"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+sqlx        = { version = "0.8.6", features = ["runtime-tokio-rustls", "postgres", "macros", "chrono"] }
+domain      = { workspace = true }
+event-payload = { workspace = true }
+anyhow      = { workspace = true }
+async-trait = { workspace = true }
+serde_json  = { workspace = true }
+tokio       = { workspace = true }
+futures     = { workspace = true }
+tracing     = { workspace = true }

crates/adapters/postgres-event-queue/migrations/0100_event_queue.sql

@@ -0,0 +1,13 @@
+CREATE TABLE IF NOT EXISTS event_queue (
+    id              BIGSERIAL    PRIMARY KEY,
+    event_type      TEXT         NOT NULL,
+    payload         TEXT         NOT NULL,
+    status          TEXT         NOT NULL DEFAULT 'pending',
+    attempts        INTEGER      NOT NULL DEFAULT 0,
+    created_at      TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+    next_attempt_at TIMESTAMPTZ  NOT NULL DEFAULT NOW(),
+    last_error      TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_event_queue_poll
+    ON event_queue (status, next_attempt_at);

crates/adapters/postgres-event-queue/src/lib.rs

@@ -0,0 +1,235 @@
+mod migrations;
+mod payload;
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    events::{AckHandle, DomainEvent, EventEnvelope},
+    ports::{EventConsumer, EventPublisher},
+};
+use futures::stream::{self, BoxStream};
+use sqlx::PgPool;
+use tokio::sync::{Mutex, mpsc};
+
+use payload::DbEventPayload;
+
+pub struct DbEventQueueConfig {
+    pub poll_interval_ms: u64,
+    pub batch_size: i64,
+    pub max_attempts: i32,
+}
+
+impl DbEventQueueConfig {
+    pub fn from_env() -> Self {
+        Self {
+            poll_interval_ms: std::env::var("EVENT_QUEUE_POLL_INTERVAL_MS")
+                .ok()
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(500),
+            batch_size: std::env::var("EVENT_QUEUE_BATCH_SIZE")
+                .ok()
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(10),
+            max_attempts: std::env::var("EVENT_QUEUE_MAX_ATTEMPTS")
+                .ok()
+                .and_then(|v| v.parse().ok())
+                .unwrap_or(5),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub struct PostgresEventQueue {
+    pool: PgPool,
+    config: Arc<DbEventQueueConfig>,
+}
+
+impl PostgresEventQueue {
+    pub async fn create(pool: PgPool, config: DbEventQueueConfig) -> anyhow::Result<Self> {
+        migrations::run(&pool).await?;
+        Ok(Self {
+            pool,
+            config: Arc::new(config),
+        })
+    }
+
+    pub async fn create_publisher(pool: PgPool) -> anyhow::Result<Arc<dyn EventPublisher>> {
+        let q = Self::create(pool, DbEventQueueConfig::from_env()).await?;
+        Ok(Arc::new(q))
+    }
+
+    pub async fn create_channel(
+        pool: PgPool,
+    ) -> anyhow::Result<(Arc<dyn EventPublisher>, Arc<dyn EventConsumer>)> {
+        let q = Self::create(pool, DbEventQueueConfig::from_env()).await?;
+        Ok((Arc::new(q.clone()), Arc::new(q)))
+    }
+}
+
+#[async_trait]
+impl EventPublisher for PostgresEventQueue {
+    async fn publish(&self, event: &DomainEvent) -> Result<(), DomainError> {
+        let db_payload = DbEventPayload::from(event);
+        let event_type = db_payload.event_type();
+        let payload_json = serde_json::to_string(&db_payload)
+            .map_err(|e| DomainError::InfrastructureError(format!("serialize: {e}")))?;
+
+        sqlx::query("INSERT INTO event_queue (event_type, payload) VALUES ($1, $2)")
+            .bind(event_type)
+            .bind(payload_json)
+            .execute(&self.pool)
+            .await
+            .map_err(|e| DomainError::InfrastructureError(format!("insert event: {e}")))?;
+
+        Ok(())
+    }
+}
+
+impl EventConsumer for PostgresEventQueue {
+    fn consume(&self) -> BoxStream<'_, Result<EventEnvelope, DomainError>> {
+        let pool = self.pool.clone();
+        let config = Arc::clone(&self.config);
+        let (tx, rx) = mpsc::channel(128);
+        let rx = Arc::new(Mutex::new(rx));
+
+        tokio::spawn(async move {
+            let poll_interval = Duration::from_millis(config.poll_interval_ms);
+            loop {
+                match claim_batch(&pool, &config).await {
+                    Err(e) => {
+                        tracing::error!("postgres event queue claim error: {e}");
+                        tokio::time::sleep(poll_interval).await;
+                    }
+                    Ok(rows) if rows.is_empty() => {
+                        tokio::time::sleep(poll_interval).await;
+                    }
+                    Ok(rows) => {
+                        for row in rows {
+                            let envelope = decode_row(&pool, row, config.max_attempts);
+                            if tx.send(envelope).await.is_err() {
+                                tracing::info!("postgres event queue consumer closed");
+                                return;
+                            }
+                        }
+                        // no sleep — re-poll immediately when batch was non-empty
+                    }
+                }
+            }
+        });
+
+        Box::pin(stream::unfold(rx, |rx| async move {
+            let item = rx.lock().await.recv().await?;
+            Some((item, rx))
+        }))
+    }
+}
+
+// ── Internal types ────────────────────────────────────────────────────────────
+
+#[derive(sqlx::FromRow)]
+struct QueueRow {
+    id: i64,
+    payload: String,
+    attempts: i32,
+}
+
+async fn claim_batch(
+    pool: &PgPool,
+    config: &DbEventQueueConfig,
+) -> Result<Vec<QueueRow>, DomainError> {
+    // CTE with FOR UPDATE SKIP LOCKED — atomic and safe for multiple workers
+    let rows = sqlx::query_as::<_, QueueRow>(
+        r#"
+        WITH claimed AS (
+            SELECT id FROM event_queue
+            WHERE status = 'pending' AND next_attempt_at <= NOW()
+            ORDER BY next_attempt_at ASC
+            LIMIT $1
+            FOR UPDATE SKIP LOCKED
+        )
+        UPDATE event_queue q
+           SET status = 'processing'
+          FROM claimed
+         WHERE q.id = claimed.id
+        RETURNING q.id, q.payload, q.attempts
+        "#,
+    )
+    .bind(config.batch_size)
+    .fetch_all(pool)
+    .await
+    .map_err(|e| DomainError::InfrastructureError(format!("claim batch: {e}")))?;
+
+    Ok(rows)
+}
+
+fn decode_row(
+    pool: &PgPool,
+    row: QueueRow,
+    max_attempts: i32,
+) -> Result<EventEnvelope, DomainError> {
+    let db_payload: DbEventPayload = serde_json::from_str(&row.payload)
+        .map_err(|e| DomainError::InfrastructureError(format!("deserialize: {e}")))?;
+    let event = DomainEvent::try_from(db_payload)?;
+    Ok(EventEnvelope::new(
+        event,
+        Box::new(DbAckHandle {
+            pool: pool.clone(),
+            row_id: row.id,
+            attempts: row.attempts,
+            max_attempts,
+        }),
+    ))
+}
+
+struct DbAckHandle {
+    pool: PgPool,
+    row_id: i64,
+    attempts: i32,
+    max_attempts: i32,
+}
+
+#[async_trait]
+impl AckHandle for DbAckHandle {
+    async fn ack(&self) -> Result<(), DomainError> {
+        sqlx::query("UPDATE event_queue SET status = 'done' WHERE id = $1")
+            .bind(self.row_id)
+            .execute(&self.pool)
+            .await
+            .map_err(|e| DomainError::InfrastructureError(format!("ack: {e}")))?;
+        Ok(())
+    }
+
+    async fn nack(&self) -> Result<(), DomainError> {
+        let new_attempts = self.attempts + 1;
+        if new_attempts >= self.max_attempts {
+            sqlx::query(
+                "UPDATE event_queue SET status = 'dead_lettered', attempts = $1, last_error = 'max attempts reached' WHERE id = $2"
+            )
+            .bind(new_attempts)
+            .bind(self.row_id)
+            .execute(&self.pool)
+            .await
+            .map_err(|e| DomainError::InfrastructureError(format!("nack dead-letter: {e}")))?;
+        } else {
+            let backoff = backoff_seconds(new_attempts).to_string();
+            sqlx::query(
+                "UPDATE event_queue SET status = 'pending', attempts = $1, next_attempt_at = NOW() + ($2 || ' seconds')::interval, last_error = 'nack' WHERE id = $3"
+            )
+            .bind(new_attempts)
+            .bind(backoff)
+            .bind(self.row_id)
+            .execute(&self.pool)
+            .await
+            .map_err(|e| DomainError::InfrastructureError(format!("nack retry: {e}")))?;
+        }
+        Ok(())
+    }
+}
+
+fn backoff_seconds(attempts: i32) -> i64 {
+    let base: i64 = 5 * (1i64 << attempts.min(6));
+    base.min(300)
+}

crates/adapters/postgres-event-queue/src/migrations.rs

@@ -0,0 +1,7 @@
+pub(crate) async fn run(pool: &sqlx::PgPool) -> anyhow::Result<()> {
+    sqlx::migrate!("./migrations")
+        .set_ignore_missing(true)
+        .run(pool)
+        .await
+        .map_err(|e| anyhow::anyhow!("postgres-event-queue migration failed: {e}"))
+}

crates/adapters/postgres-event-queue/src/payload.rs

@@ -0,0 +1 @@
+pub use event_payload::EventPayload as DbEventPayload;

crates/adapters/postgres-federation/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "postgres-federation"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+sqlx = { version = "0.8.6", features = [
+    "runtime-tokio-rustls",
+    "postgres",
+    "uuid",
+    "macros",
+    "chrono",
+] }
+activitypub = { workspace = true }
+k-ap = { version = "0.4.0", registry = "gitea" }
+domain = { workspace = true }
+uuid = { workspace = true }
+chrono = { workspace = true }
+tracing = { workspace = true }
+async-trait = { workspace = true }
+anyhow = { workspace = true }
+serde_json = { workspace = true }

crates/adapters/postgres-federation/src/lib.rs

@@ -0,0 +1,939 @@
+use anyhow::{Result, anyhow};
+use async_trait::async_trait;
+use chrono::{NaiveDateTime, Utc};
+use sqlx::{PgPool, Row};
+
+use activitypub::RemoteReviewRepository;
+use domain::models::{RemoteWatchlistEntry, Review, ReviewSource};
+use domain::ports::RemoteWatchlistRepository;
+use k_ap::{
+    ActivityRepository, ActorRepository, BlockedDomain, BlocklistRepository, FollowRepository,
+    Follower, FollowerStatus, FollowingStatus, RemoteActor,
+};
+
+fn datetime_to_str(dt: &NaiveDateTime) -> String {
+    dt.format("%Y-%m-%d %H:%M:%S").to_string()
+}
+
+pub struct PostgresFederationRepository {
+    pool: PgPool,
+}
+
+impl PostgresFederationRepository {
+    pub fn new(pool: PgPool) -> Self {
+        Self { pool }
+    }
+}
+
+fn status_to_str(status: &FollowerStatus) -> &'static str {
+    match status {
+        FollowerStatus::Pending => "pending",
+        FollowerStatus::Accepted => "accepted",
+        FollowerStatus::Rejected => "rejected",
+    }
+}
+
+fn str_to_status(s: &str) -> FollowerStatus {
+    match s {
+        "accepted" => FollowerStatus::Accepted,
+        "rejected" => FollowerStatus::Rejected,
+        _ => FollowerStatus::Pending,
+    }
+}
+
+fn pg_remote_actor(row: &sqlx::postgres::PgRow, url_col: &str) -> RemoteActor {
+    RemoteActor {
+        url: row.get(url_col),
+        handle: row.try_get("handle").unwrap_or_default(),
+        inbox_url: row.try_get("inbox_url").unwrap_or_default(),
+        shared_inbox_url: row.try_get("shared_inbox_url").ok().flatten(),
+        display_name: row.try_get("display_name").ok().flatten(),
+        avatar_url: row.try_get("avatar_url").ok().flatten(),
+        outbox_url: row.try_get("outbox_url").ok().flatten(),
+        bio: row.try_get("bio").ok().flatten(),
+        banner_url: row.try_get("banner_url").ok().flatten(),
+        followers_url: row.try_get("followers_url").ok().flatten(),
+        following_url: row.try_get("following_url").ok().flatten(),
+        also_known_as: row
+            .try_get::<Option<String>, _>("also_known_as")
+            .ok()
+            .flatten()
+            .map(|s| {
+                serde_json::from_str::<Vec<String>>(&s).unwrap_or_else(|e| {
+                    tracing::warn!(raw = %s, error = %e, "failed to parse also_known_as JSON");
+                    vec![s]
+                })
+            })
+            .unwrap_or_default(),
+        fetched_at: row.try_get("fetched_at").ok(),
+    }
+}
+
+const PG_ACTOR_COLS: &str = "a.handle, a.inbox_url, a.shared_inbox_url, a.display_name, a.avatar_url, a.outbox_url, a.bio, a.banner_url, a.followers_url, a.following_url, a.also_known_as, a.fetched_at";
+
+#[async_trait]
+impl FollowRepository for PostgresFederationRepository {
+    async fn add_follower(
+        &self,
+        local_user_id: uuid::Uuid,
+        remote_actor_url: &str,
+        status: FollowerStatus,
+        follow_activity_id: &str,
+    ) -> Result<()> {
+        let uid = local_user_id.to_string();
+        let status_str = status_to_str(&status);
+        let now = Utc::now().naive_utc();
+        let created_at = datetime_to_str(&now);
+        sqlx::query(
+            "INSERT INTO ap_followers (local_user_id, remote_actor_url, status, created_at, follow_activity_id)
+             VALUES ($1, $2, $3, $4::timestamptz, $5)
+             ON CONFLICT(local_user_id, remote_actor_url) DO UPDATE SET
+                 status = EXCLUDED.status,
+                 follow_activity_id = EXCLUDED.follow_activity_id",
+        )
+        .bind(&uid)
+        .bind(remote_actor_url)
+        .bind(status_str)
+        .bind(&created_at)
+        .bind(follow_activity_id)
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+
+    async fn get_follower_follow_activity_id(
+        &self,
+        local_user_id: uuid::Uuid,
+        remote_actor_url: &str,
+    ) -> Result<Option<String>> {
+        let uid = local_user_id.to_string();
+        let row: Option<String> = sqlx::query_scalar(
+            "SELECT follow_activity_id FROM ap_followers WHERE local_user_id = $1 AND remote_actor_url = $2",
+        )
+        .bind(&uid)
+        .bind(remote_actor_url)
+        .fetch_optional(&self.pool)
+        .await?;
+        Ok(row)
+    }
+
+    async fn remove_follower(
+        &self,
+        local_user_id: uuid::Uuid,
+        remote_actor_url: &str,
+    ) -> Result<()> {
+        let uid = local_user_id.to_string();
+        sqlx::query("DELETE FROM ap_followers WHERE local_user_id = $1 AND remote_actor_url = $2")
+            .bind(&uid)
+            .bind(remote_actor_url)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+
+    async fn get_followers(&self, local_user_id: uuid::Uuid) -> Result<Vec<Follower>> {
+        let uid = local_user_id.to_string();
+        let q = format!(
+            "SELECT f.remote_actor_url, f.status, {PG_ACTOR_COLS}
+             FROM ap_followers f LEFT JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1"
+        );
+        let rows = sqlx::query(&q).bind(&uid).fetch_all(&self.pool).await?;
+        Ok(rows
+            .iter()
+            .map(|row| {
+                let status_str: String = row.get("status");
+                Follower {
+                    actor: pg_remote_actor(row, "remote_actor_url"),
+                    status: str_to_status(&status_str),
+                }
+            })
+            .collect())
+    }
+
+    async fn get_followers_page(
+        &self,
+        local_user_id: uuid::Uuid,
+        offset: u32,
+        limit: usize,
+    ) -> Result<Vec<Follower>> {
+        let uid = local_user_id.to_string();
+        let q = format!(
+            "SELECT f.remote_actor_url, f.status, {PG_ACTOR_COLS}
+             FROM ap_followers f LEFT JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.status = 'accepted'
+             ORDER BY f.created_at ASC LIMIT $2 OFFSET $3"
+        );
+        let rows = sqlx::query(&q)
+            .bind(&uid)
+            .bind(limit as i64)
+            .bind(offset as i64)
+            .fetch_all(&self.pool)
+            .await?;
+        Ok(rows
+            .iter()
+            .map(|row| {
+                let status_str: String = row.get("status");
+                Follower {
+                    actor: pg_remote_actor(row, "remote_actor_url"),
+                    status: str_to_status(&status_str),
+                }
+            })
+            .collect())
+    }
+
+    async fn count_followers(&self, local_user_id: uuid::Uuid) -> Result<usize> {
+        let uid = local_user_id.to_string();
+        let count: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM ap_followers WHERE local_user_id = $1 AND status = 'accepted'",
+        )
+        .bind(&uid)
+        .fetch_one(&self.pool)
+        .await?;
+        Ok(count as usize)
+    }
+
+    async fn update_follower_status(
+        &self,
+        local_user_id: uuid::Uuid,
+        remote_actor_url: &str,
+        status: FollowerStatus,
+    ) -> Result<()> {
+        let uid = local_user_id.to_string();
+        let status_str = status_to_str(&status);
+        let result = sqlx::query(
+            "UPDATE ap_followers SET status = $1 WHERE local_user_id = $2 AND remote_actor_url = $3",
+        ).bind(status_str).bind(&uid).bind(remote_actor_url).execute(&self.pool).await?;
+        if result.rows_affected() == 0 {
+            tracing::warn!(local_user_id = %local_user_id, remote_actor_url, "update_follower_status: no row found");
+        }
+        Ok(())
+    }
+
+    async fn get_pending_followers(&self, local_user_id: uuid::Uuid) -> Result<Vec<RemoteActor>> {
+        let uid = local_user_id.to_string();
+        let q = format!(
+            "SELECT f.remote_actor_url, {PG_ACTOR_COLS}
+             FROM ap_followers f LEFT JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.status = 'pending'"
+        );
+        let rows = sqlx::query(&q).bind(&uid).fetch_all(&self.pool).await?;
+        Ok(rows
+            .iter()
+            .map(|row| pg_remote_actor(row, "remote_actor_url"))
+            .collect())
+    }
+
+    async fn get_accepted_follower_inboxes(
+        &self,
+        local_user_id: uuid::Uuid,
+    ) -> Result<Vec<String>> {
+        let uid = local_user_id.to_string();
+        let rows = sqlx::query(
+            "SELECT DISTINCT COALESCE(a.shared_inbox_url, a.inbox_url) as inbox
+             FROM ap_followers f
+             INNER JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.status = 'accepted'
+               AND f.remote_actor_url NOT IN (
+                   SELECT remote_actor_url FROM blocked_actors WHERE local_user_id = $1
+               )",
+        )
+        .bind(&uid)
+        .fetch_all(&self.pool)
+        .await?;
+        Ok(rows
+            .iter()
+            .filter_map(|r| r.try_get::<String, _>("inbox").ok())
+            .collect())
+    }
+
+    async fn count_accepted_followers(&self, local_user_id: uuid::Uuid) -> Result<usize> {
+        let uid = local_user_id.to_string();
+        let count: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM ap_followers WHERE local_user_id = $1 AND status = 'accepted'",
+        )
+        .bind(&uid)
+        .fetch_one(&self.pool)
+        .await?;
+        Ok(count as usize)
+    }
+
+    async fn get_accepted_followers_page(
+        &self,
+        local_user_id: uuid::Uuid,
+        offset: u32,
+        limit: usize,
+    ) -> Result<Vec<RemoteActor>> {
+        let uid = local_user_id.to_string();
+        let q = format!(
+            "SELECT f.remote_actor_url, {PG_ACTOR_COLS}
+             FROM ap_followers f LEFT JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.status = 'accepted'
+             ORDER BY f.created_at ASC LIMIT $2 OFFSET $3"
+        );
+        let rows = sqlx::query(&q)
+            .bind(&uid)
+            .bind(limit as i64)
+            .bind(offset as i64)
+            .fetch_all(&self.pool)
+            .await?;
+        Ok(rows
+            .iter()
+            .map(|row| pg_remote_actor(row, "remote_actor_url"))
+            .collect())
+    }
+
+    async fn add_following(
+        &self,
+        local_user_id: uuid::Uuid,
+        actor: RemoteActor,
+        follow_activity_id: &str,
+    ) -> Result<()> {
+        let uid = local_user_id.to_string();
+        let now = Utc::now().naive_utc();
+        let created_at = datetime_to_str(&now);
+        ActorRepository::upsert_remote_actor(self, actor.clone()).await?;
+        sqlx::query(
+            "INSERT INTO ap_following (local_user_id, remote_actor_url, follow_activity_id, created_at)
+             VALUES ($1, $2, $3, $4::timestamptz) ON CONFLICT DO NOTHING",
+        ).bind(&uid).bind(&actor.url).bind(follow_activity_id).bind(&created_at).execute(&self.pool).await?;
+        Ok(())
+    }
+
+    async fn get_follow_activity_id(
+        &self,
+        local_user_id: uuid::Uuid,
+        remote_actor_url: &str,
+    ) -> Result<Option<String>> {
+        let uid = local_user_id.to_string();
+        let row: Option<String> = sqlx::query_scalar(
+            "SELECT follow_activity_id FROM ap_following WHERE local_user_id = $1 AND remote_actor_url = $2",
+        ).bind(&uid).bind(remote_actor_url).fetch_optional(&self.pool).await?;
+        Ok(row)
+    }
+
+    async fn remove_following(&self, local_user_id: uuid::Uuid, actor_url: &str) -> Result<()> {
+        let uid = local_user_id.to_string();
+        sqlx::query("DELETE FROM ap_following WHERE local_user_id = $1 AND remote_actor_url = $2")
+            .bind(&uid)
+            .bind(actor_url)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+
+    async fn get_following(&self, local_user_id: uuid::Uuid) -> Result<Vec<RemoteActor>> {
+        let uid = local_user_id.to_string();
+        let q = format!(
+            "SELECT a.url, {PG_ACTOR_COLS}
+             FROM ap_following f INNER JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.status = 'accepted'"
+        );
+        let rows = sqlx::query(&q).bind(&uid).fetch_all(&self.pool).await?;
+        Ok(rows.iter().map(|row| pg_remote_actor(row, "url")).collect())
+    }
+
+    async fn count_following(&self, local_user_id: uuid::Uuid) -> Result<usize> {
+        let uid = local_user_id.to_string();
+        let count: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM ap_following WHERE local_user_id = $1 AND status = 'accepted'",
+        )
+        .bind(&uid)
+        .fetch_one(&self.pool)
+        .await?;
+        Ok(count as usize)
+    }
+
+    async fn get_following_page(
+        &self,
+        local_user_id: uuid::Uuid,
+        offset: u32,
+        limit: usize,
+    ) -> Result<Vec<RemoteActor>> {
+        let uid = local_user_id.to_string();
+        let q = format!(
+            "SELECT a.url, {PG_ACTOR_COLS}
+             FROM ap_following f INNER JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.status = 'accepted'
+             ORDER BY f.created_at ASC LIMIT $2 OFFSET $3"
+        );
+        let rows = sqlx::query(&q)
+            .bind(&uid)
+            .bind(limit as i64)
+            .bind(offset as i64)
+            .fetch_all(&self.pool)
+            .await?;
+        Ok(rows.iter().map(|row| pg_remote_actor(row, "url")).collect())
+    }
+
+    async fn update_following_status(
+        &self,
+        local_user_id: uuid::Uuid,
+        remote_actor_url: &str,
+        status: FollowingStatus,
+    ) -> Result<()> {
+        let uid = local_user_id.to_string();
+        let status_str = match status {
+            FollowingStatus::Pending => "pending",
+            FollowingStatus::Accepted => "accepted",
+        };
+        let result = sqlx::query(
+            "UPDATE ap_following SET status = $1 WHERE local_user_id = $2 AND remote_actor_url = $3",
+        ).bind(status_str).bind(&uid).bind(remote_actor_url).execute(&self.pool).await?;
+        if result.rows_affected() == 0 {
+            tracing::warn!(local_user_id = %local_user_id, remote_actor_url, "update_following_status: no row found");
+        }
+        Ok(())
+    }
+
+    async fn get_following_outbox_url(
+        &self,
+        local_user_id: uuid::Uuid,
+        remote_actor_url: &str,
+    ) -> Result<Option<String>> {
+        let uid = local_user_id.to_string();
+        let row: Option<Option<String>> = sqlx::query_scalar(
+            "SELECT a.outbox_url FROM ap_following f INNER JOIN ap_remote_actors a ON a.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.remote_actor_url = $2",
+        ).bind(&uid).bind(remote_actor_url).fetch_optional(&self.pool).await?;
+        Ok(row.flatten())
+    }
+
+    async fn migrate_follower_actor(
+        &self,
+        old_actor_url: &str,
+        new_actor_url: &str,
+    ) -> Result<Vec<uuid::Uuid>> {
+        let candidates: Vec<String> = sqlx::query_scalar(
+            "SELECT local_user_id FROM ap_following WHERE remote_actor_url = $1
+               AND local_user_id NOT IN (SELECT local_user_id FROM ap_following WHERE remote_actor_url = $2)",
+        ).bind(old_actor_url).bind(new_actor_url).fetch_all(&self.pool).await?;
+
+        if candidates.is_empty() {
+            return Ok(vec![]);
+        }
+
+        sqlx::query(
+            "UPDATE ap_following SET remote_actor_url = $1 WHERE remote_actor_url = $2
+               AND local_user_id NOT IN (SELECT local_user_id FROM ap_following WHERE remote_actor_url = $1)",
+        ).bind(new_actor_url).bind(old_actor_url).execute(&self.pool).await?;
+
+        candidates
+            .into_iter()
+            .map(|s| uuid::Uuid::parse_str(&s).map_err(|e| anyhow::anyhow!(e)))
+            .collect()
+    }
+}
+
+#[async_trait]
+impl ActorRepository for PostgresFederationRepository {
+    async fn get_local_actor_keypair(
+        &self,
+        user_id: uuid::Uuid,
+    ) -> Result<Option<(String, String)>> {
+        let uid = user_id.to_string();
+        let row =
+            sqlx::query("SELECT public_key, private_key FROM ap_local_actors WHERE user_id = $1")
+                .bind(&uid)
+                .fetch_optional(&self.pool)
+                .await?;
+        Ok(row.map(|r| (r.get("public_key"), r.get("private_key"))))
+    }
+
+    async fn save_local_actor_keypair(
+        &self,
+        user_id: uuid::Uuid,
+        public_key: String,
+        private_key: String,
+    ) -> Result<()> {
+        let uid = user_id.to_string();
+        let now = Utc::now().naive_utc();
+        let created_at = datetime_to_str(&now);
+        sqlx::query(
+            "INSERT INTO ap_local_actors (user_id, public_key, private_key, created_at)
+             VALUES ($1, $2, $3, $4::timestamptz)
+             ON CONFLICT(user_id) DO UPDATE SET public_key = EXCLUDED.public_key, private_key = EXCLUDED.private_key",
+        ).bind(&uid).bind(&public_key).bind(&private_key).bind(&created_at).execute(&self.pool).await?;
+        Ok(())
+    }
+
+    async fn upsert_remote_actor(&self, actor: RemoteActor) -> Result<()> {
+        let now = Utc::now().naive_utc();
+        let fetched_at = datetime_to_str(&now);
+        let aka_json = serde_json::to_string(&actor.also_known_as).unwrap_or_default();
+        sqlx::query(
+            "INSERT INTO ap_remote_actors (url, handle, inbox_url, shared_inbox_url, display_name, avatar_url, outbox_url, bio, banner_url, followers_url, following_url, also_known_as, fetched_at)
+             VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13::timestamptz)
+             ON CONFLICT(url) DO UPDATE SET
+                 handle=EXCLUDED.handle, inbox_url=EXCLUDED.inbox_url, shared_inbox_url=EXCLUDED.shared_inbox_url,
+                 display_name=EXCLUDED.display_name, avatar_url=EXCLUDED.avatar_url,
+                 outbox_url=COALESCE(EXCLUDED.outbox_url, ap_remote_actors.outbox_url),
+                 bio=EXCLUDED.bio, banner_url=EXCLUDED.banner_url, followers_url=EXCLUDED.followers_url,
+                 following_url=EXCLUDED.following_url, also_known_as=EXCLUDED.also_known_as, fetched_at=EXCLUDED.fetched_at",
+        )
+        .bind(&actor.url).bind(&actor.handle).bind(&actor.inbox_url).bind(&actor.shared_inbox_url)
+        .bind(&actor.display_name).bind(&actor.avatar_url).bind(&actor.outbox_url)
+        .bind(&actor.bio).bind(&actor.banner_url).bind(&actor.followers_url).bind(&actor.following_url)
+        .bind(&aka_json).bind(&fetched_at)
+        .execute(&self.pool).await?;
+        Ok(())
+    }
+
+    async fn get_remote_actor(&self, actor_url: &str) -> Result<Option<RemoteActor>> {
+        let q = format!("SELECT url, {PG_ACTOR_COLS} FROM ap_remote_actors a WHERE url = $1");
+        let row = sqlx::query(&q)
+            .bind(actor_url)
+            .fetch_optional(&self.pool)
+            .await?;
+        Ok(row.as_ref().map(|r| pg_remote_actor(r, "url")))
+    }
+
+    async fn add_announce(
+        &self,
+        activity_id: &str,
+        object_url: &str,
+        actor_url: &str,
+        announced_at: chrono::DateTime<chrono::Utc>,
+    ) -> Result<()> {
+        let ts = announced_at.format("%Y-%m-%d %H:%M:%S").to_string();
+        sqlx::query("INSERT INTO ap_announces (id, object_url, actor_url, announced_at) VALUES ($1, $2, $3, $4) ON CONFLICT (id) DO NOTHING")
+            .bind(activity_id).bind(object_url).bind(actor_url).bind(&ts).execute(&self.pool).await?;
+        Ok(())
+    }
+
+    async fn remove_announce(&self, activity_id: &str, actor_url: &str) -> Result<()> {
+        sqlx::query("DELETE FROM ap_announces WHERE id = $1 AND actor_url = $2")
+            .bind(activity_id)
+            .bind(actor_url)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+
+    async fn count_announces(&self, object_url: &str) -> Result<usize> {
+        let row = sqlx::query("SELECT COUNT(*) as cnt FROM ap_announces WHERE object_url = $1")
+            .bind(object_url)
+            .fetch_one(&self.pool)
+            .await?;
+        Ok(row.get::<i64, _>("cnt") as usize)
+    }
+}
+
+#[async_trait]
+impl BlocklistRepository for PostgresFederationRepository {
+    async fn add_blocked_domain(&self, domain: &str, reason: Option<&str>) -> Result<()> {
+        let ts = datetime_to_str(&Utc::now().naive_utc());
+        sqlx::query("INSERT INTO blocked_domains (domain, reason, blocked_at) VALUES ($1, $2, $3) ON CONFLICT(domain) DO UPDATE SET reason = EXCLUDED.reason")
+            .bind(domain).bind(reason).bind(&ts).execute(&self.pool).await?;
+        Ok(())
+    }
+    async fn remove_blocked_domain(&self, domain: &str) -> Result<()> {
+        sqlx::query("DELETE FROM blocked_domains WHERE domain = $1")
+            .bind(domain)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+    async fn get_blocked_domains(&self) -> Result<Vec<BlockedDomain>> {
+        let rows = sqlx::query(
+            "SELECT domain, reason, blocked_at FROM blocked_domains ORDER BY blocked_at DESC",
+        )
+        .fetch_all(&self.pool)
+        .await?;
+        Ok(rows
+            .iter()
+            .map(|r| BlockedDomain {
+                domain: r.get("domain"),
+                reason: r.get("reason"),
+                blocked_at: r.get("blocked_at"),
+            })
+            .collect())
+    }
+    async fn is_domain_blocked(&self, domain: &str) -> Result<bool> {
+        let count: i64 =
+            sqlx::query_scalar("SELECT COUNT(*) FROM blocked_domains WHERE domain = $1")
+                .bind(domain)
+                .fetch_one(&self.pool)
+                .await?;
+        Ok(count > 0)
+    }
+    async fn add_blocked_actor(&self, local_user_id: uuid::Uuid, actor_url: &str) -> Result<()> {
+        let uid = local_user_id.to_string();
+        let ts = datetime_to_str(&Utc::now().naive_utc());
+        sqlx::query("INSERT INTO blocked_actors (local_user_id, remote_actor_url, blocked_at) VALUES ($1, $2, $3) ON CONFLICT DO NOTHING")
+            .bind(&uid).bind(actor_url).bind(&ts).execute(&self.pool).await?;
+        Ok(())
+    }
+    async fn remove_blocked_actor(&self, local_user_id: uuid::Uuid, actor_url: &str) -> Result<()> {
+        let uid = local_user_id.to_string();
+        sqlx::query(
+            "DELETE FROM blocked_actors WHERE local_user_id = $1 AND remote_actor_url = $2",
+        )
+        .bind(&uid)
+        .bind(actor_url)
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+    async fn get_blocked_actors(&self, local_user_id: uuid::Uuid) -> Result<Vec<String>> {
+        let uid = local_user_id.to_string();
+        let rows = sqlx::query("SELECT remote_actor_url FROM blocked_actors WHERE local_user_id = $1 ORDER BY blocked_at DESC")
+            .bind(&uid).fetch_all(&self.pool).await?;
+        Ok(rows
+            .iter()
+            .map(|r| r.get::<String, _>("remote_actor_url"))
+            .collect())
+    }
+    async fn is_actor_blocked(&self, local_user_id: uuid::Uuid, actor_url: &str) -> Result<bool> {
+        let uid = local_user_id.to_string();
+        let count: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM blocked_actors WHERE local_user_id = $1 AND remote_actor_url = $2")
+            .bind(&uid).bind(actor_url).fetch_one(&self.pool).await?;
+        Ok(count > 0)
+    }
+}
+
+#[async_trait]
+impl ActivityRepository for PostgresFederationRepository {
+    async fn is_activity_processed(&self, activity_id: &str) -> Result<bool> {
+        let count: i64 = sqlx::query_scalar("SELECT COUNT(*) FROM ap_activities WHERE id = $1")
+            .bind(activity_id)
+            .fetch_one(&self.pool)
+            .await?;
+        Ok(count > 0)
+    }
+    async fn mark_activity_processed(&self, activity_id: &str) -> Result<()> {
+        let ts = datetime_to_str(&Utc::now().naive_utc());
+        sqlx::query(
+            "INSERT INTO ap_activities (id, processed_at) VALUES ($1, $2) ON CONFLICT DO NOTHING",
+        )
+        .bind(activity_id)
+        .bind(&ts)
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl RemoteReviewRepository for PostgresFederationRepository {
+    async fn save_remote_review(
+        &self,
+        review: &Review,
+        ap_id: &str,
+        movie_title: &str,
+        release_year: u16,
+        poster_url: Option<&str>,
+    ) -> Result<()> {
+        let actor_url = match review.source() {
+            ReviewSource::Remote { actor_url } => actor_url.clone(),
+            ReviewSource::Local => {
+                return Err(anyhow!("save_remote_review called with a local review"));
+            }
+        };
+        let movie_id = review.movie_id().value().to_string();
+        sqlx::query(
+            "INSERT INTO movies (id, external_metadata_id, title, release_year, director, poster_path)
+             VALUES ($1, NULL, $2, $3, NULL, $4)
+             ON CONFLICT(id) DO UPDATE SET
+                 poster_path = COALESCE(EXCLUDED.poster_path, movies.poster_path)",
+        )
+        .bind(&movie_id)
+        .bind(movie_title)
+        .bind(release_year.max(1888) as i64)
+        .bind(poster_url)
+        .execute(&self.pool)
+        .await?;
+
+        let id = review.id().value().to_string();
+        let user_id = review.user_id().value().to_string();
+        let rating = review.rating().value() as i64;
+        let comment = review.comment().map(|c| c.value().to_string());
+        let watched_at = datetime_to_str(review.watched_at());
+        let created_at = datetime_to_str(review.created_at());
+        sqlx::query(
+            "INSERT INTO reviews (id, movie_id, user_id, rating, comment, watched_at, created_at, remote_actor_url, ap_id)
+             VALUES ($1, $2, $3, $4, $5, $6::timestamptz, $7::timestamptz, $8, $9)
+             ON CONFLICT DO NOTHING",
+        )
+        .bind(&id)
+        .bind(&movie_id)
+        .bind(&user_id)
+        .bind(rating)
+        .bind(&comment)
+        .bind(&watched_at)
+        .bind(&created_at)
+        .bind(&actor_url)
+        .bind(ap_id)
+        .execute(&self.pool)
+        .await?;
+        Ok(())
+    }
+
+    async fn delete_remote_review(&self, ap_id: &str, actor_url: &str) -> Result<()> {
+        sqlx::query("DELETE FROM reviews WHERE ap_id = $1 AND remote_actor_url = $2")
+            .bind(ap_id)
+            .bind(actor_url)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+
+    async fn update_remote_review(
+        &self,
+        ap_id: &str,
+        actor_url: &str,
+        rating: u8,
+        comment: Option<&str>,
+        watched_at: chrono::NaiveDateTime,
+        poster_url: Option<&str>,
+    ) -> Result<()> {
+        let watched_at_str = datetime_to_str(&watched_at);
+        sqlx::query(
+            "UPDATE reviews SET rating = $1, comment = $2, watched_at = $3::timestamptz
+             WHERE ap_id = $4 AND remote_actor_url = $5",
+        )
+        .bind(rating as i64)
+        .bind(comment)
+        .bind(&watched_at_str)
+        .bind(ap_id)
+        .bind(actor_url)
+        .execute(&self.pool)
+        .await?;
+        if let Some(url) = poster_url {
+            sqlx::query(
+                "UPDATE movies SET poster_path = $1
+                 WHERE id = (SELECT movie_id FROM reviews WHERE ap_id = $2 AND remote_actor_url = $3)",
+            )
+            .bind(url)
+            .bind(ap_id)
+            .bind(actor_url)
+            .execute(&self.pool)
+            .await?;
+        }
+        Ok(())
+    }
+
+    async fn delete_by_actor(&self, actor_url: &str) -> Result<()> {
+        sqlx::query("DELETE FROM reviews WHERE remote_actor_url = $1")
+            .bind(actor_url)
+            .execute(&self.pool)
+            .await?;
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl domain::ports::SocialQueryPort for PostgresFederationRepository {
+    async fn get_accepted_following_urls(
+        &self,
+        user_id: uuid::Uuid,
+    ) -> Result<Vec<String>, domain::errors::DomainError> {
+        let user_id_str = user_id.to_string();
+        sqlx::query_scalar::<_, String>(
+            "SELECT remote_actor_url FROM ap_following WHERE local_user_id = $1 AND status = 'accepted'",
+        )
+        .bind(&user_id_str)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))
+    }
+
+    async fn list_all_followed_remote_actors(
+        &self,
+    ) -> Result<Vec<domain::ports::RemoteActorInfo>, domain::errors::DomainError> {
+        let rows = sqlx::query_as::<_, (String, String, Option<String>)>(
+            "SELECT DISTINCT ar.url, ar.handle, ar.display_name
+             FROM ap_remote_actors ar
+             JOIN ap_following f ON f.remote_actor_url = ar.url
+             WHERE f.status = 'accepted'",
+        )
+        .fetch_all(&self.pool)
+        .await
+        .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+        Ok(rows
+            .into_iter()
+            .map(
+                |(url, handle, display_name)| domain::ports::RemoteActorInfo {
+                    url,
+                    handle,
+                    display_name,
+                },
+            )
+            .collect())
+    }
+
+    async fn count_following(
+        &self,
+        user_id: uuid::Uuid,
+    ) -> Result<usize, domain::errors::DomainError> {
+        let uid = user_id.to_string();
+        let count: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM ap_following WHERE local_user_id = $1 AND status = 'accepted'",
+        )
+        .bind(&uid)
+        .fetch_one(&self.pool)
+        .await
+        .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+        Ok(count as usize)
+    }
+
+    async fn count_accepted_followers(
+        &self,
+        user_id: uuid::Uuid,
+    ) -> Result<usize, domain::errors::DomainError> {
+        let uid = user_id.to_string();
+        let count: i64 = sqlx::query_scalar(
+            "SELECT COUNT(*) FROM ap_followers WHERE local_user_id = $1 AND status = 'accepted'",
+        )
+        .bind(&uid)
+        .fetch_one(&self.pool)
+        .await
+        .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+        Ok(count as usize)
+    }
+
+    async fn get_pending_followers(
+        &self,
+        user_id: uuid::Uuid,
+    ) -> Result<Vec<domain::ports::PendingFollowerInfo>, domain::errors::DomainError> {
+        let uid = user_id.to_string();
+        let rows = sqlx::query_as::<_, (String, String, Option<String>, Option<String>)>(
+            "SELECT ar.url, ar.handle, ar.display_name, ar.avatar_url
+             FROM ap_followers f
+             JOIN ap_remote_actors ar ON ar.url = f.remote_actor_url
+             WHERE f.local_user_id = $1 AND f.status = 'pending'",
+        )
+        .bind(&uid)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+        Ok(rows
+            .into_iter()
+            .map(
+                |(url, handle, display_name, avatar_url)| domain::ports::PendingFollowerInfo {
+                    url,
+                    handle,
+                    display_name,
+                    avatar_url,
+                },
+            )
+            .collect())
+    }
+}
+
+#[async_trait]
+impl RemoteWatchlistRepository for PostgresFederationRepository {
+    async fn save(&self, entry: RemoteWatchlistEntry) -> Result<(), domain::errors::DomainError> {
+        sqlx::query(
+            "INSERT INTO ap_remote_watchlist_entries \
+             (ap_id, actor_url, movie_title, release_year, external_metadata_id, poster_url, added_at) \
+             VALUES ($1, $2, $3, $4, $5, $6, $7) \
+             ON CONFLICT(ap_id) DO UPDATE SET \
+               movie_title=excluded.movie_title, release_year=excluded.release_year, \
+               external_metadata_id=excluded.external_metadata_id, poster_url=excluded.poster_url",
+        )
+        .bind(&entry.ap_id)
+        .bind(&entry.actor_url)
+        .bind(&entry.movie_title)
+        .bind(entry.release_year as i32)
+        .bind(&entry.external_metadata_id)
+        .bind(&entry.poster_url)
+        .bind(entry.added_at)
+        .execute(&self.pool)
+        .await
+        .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn remove_by_ap_id(
+        &self,
+        ap_id: &str,
+        actor_url: &str,
+    ) -> Result<(), domain::errors::DomainError> {
+        sqlx::query("DELETE FROM ap_remote_watchlist_entries WHERE ap_id = $1 AND actor_url = $2")
+            .bind(ap_id)
+            .bind(actor_url)
+            .execute(&self.pool)
+            .await
+            .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn get_by_actor_url(
+        &self,
+        actor_url: &str,
+    ) -> Result<Vec<RemoteWatchlistEntry>, domain::errors::DomainError> {
+        let rows = sqlx::query(
+            "SELECT ap_id, actor_url, movie_title, release_year, external_metadata_id, poster_url, added_at \
+             FROM ap_remote_watchlist_entries WHERE actor_url = $1 ORDER BY added_at DESC",
+        )
+        .bind(actor_url)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+
+        rows.into_iter()
+            .map(|row| {
+                Ok(RemoteWatchlistEntry {
+                    ap_id: row.try_get("ap_id").unwrap_or_default(),
+                    actor_url: row.try_get("actor_url").unwrap_or_default(),
+                    movie_title: row.try_get("movie_title").unwrap_or_default(),
+                    release_year: row.try_get::<i32, _>("release_year").unwrap_or(0) as u16,
+                    external_metadata_id: row.try_get("external_metadata_id").ok().flatten(),
+                    poster_url: row.try_get("poster_url").ok().flatten(),
+                    added_at: row
+                        .try_get::<chrono::DateTime<chrono::Utc>, _>("added_at")
+                        .unwrap_or_else(|_| chrono::Utc::now()),
+                })
+            })
+            .collect()
+    }
+
+    async fn remove_all_by_actor(
+        &self,
+        actor_url: &str,
+    ) -> Result<(), domain::errors::DomainError> {
+        sqlx::query("DELETE FROM ap_remote_watchlist_entries WHERE actor_url = $1")
+            .bind(actor_url)
+            .execute(&self.pool)
+            .await
+            .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?;
+        Ok(())
+    }
+
+    async fn get_by_derived_uuid(
+        &self,
+        uuid: uuid::Uuid,
+    ) -> Result<Vec<RemoteWatchlistEntry>, domain::errors::DomainError> {
+        let actors: Vec<String> =
+            sqlx::query("SELECT DISTINCT actor_url FROM ap_remote_watchlist_entries")
+                .fetch_all(&self.pool)
+                .await
+                .map_err(|e| domain::errors::DomainError::InfrastructureError(e.to_string()))?
+                .into_iter()
+                .filter_map(|row| row.try_get::<String, _>("actor_url").ok())
+                .collect();
+
+        let target = actors
+            .into_iter()
+            .find(|url| uuid::Uuid::new_v5(&uuid::Uuid::NAMESPACE_URL, url.as_bytes()) == uuid);
+
+        match target {
+            None => Ok(vec![]),
+            Some(actor_url) => self.get_by_actor_url(&actor_url).await,
+        }
+    }
+}
+
+pub fn wire(pool: sqlx::PgPool) -> activitypub::FederationRepos {
+    let fed = std::sync::Arc::new(PostgresFederationRepository::new(pool));
+    (
+        std::sync::Arc::clone(&fed) as _,
+        std::sync::Arc::clone(&fed) as _,
+        std::sync::Arc::clone(&fed) as _,
+        std::sync::Arc::clone(&fed) as _,
+        std::sync::Arc::clone(&fed) as _,
+        std::sync::Arc::clone(&fed) as _,
+        fed as _,
+    )
+}

crates/adapters/postgres-search/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "postgres-search"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+domain      = { workspace = true }
+async-trait = { workspace = true }
+sqlx        = { version = "0.8.6", features = ["runtime-tokio-rustls", "postgres", "uuid", "macros"] }
+uuid        = { workspace = true }

crates/adapters/postgres-search/src/lib.rs

@@ -0,0 +1,357 @@
+use std::sync::Arc;
+
+use async_trait::async_trait;
+use domain::{
+    errors::DomainError,
+    models::PersonId,
+    models::{
+        collections::Paginated, EntityType, IndexableDocument, MovieSearchHit, PersonSearchHit,
+        SearchQuery, SearchResults,
+    },
+    ports::{SearchCommand, SearchPort},
+    value_objects::MovieId,
+};
+use sqlx::PgPool;
+
+pub struct PostgresSearchAdapter {
+    pool: PgPool,
+}
+
+impl PostgresSearchAdapter {
+    pub fn new(pool: PgPool) -> Self {
+        Self { pool }
+    }
+}
+
+pub fn create_search_adapter(pool: PgPool) -> (Arc<dyn SearchCommand>, Arc<dyn SearchPort>) {
+    let adapter = Arc::new(PostgresSearchAdapter::new(pool));
+    (
+        Arc::clone(&adapter) as Arc<dyn SearchCommand>,
+        adapter as Arc<dyn SearchPort>,
+    )
+}
+
+fn map_err(e: sqlx::Error) -> DomainError {
+    DomainError::InfrastructureError(e.to_string())
+}
+
+#[async_trait]
+impl SearchCommand for PostgresSearchAdapter {
+    async fn index(&self, doc: IndexableDocument) -> Result<(), DomainError> {
+        match doc {
+            IndexableDocument::Movie { id, movie, profile } => {
+                let movie_id = id.value().to_string();
+                let title = movie.title().value().to_string();
+                let director = movie.director().unwrap_or("").to_string();
+                let (overview, genres, keywords, cast_names, crew_names) = match profile.as_deref()
+                {
+                    Some(p) => (
+                        p.overview.clone().unwrap_or_default(),
+                        p.genres
+                            .iter()
+                            .map(|g| g.name.as_str())
+                            .collect::<Vec<_>>()
+                            .join(" "),
+                        p.keywords
+                            .iter()
+                            .map(|k| k.name.as_str())
+                            .collect::<Vec<_>>()
+                            .join(" "),
+                        p.cast
+                            .iter()
+                            .map(|c| c.name.as_str())
+                            .collect::<Vec<_>>()
+                            .join(" "),
+                        p.crew
+                            .iter()
+                            .map(|c| c.name.as_str())
+                            .collect::<Vec<_>>()
+                            .join(" "),
+                    ),
+                    None => (
+                        String::new(),
+                        String::new(),
+                        String::new(),
+                        String::new(),
+                        String::new(),
+                    ),
+                };
+
+                let fts_input = format!(
+                    "{} {} {} {} {} {} {}",
+                    title, director, overview, genres, keywords, cast_names, crew_names
+                );
+
+                sqlx::query(
+                    "INSERT INTO movies_search (movie_id, fts)
+                     VALUES ($1, to_tsvector('english', $2))
+                     ON CONFLICT (movie_id) DO UPDATE SET fts = EXCLUDED.fts",
+                )
+                .bind(&movie_id)
+                .bind(&fts_input)
+                .execute(&self.pool)
+                .await
+                .map_err(map_err)?;
+
+                Ok(())
+            }
+
+            IndexableDocument::Person { id, person } => {
+                let person_id = id.value().to_string();
+                let fts_input = format!(
+                    "{} {}",
+                    person.name(),
+                    person.known_for_department().unwrap_or("")
+                );
+
+                sqlx::query(
+                    "INSERT INTO people_search (person_id, fts)
+                     VALUES ($1, to_tsvector('english', $2))
+                     ON CONFLICT (person_id) DO UPDATE SET fts = EXCLUDED.fts",
+                )
+                .bind(&person_id)
+                .bind(&fts_input)
+                .execute(&self.pool)
+                .await
+                .map_err(map_err)?;
+
+                Ok(())
+            }
+        }
+    }
+
+    async fn remove(&self, entity_type: EntityType, id: &str) -> Result<(), DomainError> {
+        match entity_type {
+            EntityType::Movie => {
+                sqlx::query("DELETE FROM movies_search WHERE movie_id = $1")
+                    .bind(id)
+                    .execute(&self.pool)
+                    .await
+                    .map_err(map_err)?;
+            }
+            EntityType::Person => {
+                sqlx::query("DELETE FROM people_search WHERE person_id = $1")
+                    .bind(id)
+                    .execute(&self.pool)
+                    .await
+                    .map_err(map_err)?;
+            }
+        }
+        Ok(())
+    }
+}
+
+#[async_trait]
+impl SearchPort for PostgresSearchAdapter {
+    async fn search(&self, query: &SearchQuery) -> Result<SearchResults, DomainError> {
+        let movies = self.search_movies(query).await?;
+        let people = self.search_people(query).await?;
+        Ok(SearchResults { movies, people })
+    }
+}
+
+impl PostgresSearchAdapter {
+    async fn search_movies(
+        &self,
+        query: &SearchQuery,
+    ) -> Result<Paginated<MovieSearchHit>, DomainError> {
+        let limit = query.page.limit as i64;
+        let offset = query.page.offset as i64;
+
+        #[derive(sqlx::FromRow)]
+        struct Row {
+            id: String,
+            title: String,
+            release_year: Option<i32>,
+            director: Option<String>,
+            poster_path: Option<String>,
+            genres: Option<String>,
+        }
+
+        let total: u64 = if let Some(text) = &query.text {
+            let count: i64 = sqlx::query_scalar(
+                "SELECT COUNT(DISTINCT m.id)
+                 FROM movies_search ms
+                 JOIN movies m ON m.id = ms.movie_id
+                 LEFT JOIN movie_genres mg ON mg.movie_id = m.id
+                 WHERE ms.fts @@ plainto_tsquery('english', $1)
+                   AND ($2::TEXT IS NULL OR EXISTS (SELECT 1 FROM movie_genres WHERE movie_id = m.id AND name = $2))
+                   AND ($3::INT IS NULL OR m.release_year = $3)",
+            )
+            .bind(text)
+            .bind(&query.filters.genre)
+            .bind(query.filters.year.map(|y| y as i32))
+            .fetch_one(&self.pool)
+            .await
+            .map_err(map_err)?;
+            count as u64
+        } else {
+            let count: i64 = sqlx::query_scalar(
+                "SELECT COUNT(DISTINCT m.id) FROM movies m
+                 LEFT JOIN movie_genres mg ON mg.movie_id = m.id
+                 WHERE ($1::TEXT IS NULL OR EXISTS (SELECT 1 FROM movie_genres WHERE movie_id = m.id AND name = $1))
+                   AND ($2::INT IS NULL OR m.release_year = $2)",
+            )
+            .bind(&query.filters.genre)
+            .bind(query.filters.year.map(|y| y as i32))
+            .fetch_one(&self.pool)
+            .await
+            .map_err(map_err)?;
+            count as u64
+        };
+
+        let rows: Vec<Row> = if let Some(text) = &query.text {
+            sqlx::query_as::<_, Row>(
+                "SELECT m.id, m.title, m.release_year, m.director, m.poster_path,
+                        STRING_AGG(DISTINCT mg.name, ',' ORDER BY mg.name) AS genres
+                 FROM movies_search ms
+                 JOIN movies m ON m.id = ms.movie_id
+                 LEFT JOIN movie_genres mg ON mg.movie_id = m.id
+                 WHERE ms.fts @@ plainto_tsquery('english', $1)
+                   AND ($2::TEXT IS NULL OR EXISTS (SELECT 1 FROM movie_genres WHERE movie_id = m.id AND name = $2))
+                   AND ($3::INT IS NULL OR m.release_year = $3)
+                 GROUP BY m.id, m.title, m.release_year, m.director, m.poster_path, ms.fts
+                 ORDER BY ts_rank(ms.fts, plainto_tsquery('english', $1)) DESC
+                 LIMIT $4 OFFSET $5",
+            )
+            .bind(text)
+            .bind(&query.filters.genre)
+            .bind(query.filters.year.map(|y| y as i32))
+            .bind(limit)
+            .bind(offset)
+            .fetch_all(&self.pool)
+            .await
+            .map_err(map_err)?
+        } else {
+            sqlx::query_as::<_, Row>(
+                "SELECT m.id, m.title, m.release_year, m.director, m.poster_path,
+                        STRING_AGG(DISTINCT mg.name, ',' ORDER BY mg.name) AS genres
+                 FROM movies m
+                 LEFT JOIN movie_genres mg ON mg.movie_id = m.id
+                 WHERE ($1::TEXT IS NULL OR EXISTS (SELECT 1 FROM movie_genres WHERE movie_id = m.id AND name = $1))
+                   AND ($2::INT IS NULL OR m.release_year = $2)
+                 GROUP BY m.id ORDER BY m.title LIMIT $3 OFFSET $4",
+            )
+            .bind(&query.filters.genre)
+            .bind(query.filters.year.map(|y| y as i32))
+            .bind(limit)
+            .bind(offset)
+            .fetch_all(&self.pool)
+            .await
+            .map_err(map_err)?
+        };
+
+        let items = rows
+            .into_iter()
+            .map(|r| MovieSearchHit {
+                movie_id: MovieId::from_uuid(uuid::Uuid::parse_str(&r.id).unwrap_or_default()),
+                title: r.title,
+                release_year: r.release_year.map(|y| y as u16),
+                director: r.director,
+                poster_path: r.poster_path,
+                genres: r
+                    .genres
+                    .unwrap_or_default()
+                    .split(',')
+                    .filter(|s| !s.is_empty())
+                    .map(str::to_string)
+                    .collect(),
+            })
+            .collect::<Vec<_>>();
+
+        Ok(Paginated {
+            items,
+            total_count: total,
+            limit: query.page.limit,
+            offset: query.page.offset,
+        })
+    }
+
+    async fn search_people(
+        &self,
+        query: &SearchQuery,
+    ) -> Result<Paginated<PersonSearchHit>, DomainError> {
+        let Some(text) = &query.text else {
+            return Ok(Paginated {
+                items: vec![],
+                total_count: 0,
+                limit: query.page.limit,
+                offset: query.page.offset,
+            });
+        };
+
+        let limit = query.page.limit as i64;
+        let offset = query.page.offset as i64;
+
+        let total: u64 = {
+            let count: i64 = sqlx::query_scalar(
+                "SELECT COUNT(*) FROM people_search WHERE fts @@ plainto_tsquery('english', $1)",
+            )
+            .bind(text)
+            .fetch_one(&self.pool)
+            .await
+            .map_err(map_err)?;
+            count as u64
+        };
+
+        #[derive(sqlx::FromRow)]
+        struct Row {
+            person_id: String,
+            name: String,
+            known_for_department: Option<String>,
+            profile_path: Option<String>,
+            tmdb_person_id: Option<i64>,
+        }
+
+        let rows = sqlx::query_as::<_, Row>(
+            "SELECT ps.person_id, p.name, p.known_for_department, p.profile_path, p.tmdb_person_id
+             FROM people_search ps
+             JOIN persons p ON p.id = ps.person_id
+             WHERE ps.fts @@ plainto_tsquery('english', $1)
+             ORDER BY ts_rank(ps.fts, plainto_tsquery('english', $1)) DESC
+             LIMIT $2 OFFSET $3",
+        )
+        .bind(text)
+        .bind(limit)
+        .bind(offset)
+        .fetch_all(&self.pool)
+        .await
+        .map_err(map_err)?;
+
+        let mut items = Vec::with_capacity(rows.len());
+        for row in rows {
+            let known_for_titles = if let Some(tid) = row.tmdb_person_id {
+                sqlx::query_scalar::<_, String>(
+                    "SELECT m.title FROM movie_cast mc
+                     JOIN movies m ON m.id = mc.movie_id
+                     WHERE mc.tmdb_person_id = $1
+                     ORDER BY mc.billing_order
+                     LIMIT 3",
+                )
+                .bind(tid)
+                .fetch_all(&self.pool)
+                .await
+                .unwrap_or_default()
+            } else {
+                vec![]
+            };
+
+            items.push(PersonSearchHit {
+                person_id: PersonId::from_uuid(
+                    uuid::Uuid::parse_str(&row.person_id).unwrap_or_default(),
+                ),
+                name: row.name,
+                known_for_department: row.known_for_department,
+                profile_path: row.profile_path,
+                known_for_titles,
+            });
+        }
+
+        Ok(Paginated {
+            items,
+            total_count: total,
+            limit: query.page.limit,
+            offset: query.page.offset,
+        })
+    }
+}

crates/adapters/postgres/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "postgres"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+sqlx = { version = "0.8.6", features = [
+    "runtime-tokio-rustls",
+    "postgres",
+    "uuid",
+    "macros",
+    "chrono",
+] }
+domain      = { workspace = true }
+anyhow      = { workspace = true }
+uuid        = { workspace = true }
+chrono      = { workspace = true }
+tracing     = { workspace = true }
+async-trait = { workspace = true }
+tokio       = { workspace = true }
+serde       = { workspace = true, features = ["derive"] }
+serde_json  = { workspace = true }
+futures = { workspace = true }
+bytes = { workspace = true }
+async-stream = { workspace = true }

crates/adapters/postgres/migrations/0001_initial.sql

@@ -0,0 +1,69 @@
+CREATE TABLE IF NOT EXISTS movies (
+    id                   TEXT PRIMARY KEY NOT NULL,
+    external_metadata_id TEXT UNIQUE,
+    title                TEXT NOT NULL,
+    release_year         BIGINT NOT NULL,
+    director             TEXT,
+    poster_path          TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_movies_title_year ON movies (title, release_year);
+
+CREATE TABLE IF NOT EXISTS users (
+    id            TEXT PRIMARY KEY NOT NULL,
+    email         TEXT UNIQUE NOT NULL,
+    username      TEXT UNIQUE NOT NULL,
+    password_hash TEXT NOT NULL,
+    created_at    TIMESTAMPTZ NOT NULL,
+    role          TEXT NOT NULL DEFAULT 'standard'
+);
+
+CREATE TABLE IF NOT EXISTS reviews (
+    id               TEXT PRIMARY KEY NOT NULL,
+    movie_id         TEXT NOT NULL REFERENCES movies(id),
+    user_id          TEXT NOT NULL,
+    rating           BIGINT NOT NULL,
+    comment          TEXT,
+    watched_at       TIMESTAMPTZ NOT NULL,
+    created_at       TIMESTAMPTZ NOT NULL,
+    remote_actor_url TEXT,
+    ap_id            TEXT
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_reviews_ap_id ON reviews (ap_id) WHERE ap_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_reviews_movie_id ON reviews (movie_id);
+CREATE INDEX IF NOT EXISTS idx_reviews_watched_at ON reviews (watched_at);
+
+CREATE TABLE IF NOT EXISTS ap_followers (
+    local_user_id      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    remote_actor_url   TEXT NOT NULL,
+    status             TEXT NOT NULL DEFAULT 'pending',
+    follow_activity_id TEXT,
+    created_at         TIMESTAMPTZ NOT NULL,
+    PRIMARY KEY (local_user_id, remote_actor_url)
+);
+
+CREATE TABLE IF NOT EXISTS ap_following (
+    local_user_id      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    remote_actor_url   TEXT NOT NULL,
+    follow_activity_id TEXT,
+    status             TEXT NOT NULL DEFAULT 'pending',
+    created_at         TIMESTAMPTZ NOT NULL,
+    PRIMARY KEY (local_user_id, remote_actor_url)
+);
+
+CREATE TABLE IF NOT EXISTS ap_remote_actors (
+    url              TEXT PRIMARY KEY,
+    handle           TEXT NOT NULL,
+    inbox_url        TEXT NOT NULL,
+    shared_inbox_url TEXT,
+    display_name     TEXT,
+    fetched_at       TIMESTAMPTZ NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS ap_local_actors (
+    user_id     TEXT PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+    public_key  TEXT NOT NULL,
+    private_key TEXT NOT NULL,
+    created_at  TIMESTAMPTZ NOT NULL
+);

crates/adapters/postgres/migrations/0002_import.sql

@@ -0,0 +1,21 @@
+CREATE TABLE IF NOT EXISTS import_sessions (
+    id            TEXT PRIMARY KEY NOT NULL,
+    user_id       TEXT NOT NULL,
+    parsed_data   TEXT NOT NULL,
+    field_mappings TEXT,
+    row_results   TEXT,
+    created_at    TIMESTAMPTZ NOT NULL,
+    expires_at    TIMESTAMPTZ NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS import_profiles (
+    id             TEXT PRIMARY KEY NOT NULL,
+    user_id        TEXT NOT NULL,
+    name           TEXT NOT NULL,
+    field_mappings TEXT NOT NULL,
+    created_at     TIMESTAMPTZ NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_import_sessions_user_id ON import_sessions (user_id);
+CREATE INDEX IF NOT EXISTS idx_import_sessions_expires_at ON import_sessions (expires_at);
+CREATE INDEX IF NOT EXISTS idx_import_profiles_user_id ON import_profiles (user_id);

crates/adapters/postgres/migrations/0009_user_profile.sql

@@ -0,0 +1,2 @@
+ALTER TABLE users ADD COLUMN bio TEXT;
+ALTER TABLE users ADD COLUMN avatar_path TEXT;

crates/adapters/postgres/migrations/0010_ap_remote_actor_avatar.sql

@@ -0,0 +1 @@
+ALTER TABLE ap_remote_actors ADD COLUMN avatar_url TEXT;

crates/adapters/postgres/migrations/0011_ap_announces.sql

@@ -0,0 +1,8 @@
+CREATE TABLE ap_announces (
+    id           TEXT PRIMARY KEY,
+    object_url   TEXT NOT NULL,
+    actor_url    TEXT NOT NULL,
+    announced_at TEXT NOT NULL
+);
+
+CREATE INDEX idx_ap_announces_object ON ap_announces (object_url);

crates/adapters/postgres/migrations/0012_blocked_domains.sql

@@ -0,0 +1,5 @@
+CREATE TABLE blocked_domains (
+    domain     TEXT PRIMARY KEY,
+    reason     TEXT,
+    blocked_at TEXT NOT NULL
+);

crates/adapters/postgres/migrations/0013_blocked_actors.sql

@@ -0,0 +1,6 @@
+CREATE TABLE blocked_actors (
+    local_user_id    TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    remote_actor_url TEXT NOT NULL,
+    blocked_at       TEXT NOT NULL,
+    PRIMARY KEY (local_user_id, remote_actor_url)
+);