amputatorbot-migration

AmputatorBot → Devvit Migration Plan v7

Status: living draft — M1–M5 shipped, M6 (cloud deploy + launch) in progress. Drafted: 2026-05-25 Budget cap: €15/month total

---

Working style — READ THIS FIRST

Dev likes to be consulted on architectural decisions before code is written. For any choice that's:

• About which library, framework, or pattern to use
• About data model design or schema decisions
• About how to structure a new module or layer
• About cost vs. complexity tradeoffs
• About deviating from this plan in any non-trivial way

…stop and ask before proceeding. Surface the options, explain the tradeoffs honestly (including pushback if you disagree), and wait for a decision. Mechanical implementation work doesn't need consultation; architectural shape does.

External actions Dev does manually, not Claude:

• Running queries against the production MySQL / Postgres databases (Claude can write the SQL; Dev executes it)
• Signing up for services (Scaleway, Reddit developer account, App Directory submission, bounty program registration)
• Anything that hits an external account with Dev's identity (OAuth logins, devvit login, scw init, billing changes)
• DNS changes in Cloudflare
• Stopping/starting the production PythonAnywhere bot
• git push to production-affecting remotes
• Publishing the Devvit app (devvit upload --publish)

Claude prepares the exact commands and tells Dev when to run them. Reading code, writing code, running local tests, local Docker builds, local cargo/npm — Claude does those.

---

Project context

What AmputatorBot is: A Reddit bot that detects AMP URLs in comments/posts/PMs and replies with the canonical (non-AMP) link. Maintained by Dev (u/Killed_Mufasa). Live at https://github.com/jvdburgh/AmputatorBot. ~181 GitHub stars. Runs at scale. Reddit's Developer Platform migration program offers $1,000 to bots that migrate from the Data API to Devvit by Dec 31, 2026.

What's being migrated:

• Reddit bot (Python + PRAW) → Devvit app (TypeScript, @devvit/web)
• HTTP API (Flask) → Rust (Axum + Mozilla-Readability-port + sqlx)
• Website (Flask + Bootstrap) → Astro 5 + Tailwind 4 + shadcn/ui
• Database (MySQL on PythonAnywhere) → Postgres 17 on Scaleway Managed Database
• Host (PythonAnywhere) → Scaleway (Paris, France — EU-originated managed cloud)

Architectural model change: Devvit is per-subreddit opt-in, not global. Mods install the app per sub; it can't see content where it isn't installed. Replies post as per-install app identity, not u/AmputatorBot. Accepted. Estimated reply-volume drop: 30–60%.

Goals (user-stated):

1. Modern stack, learn things along the way (Rust, Devvit, Astro/Tailwind4/shadcn)
2. API contract stays backwards-compatible
3. During the rewrite (M1–M5), the old bot kept running on PythonAnywhere so the new side could break freely with no user-facing consequence. The old bot is retired at the M6 cutover — no permanent parallel-run.
4. Sledgehammer through the rewrite; preserve old code in praw-python-archive/

---

Locked decisions

---

Why these choices

The rationale behind the decisions above. Each was a deliberate pick over a credible alternative.

• Rust + Axum over Node/TS or Python. Single static binary, no runtime, no virtualenv, no node_modules. The hard parts of Rust (lifetimes, unsafe, advanced generics) don't really show up in this kind of service (HTTP fetch + regex + HTML query + DB write), so the learning curve is mostly Result/?, async/Tokio, and sqlx macros — all worth knowing. Axum 0.8 is the consensus framework in 2026 (Tokio + Hyper + Tower middleware). sqlx gives compile-time-checked queries.

C- dom_smoothie over rs-trafilatura and other Readability ports. The existing bot uses newspaper3k + difflib.SequenceMatcher for guess-and-check confidence scoring (helpers/article_comparer.py). For the Rust port we want a Mozilla-Readability-aligned extractor. The candidates as of May 2026:

• dom_smoothie 0.17 (last release 2026-03, ~40k recent downloads, repo niklak/dom_smoothie) — closely follows readability.js, two modes (Mozilla-mimic + custom), JSON-LD + OG metadata parsing, actively maintained.
• readability 0.3 by kumabook (last release 2023-12, stagnant) — port of arc90's original Readability (predates Mozilla's fork). Higher historical download count but unmaintained.
• readable-readability 0.4 (last release 2022-12, stagnant).
• llm_readability 0.0.17 (active but 0.0.x — too early-stage for production).

dom_smoothie wins on active maintenance + explicit Mozilla readability.js lineage. We use its standard (Mozilla-mimic) mode for similarity scoring. No spike needed; pin to dom_smoothie = "0.17" in M2.

• No auth, anywhere. Production currently has authorization_required=False on /convert (AmputatorBotCom/main.py:162). No one depends on bearer auth, and with opt-out gone the backend has no privileged routes at all. Cloudflare handles abuse.

• Cloudflare-side rate limiting. Cloudflare already fronts the domain. Per-IP rules there are zero Rust code and configurable without redeploy.

• No opt-out mechanic, no modmail, no DMs. Users and mods who don't want the bot can block the per-install app identity or uninstall the app respectively. That's enough — building a separate opt-out registry on top is mechanism we don't need. Cuts the modmail trigger, the welcome modmail, the bearer-auth privileged routes, the optouts table, the Redis opt-out cache, and the legacy "summoned via DM" pathway in one stroke.

• Modernize the DB schema during migration. The migration tool runs once. Cleaning up VARCHAR(4000) → TEXT, adding the indices that models/table.py lacks, and dropping any dead columns is cheap to do once and never again.

• Logs-only observability initially. Scaleway Cockpit (the built-in log + metric stream) is enough to grep when issues show up. Add Sentry/Bugsink only if log-grep becomes painful.

• Port the existing AMP detection + canonical methods, but fix false positives in place. The 14 substring patterns (static/static.py) are noisy (& HTML entities, lamp_post, streaming_amplifier). The 10 canonical methods and their order in helpers/canonical_methods.py are well-tuned and stay. The improvements happen at the AMP-detection layer (word boundaries, scoping to URL components after extraction) and in fast-path allowlists for high-signal markers.

• Refresh bot reply markdown. One-time design pass on a new template, applied at migration. Doesn't need to look identical to the old bot.

• git mv everything old into praw-python-archive/ in one commit. Sledgehammer. Old PRAW bot keeps running on PythonAnywhere during M1–M5 so the new side can break freely; it gets stopped at the M6 cutover.

• Six milestones, no calendar. Local-first: M1–M5 are all local development (scaffolding, canonical engine, API parity, Astro, Devvit playtest). M6 is the cloud + public launch (Scaleway provisioning, prod data migration, DNS cutover, App Directory, old-bot retirement). No external deadline (bounty is Dec 2026). Old bot covers production until cutover. Learning Rust + Devvit + Astro is part of the goal, so pacing should match comprehension, not a schedule.

---

Architecture

┌─────────────────────────────────────────────┐
│ Subreddit X (mod installed amputatorbot)    │
│   Comments / posts                          │
└──────────────┬──────────────────────────────┘
               │ Devvit triggers (HTTP POST to internal routes)
               ▼
