Research agents

📡 Performance

checking past performance

pending

Tracks every published post's live rank, impressions, clicks & sessions — surfaces what's working, stalling, or slipping.

📈 Trends & Rankings

reviewing trend opportunities

pending

Ranking movement & page-2/3 keyword gaps from Search Console — spots keywords on the cusp of page one and topics with no dedicated page yet.

🌐 External Research

scanning the wider market

pending

25+ Google searches across Espresso extraction forums, Reddit, new product launches, seasonal trends, and competitor blogs — surfaces what's trending outside your own data.

↓ pooled into one briefing

🧭 Research Agent pending

Synthesizes GSC, GA4, market trends & past bets into this week's briefing.

↓ then

🎯 Opportunity Agent pending

Turns the briefing into targeted keyword candidates — see the Opportunities tab.

↓ becomes this week's briefing

Run the research agents to generate this week's briefing.

Keyword opportunity gaps Google Search Console

Loading keyword data…

How this works

A decision-first SEO content engine that researches what your audience is searching for, finds the gaps worth chasing, helps you write content that fills them, and tracks whether it worked. One rule runs through the whole system: nothing gets written until a human decides it's worth writing.

The loop

Everything the tool does serves a single cycle:

Understand the business → Find the gap → Decide what & why → Write & publish → Measure → repeat

Performance data feeds back into Research and Opportunities — winners become "do more like this," losers become refresh candidates. The loop never ends.

The five tabs

Dashboard — the command center. Eight key metrics at a glance: total impressions, clicks, average position, CTR, keywords in the top 3 and top 10, page-two opportunities, and blog post impressions. Each metric shows its period-over-period change. Below that, an AI weekly briefing that reads the data and tells you what actually matters this week — written in sections (This week / Rankings / Trends / Blog movement / Best next move) so you can scan it in 30 seconds. A rank distribution chart shows how your keyword portfolio is distributed across Google's pages.
Research — the opportunity finder. Connects Google Search Console, GA4, Gemini trends, and DataForSEO into four tracked opportunity buckets: Winning (rank 1–3, defend), Quick win (rank 4–10, push to top 3), Move up (rank 11–20, biggest climb potential), and Content gap (rank 21+ or unranked, write something new). Each keyword shows its current rank, movement since first tracked, and a specific content move ("write a dedicated page," "refresh and expand the existing post," etc.). Strategic keywords — the ones that define your business — are flagged with a star and sorted to the top.
Opportunities — the decision surface. Every keyword from the latest research run is scored and ranked by a weighted formula (volume, trend, difficulty, competition, product fit, positioning headroom). But a score alone isn't a decision — so the AI also writes a strategy summary for the week and, for the top 3 picks, a written "why this, why now" rationale grounding each recommendation in evidence. The score and raw data are always available as expandable evidence beneath the rationale — the co-op model: AI recommends, you verify, then decide.
Review Gate — your call. The scored keyword cards are laid out for review. Each card shows the full scoring breakdown — volume bar, trend sparkline, difficulty dial, competition chip, product fit badge. Click Writing Studio on any card to approve it and start the writing flow. The machine will not draft a single word until you explicitly select a topic. This is the human checkpoint — scores are a signal, not a verdict.
Performance — the honest scoreboard. Every published article is tracked against real Google Search Console data: impressions, clicks, CTR, average position, and rank movement since publication. Articles are grouped by momentum: Gaining momentum (climbing or holding), Needs attention (stalled or slipping), and Too new to measure. Aggregate blog-level metrics at the top show the big picture — is the library as a whole growing? Click any article for a detail drawer with the full metrics, a notes field for your own annotations, and quick actions. This tab closes the loop: you can see whether each writing decision actually paid off.

Every page, explained

Each tab is one station in the loop. Below: what the page is for, what you'll see on it, and the logic running underneath. They're ordered the way you'd actually move through them — measure, research, decide, approve, write, then measure again.

