All projects

Case study 06 of 07 · LLM verification · Automation · SEO

Backlink Builder

A safety-first automation that runs every day without me: it finds guest-post opportunities, makes a language model prove each decision with quotes that code verifies, writes original articles and sends them.

Live, running dailyGemini, quote-verified

In 20 seconds

What it is
Earns backlinks for three small websites without manual outreach, entirely on free tiers. Most of the engineering is reliability: model failover, time budgets and not wasting limited credits.
My part
I set the goal and the rules, made the product decisions and operate it daily, reviewing results by hand. Claude Code wrote most of the code under my direction.
Built with
Claude Code, pytest, Node with jsdom for the extension and dashboard tests
AI in the product
Gemini (free tier, four-model failover) judges each site and writes the articles. Every 'yes' must come with an exact quote that plain code checks on the page.
Status
Live, running daily. Running daily since 16 Jul 2026. Paused on 28 Oct and rebuilt on 1 Nov 2026 as the guest-post pipeline described here.

Straight answer: No backlink is confirmed live yet, so I claim no traffic, ranking or SEO result. Yield is low: about 1 guest post sent a day against a target of 6, and the Gemini free tier failed on 8 of 15 site-runs between 11 and 15 November.

  • 458 tests pass in the public showcase verified
  • 8 of 9 named regression tests fail on the pre-fix code verified
  • 3 of ~410 pages that passed, in one week before the funnel fix verified
  • 2 guest posts per site per day: a hard cap in code verified
01

Overview

Backlink Builder finds websites that accept guest articles, checks each one against strict rules, writes an original article or pitch, sends it, and tracks whether it is published with a live link. It also runs a separate email campaign to venues. It exists to earn real backlinks for three small websites without manual outreach: Hypnotreatment (hypnotreatment.uk), SocialField (socialfield.uk) and Genbooks (genbooks.uk). It is an internal tool for one person, not a product for sale.

What makes it different

  • Every model “yes” must come with an exact quote, and plain code then checks the quote really is on the page.
  • Deterministic checks run before any model call.
  • It refuses competitors, paid placements, sites that ban AI-written text, sites that need an account, and any CAPTCHA bypass.
  • It runs on free tiers only, on purpose.
02

How it works

One daily run

One daily runFindexact-phrasesearches in eachsite's nicheCode checksexcluded domains,robots.txt, forms,wordingGemini judgementJSON, an exact quotefor every claimWriteoriginal article orshort pitchSendform, click link orinvited emailTrackweekly sitemap andfeed checks, live-page verifierReportMarkdown in therepo, shown on thedashboardcode firstquote verifiedOne daily runFindCode checksGeminijudgementWriteSendTrackReportcode firstquote verified
  • External service
  • Service
  • AI model
  • Data store
Read this diagram as a list

The boxes

  • Find: exact-phrase searches in each site's niche
  • Code checks: excluded domains, robots.txt, forms, wording
  • Gemini judgement: JSON, an exact quote for every claim
  • Write: original article or short pitch
  • Send: form, click link or invited email
  • Track: weekly sitemap and feed checks, live-page verifier
  • Report: Markdown in the repo, shown on the dashboard

The connections

  1. Find → Code checks
  2. Code checks → Gemini judgement (code first)
  3. Gemini judgement → Write (quote verified)
  4. Write → Send
  5. Send → Track
  6. Track → Report
From the project report. Code gates run before any model call, and every model 'yes' is checked against the page.

Three ways to send

Three ways to sendArticle or pitchwritten to thesite's ownguidelinesPlain formheadless browserfills and sends;honeypot fieldsnever touchedClick linkChrome extensionfills; the ownerticks the CAPTCHAInvited emailto an address thesite's guidelinesinvite, Wordattachment if neededVerified livechecks the page forthe linkThree ways to sendArticle orpitchPlain formClick linkInvitedemailVerifiedlive
  • AI model
  • Service
  • Human step
  • External service
Read this diagram as a list

The boxes

  • Article or pitch: written to the site's own guidelines
  • Plain form: headless browser fills and sends; honeypot fields never touched
  • Click link: Chrome extension fills; the owner ticks the CAPTCHA
  • Invited email: to an address the site's guidelines invite, Word attachment if needed
  • Verified live: checks the page for the link

