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

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

.dockerignore

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

.env.example

@@ -1,13 +1,55 @@
-DATABASE_URL=sqlite:./dev.db
+# ── Required ──────────────────────────────────────────────────
-BASE_URL=http://localhost:3000
+
-PORT=3000
+# Database (SQLite — file auto-created on first run)
-SECURE_COOKIES=false
+DATABASE_URL=sqlite:///data/movies.db
-JWT_SECRET=
+
-JWT_TTL_SECONDS=
+# 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
-OMDB_API_KEY=
+
-POSTER_FETCH_TIMEOUT_SECONDS=30
+# ── Image Storage (defaults to local filesystem) ─────────────
-MINIO_ENDPOINT=
+
-MINIO_ACCESS_KEY_ID=
+# IMAGE_STORAGE_BACKEND=local    # default
-MINIO_SECRET_ACCESS_KEY=
+# IMAGE_STORAGE_PATH=./images    # default
-MINIO_BUCKET=
+
+# 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

@@ -14,3 +14,6 @@
 .worktrees/
 .superpowers/
 docs/
+
+imgs/
+.sqlx/

.sqlx/query-01a08873b7fa815ad98a56a0902b60414cfcdc2c7a8570351320c4bc425347c6.json

@@ -1,92 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                        r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at\n                 FROM reviews r\n                 INNER JOIN movies m ON m.id = r.movie_id\n                 WHERE r.movie_id = ?\n                 ORDER BY r.watched_at ASC\n                 LIMIT ? OFFSET ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 3
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "01a08873b7fa815ad98a56a0902b60414cfcdc2c7a8570351320c4bc425347c6"
-}

.sqlx/query-026e2afeb573707cb360fcdab8f6137aabfaf603b5ed57b98ac2888b4a0389ff.json

@@ -1,92 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                        r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at\n                 FROM reviews r\n                 INNER JOIN movies m ON m.id = r.movie_id\n                 ORDER BY r.watched_at DESC\n                 LIMIT ? OFFSET ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 2
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "026e2afeb573707cb360fcdab8f6137aabfaf603b5ed57b98ac2888b4a0389ff"
-}

.sqlx/query-0963b9661182e139cd760bbabb0d6ea3a301a2a3adbdfdda4a88f333a1144c77.json

@@ -1,20 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT COUNT(*) FROM reviews",
-  "describe": {
-    "columns": [
-      {
-        "name": "COUNT(*)",
-        "ordinal": 0,
-        "type_info": "Integer"
-      }
-    ],
-    "parameters": {
-      "Right": 0
-    },
-    "nullable": [
-      false
-    ]
-  },
-  "hash": "0963b9661182e139cd760bbabb0d6ea3a301a2a3adbdfdda4a88f333a1144c77"
-}

.sqlx/query-0cd1a7b7255a0ee753deffab7cbb48027d22900a570b98a636c780cb3e2efd23.json

@@ -1,20 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT COUNT(*) FROM reviews WHERE user_id = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "COUNT(*)",
-        "ordinal": 0,
-        "type_info": "Integer"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false
-    ]
-  },
-  "hash": "0cd1a7b7255a0ee753deffab7cbb48027d22900a570b98a636c780cb3e2efd23"
-}

.sqlx/query-167481bb1692cc81531d9a5cd85425e43d09a6df97c335ac347f7cfd61acd171.json

@@ -1,32 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT id, email, password_hash FROM users WHERE email = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "email",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "password_hash",
-        "ordinal": 2,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      false,
-      false
-    ]
-  },
-  "hash": "167481bb1692cc81531d9a5cd85425e43d09a6df97c335ac347f7cfd61acd171"
-}

.sqlx/query-18de90feb13b9f467f06d0ce25332d9ea7eabc99d9f1a44694e5d10762606f82.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "INSERT OR IGNORE INTO users (id, email, password_hash, created_at) VALUES (?, ?, ?, ?)",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 4
-    },
-    "nullable": []
-  },
-  "hash": "18de90feb13b9f467f06d0ce25332d9ea7eabc99d9f1a44694e5d10762606f82"
-}

.sqlx/query-1bc5a51762717e45292626052f0a65ac0b8a001798a2476ea86143c5565df399.json