┌─────────────────────────────────────────────┐
│ Devvit app (Node, @devvit/web)              │
│   Runs on Reddit infrastructure             │
│                                             │
│   Internal HTTP routes:                     │
│     /internal/triggers/comment-submit       │
│     /internal/triggers/post-submit          │
│                                             │
│   Devvit Redis (built-in):                  │
│     handled:{commentId}  TTL 1h             │
│                                             │
│   Per-install settings:                     │
│     autoReply, customFooter, killSwitch     │
│                                             │
│   Allowlist (devvit.json):                  │
│     http.domains: ["www.amputatorbot.com"]  │
└──────────────┬──────────────────────────────┘
               │ HTTPS (no auth):
               │   GET /api/v1/convert?q=...&gac=true&md=3
               ▼
┌─────────────────────────────────────────────┐
│ Cloudflare (DNS + rate limiting + WAF)      │
└──────────────┬──────────────────────────────┘
               ▼
┌─────────────────────────────────────────────┐
│ Scaleway (Paris/AMS, EU)                    │
│ www.amputatorbot.com                        │
│                                             │
│   Rust backend (Axum 0.8) — single binary   │
│     /api/v1/convert    (existing contract)  │
│     /api/v2/convert    (camelCase JSON)     │
│     /api/v2/stats      (cached count)       │
│     /api/v2/health                          │
│     fallback → Astro static (ServeDir)      │
│                                             │
│   Canonical-finding (10 methods, same       │
│   order as Python impl):                    │
│     REL, CANURL, OG_URL,                    │
│     GOOGLE_MANUAL_REDIRECT, GOOGLE_JS_…,    │
│     BING_ORIGINAL_URL, SCHEMA_MAINENTITY,   │
│     TCO_PAGETITLE, META_REDIRECT,           │
│     GUESS_AND_CHECK (article-similarity     │
│       confidence via Mozilla Readability),  │
│     DATABASE (cache lookup)                 │
│                                             │
│   Postgres 17 (Scaleway Managed Database):  │
│     links                                   │
└─────────────────────────────────────────────┘

Why single Rust service serving API + static site: Devvit's allowlist is domain-level. One Scaleway Serverless Container keeps the deploy story simple. tower-http::ServeDir as fallback is ~5 lines.

---

API contract

Two endpoints ship side by side:

• GET /api/v1/convert — legacy contract preserved (snake_case query string, snake_case JSON response). GET-only since the legacy bot was always query-string based; POST is v2-only. Deprecated for new callers but supported indefinitely so external services don't break.
• POST /api/v2/convert — modern contract: JSON body in camelCase, JSON response in camelCase. entryType is a body field instead of a header. Strict validation (unknown fields → 422). Recommended for Devvit (M5) + website (M4) + new external callers.

