Account reset, Monica import overhaul, duplicate detection, worker clustering

.dialyzer_ignore.exs

@@ -0,0 +1,10 @@
+# Suppress dialyzer warnings produced by generated code in third-party
+# libraries. Re-evaluate this list whenever we upgrade deps.
+
+[
+  # ex_cldr_territories generates type specs that are slightly broader than
+  # the success typing for these zero-arg accessors on Kith.Cldr.Territory.
+  # Reported as `:contract_supertype` against lib/kith/cldr.ex (the backend
+  # module that injects the provider). Not actionable from our code.
+  {"lib/kith/cldr.ex", :contract_supertype}
+]

.env.example

@@ -12,6 +12,13 @@
 # Core — REQUIRED (no defaults)
 # ============================================================
 SECRET_KEY_BASE=generate-with-mix-phx-gen-secret
+# Erlang BEAM distribution cookie. Shared between the app and worker
+# containers so they can cluster for cross-container PubSub broadcasts
+# (LiveView import progress). Generate with one of:
+#   mix phx.gen.secret 32
+#   openssl rand -base64 32
+RELEASE_COOKIE=generate-with-mix-phx-gen-secret
+
 DATABASE_URL=ecto://kith:change_me@postgres:5432/kith_prod
 AUTH_TOKEN_SALT=generate-with-mix-phx-gen-secret
 CLOAK_KEY=generate-32-byte-base64-key
@@ -30,10 +37,7 @@ KITH_HOSTNAME=localhost
 POSTGRES_USER=kith
 POSTGRES_PASSWORD=change_me
 POSTGRES_DB=kith_prod
-# PostgreSQL port — used by Elixir app (dev/test) AND as Docker host port
-# Default 5434 avoids conflicts with standard postgres (5432)
-# Inside Docker, the app container overrides this to 5432 (internal network)
-DB_PORT=5434
+
 POOL_SIZE=10
 # DATABASE_SSL=false
 
@@ -121,3 +125,23 @@ SENTRY_DSN=
 SENTRY_ENVIRONMENT=production
 # Required in production for /metrics endpoint access
 METRICS_TOKEN=generate-a-random-token
+
+# ============================================================
+# Docker Host Ports
+# ============================================================
+# These configure which HOST ports Compose publishes for each service.
+# Defaults match docker-compose.{dev,prod}.yml; override only on conflict.
+# Internal container ports are NOT configurable (services talk to each other
+# on standard ports over the Docker network).
+#
+# Dev stack (docker-compose.dev.yml):
+DB_PORT=5434              # postgres -> host (default 5434, avoids local 5432)
+MAILPIT_SMTP_PORT=1025    # mailpit SMTP listener
+MAILPIT_WEB_PORT=8025     # mailpit web UI -> http://localhost:8025
+MINIO_PORT=9000           # MinIO S3 API
+MINIO_CONSOLE_PORT=9001   # MinIO web console
+APP_PORT=4000             # Phoenix app (only when running via Compose)
+#
+# Prod stack (docker-compose.prod.yml):
+HTTP_PORT=80              # Caddy HTTP (redirects to HTTPS)
+HTTPS_PORT=443            # Caddy HTTPS

CLAUDE.md

@@ -75,7 +75,7 @@ lib/kith/              # Domain layer (contexts + schemas)
   storage/             # File storage abstraction (local disk / S3)
   tasks/               # Personal tasks
   vcard/               # vCard parser + serializer
-  workers/             # 16 Oban workers across 9 queues
+  workers/             # 16 Oban workers across 7 queues
 
 lib/kith_web/          # Web layer
   controllers/api/     # REST API controllers (bearer token auth, cursor pagination)
@@ -106,7 +106,7 @@ default queries. 30-day trash before permanent purge via `ContactPurgeWorker`.
 
 ### Oban background jobs
 Workers live in `lib/kith/workers/`. Queues: default, mailers, reminders, exports,