The connections

  1. Article or pitch → Plain form
  2. Article or pitch → Click link
  3. Article or pitch → Invited email
  4. Plain form → Verified live
  5. Click link → Verified live
  6. Invited email → Verified live
The system never touches a CAPTCHA. On the click-link route the owner ticks it while the extension fills the rest.

The job state machine

The job state machineDiscoveredQualifiedpassed code gatesand the model'squotesContent readySubmittedVerifiedlive page shows thelinkThe job state machineDiscoveredQualifiedContentreadySubmittedVerified
  • Service
  • Data store
Read this diagram as a list

The boxes

  • Discovered
  • Qualified: passed code gates and the model's quotes
  • Content ready
  • Submitted
  • Verified: live page shows the link

The connections

  1. Discovered → Qualified
  2. Qualified → Content ready
  3. Content ready → Submitted
  4. Submitted → Verified
Only listed transitions are allowed, and the reason for each is recorded.

Runs every day without me

  • Discovery, checking, writing, sending by form or email, and tracking.
  • The venue campaign: 5 emails a day, written by Gemini.
  • Weekly sitemap and feed checks, and a separate verifier that looks at the live page for the link.
  • A second watchdog workflow that checks for missed runs.

Needs me

  • Ticking CAPTCHAs on click links. The system never touches them.
  • Replying to editors.
  • Publishing decisions, and reviewing results by hand.

Safety rules enforced in code. Never contact competitors. Respect robots.txt. No accounts or paid placements. A website is used once, ever. One email per address, ever. A hard cap of 2 per site per day.

The venue campaign finds venues through Google Places, checks that each is a registered company, and sends a personalised email with an opt-out line.

03

Stack

AI models and APIs

  • Google Geminifree tier only, four-model failover
  • Tavilysearch, 8 a day per site
  • Firecrawlpage reading, 4 a day per site
  • Google Places APIvenue campaign

AI techniques

  • Quote-verified model answerscode checks every quote
  • Structured JSON outputverified quote behind every claim
  • Retries, failover and rate limitingfour models, several keys, time budget
  • Deterministic state machinelisted transitions only
  • Quality gates in codedeterministic checks before any model call

Languages

  • Python3.12, about 5,900 lines
  • JavaScriptChrome extension and dashboard

Backend and APIs

  • BeautifulSoup
  • python-docxWord attachments
  • SMTP mailboxes

Frontend

  • Static single-page dashboardGitHub Pages
  • Chrome extensionManifest V3

Data and storage

  • JSON state filescommitted to a private GitHub repository
  • Markdown run reports

Automation

  • Playwrightheadless browser fills and sends plain forms

Payments and integrations

  • GitHub APIthe dashboard reads and writes state through it

Cloud and infrastructure

  • GitHub Actionsdaily run at 09:13 UTC plus a watchdog workflow
  • GitHub Pages

Testing and tooling

  • pytest
  • Node with jsdomextension and dashboard tests
  • Claude Code
04

AI and machine learning

Models and what they do

  • Gemini, free tier onlyJudges each site and writes the articles. The failover chain is gemini-3.8-flash, then 3.7, 3.6 and 3.5 flash, with several API keys.
  • Claude APIDeliberately not used anywhere in the system. This is a recorded decision.

Techniques actually used

  • The model must answer in JSON with a verified quote behind every claim. Fields cover attachment type, AI restrictions, link-builder bans, members-only, link permission and paid status.
  • Deterministic checks run before any model call: excluded domains, robots.txt, form structure, address context and wording rules.
  • A per-run budget of 5 minutes per site.
  • A stub client answers ‘busy’ instantly after the first outage, so the pass carries on with code-only checks.
  • A model that failed earlier in the run is tried last (added 2026-11-15).
  • Articles are written to each site’s own guidelines (word range, topic, link rule) with an approved author bio, and pass quality gates.

Not in this project

  • RAG
  • Embeddings
  • Vector database
  • Speech to text or text to speech
  • Free-roaming agents
  • Claude API (a deliberate decision)

A fixed pipeline, not a free-roaming agent. A state machine drives each job and allows only listed transitions.

05