Every write to the links cache records api_version (1 or 2 — NULL for the pre-v7 legacy bot's CSV-imported rows) so adoption is queryable: SELECT api_version, COUNT(*) FROM links GROUP BY 1.

v1 — GET /api/v1/convert (from AmputatorBotCom/main.py:161+)

Query params:

• q (required) — URL or text containing URLs
• gac — guess-and-check, default true
• md — max depth, default static.MAX_DEPTH (port the value)
• gc — generate reply markdown in response, default false
• r — redirect mode (303 to canonical instead of returning JSON), default false

URL encoding behavior — both must work

The API supports two callers: well-behaved clients that percent-encode their URLs, and humans who paste raw URLs into a browser address bar. The v7 contract:

1. Encoded URLs always work, regardless of q's position in the param list. ?q=https%3A%2F%2F...&gac=true and ?gac=true&q=https%3A%2F%2F... are both valid.
2. Unencoded URLs work when q is the last param. ?gac=true&q=https://example.eu/article?id=1 is fine — the URL's tail params (?id=1) are preserved. q between other known params is best-effort.

The legacy code used a %20-presence heuristic to distinguish the two cases, which silently broke for any encoded URL that didn't happen to contain a literal space (the common case once you actually look at production traffic). The v7 port replaces that with the cleaner ://-in-strip-output check: try the raw-strip path (handles unencoded URLs with tail params); if its output has a literal ://, use it; otherwise fall back to args-decoded q (handles encoded URLs).

The Rust impl is in backend/src/routes/query_parser.rs. Test fixtures must cover:

• Encoded URL, q first
• Encoded URL, q last
• Encoded URL containing no spaces or special chars (the case the legacy heuristic silently broke)
• Unencoded URL, q last, with URL-internal ? and &
• Unencoded URL with what looks like gac= or md= literally in the path (documented limitation — the strip pass would mangle these; rare in real traffic)

Response (200): array of Link objects matching models/link.py. Each contains:

{
  "origin": { "domain": "google", "url": "...", "is_amp": true, "is_cached": true, "is_valid": true },
  "canonicals": [ /* array of {domain, url, type, is_amp, is_cached, is_valid, is_alt, url_similarity} */ ],
  "canonical":   { /* best pick, same shape as canonicals[i] */ },
  "amp_canonical": null  // or a Canonical when origin is the AMP page itself
}

Confirmed against live API probe — same shape, same type enum values (DATABASE, GOOGLE_MANUAL_REDIRECT, REL, CANURL, OG_URL, etc. from CanonicalType in models/link.py:23-34).

Status codes:

• 200 — at least one canonical found
• 303 — redirect mode (r=true) successful
• 400 — missing q
• 406 — no AMP detected (result_code=error_no_amp)
• 500 — unknown error

The legacy 560 ("no canonicals") and 561 ("problematic domain") codes are collapsed to 200 + null canonical (per v7 web-standards decision). The 561 problematic-domain list is dropped entirely.

Bearer auth: present in code, currently authorization_required=False. Drop in v7 entirely.

v2 — POST /api/v2/convert

Modern JSON-in / JSON-out contract for new callers.

Request body (Content-Type: application/json):

{
  "query": "https://www.google.com/amp/s/example.eu/article",  // required
  "guessAndCheck": true,        // optional, default true
  "maxDepth": 3,                // optional, default 3
  "redirect": false,            // optional, default false
  "entryType": "COMMENT"        // optional, default "API". One of:
                                //   "API", "COMMENT", "SUBMISSION",
                                //   "MENTION", "ONLINE".
}

Strict validation (#[serde(deny_unknown_fields)] on the deserializer):

• Unknown field names → 422 Unprocessable Entity with a "expected one of …" message
• Invalid entryType values → 422
• Wrong casing on enum values ("comment" vs "COMMENT") → 422

Response (200): array of Link objects, identical structure to v1 but every key recursively camelCased.

[
  {
    "origin": { "domain": "google", "url": "...", "isAmp": true, "isCached": true, "isValid": true },
    "canonicals": [ /* {domain, url, type, isAmp, isCached, isValid, isAlt, urlSimilarity} */ ],
    "canonical": { /* best pick, same shape as canonicals[i] */ },
    "ampCanonical": null
  }
]

Error response shape: same errorMessage + resultCode body, camelCased.

Status codes: same as v1 — 200, 303, 400, 406, 500 — plus 422 for body-deserialize failures (Axum's default JsonRejection).

Cache schema annotation

The links table grows a nullable api_version SMALLINT column (migration 002_api_version.sql):

• NULL — pre-v7 legacy bot's rows (CSV-imported from PythonAnywhere)
• 1 — /api/v1/convert writes
• 2 — /api/v2/convert writes

Adding the column on the production 1.7M-row table is metadata-only in Postgres (nullable, no default → no rewrite), millisecond-scale even on Scaleway's smallest tier.

---

AMP detection — port + improve

Existing logic: 14 substring patterns in static/static.py:8-9 (/amp, amp/, .amp, amp., ?amp, amp?, =amp, amp=, &amp, amp&, %amp, amp%, _amp, amp_), scanned against lowercase body in helpers/checker_utils.py:check_if_amp.

Port direction: keep the spirit (broad keyword match) but reduce false positives:

• &amp → require not followed by ; (HTML entity)
• _amp / amp_ → require word boundary on at least one side, or scope to URL path components
• All patterns: apply to extracted URL strings only (after URL extraction), not raw body text
• Add small allowlist of high-signal AMP markers as fast-path: *.cdn.ampproject.org, www.google.com/amp/s/, www.bing.com/amp/, ?amp=1, ?output=amp, amp.* subdomain — short-circuit to "is AMP" without further pattern matching

Tests per pattern with positive + negative fixtures (incl. & HTML entity, lamp_post, streaming_amplifier, etc.).

---

Canonical-finding — port verbatim, same order

10 methods in CanonicalType enum (models/link.py:23-34). Execution flow in helpers/canonical_methods.py. Port to Rust with the same priority order:

1. REL — <link rel="canonical">
2. CANURL — regex on canurl query/path
3. OG_URL — <meta property="og:url">
4. GOOGLE_MANUAL_REDIRECT — Google AMP cache URL pattern parsing
5. GOOGLE_JS_REDIRECT — Google AMP cache JS-redirect handling
6. BING_ORIGINAL_URL — Bing AMP cache original-URL extraction
7. SCHEMA_MAINENTITY — <script type="application/ld+json"> schema.org mainEntity
8. TCO_PAGETITLE — t.co page title heuristic
9. META_REDIRECT — <meta http-equiv="refresh">
10. GUESS_AND_CHECK — pattern-based canonical guess + article-similarity confidence scoring via Mozilla Readability port. Thresholds: >0.6 high (is_valid=true), >0.35 medium, else reject. Mirrors canonical_methods.py:152-157.
11. DATABASE — cached canonical lookup (separate from the 10; used as a fast-path before/after methods)

is_valid confidence flag on each canonical reflects how strong the signal is. Don't drop this — public consumers may filter on it.

---

Repo layout (post-archive)

AmputatorBot/
├── praw-python-archive/                          # M1: everything below moved here in one git mv
│   ├── check_comments.py
│   ├── check_submissions.py
│   ├── check_inbox.py
│   ├── check_tweets.py
│   ├── helpers/
│   ├── datahandlers/
│   ├── models/
│   ├── data/
│   ├── static/
│   ├── AmputatorBotCom/              # full Flask app, incl. main.py with the API contract
│   ├── img/
│   ├── test*.py
│   ├── requirements.txt
│   └── README-archive.md             # pointer back to v7 plan
├── backend/                          # Rust
│   ├── Cargo.toml
│   ├── Cargo.lock
│   ├── Dockerfile
│   ├── rust-toolchain.toml           # pins stable + rustfmt + clippy
│   ├── deny.toml                     # cargo-deny config
│   ├── justfile                      # project-local tasks
│   ├── migrations/                   # sqlx
│   ├── src/
│   │   ├── main.rs
│   │   ├── routes/
│   │   ├── canonical/                # 10 methods + amp_detect + url_extract
│   │   ├── db/
│   │   └── readability/              # dom_smoothie wrapper + similarity
│   ├── tests/
│   │   ├── fixtures/
│   │   │   └── urlconversions.json   # user-supplied test cases
│   │   ├── snapshots/                # insta golden JSON
│   │   ├── parity.rs                 # new-vs-live API parity
│   │   ├── canonical_methods.rs
│   │   └── amp_detect.rs
│   └── tools/
│       └── record_fixtures/         # CSV → recorded HTML for parity tests
│                                     # (MySQL → Postgres migration uses
│                                     # `psql \copy` of a CSV export, not
│                                     # a Rust binary — see M3 §migration)
├── devvit-app/                       # TypeScript
│   ├── devvit.json
│   ├── package.json
│   ├── tsconfig.json
│   ├── biome.json                    # Biome lint + format config
│   ├── justfile
│   └── src/server/
│       ├── index.ts
│       ├── routes/triggers.ts        # comment-submit + post-submit only
│       ├── core/
│       │   ├── ampDetect.ts          # mirrors backend logic
│       │   ├── urlExtract.ts
│       │   └── reply.ts              # new reply markdown
│       ├── backend/client.ts         # fetch wrapper (no auth)
│       ├── storage/dedup.ts          # Redis handled:{commentId} TTL 1h
│       └── settings.ts
├── website/                          # Astro
│   ├── astro.config.mjs
│   ├── package.json
│   ├── tsconfig.json
│   ├── biome.json
│   ├── justfile
│   ├── src/
│   │   ├── pages/                    # index.astro, faq.mdx, about.mdx
│   │   ├── components/react/         # ConverterForm island
│   │   └── components/ui/            # shadcn
│   └── public/                       # icons/logos copied from praw-python-archive/AmputatorBotCom/static/
├── .github/
│   ├── workflows/                    # path-filtered CI per project (backend, devvit-app, website, security)
│   └── dependabot.yml                # Cargo + npm + Actions + Docker dep updates
├── docs/
│   └── amputatorbot-devvit-migration-plan-v7.md   # this file
├── .editorconfig
├── .gitignore
├── mise.toml                         # pins Rust + Node versions for the repo
├── lefthook.yml                      # pre-commit hooks dispatcher
├── justfile                          # root tasks: just test, just lint, just fmt
├── pnpm-workspace.yaml               # ties devvit-app + website together
└── README.md                         # rewritten for new architecture

---

Development environment

One-time setup before M1. Doing this up front means the IDE and AI tooling are ready when implementation starts.

IntelliJ + Claude Code + MCPs

IntelliJ 2025.2+ ships with a built-in MCP server. Enable it so Claude Code can read open files, run code, and use IDE-side tooling.

1. Enable IntelliJ MCP server. Settings → Tools → MCP Server → check Enable MCP Server.
2. Auto-configure for Claude Code. Same panel → "Clients Auto-Configuration" → Auto-Configure for Claude Code. This writes the JetBrains entry to ~/.claude.json.
3. Add the Devvit MCP. From a terminal:

   claude mcp add devvit -- npx -y @devvit/mcp
   

   This registers the official Devvit MCP server (reddit/devvit-mcp). Restart Claude Code afterward.
4. Verify both are connected. In Claude Code, run /mcp — should list jetbrains and devvit.

Reddit/Devvit reference material for Claude

Two docs to add to the context Claude Code sees during this migration:

• https://developers.reddit.com/docs/llms-full.txt — the full Devvit docs flattened for LLM consumption. Either WebFetch on demand during a task, or save a snapshot to docs/reference/devvit-llms-full.txt and reference it from prompts so it's available offline.
• https://developers.reddit.com/docs/guides/ai — Reddit's official guide for using AI assistants (Claude included) to build Devvit apps. Worth reading once and skimming when you hit Devvit-specific decisions.

When asking Claude Code to write Devvit code, the prompt should ideally cite which section of the llms-full doc applies. The Devvit MCP can answer many of these without you having to paste.

Other toolchain checks

node --version      # need v22.x
rustc --version     # need 1.80+; if missing: curl https://sh.rustup.rs -sSf | sh
cargo --version

npm install -g devvit
devvit login        # browser OAuth as u/Killed_Mufasa
devvit whoami       # confirms username

brew install scw   # or download from github.com/scaleway/scaleway-cli releases
scw init           # browser OAuth to a Scaleway account, sets up org + project

If Rust is brand new on this machine: rustup default stable.

Reddit Developer Platform migration program

Apply at https://support.reddithelp.com/hc/en-us/articles/47822311698452 before M6:

• Bot: u/AmputatorBot, operating since ~2019
• Migration target: Devvit, ETA in line with M6
• Submitter: u/Killed_Mufasa

Anchoring the registration date probably helps bounty selection.

Pre-M1 data sizing

Known (measured 2026-05-25 by Dev): URLConversions table is ~1.7M rows at 42.56 MB total. That's ~26 bytes/row on disk (MySQL InnoDB compression on the URL strings is doing real work). Plenty of headroom in any managed PG plan — the smallest Scaleway tier (DB DEV-S, ~€13–15/mo) handles this with 100x growth headroom before we'd need to size up. Dev provisions it during M1; no further sizing analysis needed.

---

Development tooling & CI/CD

Modern stack. Each tool picked for "what devs in 2026 actually like and use" rather than legacy familiarity. All tools below are either Rust-written (fast), industry-default, or both.

Tool version management

• mise (https://mise.jdx.dev) — replaces nvm + rustup + asdf + similar with one tool. mise.toml at repo root pins Rust + Node versions; mise install reproduces the toolchain on any machine.

Rust (backend/)

rust-toolchain.toml in backend/ pins the toolchain channel (stable) and required components (rustfmt, clippy).

TypeScript (devvit-app/) + Astro (website/)

Cross-cutting

• just (https://github.com/casey/just) — Rust-written task runner, replaces Make. One justfile at repo root and one per subproject. just test, just lint, just fmt, just dev work consistently across all three projects.
• lefthook (https://lefthook.dev) — Git hook manager. Fast, parallel, language-agnostic. One lefthook.yml at root dispatches to per-project formatters/linters on staged files.
• .editorconfig at root — tabs/spaces, line endings, trailing whitespace.
• Dependabot — dependency updates. Configured via .github/dependabot.yml. Manages Cargo, npm, GitHub Actions, Docker base images. Native GitHub integration, zero external app to install.
• Conventional Commits — lightly recommended in commit messages (not enforced by hook). Helpful for future changelog generation if we ever want it.

CI — GitHub Actions

Path-filtered workflows so a TS change doesn't run Rust tests and vice versa.

GitHub's free tier covers all of this for a public repo.

Why these (rather than alternatives)

• Biome over ESLint + Prettier: one tool, one config, Rust-written, 10–100× faster. Increasingly the 2026 default. The only reasons to keep ESLint+Prettier are existing config bulk or a specific plugin Biome doesn't support yet — neither applies here.
• cargo nextest over cargo test: faster, better output, per-test isolation. Drop-in replacement.
• cargo deny over cargo audit + cargo license: one tool covers vulns, licenses, and dep duplication. CI step is unified.
• just over Make: modern, fast, predictable cross-shell behavior, no .PHONY ceremony.
• lefthook over husky: language-agnostic (we have Rust + TS + Astro in one repo), fast, parallel by default.
• mise over asdf + per-language version managers: single tool covers Node, Rust, anything else we add. Rust-written, fast.
• pnpm over npm or yarn: faster installs, disk-efficient. Devvit + Astro both support it.
• Not Bun: great runtime, but Devvit's CLI + MCP are tested against Node + pnpm. Sticking with the ecosystem default reduces friction. Revisit later if Bun gains official Devvit support.

---

Milestones

No calendar. Each milestone has a clear "done" criterion.

M1 — Sledgehammer + scaffold + tooling (local only) ✓ DONE

Done when: old code in praw-python-archive/, three empty project skeletons in place, root tooling configured, every project's local check pipeline (just check) is green, lefthook pre-commit hooks fire.

Tasks (code/structure):

• git mv all old code into praw-python-archive/, single commit, write praw-python-archive/README-archive.md
• Init backend/ with cargo init, minimal main.rs exposing GET /api/v1/health, Dockerfile (multi-stage, cargo chef for cached deps)
• Init devvit-app/ with minimal Hono server using @devvit/web/server's createServer + @hono/node-server's getRequestListener; configure devvit.json and vite.config.ts per Devvit docs (Vite plugin via @devvit/start/vite)
• Init website/ (Astro 6 + Tailwind 4 + React 19), single landing page, pnpm astro build outputs to dist/

Tasks (tooling, in order):

• Add .editorconfig and .gitignore at root
• Add mise.toml pinning Rust stable + Node 22 + pnpm 11 + just + lefthook; verify mise install reproduces
• Add pnpm-workspace.yaml declaring devvit-app and website as workspaces (incl. allowBuilds for esbuild/protobufjs/sharp under pnpm v10+)
• Add lefthook.yml at root with per-project pre-commit dispatchers (rustfmt + clippy / biome)
• Add .github/dependabot.yml with ecosystems: cargo, npm, github-actions, docker
• Add root justfile with test, lint, fmt, dev recipes that fan out to per-project justfiles
• Per-project: backend/rust-toolchain.toml, backend/deny.toml, backend/justfile, devvit-app/biome.json, devvit-app/justfile, website/biome.json, website/justfile
• Add the four GitHub Actions workflows (backend.yml, devvit-app.yml, website.yml, security.yml) with path filters
• Open a draft PR; confirm all four CI workflows trigger correctly and pass on the empty projects

Ask points: Devvit MCP availability. Any remaining framework picks (Hono vs. Express was resolved in favor of Hono for modernity).

Scaleway is intentionally NOT in M1. Local-first: prove the toolchain works end-to-end before engaging with any cloud provider. Cloud provisioning + deployment is M6.

M2 — Canonical engine in Rust + parity tests ✓ DONE

Done when: all 10 canonical methods ported; AMP detection ported with false-positive fixes; fixture-based parity test suite green on user-supplied URLConversations.

Tasks:

• Wire dom_smoothie (≈0.17) as the article extractor. Use its Mozilla-mimic mode. Wrap in backend/src/readability/ with a small adapter (fn extract_article_text(html: &str) -> String) so the rest of the code doesn't depend on the crate's surface directly.
• Port 10 canonical methods one by one, with per-method unit tests
• Port AMP detection with the improvements outlined above
• Port URL extraction (Rust url crate + regex pass for unstructured text)
• Write backend/tests/parity.rs — reads fixtures/urlconversions.json, runs each through both the local Rust impl and the live API at www.amputatorbot.com/api/v1/convert, diffs the canonical pick. Reports drift with readable output.
• Snapshot tests: ~20 representative cases as golden JSON files in backend/tests/snapshots/
• All cargo test green

Ask points: Edge cases in canonical methods that don't translate cleanly (duck typing, ad-hoc normalization) — surface, don't paper over. If dom_smoothie's standard mode produces similarity scores that misalign with the existing >0.6 / >0.35 thresholds on the fixture set, retune the thresholds rather than swapping the extractor.

M3 — /api/v1/convert endpoint + links cache (local) ✓ DONE

Done when: the Axum handler returns shape-compatible responses to the legacy /api/v1/convert against a local Docker Postgres seeded with the historical URLConversions data; ?r=true redirect mode works end-to-end via live HTTP; the X-AmputatorBot-Entry-Type header is honored on writes. Two locked deviations from the legacy contract: ?gc=true is silently ignored (deferred to M5 alongside the Devvit-side reply template refresh — legacy run_api never read it either), and the custom 5xx codes 560 + 561 are collapsed to 200 + null canonical (web-standard shape; clients differentiate via the response body).

Result: 167 tests (up from 112 at M2). End-to-end smoke verified against the local DB seeded with 9998 historical rows. Both endpoints ship:

• v1 (GET|POST /api/v1/convert) — legacy contract preserved; encoded URLs via curl --data-urlencode work, ?r=true returns 303. entry_type always logs API.
• v2 (POST /api/v2/convert) — JSON-in/JSON-out, camelCase both ways, entryType body field, api_version=2 written. Strict body deserialization (typos → 422).
• Schema: links.api_version SMALLINT added (NULL = legacy CSV-imported rows, 1 = v1 writes, 2 = v2 writes).

Schema (locked)

Two enums + one table — table name links (snake_case, matches legacy URLConversions content but with a cleaner name). Migration lives at backend/migrations/001_initial.sql, managed by sqlx-migrate.

CREATE TYPE canonical_type AS ENUM (
    'REL', 'CANURL', 'OG_URL',
    'GOOGLE_MANUAL_REDIRECT', 'GOOGLE_JS_REDIRECT',
    'BING_ORIGINAL_URL',
    'SCHEMA_MAINENTITY', 'TCO_PAGETITLE',
    'META_REDIRECT', 'GUESS_AND_CHECK', 'DATABASE'
);
CREATE TYPE entry_type AS ENUM (
    'ONLINE', 'COMMENT', 'SUBMISSION', 'MENTION',
    'TEST', 'TWEET',    -- historical only; new code never inserts these
    'API'
);
CREATE TABLE links (
    entry_id       BIGSERIAL     PRIMARY KEY,
    entry_type     entry_type,                            -- nullable (some legacy rows)
    handled_utc    TIMESTAMPTZ   NOT NULL DEFAULT NOW(),
    original_url   TEXT          NOT NULL,
    canonical_url  TEXT,                                  -- null = failure / false positive
    canonical_type canonical_type,                        -- null when canonical_url is null
    note           TEXT
);
-- Composite supports `WHERE original_url = $1 ORDER BY handled_utc DESC
-- LIMIT 1` (the DATABASE-method lookup) as an index-only scan. Btree
-- prefix matching means it also covers plain `WHERE original_url = $1`,
-- so a separate single-column index on `original_url` is redundant.
CREATE INDEX idx_links_original_url_handled ON links (original_url, handled_utc DESC);
CREATE INDEX idx_links_canonical_url        ON links (canonical_url);
CREATE INDEX idx_links_handled_utc          ON links (handled_utc);

Schema decisions (these supersede earlier "drop dead columns" / "modernize" wording in v7):

• Mirror the legacy columns — entry_id, entry_type, note all stay. Cleanup in behavior (new Rust code only ever inserts COMMENT / SUBMISSION / ONLINE / MENTION / API), not in historical preservation.
• canonical_type is a Postgres ENUM with SCREAMING_SNAKE_CASE values matching the Rust CanonicalType enum's JSON serialization byte-for-byte. sqlx maps both sides cleanly.
• entry_type includes TEST and TWEET for the legacy rows that have them; new code never inserts these values but they import cleanly.
• entry_id is BIGSERIAL — autoincrement, explicit inserts during import keep their original IDs, new rows get fresh ones.

Migration approach (locked)

CSV ingest via psql \copy — no Rust binary. M2 already exports the table to CSV (backend/tests/fixtures/urlconversions/*.csv); for M3 Dev exports the full ~1.7M rows the same way. Production cutover (M6) reuses the same command against the Scaleway endpoint.

psql "$DATABASE_URL" -c "\
    \copy links(entry_id, entry_type, handled_utc, original_url, canonical_url, canonical_type, note) \
    FROM 'tests/fixtures/urlconversions/URLConversions_full.csv' \
    WITH (FORMAT csv, HEADER true, NULL '')"

~1.7M rows in under a minute. No SSH tunnel, no sqlx wiring just for the import, no Rust binary to maintain.

Tasks

1. docker-compose.yml at repo root for local Postgres 17 + DATABASE_URL plumbing in the backend.
2. backend/migrations/001_initial.sql with the schema above; sqlx-migrate setup.
3. DATABASE canonical method — port the 11th method (stubbed in M2.5). Modernized from the legacy LIMIT 1: prefer the most-recently-resolved canonical, since the bot has run for years and the "right" canonical for a given URL can change over time (sites move, canonical-finding has improved). entry_id DESC is a deterministic tiebreaker. The composite index makes this an index-only scan.

   SELECT canonical_url FROM links
   WHERE original_url = $1 AND canonical_url IS NOT NULL
   ORDER BY handled_utc DESC, entry_id DESC
   LIMIT 1
   

4. PgPool plumbed into MethodContext (parallels how PageSource got added in M2.8).
5. Axum handler for GET /api/v1/convert wrapping canonical::resolve().
6. The %20 query-parsing heuristic from praw-python-archive/AmputatorBotCom/main.py:116-127 so unencoded URLs with q last still work (the load-bearing public-API contract per §"API contract").
7. Status code mapping: 200, 303 (r=true), 400 (no q), 406 (no AMP), 500 (unknown), 560 (no canonicals), 561 (problematic domain), with the result_code field on error responses.
8. r=true — 303 redirect to link.canonical.url.
9. gc=true reply markdown — port the legacy template, refresh per the v7 decision. Surface the draft for visual review before locking.
10. Integration tests against the handler with real query strings.

Ask points: the refreshed gc=true reply markdown — needs visual review before lock-in. Whether to also write the legacy URLConversions_full.csv export workflow into backend/README.md so it's reproducible later.

Production data migration to Scaleway PG happens in M6, not here. M3 just verifies the schema + \copy flow against a local Docker Postgres.

M4 — Astro website (local) ✓ DONE

Done when: the full Astro site builds locally, all content is in place, the ConverterForm works against the local Rust backend, and the two-stage Dockerfile produces a single image containing both the Rust binary and the Astro static bundle.

Why M4 (before Devvit): the website turns the abstract Rust backend into something visible — buttons to click, a form to paste URLs into, immediate "it works" feedback. Easier to keep momentum and easier to validate the API contract by hand.

Result

Combined Astro + Rust image (Dockerfile at repo root, multi-stage node:22 → rust:1.95 → debian-slim, ~165 MB stripped). tower-http::ServeDir mounted as Axum's fallback when STATIC_DIR points at an existing directory; the binary stays API-only when unset. Container runs Astro static on / and the API on /api/*. All 134 backend lib tests + Vitest smoke test green; astro check + biome check clean.

Homepage is composed of six section components (HeroSection, WhyAmpSection, TechSection, UkraineSection, CanonicalMethodsSection, plus the layout shell). Order: Hero → WhyAmp → Tech → Ukraine → Methods. No footer.

Locked deviations from the original M4 task list:

• /about page dropped. Long-form AMP write-up lives on the Reddit "why I built it" thread (r/AmputatorBot/comments/ehrq3z/...), linked from the header nav and from the WhyAmpSection card.
• /faq page dropped. Content folded back to the same Reddit thread; @astrojs/mdx and MdxLayout.astro removed since nothing else used MDX.
• SiteFooter dropped. All navigation lives in the header. Mobile nav uses a native <details>/<summary> collapsing menu — keyboard- and screen-reader-accessible by default, zero JS, near-full-width on mobile.
• /amputatorbot legacy route NOT preserved (Dev confirmed it was never used in practice). The ?q=<url> pre-fill on / is preserved (legacy bot DM templates deep-link with that pattern).
• GET /api/v2/stats added (not in original plan; later moved from /api/v1/stats since it's a new endpoint, not part of the legacy contract). Returns {"convertedTotal": N} from SELECT COUNT(*) FROM links, cached 1h via Arc<RwLock<...>> in src/stats.rs. Powers the homepage's live count via the ConvertedCount React island.
• Tiny zero-dep token-based highlighter at website/src/lib/highlight.ts covers html/json/js/url. Both Astro CodeSnippet.astro and the React Snippet in ConverterForm.tsx render the same tokens (no dangerouslySetInnerHTML). Token CSS in global.css.
• gc=true and the bot reply markdown stay deferred to M5 (already noted in M3 lock). The "Generate comment" option was deliberately not added to the converter form to avoid building UI against a template that's about to change.

Tasks (as-built):

• ConverterForm: ?q= prefill, "forward to canonical" via JS navigation, prominent copy-canonical button, "how we found it" card per result with syntax-highlighted snippet, optional-settings panel with breathing room when expanded.
• canonical-methods.ts maps every CanonicalType to {label, summary, explanation, snippet, snippetLanguage}. Consumed by both the result card and the homepage methods explainer.
• WhyAmpSection content sourced from the Reddit "why" thread — antitrust receipts (40% revenue drop, "how to publicly justify making something slower"), AMP committee resignations, empowerment pull-quote.
• UkraineSection: U24 as primary CTA, PayPal sponsorship as alternative. Copy makes the not-affiliated stance explicit.
• TechSection: "rewritten in Rust for perf + because it's fun, now also a Devvit app", EU-hosted (Scaleway Paris/AMS), live count.
• postcss.config.mjs wires @tailwindcss/postcss — was missing initially, so the first M4 build emitted theme + preflight but no utility classes.
• Image build context now ~10 MB after .dockerignore excludes target/, backend/tests/ (~3 GB of recorded HTML fixtures), node_modules/, dist/, praw-python-archive/.

No cloud, no DNS, no Devvit publish here — that's M6.

M5 — Devvit bot E2E

Done when: AMP comment in r/test → bot replies with correct canonical; dedup prevents double-reply; the autoReply setting silences the bot when toggled off.

Scope-down vs. earlier drafts. This milestone was originally going to ship a modmail handler, a welcome modmail on install, a Redis-cached opt-out lookup, an /api/v1/optout privileged route on the backend, and a Postgres optouts table. All dropped — see the "Locked decisions" table and the "No opt-out mechanic" rationale. Users and mods who don't want the bot block the per-install app identity or uninstall the app respectively.

Tasks:

• Port AMP detection patterns to TS (devvit-app/src/server/core/ampDetect.ts) — mirror Rust logic in backend/src/canonical/amp_detect.rs
• Port URL extraction to TS (devvit-app/src/server/core/urlExtract.ts) — mirror backend/src/canonical/url_extract.rs
• Write backend/client.ts — fetch wrapper for POST /api/v2/convert (camelCase JSON, recorded with entry_type=COMMENT|SUBMISSION and api_version=2, giving us per-source visibility into the links cache). No auth. Configurable base URL via setting (prod = https://www.amputatorbot.com, dev playtest = local Rust backend over a tunnel).
• Write core/reply.ts — generate the comment markdown from a backend Link[] response. See "Reply markdown (locked)" below.
• Write storage/dedup.ts — wraps Devvit Redis: setHandled(commentId) with 1h TTL, isHandled(commentId) returns bool.
• Settings (devvit.json + settings.ts): autoReply (bool, default true — the single on/off toggle), customFooter (optional string — appended after the standard footer when set).
• Implement /internal/triggers/comment-submit:
  • Early return if autoReply is off
  • Extract URLs from comment body, filter to AMP
  • Skip if dedup says we've handled this commentId in the last hour
  • GET /api/v1/convert?q=<url>&gac=true&md=3
  • Build reply via reply.ts, context.reddit.submitComment
  • Mark dedup with 1h TTL
• Implement /internal/triggers/post-submit — same flow, URLs sourced from title + url + selftext, dedup key is postId.
• Vitest unit tests for ampDetect, urlExtract, reply (snapshot), and the trigger handlers (mocked backend client, mocked Reddit context).
• Playtest end-to-end via just dev (rebuild loop in one terminal) + just playtest (defaults to r/AmputatorBotTest) in another. App slug landed on amputatorbot-app — Reddit account-namespace collision with the legacy u/AmputatorBot blocked the simpler slug.

Playtest setup gotchas

• First-time only: just init registers the app on Reddit's side. The slug in devvit.json (amputatorbot-app) must not collide with an existing Reddit account.
• vite: command not found in pnpm exec vite build: the workspace's per-project node_modules/.bin/ got out of sync (commonly after npx devvit init or hand-editing package.json). Fix by running pnpm install from the repo root, not from devvit-app/. If that still leaves .bin/ empty, rm -rf devvit-app/node_modules && pnpm install from the repo root.
• CLI version mismatch: the devvit binary must match @devvit/web major.minor. Both are pinned at 0.13.0 via devvit-app/package.json; if you ever see @devvit/cli/0.12.x from pnpm exec devvit --version, re-run pnpm install from the root.

Reply markdown (locked)

Preserves the legacy template's structure and quirks (singular/plural agreement, who/what, cached-AMP note, alt-domain canonical, ***** rule, superscript footer). Changes from legacy: drop the ^(I'm a bot | ) opener (Reddit's "App" badge handles disclosure), drop the Summon: u/AmputatorBot link (doesn't work in Devvit's per-install model), and replace the AMP-disclaimer sentence.

Singular (one AMP URL, one canonical):

It looks like {who} {what} an AMP link. AMP is supposed to be faster, but it's controversial because of [concerns over privacy and the Open Web]({FAQ_LINK}).{cached_note}

Maybe check out **the canonical page** instead: **[{canonical_url}]({canonical_url})**{alt_canonical}

*****

^([Why & About]({FAQ_LINK})^( | )[r/AmputatorBot](https://reddit.com/r/AmputatorBot)^( | )[Source](https://github.com/jvdburgh/AmputatorBot))

Plural (multiple AMP URLs):

It looks like {who} {what} some AMP links. AMP is supposed to be faster, but it's controversial because of [concerns over privacy and the Open Web]({FAQ_LINK}).{cached_note}

Maybe check out **the canonical pages** instead:

- **[{url1}]({url1})**{alt1}
- **[{url2}]({url2})**{alt2}

*****

^([Why & About]({FAQ_LINK})^( | )[r/AmputatorBot](https://reddit.com/r/AmputatorBot)^( | )[Source](https://github.com/jvdburgh/AmputatorBot))

Variables:

• {who} / {what} — OP / posted for post-submit, you / shared for comment-submit
• {cached_note} — when at least one origin URL was cached (origin.is_cached=true): Fully cached AMP pages (like the one {who} {what}), are [especially problematic]({FAQ_LINK}). (use "the ones" plural when >1, "some of the ones" when only some are cached — mirror reddit_comment_generator.py:84-90)
• {alt_canonical} — when a canonical at a different domain is also available: | {AltDomain.capitalize()} canonical: **[{alt_url}]({alt_url})** (mirror reddit_comment_generator.py:48)
• {FAQ_LINK} — https://www.reddit.com/r/AmputatorBot/comments/ehrq3z/why_did_i_build_amputatorbot/
• {customFooter} — when set on the install: appended as | {customFooter} inside the superscript group

Ask points: none — content and tasks both locked.

M6 — Cloud deployment + public launch

Done when: the Astro+Rust container is live at www.amputatorbot.com on Scaleway, prod Postgres holds the migrated dataset, the Devvit app is in the App Directory, r/AmputatorBot has the announcement sticky, and the old PythonAnywhere bot has been stopped after a 72h smoke window on the new stack.

Pre-deploy audit (do BEFORE any Scaleway provisioning — finding stale deps or leaked secrets after deploy is much more expensive):

• Dependency freshness. Bump everything to the latest compatible version we can — Postgres stays on 17 (the schema is sized for it; we don't gain anything by chasing a pg_* bump now), everything else fair game:
  • Rust: cargo update then cargo outdated -R to spot anything held back by semver caret pins. Patch Cargo.toml for the ones worth pulling forward (Axum, sqlx, reqwest, scraper, dom_smoothie). Re-run cargo nextest run + cargo deny check after each.
  • TS: pnpm -r outdated across devvit-app/ and website/. Update @devvit/web, Astro 5/6 LTS, Tailwind, Vitest, Biome, tsgo's preview tag.
  • GitHub Actions: dependabot already handles weekly bumps, but verify the actions/checkout@v4 / Swatinem/rust-cache@v2 / jdx/mise-action@v2 pins in .github/workflows/ are still current.
  • Docker base image: bump the Rust + Debian base tags in backend/Dockerfile to current LTS.
• Secret scan. gitleaks detect --no-banner --redact against the full history (not just current tree — the praw-python-archive/static/static.py credentials are still in older commits). Confirm every leaked credential has either (a) been rotated upstream (Reddit OAuth, MySQL, Twitter, SSH) or (b) is a now-defunct service we no longer use. Also git grep -nE "Bearer |password|secret|client_secret|api_key" -- ':!archive' for stray modern leaks.
• Vulnerability sweep. cargo deny check advisories (force-refresh the RustSec DB), pnpm -r audit --prod, GitHub Dependabot alerts dashboard. Triage each finding; fix or accept-with-rationale.
• Performance sanity. Build release: cargo build --release — confirm the binary stays under ~20 MB stripped (M2 baseline was around there). Run the full parity test (just parity-full) and check the report's success rate hasn't regressed since M3 lock. Boot the container locally and curl a cold request — record the latency so we have a baseline for Scaleway's cold-start measurement.
• Code-quality sweep. cargo clippy --all-targets -- -D warnings (already CI-gated, force-run anyway), pnpm biome ci, astro check. git grep -nE "TODO|FIXME|XXX|HACK" -- backend/src devvit-app/src website/src — every hit should either get resolved or be promoted to an issue with a milestone.
• Docs sanity. Re-read README.md, backend/README.md, CLAUDE.md, and this plan. Anything that drifted during M3–M5 gets fixed in-place. The Postman API docs link in §References should still describe the live shape (or have a TODO to update post-cutover).

Done criteria for the audit: zero open advisories, zero unrotated secrets in current HEAD, all CI checks green on a fresh push, parity report at or above the last locked rate.

Cloud setup (Dev does the signups; Claude prepares exact commands):

• Provision Scaleway Managed Database for PostgreSQL (DB DEV-S tier; the live MySQL is 42.56 MB so smallest tier is plenty)
• Provision Scaleway Container Registry namespace
• Note connection strings + registry URL; Dev sets the env vars on the Serverless Container

Production data migration:

• Export the full URLConversions table to CSV from PythonAnywhere MySQL (same export workflow as the M2 fixture CSVs).
• \copy it into Scaleway PG using the M3-validated command:

  psql "$SCALEWAY_DATABASE_URL" -c "\copy links(entry_id, entry_type, handled_utc, original_url, canonical_url, canonical_type, note) FROM 'URLConversions_full.csv' WITH (FORMAT csv, HEADER true, NULL '')"
  

• Run a small-batch smoke test first (e.g. head -1000 of the CSV) before the full load; verify row counts match the source.

Deploy:

• Build the two-stage Astro+Rust Docker image, push to Scaleway Container Registry
• Deploy the Serverless Container; configure env vars (DATABASE_URL)
• Smoke-test the container endpoint via curl (health, /api/v1/convert, static page, ?r=true redirect)
• Switch DNS (www.amputatorbot.com → Scaleway Serverless Container endpoint) in Cloudflare; verify TLS

Public launch:

• Submit Devvit app to App Directory (devvit upload --publish), write termsprivacy.md
• Install on r/AmputatorBot (canary), then r/test
• Draft + post r/AmputatorBot sticky announcement explaining the migration + per-install identity reality
• Send modmail wave to top N subreddits (by historical link volume)

Post-launch:

• Monitor Scaleway Cockpit logs for 72h
• After 72h clean, stop the old PythonAnywhere bot and cancel the subscription

Ask points: DNS switch timing. Outreach list size and tone. Exact stop-day for the old PythonAnywhere bot (target: 72h after cutover assuming no regressions).

---

Testing strategy

The load-bearing question: did we preserve canonical correctness while changing everything else?

Fixture-based parity (M2 + M3)

User provides backend/tests/fixtures/urlconversions.json:

[
  {
    "original_url": "https://www.google.com/amp/s/electrek.co/2018/06/19/.../amp/",
    "expected_canonical": "https://electrek.co/2018/06/19/.../",
    "expected_type": "GOOGLE_MANUAL_REDIRECT",
    "notes": "optional"
  }
]

cargo test --test parity runs each through:

1. New Rust impl directly
2. Live https://www.amputatorbot.com/api/v1/convert (old API)

Asserts:

• New canonical matches expected
• OR new canonical "better" by rule (non-AMP when old returned AMP)
• Reports any drift in a readable diff

Snapshot tests (M2)

~20 representative responses checked into backend/tests/snapshots/*.json. Catches response-shape drift. INSTA_UPDATE=1 cargo test to regenerate when intentionally changing shape.

Per-method unit tests (M2)

Each canonical method tested in isolation with HTML fixtures in backend/tests/fixtures/html/. No network. Fast feedback.

AMP detection tests (M2)

Per-pattern positive + negative fixtures, including the false-positive cases (&, lamp_post, etc.).

Devvit-side unit tests (M5)

Vitest. Mock backend client, mock Reddit context. Assert dedup, autoReply short-circuit, reply markdown (snapshot test against fixture Link[] responses).

Manual smoke (M3, M4, M5, M6)

• curl 10 known URLs against new endpoint, compare to live
• devvit playtest r/test: post 5+ fixtures as AMP comments, eyeball replies
• Browser test the Astro ConverterForm with the same fixtures

What we don't test

• Production traffic — until the M6 cutover, the old PythonAnywhere bot still serves users; the new stack only needs to be load-bearing once we flip DNS
• DDoS / abuse — Cloudflare's problem
• Devvit infra behavior — Reddit's problem

---

Gotchas (relevant ones only)

Rust-specific

• First cargo build pulls all transitive deps, ~5 min. Subsequent incremental ~10 sec. Use cargo check for fast iteration.
• sqlx::query! is compile-time-checked against live DB. Set DATABASE_URL at compile time, or use cargo sqlx prepare for offline.
• reqwest defaults to no redirects-on-POST. For redirect-chain canonical methods, configure: ClientBuilder::redirect(Policy::limited(10)).
• Borrow checker errors are educational — read them; the compiler usually tells you exactly what to fix.

API contract

• The %20 heuristic is the most fragile thing in the port. Test extensively. Public consumers depend on unencoded-URL behavior.
• is_alt, is_cached, url_similarity are all in the response shape — port them, don't skip.
• 303 redirect mode (?r=true) — implement, even if you'd rather not.

Devvit

• Use @devvit/web, not @devvit/public-api (legacy Blocks).
• Bot replies post as per-install app identity, not u/AmputatorBot. Communicate in launch announcement.
• permissions.http.domains is domain-level only.
• Triggers are HTTP routes — Reddit POSTs to internal paths.
• devvit playtest for one-sub dev install; only --publish at M6.

Scaleway

• Deploy flow: build Docker image locally → push to Scaleway Container Registry → deploy/update Serverless Container at that image tag. Automate via the scw CLI or the Terraform provider once it's working manually.
• Serverless Containers bind to the port set via PORT env var (default 8080). The Rust binary should read PORT and bind to 0.0.0.0:$PORT.
• Cold-start latency on first request after idle (auto-pause). For a Rust binary this is typically <500ms but worth measuring. If unacceptable, set min-scale to 1 (costs a bit more, no pauses).
• Container memory + CPU are configured per-deployment. Start small (256MB / 100m vCPU) and scale up if profiling shows pressure.
• Managed Database: use the DATABASE_URL Scaleway exposes; sslmode=require by default.
• Cockpit (logs/metrics) is enabled per-project — turn it on at provisioning time.
• Cost watch: Serverless Containers free tier is generous, but check the dashboard occasionally — runaway loops can chew through GB-seconds quickly.

Astro + shadcn

• Path alias @/* required in tsconfig.json before shadcn init.
• React-context-heavy shadcn components (Popover, Dialog, Tabs) need single-.tsx-file composition. Not an issue for a single ConverterForm.
• client:load for the converter island.

Don't-shoot-yourself-in-the-foot

• Never commit the Postgres URL. Set it via Scaleway container env vars.
• Don't stop the old PRAW bot before the M6 cutover — that's an explicit step in the launch sequence, not an ad-hoc action.
• Rotate credentials in praw-python-archive/static/static.py and praw-python-archive/AmputatorBotCom/main.py — they're checked into git history. Anything reachable (Reddit OAuth secrets, Twitter keys, SSH passwords, MySQL passwords) needs rotation regardless of the archive move.

---

Cost summary

Honest framing: all-in for the new stack is ~€15–18/mo, roughly the same as the current PythonAnywhere bill. This migration is not a cost-reduction play; it's modernization + learning + bounty eligibility. PythonAnywhere stops at the M6 cutover (after a 72h smoke window), so the dual-running window is brief and the steady-state is ~€15–18.

---

References

Reddit

• Migration program: https://support.reddithelp.com/hc/en-us/articles/47822311698452
• Devvit docs: https://developers.reddit.com/docs
• Devvit MCP: https://github.com/reddit/devvit-mcp
• Devvit template: https://github.com/reddit/devvit-template-bare

Stack

• Axum: https://docs.rs/axum/latest/axum/
• sqlx: https://docs.rs/sqlx/latest/sqlx/
• scraper: https://docs.rs/scraper/latest/scraper/
• reqwest: https://docs.rs/reqwest/latest/reqwest/
• Astro: https://docs.astro.build
• shadcn Astro install: https://ui.shadcn.com/docs/installation/astro

Scaleway

• Serverless Containers: https://www.scaleway.com/en/docs/serverless-containers/
• Managed PostgreSQL: https://www.scaleway.com/en/docs/managed-databases-for-postgresql-and-mysql/
• Pricing: https://www.scaleway.com/en/pricing/
• scw CLI: https://github.com/scaleway/scaleway-cli

Existing AmputatorBot

• Repo: https://github.com/jvdburgh/AmputatorBot
• Postman docs: https://documenter.getpostman.com/view/12422626/UVC3n93T