-imports, immich, purge, photo_sync, api_supplement. Four cron jobs run nightly/weekly.
+imports, immich, purge. Four cron jobs run nightly/weekly.
 Tests use `Oban.Testing` — Oban is disabled in test env.
 
 ### REST API conventions

config/config.exs

@@ -10,6 +10,14 @@ import Config
 # Register .vcf (vCard) MIME type for LiveView uploads
 config :mime, :types, %{"text/vcard" => ["vcf"], "application/json" => ["json"]}
 
+# Default CLDR backend — required so ex_cldr_territories can resolve
+# locale-aware territory data without an explicit per-call backend argument.
+config :ex_cldr, default_backend: Kith.Cldr
+
+# Outbound rate limit for Monica API calls. One below the documented
+# default of 60 req/min leaves a one-call safety margin.
+config :kith, :monica_rate_limit, 55
+
 config :kith, :scopes,
   user: [
     default: true,
@@ -40,8 +48,7 @@ config :kith, Oban,
     exports: 2,
     imports: 2,
     immich: 3,
-    purge: 1,
-    photo_sync: 5
+    purge: 1
   ],
   plugins: [
     Oban.Plugins.Pruner,
@@ -118,7 +125,8 @@ config :logger, :default_formatter,
     :attempt,
     :max_attempts,
     :state,
-    :source
+    :source,
+    :import_id
   ]
 
 # Cloak encryption vault — key set per-environment

config/runtime.exs

@@ -215,6 +215,54 @@ if config_env() == :prod do
       backend: {Hammer.Backend.Redis, [expiry_ms: 60_000 * 60, redis_url: redis_url]}
   end
 
+  # Oban — only the worker container processes jobs in production.
+  # The web container can call `Oban.insert/1` to enqueue jobs, but
+  # runs no queues or plugins (no cron, no pruner) — so it never claims
+  # rows from `oban_jobs`. The worker container keeps the full config
+  # from `config.exs`.
+  #
+  # Dev (`config_env() == :dev`) is unaffected: this block only runs in
+  # `:prod`. Test env is pinned to `testing: :manual` in `config/test.exs`.
+  case System.get_env("KITH_MODE", "web") do
+    "worker" ->
+      :ok
+
+    _web ->
+      config :kith, Oban, queues: false, plugins: false
+  end
+
+  # libcluster — connect this BEAM node to its peer(s) so Phoenix.PubSub
+  # broadcasts span containers (web ↔ worker). Configure via
+  # `KITH_CLUSTER_HOSTS` env var: comma-separated long node names, e.g.
+  # `kith@app,kith@worker`. Leave unset to disable clustering (single-node).
+  #
+  # Each container must also set `RELEASE_DISTRIBUTION=name` and
+  # `RELEASE_NODE=kith@<hostname>` so its actual node name matches the
+  # name listed in `KITH_CLUSTER_HOSTS`. `RELEASE_COOKIE` must be shared.
+  cluster_hosts =
+    case System.get_env("KITH_CLUSTER_HOSTS") do
+      nil ->
+        []
+
+      "" ->
+        []
+
+      str ->
+        str
+        |> String.split(",", trim: true)
+        |> Enum.map(&(&1 |> String.trim() |> String.to_atom()))
+    end
+
+  if cluster_hosts != [] do
+    config :libcluster,
+      topologies: [
+        kith: [
+          strategy: Cluster.Strategy.Epmd,
+          config: [hosts: cluster_hosts]
+        ]
+      ]
+  end
+
   # Sentry error tracking (optional — only when SENTRY_DSN is set)
   if sentry_dsn = System.get_env("SENTRY_DSN") do
     config :sentry,

config/test.exs

@@ -26,6 +26,14 @@ config :kith, KithWeb.Endpoint,
 # Disable Oban in tests (use Oban.Testing)
 config :kith, Oban, testing: :manual
 