1 Dashboard the command center — "how are we doing?"

The 30-second read on organic health. Opens on load and answers one question before you do anything else: is search traffic growing or shrinking, and what moved?

What's on the page

Headline trend + stat cards — impressions, clicks, average position, CTR, keywords in top 3 / top 10, page-two opportunities, blog impressions. Each shows its period-over-period change.
Organic Traffic chart — full-width click/impression trend over the selected window.
Blog Post Traffic chart — sessions driven by the blog specifically.
Keyword Overview + Blog Performance split — expandable cards for average position and top-3 / top-10 counts, beside per-post blog metrics.
Blog post traffic table — sortable by impressions, clicks, or CTR.

How it works

Pulls live Google Search Console (rank, impressions, clicks, CTR) and GA4 (sessions) for the window.
Period-over-period deltas compare the current window against the prior equal-length window.
If Search Console is offline it shows an onboarding prompt and degrades to what it can render — never a blank screen or a 500.

integrations/analytics.py web/server.py

2 Research the opportunity finder — "what should we look at?"

Where a run begins. Three data agents work in parallel, pool their findings into one weekly briefing, and hand that briefing to the Opportunity Agent to turn into keyword candidates.

What's on the page

Research agents pipeline — three parallel stages: Performance (past bets), Trends & Rankings (GSC ranking movement + page 2/3 gaps), External Research (25+ grounded Google searches on forums, Reddit, launches, seasonality).
Research Agent — synthesizes all three into "this week's briefing."
Opportunity Agent — converts the briefing into targeted keyword candidates.
Signal dropdowns — each agent stage exposes the signals it read and the candidates it produced, collapsible for inspection.
⟳ Run Research — the button that fires the whole pipeline (gated by the run password).

How it works

Performance is one input among three, not the lead signal — the design deliberately avoids letting past results dictate the whole field.
External Research runs Gemini 2.5 Flash with Google Search grounding across multiple angles (25–50 searches).
The briefing and candidates are written by Claude Opus, then persisted as a numbered run you can revisit.

app/agents/keyword_trends.py app/insights.py

3 Opportunities the decision surface — "what's worth it, and why?"

Every candidate from the latest run, scored and ranked — but paired with a written rationale so a number never has to stand alone. This is the co-op model in its purest form.

What's on the page

Run selector — switch between historical runs; weights legend shows the active formula.
Strategy This Week — Opus writes Picks / This week's signal / Watch, grounded in the run's data.
Top Picks — the top recommendations as detail cards with a "why this, why now" rationale.
Targeted opportunities — the Opportunity Agent's candidates from the Research loop.
Full shortlist — every scored keyword, with expandable evidence beneath each.
Re-entry row — published pages that stalled or slipped, surfaced back as refresh candidates.

How it works

Six weighted factors (volume, trend, difficulty, competition, product fit, positioning headroom) produce a base score.
The base score is multiplied by an opportunity gate keyed to your live Google rank — keywords you already own are discounted so the engine hunts climbs. (Full formula in the Scoring Engine tab.)
The score and raw data are always one click away as evidence — AI recommends, you verify, you decide.

app/insights.py app/agents/opportunity_agent.py

4 Review Gate the human checkpoint — "yes, write this one"

The one place a decision becomes an action. Scored keyword cards are laid out for review, and nothing is drafted until you explicitly send a topic to the Writing Studio.

What's on the page

Keyword cards — each with its full scoring breakdown: volume bar, trend sparkline, difficulty dial, competition chip, product-fit badge.
Writing Studio button — on each card, approves the topic and opens the writing flow.

How it works

Scores are a signal, not a verdict — the machine will not write a single word until you select a topic.
Approving a card seeds the writing flow: gap brief → draft → QA → revisions → accept.

web/server.py app/agents/context_layer.py

5 Performance the honest scoreboard — "did the bet pay off?"