Features

  • A pipeline of search, checks, evidence quotes and fit scoring, then article and pitch writing, form-field mapping (honeypot fields are never touched), three send routes, and publication tracking with link verification and an “indexable and followed” check.
  • A dashboard with today’s guest posts, click-to-submit buttons, tabs by status, live backlinks and a field to paste a published address.
  • Search limits of 8 Tavily searches and 4 Firecrawl reads a day per site.
  • No payments, and no users or admin accounts apart from me.
06

My role

What I did. I set the goal and the rules: 2 a day per site, never contact competitors, free tiers only, and no Claude API anywhere in the system. I made the product decisions, such as forms only versus email, CAPTCHA via the extension, and removing DEV.to and WordPress.com. I operate it daily and review the results by hand.

What Claude Code did. Most of the code, under my direction. I reviewed it and verified behaviour, for example by reporting that forms emptied themselves in my own Chrome. Problems solved with the assistant: measuring where pages were lost, the form-wipe bug, the false “published” match and Gemini outages.

07

Engineering challenges

Pages lost in the funnel

In one week about 410 pages were opened and only 3 passed.

How it was solvedHide

The causes were found by counting, then fixed: search ignoring quotation marks (fixed with the exact-match option), over-strict email rules, login boxes read as “account required”, and wasted re-checks.

A form that emptied itself

After filling, the form wiped its own fields in my Chrome.

How it was solvedHide

Reproduced with the real extension loaded in Chromium and fixed with a refill triggered by the form’s reset event. A regression test was added.

A pitch reported as published

A title-word match hit an unrelated article.

How it was solvedHide

Fixed, with a test.

Gemini free-tier outages

The free tier fails often. On 2026-11-15 a frozen model was found to cost up to 2 minutes per try on every request.

How it was solvedHide

Handled by a four-model failover, several keys, a time budget and a stub client. The client now moves on at once and remembers failed models for the run.

Proving the tests mean something

A regression test that passes before the fix proves nothing.

How it was solvedHide

Each named regression test was run at the commit before its fix: 8 of 9 fail on behaviour and 1 on a missing function.

08

Status

Live, running daily since 2026-07-16, the date of the first commit and the first automated run. The first design published to DEV.to and WordPress.com. It was paused on 2026-10-28 and rebuilt on 2026-11-01 as the guest-post pipeline described here. The daily run starts at 09:13 UTC through an external cron call to a workflow_dispatch, and a watchdog checks for missed runs.

Complete

  • The three send routes, publication tracking, the dashboard and the venue campaign.
  • The Gemini failover.

Partial or still open

  • Yield is low: about 1 guest post sent a day against a target of 6.
  • The Gemini free tier failed on 8 of 15 site-runs between 11 and 15 November.
  • Of roughly 17 guest posts sent since 1 November, none was confirmed published by 15 November.

Not built, and not claimed

  • Automatic reply handling for editors.
  • Any paid-tier path.
09

Evidence

  • 458 tests pass in the public showcase 465 in the private repository. About 5,900 lines of Python source and 4,500 lines of tests.verified
  • 8 of 9 named regression tests fail on the pre-fix code Checked by running each at the commit before its fix. The ninth fails on a missing function.verified
  • 3 of ~410 pages that passed, in one week before the funnel fix The causes were found by counting, then fixed one at a time.verified
  • 2 guest posts per site per day: a hard cap in code A website is used once, ever, and an email address once, ever.verified
  • 8 and 4 Tavily searches and Firecrawl reads per site per day The free tiers are the budget.verified
  • 8 of 15 Gemini free-tier site-runs failed, 11 to 15 Nov A limit I report rather than hide.verified

Code worth reading (public showcase, plus a private repository)

  • docs/ARCHITECTURE.md (showcase)Mermaid flow and state-machine diagrams.
  • Engineering log (showcase)The fixes and the numbers behind them.
  • logs/ (private repository)Run reports from each daily run.

What I can't verify, so I don't claim

  • Any traffic, ranking or SEO outcome. No backlink is confirmed live yet, so I claim none.
  • Whether the dashboard shows data to outsiders.

Public links

verified checked against the code, tests, logs or the live system. reported from my own notes or hands-on use. unverified could not be checked, so it is not claimed.