@@ -1,32 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT id, email, password_hash FROM users WHERE id = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "email",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "password_hash",
-        "ordinal": 2,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      false,
-      false
-    ]
-  },
-  "hash": "1bc5a51762717e45292626052f0a65ac0b8a001798a2476ea86143c5565df399"
-}

.sqlx/query-217854179b4f77897178e6cfae51fb743e5be49ffc59826509be37a7cc81b6ee.json

@@ -1,98 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                    r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at,\n                    u.email AS user_email\n             FROM reviews r\n             INNER JOIN movies m ON m.id = r.movie_id\n             INNER JOIN users u ON u.id = r.user_id\n             ORDER BY r.watched_at DESC\n             LIMIT ? OFFSET ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_email",
-        "ordinal": 13,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 2
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false,
-      false
-    ]
-  },
-  "hash": "217854179b4f77897178e6cfae51fb743e5be49ffc59826509be37a7cc81b6ee"
-}

.sqlx/query-3047579c6ed13ce87aad9b9ce6300c02f0df3516979518976e13f9d9abc6a403.json

@@ -1,50 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT id, external_metadata_id, title, release_year, director, poster_path\n             FROM movies WHERE title = ? AND release_year = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 2
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true
-    ]
-  },
-  "hash": "3047579c6ed13ce87aad9b9ce6300c02f0df3516979518976e13f9d9abc6a403"
-}

.sqlx/query-33d0dae7d16b0635c1c7eb5afd10824bb55af7cc7a854f590d326622863759d1.json

@@ -1,50 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT id, external_metadata_id, title, release_year, director, poster_path\n             FROM movies WHERE id = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true
-    ]
-  },
-  "hash": "33d0dae7d16b0635c1c7eb5afd10824bb55af7cc7a854f590d326622863759d1"
-}

.sqlx/query-47f7cf95ce3450635b643ab710cadba96f40319140834d510bc5207b2552e055.json

@@ -1,92 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                        r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at\n                 FROM reviews r\n                 INNER JOIN movies m ON m.id = r.movie_id\n                 WHERE r.movie_id = ?\n                 ORDER BY r.watched_at DESC\n                 LIMIT ? OFFSET ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 3
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "47f7cf95ce3450635b643ab710cadba96f40319140834d510bc5207b2552e055"
-}

.sqlx/query-4b3074b532342c6356ee0e8e4d8c4a830f016234bb690e1f6240f02824d6d84f.json

@@ -1,20 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT COUNT(*) FROM reviews WHERE movie_id = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "COUNT(*)",
-        "ordinal": 0,
-        "type_info": "Integer"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false
-    ]
-  },
-  "hash": "4b3074b532342c6356ee0e8e4d8c4a830f016234bb690e1f6240f02824d6d84f"
-}

.sqlx/query-4d85f0ff9732576bba77dc84d3885a0002c2b600c34ba4d99f1e1c5e99f35e75.json

@@ -1,20 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT strftime('%Y-%m', watched_at) AS month\n             FROM reviews\n             WHERE user_id = ?\n             GROUP BY month\n             ORDER BY COUNT(*) DESC\n             LIMIT 1",
-  "describe": {
-    "columns": [
-      {
-        "name": "month",
-        "ordinal": 0,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      true
-    ]
-  },
-  "hash": "4d85f0ff9732576bba77dc84d3885a0002c2b600c34ba4d99f1e1c5e99f35e75"
-}

.sqlx/query-5a861b5a934c9831ff17d896fa48feb95e6dab051c5ac55a66f9793482522199.json

@@ -1,92 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                    r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at\n             FROM reviews r\n             INNER JOIN movies m ON m.id = r.movie_id\n             WHERE r.user_id = ?\n             ORDER BY r.watched_at DESC\n             LIMIT ? OFFSET ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 3
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "5a861b5a934c9831ff17d896fa48feb95e6dab051c5ac55a66f9793482522199"
-}

.sqlx/query-630e092fcd33bc312befef352a98225e6e18e6079644b949258a39bf4b0fe3e5.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "INSERT INTO reviews (id, movie_id, user_id, rating, comment, watched_at, created_at)\n             VALUES (?, ?, ?, ?, ?, ?, ?)",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 7
-    },
-    "nullable": []
-  },
-  "hash": "630e092fcd33bc312befef352a98225e6e18e6079644b949258a39bf4b0fe3e5"
-}