+# Use the production libphonenumber metadata in tests so test-only validation
+# rules (NANP "555" prefixes, etc.) don't diverge from real behavior.
+config :ex_phone_number, metadata_file: Path.join("resources", "PhoneNumberMetadata.xml")
+
+# Effectively unthrottled in tests — throttle logic is exercised in
+# isolation in rate_limiter_test.exs, not via the full crawl integration.
+config :kith, :monica_rate_limit, 1_000_000
+
 # Disable PromEx in tests (its Ecto poller conflicts with sandbox ownership)
 config :kith, Kith.PromEx, disabled: true
 

docker-compose.dev.yml

@@ -1,3 +1,14 @@
+# Kith Development Docker Compose
+#
+# Host ports are configurable via a `.env` file in the project root (auto-loaded
+# by Compose). All variables have defaults — `.env` is only needed to override.
+# See `.env.example` ("Docker Host Ports" section) for the full list.
+#
+# Usage:
+#   docker compose -f docker-compose.dev.yml up -d                  # infra only
+#   docker compose -f docker-compose.dev.yml up -d postgres mailpit # subset
+#   docker compose -f docker-compose.dev.yml --profile app up -d    # also run app
+
 services:
   postgres:
     image: postgres:15-alpine
@@ -16,8 +27,8 @@ services:
   mailpit:
     image: axllent/mailpit:latest
     ports:
-      - "1025:1025"
-      - "8025:8025"
+      - "${MAILPIT_SMTP_PORT:-1025}:1025"
+      - "${MAILPIT_WEB_PORT:-8025}:8025"
 
   minio:
     image: minio/minio:latest
@@ -52,7 +63,7 @@ services:
       context: .
       dockerfile: Dockerfile.dev
     ports:
-      - "4000:4000"
+      - "${APP_PORT:-4000}:4000"
     environment:
       DB_HOST: postgres
       DB_PORT: "5432"

docker-compose.prod.yml

@@ -61,6 +61,7 @@ services:
   app:
     image: kith:latest
     command: ["start"]
+    hostname: app
     depends_on:
       migrate:
         condition: service_completed_successfully
@@ -72,6 +73,12 @@ services:
     tmpfs:
       - /tmp:size=64M
     environment:
+      # ── BEAM distribution / clustering (libcluster Epmd strategy) ──
+      RELEASE_COOKIE: ${RELEASE_COOKIE}
+      RELEASE_DISTRIBUTION: sname
+      RELEASE_NODE: kith@app
+      KITH_CLUSTER_HOSTS: kith@app,kith@worker
+      # ── existing env vars unchanged ──
       DATABASE_URL: ${DATABASE_URL}
       SECRET_KEY_BASE: ${SECRET_KEY_BASE}
       KITH_HOSTNAME: ${KITH_HOSTNAME:-localhost}
@@ -135,6 +142,7 @@ services:
   worker:
     image: kith:latest
     command: ["start"]
+    hostname: worker
     security_opt:
       - no-new-privileges:true
     cap_drop:
@@ -148,6 +156,12 @@ services:
       migrate:
         condition: service_completed_successfully
     environment:
+      # ── BEAM distribution / clustering (libcluster Epmd strategy) ──
+      RELEASE_COOKIE: ${RELEASE_COOKIE}
+      RELEASE_DISTRIBUTION: sname
+      RELEASE_NODE: kith@worker
+      KITH_CLUSTER_HOSTS: kith@app,kith@worker
+      # ── existing env vars unchanged ──
       DATABASE_URL: ${DATABASE_URL}
       SECRET_KEY_BASE: ${SECRET_KEY_BASE}
       KITH_HOSTNAME: ${KITH_HOSTNAME:-localhost}
@@ -202,8 +216,8 @@ services:
   caddy:
     image: caddy:2-alpine
     ports:
-      - "80:80"
-      - "443:443"
+      - "${HTTP_PORT:-80}:80"
+      - "${HTTPS_PORT:-443}:443"
     volumes:
       - ./Caddyfile:/etc/caddy/Caddyfile:ro
       - caddy_data:/data