Closes the loop. Every published article is tracked against real Search Console data since publish, so each writing decision gets a verdict written by the market, not the model.

What's on the page

Accepted — not yet published — drafts you've approved but haven't put live; surfaced first because there's nothing to measure until they publish.
Did the bet pay off? — each tracked post's position / clicks / impressions then→now since first tracked, with a horizon toggle (last week / month / year).
Keyword Rankings — all blog posts — every post GSC knows about (including pre-tool content), sortable by rank, impressions, clicks, or CTR. Click a row for its rank & click trend.

How it works

Rank/clicks come from Search Console; sessions from GA4 — reconciled per post URL.
Position shown is GSC's click-weighted average rank across every query that lands on the page, not one keyword.
Winners feed back into Research as "more like this"; losers become refresh candidates on Opportunities.

integrations/analytics.py web/server.py

The Writing Studio isn't a top-level tab — it's the workspace Review Gate opens into. Its five-step flow (gap brief → draft → QA → revisions → accept) has its own Writing Flow tab.

How the research engine is wired

The system is a pipeline, not a pile of features. Every run flows through the same ordered stages — each one narrows a wide field of possibilities down to a single, evidenced decision. Nothing is a black box: every stage names the agent that runs it and the data it reads.

Company ProfileGemini 2.5 Flash

Before any number is interpreted, Gemini researches the business via Google Search grounding and writes a profile: products, audience, expertise areas, and the strategic keywords that define the company. Stored once, read by every downstream stage so "espresso extraction" is treated as a priority, not just another phrase.

app/agents/keyword_trends.py

Keyword DiscoveryGemini · grounded

Seeds expand into hundreds of candidate keywords through Google Search grounding, anchored to the company profile so the field stays on-topic. This is the wide end of the funnel — quantity, not yet judgement.

app/agents/keyword_trends.py

ValidationDataForSEO · metered

Candidates are checked against real market data: search volume, CPC, competition (google_ads), and keyword difficulty 0–100 (Labs). Every call is hard-capped and counted — an LLM never drives a metered loop. Missing data degrades to null, never a crash.

app/dataforseo.py GoogleAdsProvider

Clustering$0 · offline

Validated keywords are grouped into intent clusters by token-overlap (Jaccard) similarity — no API, deterministic, testable. The highest-scoring keyword in each cluster becomes the pillar; the rest are kept as internal-link variants.

app/clustering.py

Scoring & the Opportunity Gateweighted

Six weighted factors produce a base score, which is then multiplied by an opportunity gate keyed to where you actually rank in Google right now (from Search Console). A keyword you already own at #2 is deliberately discounted — the engine hunts climbs, not traffic you already have. See the Scoring Engine tab for the full formula.

app/insights.py

Context LayerDataForSEO SERP

For an approved topic, the live page-1 SERP is pulled and each competitor page analyzed to build a gap brief: table stakes, the gap nobody covers, a winning outline, and product tie-ins. This is the Information-Gain anchor for writing.

DataForSEOSerpProvider

Writing & QAOpus + Sonnet

Opus writes the gap brief; Sonnet drafts the article against it; a second AI pass enforces brand voice and spec accuracy, retrying on failure. Detailed in the Writing Flow tab.

MeasurementGSC + GA4

Published articles are tracked against real Search Console rank/clicks and GA4 sessions. Winners feed back into discovery as "more like this"; losers become refresh candidates. The loop closes and restarts.

integrations/analytics.py

The layers underneath

Cross-cutting concerns are isolated so any single source can fail without taking the system down:

Config

One place loads the environment. Pure stdlib so the preflight check runs before any dependency is installed.

app/config.py

Integrations

GA4 + Search Console share one service account; DataForSEO is a metered, capped REST client. Every client returns OFFLINE instead of throwing.

integrations/analytics.py · app/dataforseo.py

Persistence

SQLite holds runs, scored topic evaluations, and drafts. Railway mounts a volume so data survives redeploys.