.sqlx/query-70ee6050284475b5641af712e5923ba2091b8b70b1885ca6518dfa4bb01fdac2.json

@@ -1,56 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT id, movie_id, user_id, rating, comment, watched_at, created_at\n             FROM reviews WHERE id = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 6,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "70ee6050284475b5641af712e5923ba2091b8b70b1885ca6518dfa4bb01fdac2"
-}

.sqlx/query-7bc4aebcb94547976d3d7e063e4e908fc22b977b3cbf063ee93ffe4648c42011.json

@@ -1,50 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT id, external_metadata_id, title, release_year, director, poster_path\n             FROM movies WHERE external_metadata_id = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true
-    ]
-  },
-  "hash": "7bc4aebcb94547976d3d7e063e4e908fc22b977b3cbf063ee93ffe4648c42011"
-}

.sqlx/query-7d7e23355ee0e442f2aa27e898dcfa40bdc4b09391afe04325f076157d9d84aa.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "INSERT INTO movies (id, external_metadata_id, title, release_year, director, poster_path)\n             VALUES (?, ?, ?, ?, ?, ?)\n             ON CONFLICT(id) DO UPDATE SET\n                 external_metadata_id = excluded.external_metadata_id,\n                 title                = excluded.title,\n                 release_year         = excluded.release_year,\n                 director             = excluded.director,\n                 poster_path          = excluded.poster_path",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 6
-    },
-    "nullable": []
-  },
-  "hash": "7d7e23355ee0e442f2aa27e898dcfa40bdc4b09391afe04325f076157d9d84aa"
-}

.sqlx/query-8d144859b397a842118c2dc4ab30e74015a814ed8185b6f86fbe39e641ab804e.json

@@ -1,92 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                    r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at\n             FROM reviews r\n             INNER JOIN movies m ON m.id = r.movie_id\n             WHERE r.user_id = ?\n             ORDER BY r.watched_at DESC",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "8d144859b397a842118c2dc4ab30e74015a814ed8185b6f86fbe39e641ab804e"
-}

.sqlx/query-a01336632a54099e31686a9cbe6fc53fef1299fc7c7b52be44f99c2302490a22.json

@@ -1,26 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT COUNT(DISTINCT movie_id) AS \"total!: i64\",\n                      AVG(CAST(rating AS REAL)) AS avg_rating\n               FROM reviews WHERE user_id = ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "total!: i64",
-        "ordinal": 0,
-        "type_info": "Integer"
-      },
-      {
-        "name": "avg_rating",
-        "ordinal": 1,
-        "type_info": "Float"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      true
-    ]
-  },
-  "hash": "a01336632a54099e31686a9cbe6fc53fef1299fc7c7b52be44f99c2302490a22"
-}

.sqlx/query-a3f4385bac7f78a9959648fb325d37096c87859ded1762137ce745955f46830c.json

@@ -1,92 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                    r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at\n             FROM reviews r\n             INNER JOIN movies m ON m.id = r.movie_id\n             WHERE r.user_id = ?\n             ORDER BY r.rating DESC, r.watched_at DESC\n             LIMIT ? OFFSET ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 3
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "a3f4385bac7f78a9959648fb325d37096c87859ded1762137ce745955f46830c"
-}

.sqlx/query-aca9e7aaa32c23b4de3f5048d60340e978d31a36be9121da3c59378f2fc1ed8e.json

@@ -1,26 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.director AS \"director!\",\n                          COUNT(*) AS \"count!: i64\"\n                   FROM reviews r\n                   INNER JOIN movies m ON m.id = r.movie_id\n                   WHERE r.user_id = ? AND m.director IS NOT NULL\n                   GROUP BY m.director\n                   ORDER BY COUNT(*) DESC\n                   LIMIT 5",
-  "describe": {
-    "columns": [
-      {
-        "name": "director!",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "count!: i64",
-        "ordinal": 1,
-        "type_info": "Integer"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      true,
-      false
-    ]
-  },
-  "hash": "aca9e7aaa32c23b4de3f5048d60340e978d31a36be9121da3c59378f2fc1ed8e"
-}

.sqlx/query-af883f8b78f185077e2d3dcfaa0a6e62fbdfbf00c97c9b33b699dc631476181d.json

@@ -1,56 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT id, movie_id, user_id, rating, comment, watched_at, created_at\n             FROM reviews WHERE movie_id = ? ORDER BY watched_at ASC",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 6,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "af883f8b78f185077e2d3dcfaa0a6e62fbdfbf00c97c9b33b699dc631476181d"
-}

.sqlx/query-affe1eb261283c09d4b1ce6e684681755f079a044ffec8ff2bd79cfd8efe16b8.json

@@ -1,92 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.id, m.external_metadata_id, m.title, m.release_year, m.director, m.poster_path,\n                        r.id AS review_id, r.movie_id, r.user_id, r.rating, r.comment, r.watched_at, r.created_at\n                 FROM reviews r\n                 INNER JOIN movies m ON m.id = r.movie_id\n                 ORDER BY r.watched_at ASC\n                 LIMIT ? OFFSET ?",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "external_metadata_id",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "title",
-        "ordinal": 2,
-        "type_info": "Text"
-      },
-      {
-        "name": "release_year",
-        "ordinal": 3,
-        "type_info": "Integer"
-      },
-      {
-        "name": "director",
-        "ordinal": 4,
-        "type_info": "Text"
-      },
-      {
-        "name": "poster_path",
-        "ordinal": 5,
-        "type_info": "Text"
-      },
-      {
-        "name": "review_id",
-        "ordinal": 6,
-        "type_info": "Text"
-      },
-      {
-        "name": "movie_id",
-        "ordinal": 7,
-        "type_info": "Text"
-      },
-      {
-        "name": "user_id",
-        "ordinal": 8,
-        "type_info": "Text"
-      },
-      {
-        "name": "rating",
-        "ordinal": 9,
-        "type_info": "Integer"
-      },
-      {
-        "name": "comment",
-        "ordinal": 10,
-        "type_info": "Text"
-      },
-      {
-        "name": "watched_at",
-        "ordinal": 11,
-        "type_info": "Text"
-      },
-      {
-        "name": "created_at",
-        "ordinal": 12,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 2
-    },
-    "nullable": [
-      false,
-      true,
-      false,
-      false,
-      true,
-      true,
-      false,
-      false,
-      false,
-      false,
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "affe1eb261283c09d4b1ce6e684681755f079a044ffec8ff2bd79cfd8efe16b8"
-}

.sqlx/query-d5d2a81306488a8cee5654cea7e14d76d76ecc7d2190ffb73d12bec2874111d2.json

@@ -1,20 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT m.director\n             FROM reviews r\n             INNER JOIN movies m ON m.id = r.movie_id\n             WHERE r.user_id = ? AND m.director IS NOT NULL\n             GROUP BY m.director\n             ORDER BY COUNT(*) DESC\n             LIMIT 1",
-  "describe": {
-    "columns": [
-      {
-        "name": "director",
-        "ordinal": 0,
-        "type_info": "Text"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      true
-    ]
-  },
-  "hash": "d5d2a81306488a8cee5654cea7e14d76d76ecc7d2190ffb73d12bec2874111d2"
-}

.sqlx/query-e431381ad41c1c2f7b9c89509d5e3f4c19cb52dcfff66772145cd80c53c16883.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "DELETE FROM movies WHERE id = ?",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": []
-  },
-  "hash": "e431381ad41c1c2f7b9c89509d5e3f4c19cb52dcfff66772145cd80c53c16883"
-}

.sqlx/query-f259059d76f29cade94e249735d37ef4993fe5bff095dc43e681b848a398f318.json

@@ -1,38 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT u.id,\n                      u.email,\n                      COUNT(DISTINCT r.movie_id) AS \"total_movies!: i64\",\n                      AVG(CAST(r.rating AS REAL)) AS avg_rating\n               FROM users u\n               LEFT JOIN reviews r ON r.user_id = u.id\n               GROUP BY u.id, u.email\n               ORDER BY u.email ASC",
-  "describe": {
-    "columns": [
-      {
-        "name": "id",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "email",
-        "ordinal": 1,
-        "type_info": "Text"
-      },
-      {
-        "name": "total_movies!: i64",
-        "ordinal": 2,
-        "type_info": "Integer"
-      },
-      {
-        "name": "avg_rating",
-        "ordinal": 3,
-        "type_info": "Float"
-      }
-    ],
-    "parameters": {
-      "Right": 0
-    },
-    "nullable": [
-      false,
-      false,
-      false,
-      true
-    ]
-  },
-  "hash": "f259059d76f29cade94e249735d37ef4993fe5bff095dc43e681b848a398f318"
-}