app/db.py

Web / API

FastAPI serves a single-page app. Every endpoint degrades gracefully — an offline source returns a flag, never a 500.

web/server.py · web/static/index.html

The seam pattern repeats everywhere: each data source sits behind a Protocol (KeywordDataProvider, SerpProvider) so DataForSEO can be swapped for any future backend without touching the scoring or writing logic.

The writing flow

When you approve a topic in Review Gate and open Writing Studio:

Gap Brief — Opus reads the top-10 competitors from page 1, fetches and analyzes each page, then writes a structured brief: table stakes (what everyone covers), the gap (what no one covers), a winning outline, product tie-ins from the catalog, and a target word count. This is the Information Gain anchor — it ensures the article adds something competitors don't have.
Article Draft — Sonnet writes a full-length article following the gap brief. The draft renders as a live blog preview. Product names auto-link to their product pages.
QA Gate — a second AI pass checks for brand voice, spec accuracy, and structural compliance. Violations get flagged; if QA fails, the writer retries with the violation list appended.
Revisions — type revision instructions ("shorten the intro," "add a comparison table") and the AI rewrites with your guidance.
Accept & Publish — mark the article accepted, paste its live URL, and it moves to Performance for tracking.

The company profile

Before any agent runs, it knows who the business is. A Gemini-researched company profile is generated during onboarding and stored in the database. It identifies the company's products, target audience, expertise areas, and strategic keywords — the terms that define the business. Every downstream agent (research, opportunities, briefing, writing) reads this profile before interpreting a single number. This is why "ranking #11 for espresso extraction" gets treated as a strategic priority, not just another keyword.

The opportunity score

Every keyword gets a base score from six weighted factors, shown by their actual weight so nothing is a black box:

That base score is then multiplied by an opportunity gate — how much room there is to climb, based on where you actually rank in Google right now:

Current rank	Gate	Move	Why
#1–3	×0.10	Owned	Already winning — little upside in rewriting it.
#4–10	×0.45	Optimize	Page 1 — sharpen it to reach the top 3.
#11–25	×0.95	Refresh	Page 2 — the single biggest climb opportunity.
#26+	×0.90	New post	Barely ranking — effectively a content gap.
Not ranking	×1.00	New post	A true gap — no page exists yet.

A keyword you already own at #2 can score lower than a page-2 keyword with half the volume — on purpose. The engine hunts climbs, not just traffic.

Data sources

Source	What it provides
Google Search Console	Real rank, impressions, clicks, CTR, position for every keyword and page you appear in Google for. The ground truth.
Google Analytics 4	Traffic sessions, pageviews, blog contribution %. Tells you what's actually driving visits.
Gemini 2.5 Flash	Keyword discovery via Google Search grounding, company profile research, trend detection. The explorer.
DataForSEO Labs	Search volume, keyword difficulty (0–100), CPC, competition level, 12-month trend data. The validator.
DataForSEO SERP	Live page-1 competitor analysis for gap briefs. What you're actually up against.
Claude Opus	Strategic analysis: weekly briefing, opportunity rationales, gap briefs. The analyst.
Claude Sonnet	Article writing, QA checks, revisions. The writer.

Every data source degrades gracefully. If Search Console is offline, the Dashboard shows what it can without it. If DataForSEO is unreachable, scoring uses cached data. If an AI model is down, the endpoint returns an offline flag — never a 500 error. The tool always loads; it just tells you what it couldn't reach.

The co-op model

This tool is built around a fixed pattern on every AI surface:

Recommendation
One line — what to do

→

The why
Plain language — why this, why now

→

The evidence
Expandable — the data receipt

Data is never the headline; it's the receipt behind the decision. The AI leads with a recommendation and its reasoning. The underlying GSC/GA4/DataForSEO numbers are always one click away to verify. You work alongside the AI — not blindly trusting scores, not drowning in raw data.