.sqlx/query-f84e5483ca4210aec67b38cc1a9de4a42c12891025236abc48ea4f175292a6cc.json

@@ -1,12 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "DELETE FROM reviews WHERE id = ?",
-  "describe": {
-    "columns": [],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": []
-  },
-  "hash": "f84e5483ca4210aec67b38cc1a9de4a42c12891025236abc48ea4f175292a6cc"
-}

.sqlx/query-fdd5b522f26b5e0ce62f76c774fbb606fd9ee9884f4457831f693a0df3609317.json

@@ -1,32 +0,0 @@
-{
-  "db_name": "SQLite",
-  "query": "SELECT strftime('%Y-%m', watched_at) AS \"month!\",\n                          AVG(CAST(rating AS REAL)) AS \"avg_rating!: f64\",\n                          COUNT(*) AS \"count!: i64\"\n                   FROM reviews\n                   WHERE user_id = ? AND watched_at >= datetime('now', '-12 months')\n                   GROUP BY \"month!\"\n                   ORDER BY \"month!\" ASC",
-  "describe": {
-    "columns": [
-      {
-        "name": "month!",
-        "ordinal": 0,
-        "type_info": "Text"
-      },
-      {
-        "name": "avg_rating!: f64",
-        "ordinal": 1,
-        "type_info": "Float"
-      },
-      {
-        "name": "count!: i64",
-        "ordinal": 2,
-        "type_info": "Integer"
-      }
-    ],
-    "parameters": {
-      "Right": 1
-    },
-    "nullable": [
-      true,
-      false,
-      false
-    ]
-  },
-  "hash": "fdd5b522f26b5e0ce62f76c774fbb606fd9ee9884f4457831f693a0df3609317"
-}

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

@@ -4,18 +4,41 @@ members = [
     "crates/adapters/event-publisher",
     "crates/adapters/metadata",
     "crates/adapters/poster-fetcher",
-    "crates/adapters/poster-storage",
+    "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/adapters/tmdb-enrichment",
+    "crates/adapters/image-converter",
     "crates/domain",
-    "crates/presentation", "crates/tui",
+    "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"
@@ -24,25 +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",
-    "macros",
 ] }
+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" }
+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" }
-poster-storage = { path = "crates/adapters/poster-storage" }
+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

@@ -1,54 +1,92 @@
+# ----- 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
 
-RUN apt-get update && apt-get install -y --no-install-recommends sqlite3 && rm -rf /var/lib/apt/lists/*
-
 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/poster-storage/Cargo.toml    crates/adapters/poster-storage/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
 
-# sqlx macros verify queries at compile time; create a real DB from migrations
+# All sqlx queries use the runtime API (no query! macros), so no database
-RUN sqlite3 /build/dev.db \
+# or .sqlx cache is needed at compile time.
-      < crates/adapters/sqlite/migrations/0001_initial.sql && \
+#
-    sqlite3 /build/dev.db \
+# To build with PostgreSQL backend instead:
-      < crates/adapters/sqlite/migrations/0002_users.sql
+#   --build-arg FEATURES=postgres,postgres-federation
-
+# To add NATS support (EVENT_BUS_BACKEND=nats):
-ENV DATABASE_URL=sqlite:///build/dev.db
+#   --build-arg FEATURES=sqlite,sqlite-federation,nats
-
+ARG FEATURES=sqlite,sqlite-federation
-RUN cargo build --release -p presentation
+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
 

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

@@ -1,85 +1,305 @@
 # Movies Diary
 
-A self-hosted, server-side rendered movie logging system. Built in Rust — no JavaScript, no SPA, just HTML forms and an RSS feed. Designed to run as a lightweight widget embedded on a personal site.
+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 and a 0–5 rating
+- 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 (S3-compatible)
+- Background poster fetching and storage (local filesystem or S3-compatible)
-- RSS/Atom feed for public subscription
+- 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)
-- Zero JavaScript
+- 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 / business logic orchestration
+application         — use cases (commands + queries), business logic orchestration; handlers delegate here for all domain logic
-presentation  — Axum HTTP router, wires all adapters together
+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 via sqlx
+  sqlite               — SQLite repository + connection factory
-  metadata    — OMDb HTTP client
+  postgres             — PostgreSQL repository + connection factory
+  metadata             — TMDB / OMDb HTTP client
   poster-fetcher       — downloads poster images
-  poster-storage — uploads posters to S3-compatible storage
+  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
-  event-publisher — async event channel for background poster sync
+  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
-- An S3-compatible object store (e.g. MinIO) for poster storage
+- 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)
 
-## Environment Variables
+## Configuration
 
-Copy and fill in the following (e.g. in a `.env` file):
+Copy `.env.example` to `.env` and set the values below. Required fields must be set before the server will start.
 
-```env
+| Variable | Default | Required | Description |
-# Database
+|---|---|---|---|
-DATABASE_URL=sqlite://movies.db
+| `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`) |
 
-# Authentication
+The `worker` binary must run alongside `presentation` to process events:
-JWT_SECRET=change-me
-JWT_TTL_SECONDS=86400
 
-# OMDb metadata
+```bash
-OMDB_API_KEY=your-key
+cargo run -p worker
-
-# Poster storage (S3-compatible)
-MINIO_ENDPOINT=http://localhost:9000
-MINIO_BUCKET=posters
-MINIO_REGION=us-east-1
-MINIO_ACCESS_KEY_ID=minioadmin
-MINIO_SECRET_ACCESS_KEY=minioadmin
-
-# Optional
-ALLOW_REGISTRATION=false
-POSTER_FETCH_TIMEOUT_SECONDS=10
-EVENT_CHANNEL_BUFFER=32
-RUST_LOG=presentation=debug,tower_http=debug
 ```
 
 ## Run
 
 ```bash
-cargo run -p presentation
+cargo run -p presentation   # HTTP server (0.0.0.0:3000)
+cargo run -p worker         # event worker (poster sync, in a separate terminal)
 ```
 
-Server listens on `0.0.0.0:3000`.
+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
+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/src/lib.rs

@@ -1,8 +1,8 @@
-use async_trait::async_trait;
 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;
@@ -30,8 +30,11 @@ impl AuthConfig {
         let ttl_seconds = std::env::var("JWT_TTL_SECONDS")
             .ok()
             .and_then(|v| v.parse().ok())
-            .unwrap_or(86400u64);
+            .unwrap_or(900u64);
-        Ok(Self { secret, ttl_seconds })
+        Ok(Self {
+            secret,
+            ttl_seconds,
+        })
     }
 }
 
@@ -102,3 +105,14 @@ impl PasswordHasher for Argon2PasswordHasher {
             .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

@@ -7,4 +7,4 @@ edition = "2024"
 domain      = { workspace = true }
 async-trait = { workspace = true }
 tokio       = { workspace = true }
-tracing     = { workspace = true }
+futures     = { workspace = true }

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

@@ -1,7 +1,16 @@
 use async_trait::async_trait;
-use domain::{errors::DomainError, events::DomainEvent, ports::EventPublisher};
+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,
 }
@@ -16,11 +25,6 @@ impl EventPublisherConfig {
     }
 }
 
-#[async_trait]
-pub trait EventHandler: Send + Sync {
-    async fn handle(&self, event: &DomainEvent) -> Result<(), DomainError>;
-}
-
 pub struct ChannelEventPublisher {
     sender: mpsc::Sender<DomainEvent>,
 }
@@ -35,49 +39,30 @@ impl EventPublisher for ChannelEventPublisher {
     }
 }
 
-pub struct EventWorker {
+struct NoopAck;
-    receiver: mpsc::Receiver<DomainEvent>,
+
-    handlers: Vec<Box<dyn EventHandler>>,
+#[async_trait]
+impl AckHandle for NoopAck {
+    async fn ack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
+    async fn nack(&self) -> Result<(), DomainError> {
+        Ok(())
+    }
 }
 
-impl EventWorker {
+pub struct ChannelEventConsumer {
-    pub async fn run(mut self) {
+    receiver: Arc<Mutex<mpsc::Receiver<DomainEvent>>>,
-        while let Some(event) = self.receiver.recv().await {
+}
-            match &event {
+
-                DomainEvent::ReviewLogged {
+impl EventConsumer for ChannelEventConsumer {
-                    review_id,
+    fn consume(&self) -> BoxStream<'_, Result<EventEnvelope, DomainError>> {
-                    movie_id,
+        let receiver = Arc::clone(&self.receiver);
-                    user_id,
+        Box::pin(stream::unfold(receiver, |rx| async move {
-                    rating,
+            let event = rx.lock().await.recv().await?;
-                    watched_at,
+            let envelope = EventEnvelope::new(event, Box::new(NoopAck));
-                } => {
+            Some((Ok(envelope), rx))
-                    tracing::info!(
+        }))
-                        review_id  = %review_id.value(),
-                        movie_id   = %movie_id.value(),
-                        user_id    = %user_id.value(),
-                        rating     = rating.value(),
-                        watched_at = %watched_at,
-                        "event: review_logged"
-                    );
-                }
-                DomainEvent::MovieDiscovered {
-                    movie_id,
-                    external_metadata_id,
-                } => {
-                    tracing::info!(
-                        movie_id    = %movie_id.value(),
-                        external_id = external_metadata_id.value(),
-                        "event: movie_discovered"
-                    );
-                }
-            }
-            for handler in &self.handlers {
-                if let Err(e) = handler.handle(&event).await {
-                    tracing::error!("event handler error: {e}");
-                }
-            }
-        }
-        tracing::info!("event worker shut down");
     }
 }
 
@@ -92,118 +77,16 @@ impl EventPublisher for NoopEventPublisher {
 
 pub fn create_event_channel(
     config: EventPublisherConfig,
-    handlers: Vec<Box<dyn EventHandler>>,
+) -> (ChannelEventPublisher, ChannelEventConsumer) {
-) -> (ChannelEventPublisher, EventWorker) {
     let (tx, rx) = mpsc::channel(config.channel_buffer);
     (
         ChannelEventPublisher { sender: tx },
-        EventWorker {
+        ChannelEventConsumer {
-            receiver: rx,
+            receiver: Arc::new(Mutex::new(rx)),
-            handlers,
         },
     )
 }
 
 #[cfg(test)]
-mod tests {
+#[path = "tests/lib.rs"]
-    use super::*;
+mod tests;
-    use std::sync::{Arc, Mutex};
-    use domain::{
-        errors::DomainError,
-        events::DomainEvent,
-        value_objects::{ExternalMetadataId, MovieId},
-    };
-
-    struct RecordingHandler {
-        calls: Arc<Mutex<Vec<String>>>,
-    }
-
-    #[async_trait]
-    impl EventHandler for RecordingHandler {
-        async fn handle(&self, event: &DomainEvent) -> Result<(), DomainError> {
-            let label = match event {
-                DomainEvent::MovieDiscovered { .. } => "movie_discovered",
-                DomainEvent::ReviewLogged { .. } => "review_logged",
-            };
-            self.calls.lock().unwrap().push(label.to_string());
-            Ok(())
-        }
-    }
-
-    #[tokio::test]
-    async fn single_handler_receives_event() {
-        let calls = Arc::new(Mutex::new(vec![]));
-        let handler = RecordingHandler { calls: Arc::clone(&calls) };
-        let config = EventPublisherConfig { channel_buffer: 8 };
-        let (publisher, worker) = create_event_channel(config, vec![Box::new(handler)]);
-
-        let handle = tokio::spawn(worker.run());
-
-        let event = DomainEvent::MovieDiscovered {
-            movie_id: MovieId::generate(),
-            external_metadata_id: ExternalMetadataId::new("tt1234567".into()).unwrap(),
-        };
-        publisher.publish(&event).await.unwrap();
-        drop(publisher);
-        handle.await.unwrap();
-
-        assert_eq!(*calls.lock().unwrap(), vec!["movie_discovered"]);
-    }
-
-    #[tokio::test]
-    async fn multiple_handlers_all_receive_event() {
-        let calls1 = Arc::new(Mutex::new(vec![]));
-        let calls2 = Arc::new(Mutex::new(vec![]));
-        let handler1 = RecordingHandler { calls: Arc::clone(&calls1) };
-        let handler2 = RecordingHandler { calls: Arc::clone(&calls2) };
-        let config = EventPublisherConfig { channel_buffer: 8 };
-        let (publisher, worker) = create_event_channel(
-            config,
-            vec![Box::new(handler1), Box::new(handler2)],
-        );
-
-        let handle = tokio::spawn(worker.run());
-
-        let event = DomainEvent::MovieDiscovered {
-            movie_id: MovieId::generate(),
-            external_metadata_id: ExternalMetadataId::new("tt9999999".into()).unwrap(),
-        };
-        publisher.publish(&event).await.unwrap();
-        drop(publisher);
-        handle.await.unwrap();
-
-        assert_eq!(calls1.lock().unwrap().len(), 1);
-        assert_eq!(calls2.lock().unwrap().len(), 1);
-    }
-
-    #[tokio::test]
-    async fn handler_error_does_not_stop_worker() {
-        struct FailingHandler;
-        #[async_trait]
-        impl EventHandler for FailingHandler {
-            async fn handle(&self, _: &DomainEvent) -> Result<(), DomainError> {
-                Err(DomainError::InfrastructureError("boom".into()))
-            }
-        }
-
-        let calls = Arc::new(Mutex::new(vec![]));
-        let good = RecordingHandler { calls: Arc::clone(&calls) };
-        let config = EventPublisherConfig { channel_buffer: 8 };
-        let (publisher, worker) = create_event_channel(
-            config,
-            vec![Box::new(FailingHandler), Box::new(good)],
-        );
-
-        let handle = tokio::spawn(worker.run());
-
-        let event = DomainEvent::MovieDiscovered {
-            movie_id: MovieId::generate(),
-            external_metadata_id: ExternalMetadataId::new("tt0000001".into()).unwrap(),
-        };
-        publisher.publish(&event).await.unwrap();
-        drop(publisher);
-        handle.await.unwrap();
-
-        assert_eq!(calls.lock().unwrap().len(), 1);
-    }
-}

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,6 +4,7 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
+anyhow = { workspace = true }
 async-trait = { workspace = true }
 reqwest = { workspace = true }
 serde = { workspace = true }

crates/adapters/metadata/src/lib.rs

@@ -7,6 +7,7 @@ use domain::{
 };
 
 mod omdb;
+mod tmdb;
 
 pub(crate) struct ProviderMovie {
     pub imdb_id: ExternalMetadataId,
@@ -31,6 +32,12 @@ impl MetadataClientImpl {
             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]
@@ -40,7 +47,13 @@ impl MetadataClient for MetadataClientImpl {
         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))
+        Ok(Movie::new(
+            Some(pm.imdb_id),
+            pm.title,
+            pm.release_year,
+            pm.director,
+            None,
+        ))
     }
 
     async fn get_poster_url(
@@ -52,3 +65,14 @@ impl MetadataClient for MetadataClientImpl {
         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

@@ -56,9 +56,9 @@ impl MetadataProvider for OmdbProvider {
                     params.append_pair("i", id.value());
                 }
                 MetadataSearchCriteria::Title { title, year } => {
-                    params.append_pair("t", title);
+                    params.append_pair("t", title.value());
                     if let Some(y) = year {
-                        params.append_pair("y", &y.to_string());
+                        params.append_pair("y", &y.value().to_string());
                     }
                 }
             }
@@ -101,8 +101,8 @@ impl MetadataProvider for OmdbProvider {
             .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)
+        let release_year =
-            .map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
+            ReleaseYear::new(year).map_err(|e| DomainError::InfrastructureError(e.to_string()))?;
 
         let director = match resp.director.as_str() {
             "N/A" | "" => None,
@@ -114,6 +114,12 @@ impl MetadataProvider for OmdbProvider {
             url => PosterUrl::new(url.to_string()).ok(),
         };
 
-        Ok(ProviderMovie { imdb_id, title, release_year, director, poster_url })
+        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

@@ -1,5 +1,5 @@
 [package]
-name = "poster-storage"
+name = "object-storage"
 version = "0.1.0"
 edition = "2024"
 
@@ -8,6 +8,8 @@ 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"
 

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;