Originally published at spectredev.xyz. Cross-posted here for the Dev.to community.

Choosing between monolith, modular monolith, and microservices? Here’s the honest, opinionated framework your startup actually needs. Stop copying Netflix.

Your architecture choice shouldn’t be driven by what Netflix or Uber is doing. It should be driven by where you are right now your team size, your traffic, your deployment maturity, and your runway. The monolith vs microservices debate has a real answer for your situation. It’s just not the one most blog posts give you.

Here’s the framework we use when helping startups and growth-stage companies make this call.

Why Most Teams Get This Wrong From the Start

The mistake I see most often: founders read about how Airbnb or Grab migrated from a monolith to microservices, and they decide to build microservices from day one because that’s what scale looks like.

It isn’t. That’s what post-scale looks like. There’s a difference.

When those companies broke apart their monoliths, they had hundreds of engineers, mature CI/CD pipelines, dedicated platform teams, and years of operational experience with their own domain boundaries. They weren’t starting fresh. They were solving a problem that emerged from growth, not anticipating one that might never arrive.

Starting with microservices before you have product-market fit is one of the fastest ways to burn engineering resources on infrastructure instead of product. We’ve seen it happen. It’s painful to watch.

The Monolith: Unfairly Maligned

A monolith isn’t a bad architecture. It’s a starting point. And for most teams honestly, for teams up to 10–15 engineers with a single product it’s the right one.

In a traditional monolith, all your application code lives in one deployable unit. One codebase, one database, one deployment pipeline. The benefits are real and often underappreciated.

Development velocity is genuinely faster early on. There’s no network latency between services, no distributed transaction complexity, no service discovery overhead. You can refactor across the entire codebase in one shot. Debugging is straightforward because everything runs in one process.

The problems come later. As your team grows, the codebase becomes harder to navigate. Different teams start stepping on each other’s work. Deployments get slow and risky because every change ships everything. That’s when the architecture starts to fight you, not help you.

The real signal you’ve outgrown a monolith isn’t traffic. It’s team friction and deployment pain.

How to build a backend that scales from 100 to 10 million usershow-to-scale-startup-backend)

The Modular Monolith: The Option Nobody Talks About Enough

Here’s the counter-intuitive point: for most startups that think they need microservices, a modular monolith is actually the better answer.

A modular monolith is still a single deployable unit, but the internals are deliberately structured into isolated modules each with clear boundaries, their own data ownership, and strict rules about how modules interact. Think of it as microservices discipline inside a monolith’s deployment model.

The practical result: you get much of the architectural clarity of microservices without the operational overhead. You can enforce team ownership of modules. You can move faster without breaking unrelated parts of the system. And when you eventually decide to extract a service, the module boundary makes it a surgical operation instead of a painful untangling.

Shopify ran a monolith for years, and the work they did to make it modular what they called “componentisation” is one of the more honest engineering stories out there. It wasn’t glamorous. It was just effective.

A modular monolith is the architecture that earns microservices. You build the discipline first, then you extract services when the operational case is clear.

Microservices: When They Actually Make Sense

Microservices are the right answer for a specific set of conditions. All of them need to be true, not just one.

Your team is large enough that different groups genuinely need independent deployment cycles. You have parts of your system with radically different scaling characteristics say, a real-time notification service that spikes to millions of events per second while your invoicing service handles hundreds of requests per day. You have the platform engineering capacity to run container orchestration, service meshes, distributed tracing, and on-call rotations for multiple services. Your domain boundaries are well understood because you’ve built and operated the system long enough to know where they should be.

If you’re missing any of those, microservices will slow you down.

The operational surface area is real. In a distributed system, you’re now debugging network partitions, handling partial failures, managing schema migrations across service boundaries, and coordinating deployments across multiple repositories. Each of those is a solvable problem. Collectively, they require a team that has the headspace to solve them.

One of SpectreDev’s clients a Series A fintech came to us after attempting a microservices migration with a team of six engineers. Eighteen months in, they had eight services, three of which couldn’t be deployed independently because of undocumented shared state. The team was spending more time on infrastructure incidents than feature work. We spent three months collapsing it back to a modular monolith before rebuilding the extraction incrementally. The irony isn’t lost on anyone.

What is database sharding and when does your startup actually need it

The Decision Framework

Use this as a starting point. It’s opinionated and it’s supposed to be.

Build a monolith if: you’re pre-product-market fit, your team is under 8 engineers, and your primary constraint is development speed.

Refactor toward a modular monolith if: you’ve found product-market fit, your team is growing, and you’re starting to feel the organisational friction of a shared codebase but you don’t yet have the platform maturity for distributed systems.

Extract services from that modular monolith if: a specific module has a genuinely different deployment cadence, a clearly different scaling profile, or a different team ownership model that justifies the operational overhead. Extract one service, operate it well, then decide on the next.

Notice what’s not on that list: “because we expect to have 10 million users someday.” That’s not an architecture decision. That’s wishful thinking. Architect for where you are and the next logical growth phase, not for a ceiling you may never approach.

For Indonesian companies specifically, there’s an additional layer to consider: talent availability. Engineers comfortable with distributed systems operations Kubernetes, service mesh, distributed tracing are a thinner slice of the market in Jakarta than in San Francisco. A modular monolith your current team can operate confidently is worth more than a microservices setup that creates a hiring dependency you can’t fill.

Practical Example: How a Regional E-Commerce Startup Should Think About This

Consider a regional e-commerce platform think something operating across Indonesia, Malaysia, and the Philippines in the 50,000–200,000 active users range and growing.

At that scale, the right architecture is almost certainly a modular monolith. You’d want clearly isolated modules for the product catalogue, order management, payments (especially given regional payment methods like GoPay, OVO, and GrabPay that each have their own integration logic), and logistics tracking.

None of those need independent deployments yet. But structuring them as modules means when you hit 2 million users and the payments module is getting hammered during 11.11 flash sales, you can extract it as a standalone service with a clear API contract already in place. The groundwork is done.

The alternative building microservices for each of those domains at 50,000 users would add months of infrastructure work before you’ve even proven the product works in all three markets.

How to build a backend that scales from 100 to 10 million users

FAQ

Q: Can I start with a monolith and migrate to microservices later without rewriting everything?

A: Yes and this is actually the intended migration path. The key is maintaining clean module boundaries inside your monolith from early on. If you’ve built a well-structured modular monolith, extracting a service means defining the API boundary (it probably already exists as a module interface), setting up the deployment infrastructure for that service, and gradually moving traffic. It’s still significant work, but it’s not a rewrite. A “big bang” monolith with tangled dependencies is the one that requires a painful rewrite.

Q: At what team size should I seriously consider moving to microservices?

A: Team size isn’t the only variable, but a rough heuristic: when you have more than 15–20 engineers working on the same codebase and deployment friction is measurably slowing you down, it’s worth having the conversation. The more useful indicator is whether you can deploy changes to one part of the system without risking unrelated parts and whether the answer is “no” consistently enough to hurt you.

Q: Are microservices harder to secure than a monolith?

A: Differently hard, not necessarily harder. In a monolith, your attack surface is more contained but a compromise can affect the whole system. In microservices, you have more network attack surface and need to secure service-to-service communication (mTLS, service accounts, network policies). The security posture depends entirely on your implementation. Neither architecture is inherently more secure.

Q: What about serverless is that a fourth option?

A: Serverless functions can be a useful pattern within any of these architectures, but they’re not a replacement architecture. You can have serverless functions inside a modular monolith (for async event processing, for example), and you can have them inside a microservices system. Serverless introduces its own complexity around cold starts, stateless design, and vendor lock-in that most teams underestimate. For most startups, it’s a tool, not a strategy.

Q: We’re a non-technical founder. How do we evaluate whether our current tech team is recommending the right architecture?

A: Ask them to explain the trade-offs, not just the choice. A strong engineer can tell you what you’re giving up with their recommended approach, not just what you’re gaining. If the pitch for microservices doesn’t include an honest discussion of operational overhead, distributed system complexity, and your team’s current capability to manage it that’s a flag. The best architecture recommendation for your stage should feel slightly boring. Exciting architecture choices are usually expensive ones.

The right architecture is the one that lets your team ship product, maintain reliability, and adapt as your business changes. That’s not microservices for most of you reading this. It’s probably a well-structured monolith or modular monolith that gives you the discipline to grow into something more distributed when the evidence actually demands it.

If you’re at the stage where these decisions are becoming real whether you’re building 0 to 1 or hitting the walls of a system you’ve outgrown this is exactly what we work through with clients at SpectreDev.

DeepSeek V4-Pro Just Got 4x Cheaper. But Here’s What Nobody’s Talking About

DeepSeek dropped a bombshell on May 22: the 75% discount on V4-Pro is now permanent.

That’s 20–35x cheaper than GPT-5.5. If you’re building AI agents or running automated coding pipelines, this changes everything.

The HN thread hit 433 points and 248 comments. Developers are excited. But there’s a catch almost nobody is discussing.

The Silent Problem: Single-Key Rate Limits

Here’s what happens when you actually try to use DeepSeek at scale with the new pricing:

[ERROR] 429 Too Many Requests

Every DeepSeek API key has a rate limit. When you’re running Claude Code, Cline, or any AI agent loop that fires off dozens of requests per second, you’ll hit that wall fast.

And when you hit it, your workflow stops. Dead.

The Fix: Multi-Key Load Balancing with Automatic Failover

The solution is conceptually simple but tricky to implement well:

┌─────────────┐     ┌──────────────────┐
│  Your App    │────▶│  Load Balancer   │
│  (Claude     │     │  (One-API /      │
│   Code, etc) │     │   custom proxy)  │
└─────────────┘     └──────┬───────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
        ┌─────────┐ ┌─────────┐ ┌─────────┐
        │ Key #1  │ │ Key #2  │ │ Key #3  │
        │ $5      │ │ $5      │ │ $5      │
        └─────────┘ └─────────┘ └─────────┘

Here’s how it works:

1. Round-robin distribution — spread requests across multiple keys so no single key hits the limit
2. Automatic failover — if Key #1 returns 429, the request automatically retries on Key #2
3. Transparent to your app — just point your OPENAI_BASE_URL at the proxy, keep using the same API format

Option 1: Roll Your Own

You can set this up with One-API (open source, Docker-friendly):

docker run -d -p 3000:3000   -e CHANNEL_TYPE=deepseek   -e CHANNEL_KEYS=sk-key1,sk-key2,sk-key3   justsong/one-api

Then configure multiple DeepSeek API accounts, each with its own key. One-API handles the load balancing and failover transparently.

Caveat: You need to manage key rotation yourself, monitor balance across accounts, and handle the ops overhead.

Option 2: Use a Managed Proxy

If you don’t want to run Docker containers and monitor key balances, there are services that handle this for you.

One option is AiCredits, which pools multiple DeepSeek keys behind a single endpoint with built-in failover. Same OpenAI-compatible API. Same DeepSeek models. But with redundancy baked in.

The tradeoff is a small markup over direct pricing — but you’re paying for:

• Automatic failover when keys hit rate limits
• No need to manage multiple accounts
• No Docker containers to maintain

What This Means for AI Agents

The real killer use case for DeepSeek V4-Pro at $0.87/M output is autonomous AI agents.

Claude Code, Cline, OpenCode — these tools fire off hundreds of API calls per session. With GPT-5.5 at $30/M output, a heavy coding session could cost $20+. With DeepSeek V4-Pro, the same session costs under $1.

But only if your setup can handle the throughput. Single-key setups will choke. Multi-key with failover won’t.

The Bottom Line

DeepSeek V4-Pro’s permanent 75% price cut is the biggest AI pricing event of 2026. But extracting maximum value requires solving the rate-limit bottleneck.

Whether you DIY with One-API or use a managed proxy, the important thing is: don’t build your agent pipeline on a single key.

What’s your setup for handling DeepSeek rate limits? Let me know in the comments.

I wanted to build a roulette website. I also set out to learn.

I have worked in IT for some time, started with Windows admin, moved to Linux, and then onto some basic DevOps work. I may have gotten to the 4th chapter of every Python book ever written, but never fully committed to programming. I have never really done every aspect of the build process, the “Full Stack.”

I wanted to understand the full picture — how a modern web application actually gets built, containerized, deployed, and maintained in production. Not just the code, but the infrastructure. Docker. Reverse proxies. SSL certificates. DNS. The things that tutorials skip over and production demands.

I also wanted to test a theory: could I use AI — specifically Claude — as a genuine development partner to build something real? Not to generate a throwaway script, but to architect, debug, and ship a production application across multiple servers, frameworks, and deployment environments?

So I built Big Spin Fun, a free online roulette game with European, American, and Triple Zero variants. It runs on Next.js, Django, PostgreSQL, and Nginx, all containerized with Docker Compose and deployed to AWS Lightsail. And I built virtually all of it through a conversation with Claude.

Here’s how it actually happened — the messy, nonlinear, real version.

Why Roulette?

I’ve always been a casual gambler with a genuine interest in the mechanics of different betting systems. I’m a regular viewer of channels like CEG Dealer School, The Roulette Master, and Jack Ace, and I found myself wanting a sandbox where I could test out strategies without any financial risk. In the end, building my own simulator felt like a much more rewarding challenge than simply clicking around on someone else’s site.
Claude as a Development Partner
Let me be upfront about this: Claude wrote the vast majority of the code in this project. But that sentence undersells what actually happened.

I didn’t paste in a prompt that said “build me a roulette game” and get back a finished product. The project evolved over a long, iterative conversation that spanned the full lifecycle of a real application — from a single React component to a multi-container Docker deployment with HTTPS, user authentication, and SEO optimization.

What made it work was that I brought the vision and the decisions, and Claude brought the implementation knowledge. I’d say “I want user accounts and a database,” and Claude would lay out the options — Django vs Flask, Postgres vs SQLite — explain the tradeoffs, and then build it once I chose a direction. When something broke, I’d paste the error, and Claude would diagnose it.

This wasn’t autopilot. I had to understand what was happening at every step. When Claude generated a Dockerfile, I needed to understand multi-stage builds to know why it was structured that way. When it wrote a Django model, I needed to understand what migrations were to debug why the database wasn’t creating tables. The AI accelerated my learning — it didn’t replace it.

The conversation itself became a kind of documentation. Every architectural decision, every debugging session, every “why did I get a 502 Bad Gateway” was captured in the chat history. I could scroll back and see exactly why we chose Next.js over plain React (SEO), why we added Nginx in front of everything (SSL termination and security), and why the database password couldn’t contain a + character (URL parsing).
Starting on Windows with VS Code
The project started on my Windows machine (using Windows Subsystem for Linux) with VS Code open and a vague idea: build a roulette wheel that spins. That was it. No grand architecture plan, no deployment strategy, just curiosity.

I opened Claude and described what I wanted. Within minutes, I had a working React component — a spinning SVG wheel with authentic pocket ordering, a grid of clickable numbers, chip selection, and payout calculations. It ran in Vite on localhost. You could click a number, hit spin, and watch an animated wheel land on a random pocket.

That first component was maybe 400 lines of JSX. Claude generated the entire thing — the SVG math for the wheel segments, the CSS animations for the spin physics, the betting logic, the color mapping for red and black numbers. Things that would have taken me days of MDN documentation and Stack Overflow to figure out came together in a single response.

But here’s the thing: I immediately started asking questions. “What language is React?” “How do I make changes to this?” These weren’t embarrassing questions — they were the natural learning path of someone using AI to build beyond their current skill level. And Claude answered them without judgment, at exactly the level of detail I needed.

VS Code was my constant companion through every phase. The search and replace functionality alone probably saved me hours. When you’re renaming things across a full-stack app — changing “Roulette Royale” to “Big Spin Fun” across frontend pages, meta tags, Docker configs, and Nginx files — Ctrl+Shift+H becomes your best friend.
The Docker Obsession
Docker is the cornerstone of the modern-day app in the cloud. I could have stopped at a single React app served by Nginx. But I wanted to understand Docker. Not just “run a container,” but actually architect a multi-container application the way production systems work.

I told Claude I wanted everything in Docker containers, very portable, something I could eventually move to AWS. Claude scaffolded a multi-stage Dockerfile — Node builds the React app, then only the compiled static files get copied into an Nginx Alpine image. The result was about 25MB. That felt satisfying.

But then I started thinking bigger. I wanted user accounts. A database. Server-side game logic so players couldn’t just edit their balance in the browser console. I asked Claude about Django, and that led to a conversation about architecture that fundamentally changed the project.

I am a perpetual beginner when it comes to Python. I have always had the intent to get more comfortable with it, so moving to Django seemed like a logical step

Claude didn’t just say “use Django.” It explained the tradeoffs. Django would give me auth, an admin panel, and an ORM, but the frontend would still need React for the interactive game. I’d end up with two containers plus a database. Was I ready for that complexity? I said yes.

That “yes” turned a weekend project into a real full-stack application:

Next.js for the frontend — Claude recommended it over plain React because I mentioned wanting SEO and advertising revenue eventually. That one recommendation shaped the entire frontend architecture.
Django REST Framework for the backend API — user auth, game engine, leaderboard
PostgreSQL for persistent data
Nginx as a reverse proxy in front of everything

Four services. One docker-compose.yml. Claude generated all of it — the Dockerfiles, the compose configuration, the Django models, the API views, the Next.js pages, the Nginx config. But each piece came through conversation, not a single prompt.
Docker Compose: Simple in Theory, Brutal in Practice
The docker-compose.yml looks clean when it’s done. Four services, some environment variables, a few volume mounts, a health check. Maybe 50 lines of YAML.

Getting to those 50 lines was anything but clean. And this is where working with Claude on real infrastructure problems — not textbook examples — taught me the most.
The Rocky Linux Detour
After getting everything working locally on Windows, I deployed to a Rocky Linux server. This was my first time running Docker Compose on a remote machine, and the workflow was clunky.

I’d edit files locally in VS Code, push to GitLab, SSH into the Rocky server, pull the changes, rebuild, and check if it worked. When it didn’t — and it often didn’t — I’d SSH back in, read the logs, paste them into Claude, get a fix, go back to VS Code, make the change, push, pull, rebuild.

Claude was patient through all of this. The same kinds of errors would come up in slightly different forms, and it would adjust its advice based on what we’d already tried. It remembered context from earlier in the conversation — “we fixed the migration issue already, so this is a different problem” — which kept the debugging focused.

Rocky Linux worked fine as a Docker host, but when I decided to move to AWS, Ubuntu was the more natural choice for Lightsail.
Moving to AWS Lightsail
Lightsail is AWS’s simplified VPS offering. You pick a size, pick an OS, and you get a server with a static IP. No VPC configuration, no security group mazes, no IAM policy debugging. Claude recommended it as the simplest path to AWS — it’s AWS for people who just want a server.

Claude walked me through the entire setup: SSH key generation, installing Docker on Ubuntu, cloning from GitLab using SSH keys, configuring DNS. Each step was a short exchange — I’d ask “how do I do X,” Claude would give me the exact commands, I’d run them, report back, and move on.

When the build hung on the small Lightsail instance, Claude suggested the GitLab Container Registry — build on my local machine, push images to GitLab’s free registry, pull pre-built images on the server. The server only needs enough RAM to run the containers, not build them.

Before: build on the server (needs RAM)

frontend:

build: ./frontend

After: pull pre-built images (needs almost no RAM)

frontend:

image: registry.gitlab.com/booker357/roulette-page/frontend:latest

Eventually I added swap space and switched back to building on the server directly, which simplified the workflow. Edit files on Lightsail, build on Lightsail, push to GitLab for version control. One machine, one workflow.
The Migration Problem
Django uses migration files to create database tables. These files need to exist in the codebase before the application starts. Claude had generated the models and the views, but the migration files — the glue between the code and the database — were missing from the project.

The cycle went like this: start the app, Django crashes because the accounts_player table doesn’t exist, paste the error into Claude, get told to run makemigrations, run it inside the container, migrations get created in the container’s filesystem, stop the container, migrations disappear, start the container, crash again.

This went on for multiple rounds. Each time I’d paste the error into Claude, and each time we’d get a little closer to understanding the root cause. Claude eventually realized the issue: the migration files were being generated inside ephemeral containers and never persisted to the host filesystem. The fix was to create the migration files directly and commit them to the repo.
I was, admittedly, pretty dependent on Claude.

Claude then generated the complete migration files by hand — reading the Django models it had written earlier and producing the corresponding migration Python code. It was like watching someone debug their own work in real time.

This was a turning point in how I thought about AI-assisted development. Claude had made an oversight in the initial scaffolding (not including migration files), but it was also the one that diagnosed the problem, explained why it was happening, and generated the fix. The AI wasn’t perfect, but it was resilient — each error message I fed back in got us closer to a working system.
The Build Problem
Building Docker images requires RAM. Building a Next.js app inside a Docker container on a small server requires more RAM than a small server has. I learned this the hard way when docker compose build would just hang indefinitely on a 512MB VPS, the cheapest host option in AWS Lightsail.

I told Claude it was hanging, and it immediately identified the issue: insufficient RAM for the Node.js build process. It gave me a few solutions — add swap space, use a container registry to build elsewhere, or upgrade to a larger VPS. I built the containers remotely using GitLab at first, but I eventually upgraded the VPS instance and added additional swap space so I could build on the VPS.

Environment Variables and Special Characters
I generated a random database password with openssl rand -base64 24. The password contained a + character. That + got embedded in the database URL (postgres://user:pass+word@db:5432/roulette) and broke Python’s URL parser. The error message — ValueError: Port could not be cast to integer value as ‘zu1mnDRpA6v+’ — made no sense to me.

I pasted it into Claude. Within seconds, it identified that the + in the base64 password was being interpreted as a URL-encoded space, corrupting the port parsing. The fix: use openssl rand -hex 24 instead. Only alphanumeric characters. No special characters to break URL parsing.

This is the kind of bug that could take hours to figure out on your own. Claude diagnosed it from the error message in one turn. That’s not replacing my learning — it’s accelerating it. I now understand URL encoding, database connection strings, and why special characters in environment variables are dangerous. I learned it through a real bug, not a textbook.
HTTPS: The Certificate Dance
Getting SSL working was its own adventure. Claude generated the entire Nginx configuration, the Certbot Docker setup, and a setup script that handled the chicken-and-egg problem: Nginx needs SSL certificates to start, but Let’s Encrypt needs Nginx running to verify your domain.

The solution is a multi-step dance:

Create a temporary self-signed certificate so Nginx can boot
Start Nginx
Run Certbot to get a real certificate via the ACME challenge
Reload Nginx with the real certificate

Except the real certificate ended up in bigspinfun.com-0001 instead of bigspinfun.com because the self-signed cert was already occupying the expected directory. So Nginx kept serving the self-signed cert, and browsers showed a security warning.

I told Claude the browser was showing “Not Secure.” It had me check which certificate was actually being served using openssl s_client, which revealed the self-signed cert was still active. Claude figured out that Certbot had created the real cert in a -0001 suffixed directory to avoid overwriting the temp cert. The fix was renaming the directory:

sudo mv …/bigspinfun.com-0001 …/bigspinfun.com

docker compose restart nginx

This was a problem neither of us anticipated. Claude didn’t generate a bug-free setup — it generated a setup that worked in theory but hit an edge case in practice. Then it debugged that edge case from the symptoms I reported. That’s how real development works, with or without AI.
Claude for SEO and Marketing
Once the site was running, the conversation shifted from infrastructure to business. I told Claude I wanted advertising revenue and SEO optimization. It laid out a complete strategy:

SEO first — the site needs to be crawlable before ads make sense
Advertising second — apply for AdSense once content is solid
Expense tracking last — internal tooling can wait

Claude then generated everything for SEO: a robots.txt, a dynamic sitemap, JSON-LD structured data, Open Graph tags, Twitter Cards, and three full content pages targeting specific search queries — “how to play roulette,” “roulette odds,” and “roulette bet types.” Each page had unique metadata, proper heading hierarchy, FAQ sections with schema markup, and internal linking.

It also generated a privacy policy (required for AdSense) and walked me through submitting the sitemap to Google Search Console and Bing Webmaster Tools, setting up Google Analytics, and fixing SEO issues that Bing’s crawler flagged — a missing H1 tag and duplicate canonical URLs.

The SEO work was where Claude’s breadth of knowledge really showed. It wasn’t just writing code — it was making strategic decisions about which keywords to target, how to structure content for featured snippets, how to optimize for AI search engines (allowing GPTBot and ClaudeBot in robots.txt), and when to use server-rendered pages vs client-side components.
What AI-Assisted Development Actually Feels Like
People have strong opinions about AI coding tools. Some think it’s cheating. Some think it produces garbage. Some think it replaces developers. After building an entire production application through conversation with Claude, here’s my experience:

It’s not cheating. I made every architectural decision. I chose the stack, the hosting, the domain, the feature set. Claude implemented those decisions, but the judgment calls were mine. When Claude suggested Next.js for SEO, I had to understand what SSR meant and why it mattered before saying yes.

It’s not garbage. The code Claude generated was clean, well-structured, and production-ready. The Django models had proper indexes and ordering. The Nginx config had security headers and gzip compression. The React components used proper state management. Was it perfect? No — the missing migration files and the SSL certificate edge case prove that. But the quality was consistently high.

It doesn’t replace understanding. I learned more about web infrastructure in this project than in any course I’ve taken. Every error message I pasted into Claude became a learning opportunity. I didn’t just fix the problem — I understood why it happened. The AI compressed what would have been weeks of Stack Overflow and documentation into hours of focused, contextual learning.

It changes the ambition curve. Without Claude, I would have built a static HTML roulette game and called it done. With Claude, I built a full-stack application with user auth, server-side RNG, a PostgreSQL database, Docker containers, Nginx reverse proxy, SSL certificates, SEO optimization, and analytics — and deployed it to AWS. The AI didn’t lower the bar. It raised how far I was willing to reach.

The conversation is the product. The most underrated aspect of AI-assisted development is the conversation itself. Every decision, every debugging session, every “why did we do it this way” is captured in the chat history. It’s like pair programming with someone who has infinite patience and remembers everything you’ve discussed.
GitLab as the Backbone
Throughout all of this — Windows to Rocky to Lightsail — GitLab was the constant. Every change got committed and pushed. When I broke something (which happened regularly), I could look at the git log and figure out what changed. When I moved servers, I could clone the repo and have the entire project structure in seconds.

I set up SSH keys on each server so git operations were seamless. No tokens to manage, no passwords to type. Claude walked me through the SSH key setup for each environment.

The GitLab Container Registry was a bonus I didn’t expect. Free private Docker image hosting, integrated with the repo. Push an image, pull it on any server. No separate Docker Hub account needed.
The Stack Today
The production setup at bigspinfun.com:

Next.js 14 — server-side rendered frontend with SEO content pages
Django REST Framework — user accounts, server-side RNG, game history API
PostgreSQL 16 — persistent storage for users, spins, leaderboard
Nginx — reverse proxy, SSL termination, gzip, security headers
Let’s Encrypt — auto-renewing SSL certificates via Certbot
Docker Compose — all four services defined in one file
AWS Lightsail — Ubuntu instance with 2GB RAM, 12$ per month, at the time of this writing
GitLab — source control and container registry
Claude — development partner from first line of code to production deployment

The entire thing can be cloned and started with docker compose up. That was always the goal — portability. Move it to any server with Docker installed, and it just works.
What I’d Do Differently
If I started over, I’d start by using the cloud from day one. I would start with the cheapest solution and work my way up from there. I’d also set up the migration files and Docker Compose health checks. The number of hours spent debugging “why won’t Django start” because of missing migrations was embarrassing — even with Claude helping.

I’d also start with HTTPS immediately. Setting it up after the fact means reconfiguring CORS origins, cookie settings, and CSRF trusted origins. Setting it up first means everything just works with the secure defaults.

And I’d build on a machine with at least 2GB of RAM from the start. The time spent debugging “why is Docker Compose hanging” on undersized servers was time I could have spent on features.
The Point
This project taught me more about real-world web development than any course or tutorial. Not because the roulette game is complex — it’s a fairly simple application. But because deploying it to production, keeping it running, and making it accessible to the world involves a web of interconnected systems that you can only understand by building through the problems.

Claude didn’t remove the problems. It made them solvable at a pace that kept me engaged instead of frustrated. Every error became a five-minute conversation instead of a two-hour rabbit hole. That’s the difference between giving up and shipping.

If you’re trying to learn infrastructure, pick a project you actually want to build and deploy it for real. Not to localhost. Not to a tutorial sandbox. To a real server with a real domain and real SSL certificates. And if you use an AI to help you get there, don’t feel guilty about it — feel empowered. The understanding you gain from building something real, even with help, is worth more than the theoretical knowledge of doing it alone.

The game is live at bigspinfun.com. It’s free, no real money, no signup required. Spin the wheel, place some bets, and if you’re curious about how it’s built, now you know.

Java Records have been stable since Java 16, and with Java 21 now the LTS baseline, they’re showing up everywhere – DTOs, value objects, domain models. Immutable by design, concise, and semantically clear.

But here’s the gap nobody talks about: every object mapper in the Java ecosystem was built before Records existed. They were designed around JavaBeans – mutable objects with getters, setters, and no-arg constructors. Records have none of that. So what happens? These libraries bolt on partial Record support as an afterthought, and the seams show.

I built Immuto to fill that gap.

The problem with retrofitted Record support

A Record’s identity is its canonical constructor:

public record PersonDTO(Long id, String fullName, String email) {}

That constructor is the only way to create a PersonDTO. There are no setters. There is no builder unless you write one yourself. The component accessors are read-only.

Existing mappers were not designed with this in mind. To work with Records, they either:

• Generate setter calls that don’t exist (and fail at runtime)
• Require you to write a mutable builder as a workaround
• Fall back to reflection on private fields — bypassing the canonical constructor entirely

These are runtime failures. You don’t know something is wrong until you run the code.

What Immuto does differently

Immuto is an annotation processor – it runs during mvn compile, the same way Lombok and the APT-based approach work. It generates plain .java source files that call your record’s canonical constructor directly. No reflection. No setters. No runtime surprises.

@RecordMapper
public interface PersonMapper {

    @Mapping(target = "fullName",
             expression = "java(source.firstName() + " " + source.lastName())")
    PersonDTO toDto(PersonEntity source);

    @InheritInverseConfiguration(name = "toDto")
    PersonEntity toEntity(PersonDTO source);
}

After mvn compile, Immuto writes PersonMapperImpl.java into target/generated-sources. It looks exactly like code you’d write by hand:

@Generated("io.github.karunarathnad.immuto.processor.RecordMapperProcessor")
public final class PersonMapperImpl implements PersonMapper, ImmutoMapper {

    @Override
    public PersonDTO toDto(PersonEntity source) {
        if (source == null) return null;
        return new PersonDTO(
            source.id(),
            source.firstName() + " " + source.lastName(),
            source.email()
        );
    }
}

Canonical constructor. Always. That’s the contract Immuto enforces.

Compile-time validation

If a record component can’t be mapped, the build fails — not at runtime, not in a test, but during compilation.

• Unmapped component → build error
• Type mismatch with no registered converter → build error
• @RecordMapper on a class instead of an interface → build error

This is the behaviour Records deserve. They were designed to be explicit and safe; your mapper should be too.

Key features

Nested records — mapped recursively by matching component names. Use @Mapping(expression=...) for asymmetric nesting.

Bidirectional mapping via @InheritInverseConfiguration — define toDto, get toEntity for free.

@NullSafe — wraps the result in Optional.ofNullable(...) at the call site:

@NullSafe
Optional<AddressDTO> toAddressDto(AddressEntity entity);

Sealed class support – Immuto understands sealed hierarchies, something no existing mapper handles.

Lifecycle hooks – @BeforeMapping and @AfterMapping methods are inlined into the generated code. No AOP, no proxy.

Custom type converters:

@Named("isoDate")
public class IsoDateConverter implements TypeConverter<LocalDate, String> {
    @Override
    public String convert(LocalDate source, MappingContext ctx) {
        return source == null ? null : source.toString();
    }
}

Fluent runtime API – for tests or dynamic environments where APT isn’t available:

FluentMapper<PersonEntity, PersonDTO> mapper = FluentMapper
    .from(PersonEntity.class)
    .to(PersonDTO.class)
    .override("fullName", p -> p.firstName() + " " + p.lastName())
    .build();

Note: FluentMapper does use reflection — it’s the explicit opt-in escape hatch, not the default path.

Getting started

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>immuto-annotations</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>immuto-core</artifactId>
    <version>1.1.0</version>
</dependency>

<dependency>
    <groupId>io.github.karunarathnad</groupId>
    <artifactId>immuto-processor</artifactId>
    <version>1.1.0</version>
    <scope>provided</scope>
</dependency>

Add the processor path to the compiler plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>io.github.karunarathnad</groupId>
                <artifactId>immuto-processor</artifactId>
                <version>1.1.0</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

Then annotate an interface, run mvn compile, and use it:

PersonMapper mapper = Immuto.getMapper(PersonMapper.class);
PersonDTO dto = mapper.toDto(entity);

Why now

Java 21 is the current LTS. Records are not experimental — they’re the idiomatic way to model immutable data in modern Java. As more codebases adopt them, the need for tooling that treats them as first-class citizens (not an edge case) grows with it.

Immuto is on Maven Central, Apache 2.0 licensed, and under active development.

GitHub: github.com/karunarathnad/immuto

Feedback, issues, and contributions are very welcome.

This is where most tutorials stop. But if you try to use use() with a promise created inside a Client Component, you will hit a subtle and frustrating bug.

// Bug: creates a new promise on every render
function UserProfile({ userId }: { userId: string }) {
  const user = use(fetchUser(userId)); // new promise every render
  return <ProfileCard user={user} />;
}

fetchUser(userId) returns a new Promise object on every render. React sees a new promise, suspends again, and the component re-renders, creates another new promise, suspends again, infinite loop.

use() does not fetch data. It reads a promise. The promise must have a stable identity across renders. If you create a new promise on every render, you get an infinite suspension loop.

How to Stabilize the Promise
There are several approaches, each suited to a different archtecture:

1. Create the promise in a parent component or Server Component

// Server Component - promise created once, stable across renders
export default function UserPage({ params }: { params: { id: string } }) {
  const userPromise = fetchUser(params.id);

  return (
    <Suspense fallback={<Skeleton />}>
      <UserProfile userPromise={userPromise} />
    </Suspense>
  );
}

No async/await needed, the promise is passed down unresolved. The Client Component unwraps it with use(). Server Components don’t re-render, so the promise reference is inherently stable.

2. Use a module-level cache

For Client Components that need to initiate fetches, cache the promise so the same reference is returned on subsequent calls:

const cache = new Map<string, Promise<User>>();

function fetchUserCached(id: string): Promise<User> {
  if (!cache.has(id)) {
    cache.set(id, fetchUser(id));
  }
  return cache.get(id)!;
}

function UserProfile({ userId }: { userId: string }) {
  const user = use(fetchUserCached(userId));
  return <ProfileCard user={user} />;
}

Same arguments produce the same promise reference. No infinite loop.

Avoid async in Cache Wrappers

Do not mark your cache function as async. The async keyword always creates a new promise, even if you return a cached value. Use a synchronous function that stores and returns the original promise object.

3. Use a data fetching library

Libraries like TanStack Query or SWR handle caching, deduplication, and revalidation out of the box. They predate use() and solve a much broader problem – but they also add ~13kB gzipped and a provider wrapper. For a simple “fetch once, display result” pattern, use() with a 5-line cache function (option 2 above) does the job without the extra dependency. The library earns its keep when your UI has long-lived client state that needs to stay fresh: think dashboards that refetch on tab focus, lists with pagination, or mutations that should optimistically update related queries.

4. Use React’s cache() in Server Components
React provides a built-in cache() function for Server Components. It memoizes a function’s return value for the lifetime of a single server request:

import { cache } from "react";

const getUser = cache(async (id: string): Promise<User> => {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
});

Multiple components calling getUser("123") during the same render will share one fetch. The cache is scoped to the request, it resets on every new page load.

cache() vs. useMemo
Both memoize. But cache() works across components in a server render (deduplication), while useMemo works within a single component across re-renders. cache() is for data fetching. useMemo is for computations. Different tools, different jobs.

Originally published at thatdevpro.com. Part of ThatDevPro’s open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Google’s Core Algorithm Updates — Detection, Response, Recovery, and Prevention

A comprehensive installation and audit reference for monitoring Google’s core algorithm updates, classifying their impact on a website, executing the response protocol, tracking recovery, and building structural resilience to future updates. This document is dual-purpose: installation manual and audit document.

1. Document Purpose & How to Use This Document

1.1 What This Document Is

This is the canonical reference for handling Google core algorithm updates — the periodic broad-spectrum changes Google makes to its ranking systems that can dramatically reshape search results across millions of sites simultaneously. Core updates are different from spam updates, helpful content updates (now part of core), product reviews updates, and minor tweaks. Core updates are the largest, most consequential, and most disruptive changes Google deploys.

This document specifies how to detect when a core update is happening, how to assess its impact on a specific site, how to respond constructively (rather than panic-react), how to track recovery over the typical 60-90 day post-update period, and how to build a site that’s structurally resilient to future updates.

1.2 Three Operating Modes

Mode A — Install Mode: Building monitoring and response infrastructure into ongoing site operations. Follow Sections 2 → 14.

Mode B — Audit Mode: Evaluating an existing site’s preparedness for or response to core updates. Skip to Section 11.

Mode C — Hybrid Mode: Audit current state then install missing infrastructure.

1.3 How Claude Code CLI Should Consume This Document

1. Read Section 2 — collect client variables and historical update impact data
2. Read Section 3 — understand what core updates are and aren’t
3. Install monitoring infrastructure — Section 5
4. Define response protocols — Section 6
5. Build resilience patterns — Section 7
6. Validate — Section 11
7. Generate report — Section 14

1.4 Conflict Resolution Rules

1.5 Required Tools

• Google Search Console — primary source for traffic and ranking data
• Google Analytics 4 — for engagement data and traffic patterns
• Semrush Sensor / Mozcast / Advanced Web Ranking — for SERP volatility tracking
• Ahrefs / Semrush — for ranking history and competitor comparison
• Wayback Machine — for historical site state research
• Google Search Status Dashboard — status.search.google.com/
• Algoroo / SEMrush Sensor / RankRanger — for daily SERP volatility tracking

2. Client Variables Intake

# ============================================
# CORE UPDATES FRAMEWORK CLIENT VARIABLES
# ============================================

# --- Business Identity (REQUIRED) ---
business_name: ""
primary_domain: ""
business_industry: ""
ymyl_classification: ""              # "full", "partial", "lite", "non" (affects update sensitivity)

# --- Site History (REQUIRED) ---
domain_age_years: 0
historical_traffic_baseline: 0       # Pre-most-recent-update average daily organic traffic
historical_keyword_count: 0          # Number of keywords ranking in top 10
last_known_volatility_event: ""      # Date of last identified algorithm impact

# --- Past Core Update Impacts (REQUIRED) ---
past_update_impacts:
  - update_name: ""                  # e.g., "March 2026 Core Update"
    update_date: ""                  # YYYY-MM-DD
    direction: ""                    # "loss", "gain", "neutral", "mixed"
    magnitude_percent: 0             # Percent change in organic traffic
    pages_most_affected: []          # URLs with biggest changes
    hypothesis_about_target: ""      # What this site/team believes the update targeted
    remediation_actions_taken: []
    recovery_status: ""              # "full", "partial", "none", "still_in_progress"
    recovery_completion_date: ""

# --- Monitoring Infrastructure Status (REQUIRED) ---
has_gsc_property_verified: false
has_ga4_configured: false
has_serp_volatility_monitoring: false
has_ranking_tracker: false           # Ahrefs, Semrush, AWR, etc.
has_brand_alert_monitoring: false    # Google Alerts, Mention, Brand24
has_competitor_tracking: false

# --- Response Capability (REQUIRED) ---
has_documented_response_protocol: false
response_team_identified: false
response_team_members: []
emergency_communication_channel: ""  # How team alerts each other to volatility

# --- Site Resilience Posture (RECOMMENDED) ---
eeat_score: 0                        # From framework-eeat.md audit
hcs_score: 0                         # From framework-hcs.md audit
ymyl_score: 0                        # From framework-ymyl.md audit if applicable
sqrg_estimated_rating: ""            # From framework-sqrg.md
content_quality_distribution:        # From HCS audit
  highest_or_high: 0                 # Percentage
  medium: 0                          # Percentage
  low_or_lowest: 0                   # Percentage

# --- Documentation (RECOMMENDED) ---
has_algorithm_update_log: false      # Internal log tracking all updates and impacts
has_post_update_review_process: false
has_quarterly_resilience_audit: false

# --- Recent Update Status (FILLED DURING ACTIVE UPDATE) ---
current_update_active: false
current_update_name: ""
current_update_started: ""           # Detection date
current_update_status: ""            # "rumored", "rolling_out", "completed", "in_recovery"
current_update_traffic_change: 0     # Percentage
current_update_response_phase: ""    # "detect", "assess", "diagnose", "remediate", "recover", "review"

3. What Core Updates Are

Google deploys algorithm changes constantly — hundreds of small updates per year. Most are imperceptible to individual sites. Three categories of updates have outsized impact and are publicly named by Google:

3.1 Core Updates

Core updates are broad changes to how Google’s core ranking algorithms evaluate content. They typically:

• Roll out over 1-3 weeks (some longer)
• Affect rankings across all niches simultaneously
• Are publicly announced by Google before, during, and after
• Get named after the month and year (e.g., “March 2026 Core Update”)
• Cause significant SERP volatility during rollout
• Reshape rankings substantially — some sites gain, some lose, most see some change

Google deploys 3-6 named core updates per year. Recent core updates and their characteristic focus:

• March 2024 Core Update — Integrated the Helpful Content System into core ranking; expanded site reputation abuse guidance
• August 2024 Core Update — Refined HCS signal weighting; addressed feedback about small site recovery from prior core updates
• November 2024 Core Update — Significant rollout addressing site quality holistically
• December 2024 Core Update — Targeted AI mass-production patterns specifically
• March 2025 Core Update — Significant E-E-A-T re-weighting
• June 2025 Core Update — Refinements to AI Overview source selection
• November 2025 Core Update — Reputation and content originality emphasis
• March 2026 Core Update — Most recent major update at time of this framework’s creation; focused on entity-based ranking and AI citation worthiness

3.2 What Core Updates Are Not

Core updates are not:

• Spam updates — These target manipulative practices specifically (link schemes, doorway pages, scraped content). Spam updates are separate.
• Reviews updates — Targeted at product/service review content quality. Now folded into core updates as of late 2023.
• Helpful Content updates — Now part of core ranking system as of March 2024.
• Manual actions — Penalties applied by human reviewers, communicated via Search Console. Different mechanism entirely.
• Indexing changes — When pages drop out of the index entirely, that’s typically a different issue (technical, manual action, or sitewide spam).
• SERP feature changes — When the SERP itself changes layout (more AI Overviews, more videos, etc.), that’s separate from core updates though often coincident.

3.3 What Core Updates Reward and Punish

Google’s official guidance: “There’s nothing wrong with pages that drop after a core update. They haven’t violated our spam policies nor are subject to a manual or algorithmic action, as can happen to pages that do violate those policies. In fact, there are no specific actions to take to recover from a core update. Negative rankings are not a signal that you have done anything wrong.”

In practice, core updates appear to:

Reward:

• Strong E-E-A-T signals (see framework-eeat.md)
• Helpful Content System compliance (see framework-hcs.md)
• Entity-based authority (see framework-knowledgegraph.md and framework-entitysalience.md)
• Genuine first-hand experience and original content
• Demonstrated topical authority through depth
• Sites with strong reputation research signals (see framework-sqrg.md)
• Sites with high information gain (see framework-infogain.md)
• For YMYL: credentialed authorship and rigorous editorial process

Punish:

• Thin or low-value content
• Aggregated content that doesn’t add original insight
• Mass-produced AI content without expert review
• Sites with reputation issues
• YMYL content from non-credentialed sources
• Sites violating spam policies (though spam violations typically trigger spam updates)
• Sites with significant Helpful Content System failures
• Sites that game freshness signals without substantive updates

3.4 The Recovery Truth

Recovery from a core update is possible but not guaranteed. Google’s guidance: “Improvements in your content might result in better rankings — though changes might not be reflected until the next core update.”

Core updates are evaluative re-baselines. Once Google’s evaluation of a site changes negatively, recovery typically requires:

1. The site genuinely improving (content quality, E-E-A-T, etc.)
2. Time for Google to recognize the improvement
3. The next core update incorporating the new evaluation

Sites typically don’t “recover” between core updates. They might see modest fluctuation but the major re-baseline happens at the next core update. This means recovery cycles are typically 90+ days minimum, often 6-12 months.

Some sites never recover. If the core update detected fundamental issues with the site’s purpose, content strategy, or trust posture, those issues need fundamental remediation. Cosmetic changes don’t trigger recovery.

4. Update Detection Protocol

4.1 Signals That an Update Is Happening

Detect updates through multiple signal sources:

4.1.1 Official Google announcements

Google typically announces core updates via:

• @SearchLiaison on X — primary public communication channel
• developers.google.com/search/blog — official blog posts
• status.search.google.com — Search Status Dashboard
• Reddit r/google_seo and r/seo — community confirmation

Set up alerts:

# Monitor SearchLiaison via RSS or alternative
# Monitor Google Search Blog RSS:
# https://developers.google.com/search/blog/feed.xml

4.1.2 SERP volatility tools

Daily volatility tracking:

• Semrush Sensor — semrush.com/sensor/ — daily volatility per category
• Mozcast — moz.com/mozcast/ — Moz’s tracker
• Advanced Web Ranking SERP Volatility — daily
• Algoroo — algoroo.com — ranking volatility tracker
• CognitiveSEO Signals — independent volatility tracker

When volatility spikes 7+ across multiple trackers, an update is likely active.

4.1.3 Site-specific signals

For each monitored site, set up:

• GSC daily traffic alerts — flag any day with >15% traffic deviation
• Ranking tracker alerts — flag tracked keywords with >5 position drops
• Server log monitoring — sudden Googlebot crawl pattern changes
• Brand mention alerts — sudden coverage in SEO publications

4.1.4 Industry signal aggregation

Monitor:

• Search Engine Land — official update coverage
• Search Engine Roundtable — Barry Schwartz’s daily volatility coverage
• Search Engine Journal — algorithm coverage
• r/SEO — community-level confirmation

4.2 Detection Workflow

When potential update is detected:

1. Confirm via multiple sources — Don’t react to single-source rumors
2. Document detection time — Note the moment volatility appeared
3. Note Google’s communication status — Has Google confirmed officially?
4. Open algorithm update incident log entry — Begin tracking impact

Algorithm update incident log template at /admin/algorithm-incidents/{{date}}-{{update-name}}.md:

# Update Incident: {{UPDATE_NAME}}

## Detection
- Detected: {{DATETIME}}
- Detection sources: {{LIST}}
- Google confirmation: {{YES/NO/PENDING}}
- Confirmation date: {{DATE_IF_CONFIRMED}}

## Volatility Indicators
- Semrush Sensor: {{SCORE}}/10
- Mozcast: {{SCORE}}
- Other trackers: {{SCORES}}
- Industry sources reporting: {{LIST}}

## Initial Impact Assessment (24 hours post-detection)
- Traffic delta vs 7-day average: {{PERCENTAGE}}
- Top affected pages: {{LIST}}
- Top affected keywords: {{LIST}}

## Working Hypothesis
{{WHAT_WE_THINK_THIS_UPDATE_TARGETS}}

## Status
{{DETECTING / ASSESSING / DIAGNOSING / REMEDIATING / RECOVERING / REVIEWED}}

4.3 The 72-Hour Hold

Critical rule: do not take significant remediation action within 72 hours of detection.

Reasons:

1. The update is probably still rolling out — early data is incomplete
2. SERP volatility within an update is normal and self-corrects
3. Knee-jerk responses cause damage that’s hard to reverse
4. The update may not target what you think it targets
5. Three days of data lets you distinguish signal from noise

During the 72-hour hold:

• Document what’s happening
• Monitor (don’t react)
• Read Google’s official communications
• Read industry analysis
• Survey community discussions
• Resist client/stakeholder pressure to “do something now”

After 72 hours, you have enough data to begin assessment.

5. Update Impact Assessment

5.1 Quantitative Impact Analysis

After 72 hours, gather data:

5.1.1 Site-wide traffic delta

Compare: 7-day average post-detection vs 7-day average pre-detection
Compare: Same period year-over-year (control for seasonality)
Compare: Specific weekday-to-weekday (Monday vs Monday)

Calculate:
- Total organic traffic change (%)
- Total organic clicks change (GSC)
- Total impressions change (GSC) — distinguishes ranking from CTR issues
- Average position change (GSC)

5.1.2 Per-page impact

In GSC Performance report:

1. Filter date range: 7 days post-update vs 7 days pre-update
2. Sort by traffic change descending and ascending
3. Identify pages with >25% traffic change in either direction
4. Document URL, change percentage, page type, primary topic

Build a per-page impact spreadsheet:

url,page_type,primary_topic,traffic_pre,traffic_post,traffic_delta_pct,impressions_pre,impressions_post,impressions_delta_pct,position_pre,position_post,position_delta,ymyl_status,word_count,content_age_days,last_refresh_days_ago,has_credentialed_author,notes
/articles/medication-guide,article,health/medication,1247,621,-50.2,4500,3200,-28.9,3.2,4.8,-1.6,full_ymyl,2400,367,367,no,major_loss_no_credentialed_review
/articles/site-speed-guide,article,seo/technical,892,1108,+24.2,3200,3850,+20.3,4.1,3.6,+0.5,non,1850,121,32,yes,small_gain

5.1.3 Per-query impact

In GSC Performance:

1. Pivot by query
2. Identify queries with significant change
3. Determine if changes cluster around specific topics or page types

5.1.4 Per-content-type impact

Group affected pages by type:

• Blog articles
• Service pages
• Product pages
• Local landing pages
• Author/author pages
• Resource/tool pages
• Category/hub pages

Compare change distribution across types. If one type is dramatically worse hit, the update likely targeted something specific to that type.

5.2 Pattern Recognition

Look for patterns among losing pages:

Content patterns:

• Common topic clusters?
• Common content type?
• Common publication age?
• Common author?
• AI vs human-written?
• Original vs aggregated content?
• Length patterns?

Quality patterns:

• Common E-E-A-T weaknesses?
• Common HCS failures?
• Common YMYL gaps?
• Thin content patterns?

Technical patterns:

• Common URL structures?
• Common templates?
• Common rendering issues?
• Common Core Web Vitals issues?

Reputation patterns:

• Topics where the site has weak authority?
• Topics where competitors have stronger E-E-A-T?
• Niches where the site doesn’t fit the established expert pattern?

Document patterns in the incident log.

5.3 Hypothesis Formation

After pattern analysis, form 2-3 hypotheses about what the update targeted:

Example hypotheses:

• H1: “Update targeted AI-generated YMYL content without expert review. Pages lost: 80% are AI-assisted YMYL articles. Pages held: 90% have credentialed reviewers.”
• H2: “Update reweighted entity-based authority. Pages lost: those on topics where the site lacks topical authority. Pages held: those in our 3 primary topical pillars.”
• H3: “Update penalized aggregator pages. Pages lost: ‘best of’ lists with no original testing. Pages held: original testing/research pages.”

Test each hypothesis against the data:

• Does the pattern hold across the affected page set?
• Are there counter-examples?
• Does the hypothesis explain the magnitude of loss?
• Is the hypothesis consistent with Google’s official communications?

The hypothesis that explains the most data is most likely correct. If multiple hypotheses fit, multiple changes may have happened.

5.4 External Hypothesis Validation

Compare to industry analysis:

• What’s the consensus from Search Engine Land, Search Engine Journal, Barry Schwartz’s coverage?
• What patterns are other practitioners reporting?
• Has Google given any specific guidance about this update?

If external analysis matches your internal pattern, confidence is high. If it doesn’t match, either your situation is unusual (worth investigating why) or your hypothesis is wrong.

6. Response Protocol

6.1 Response Phase Decision Matrix

Based on impact assessment, choose response track:

Minimal impact (<10% traffic change):

• Document the update
• Monitor for 30 days
• No remediation action
• Review at quarterly resilience audit

Moderate loss (10-30% traffic change):

• Document patterns identified
• Initiate targeted remediation on identified weaknesses
• 60-90 day recovery monitoring
• Full audit using applicable frameworks

Significant loss (30-50%):

• Comprehensive audit using all foundational frameworks
• Aggressive remediation
• 6-12 month recovery expectation
• Strategic review of content portfolio

Catastrophic loss (>50%):

• Full strategic reset
• Remove or significantly remediate large content sections
• Likely 12+ month recovery if at all
• Consider whether site model is viable

6.2 What Not to Do (Immediate)

Within first 30 days post-update, avoid:

• Mass deletion of content — without rigorous analysis, you may delete the wrong content
• Mass canonicalization changes — can compound the problem
• Mass redirect operations — if rankings recover, redirects work against you
• Major site architecture changes — distracts from the actual issue
• Removing internal links — if you misdiagnose, you’ve lost link equity unnecessarily
• Changing CMS or stack — adds variables that obscure what’s working
• Buying/exchanging links — never appropriate, especially during an update
• Mass content rewriting — rewriting hundreds of articles in panic mode produces lower-quality content

6.3 Constructive Response Actions

6.3.1 If E-E-A-T issues identified

Apply framework-eeat.md remediation per pillar:

• Strengthen author credentials and bio pages
• Add reviewer credit to YMYL content
• Improve schema graph for entity recognition
• Build reputation infrastructure
• Add citation lists to factual content

6.3.2 If HCS issues identified

Apply framework-hcs.md remediation:

• Identify and remove/consolidate thin content
• Refocus on topical pillars
• Improve About page substantively
• Add original value markers per article
• Disclose AI use properly

6.3.3 If YMYL issues identified

Apply framework-ymyl.md remediation:

• Add credentialed reviewers
• Add primary literature citations
• Build out editorial and corrections policies
• Add topic-specific disclaimers per article

6.3.4 If entity issues identified

Apply framework-entitysalience.md and framework-knowledgegraph.md:

• Reinforce primary entity per page
• Build entity sameAs graph
• Pursue Wikidata entry
• Strengthen topical hub pages

6.3.5 If technical issues identified

Apply Tier 1 of the 14-tier framework:

• Fix Core Web Vitals issues
• Resolve crawl errors
• Improve mobile experience
• Address indexing problems

6.4 Remediation Documentation

Track every remediation action in the incident log:

## Remediation Actions Taken

### Week 1 ({{DATE_RANGE}})
- {{DATE}}: {{ACTION}} — {{PAGES_AFFECTED}} — {{REASONING}}
- {{DATE}}: {{ACTION}} — {{PAGES_AFFECTED}} — {{REASONING}}

### Week 2 ({{DATE_RANGE}})
- {{DATE}}: {{ACTION}} — {{PAGES_AFFECTED}} — {{REASONING}}

### Week 3+ ({{DATE_RANGE}})
{{...}}

This documentation is essential for:

• Understanding what helped (correlation with recovery)
• Avoiding repeated mistakes
• Learning across multiple updates over time

6.5 Communication With Stakeholders

During an update, communicate clearly with clients/management:

Initial communication (within 48 hours of detection):

• “Google deployed a core update. Industry-wide volatility is significant.”
• “Our site is showing {{IMPACT_DESCRIPTION}}.”
• “We’re in the data-gathering phase. Substantive remediation begins in 72-96 hours.”
• “Recovery expectation: {{TIMEFRAME_BASED_ON_IMPACT_LEVEL}}.”

Weekly during active update:

• Status of impact (improving/stable/worsening)
• Hypothesis about update targets
• Remediation actions in progress
• What we’re not doing and why
• Expected next milestone

Post-stabilization (4-6 weeks post-update):

• Final impact assessment
• Comprehensive remediation plan
• Recovery monitoring schedule
• Strategic recommendations

7. Recovery Tracking

7.1 Recovery Indicators

Monitor weekly:

Recovery signal indicators:

• Traffic trending upward week-over-week
• Lost keywords regaining position
• Affected pages crawled more frequently
• New impressions in GSC for previously suppressed queries
• Indexed page count returning to baseline
• Engagement metrics improving on remediated content

Continued suppression indicators:

• Traffic remains flat at reduced level
• Keywords don’t recover position
• Crawl frequency doesn’t return to baseline
• New content also struggles to rank

7.2 Recovery Timeline Expectations

Based on impact severity:

Recovery is not linear. Expect ups and downs week-to-week. The trend over 30-60 day windows is what matters.

7.3 Cross-Update Recovery Patterns

Review historical update impact data:

• Did this site recover from previous updates? On what timeline?
• Were recovery efforts effective?
• What patterns of remediation correlate with recovery?

Build institutional memory of what works for this specific site.

7.4 When Recovery Doesn’t Happen

If 6-12 months post-update show no recovery signals:

1. Reassess hypothesis — was the diagnosis correct?
2. Audit remediation execution — did we actually do what we documented?
3. Compare to recovered competitors — what did they do differently?
4. Consider strategic reset — is the site model fundamentally compromised?

Strategic resets may include:

• Migrating to a new domain
• Spinning off categories into separate sites
• Drastically reducing content footprint
• Rebuilding from a different angle

These are major decisions made over months of consideration, not immediate post-update reactions.

8. Building Resilience to Future Updates

The best response to a core update is having built a site that wasn’t going to be hit by it in the first place. Resilient sites share characteristics.

8.1 Foundational Resilience

E-E-A-T strong by default — Sites that score 110+/130 on E-E-A-T audit before an update are resilient by default. Apply framework-eeat.md continuously, not reactively.

HCS-aligned content strategy — Sites that publish for users, not for search, weather updates better. Apply framework-hcs.md.

YMYL standards maintained — YMYL content meeting elevated standards rarely loses in updates. Apply framework-ymyl.md.

Entity authority — Sites with strong entity recognition through Wikidata, Wikipedia, schema graph, and topical authority weather updates better. Apply framework-knowledgegraph.md and framework-entitysalience.md.

8.2 Content Portfolio Resilience

Topical focus — Sites covering 3-7 topics deeply outperform sites covering 30 topics shallowly. Don’t dilute.

Quality over quantity — Better to have 100 high-quality articles than 1000 mediocre ones. The mediocre ones drag the whole site down.

Genuine first-hand expertise — Content built on actual experience holds value through algorithm changes.

Original research and insight — Information Gain (see framework-infogain.md) is durable across updates.

Refresh discipline — Time-sensitive content kept current; outdated content retired.

8.3 Trust Infrastructure Resilience

Reputation infrastructure — Strong reviews, earned media, industry recognition compound over time and protect against reputation-targeting updates.

Author identity stability — Real, credentialed, persistent authors. Not turnover-heavy author rosters.

Technical foundations solid — Fast, secure, accessible, well-structured sites are easier for Google to evaluate accurately.

8.4 Operational Resilience

Algorithm update log maintained — Every update tracked. Learning compounds.

Quarterly resilience audits — Catch drift before it costs.

Foundational framework compliance — These frameworks are not one-time installs. Maintain compliance continuously.

Don’t over-optimize — Aggressive optimization creates fragility. Sites that try to game algorithms get hit by algorithm changes.

8.5 Resilience Audit

Quarterly, score the site against:

Score: 30 max. Resilient site: 25+/30. Sites scoring below 20 are at substantial risk in core updates.

9. Learning From Updates

9.1 Post-Update Review Cadence

After each core update completes (typically 4-6 weeks post-rollout):

1. Conduct full impact analysis
2. Validate or revise hypothesis
3. Document what remediation worked or didn’t
4. Update institutional knowledge
5. Update this framework if patterns suggest framework gaps

9.2 Cross-Update Pattern Analysis

Annually, review all algorithm update incidents:

• What patterns repeat across updates?
• What characteristics of this site keep getting hit?
• What characteristics keep being rewarded?
• What strategic changes should the site consider?

9.3 Industry Learning Integration

Continuously consume:

• Search Engine Land’s algorithm coverage
• Google Search Central blog
• Search Engine Roundtable’s daily reports
• WhitePress, Search Engine Journal analysis
• @SearchLiaison communications

But filter heavily — much SEO commentary is speculation. Trust patterns from your own data more than generic guidance.

10. Spam Updates and Manual Actions (Adjacent Issues)

While this document is about core updates specifically, related events require similar protocols.

10.1 Spam Updates

Spam updates target manipulative practices. If a site is hit by a spam update:

• Review Google’s spam policies (developers.google.com/search/docs/essentials/spam-policies)
• Identify and remediate violating practices
• Recovery from spam updates can be faster than core updates if violations are clearly remediated

10.2 Manual Actions

Manual actions are penalties applied by human reviewers and communicated via Search Console.

• Check Search Console > Security & Manual Actions > Manual actions regularly
• If a manual action is issued, follow Google’s reconsideration request process
• Document everything; reconsideration requires showing remediation

10.3 Algorithmic Action Without Public Update

Sometimes sites lose ranking without a publicly-named update. Possible causes:

• Localized algorithm changes
• Targeted spam intervention
• Hacking/security compromise
• Technical issue (de-indexing, canonical confusion)
• Reputation event

Investigation:

1. Check Search Console for security warnings, manual actions
2. Audit technical health (crawl errors, indexability, redirects)
3. Audit reputation (new negative content, hacked pages)
4. Audit content (was something published that violates policies?)
5. Compare to volatility trackers — was there an unannounced update?

Many “algorithmic actions” without public updates turn out to be technical issues or reputation issues remediable by direct action.

11. Audit Mode

11.1 Algorithm Update Preparedness Audit

Score the site:

11.2 Active Update Response Audit

If currently in an active update response, score:

11.3 Post-Update Review Audit

After update completes (4-6 weeks post-rollout), score:

12. Common Mistakes & Anti-Patterns

12.1 Panic Reaction

Anti-pattern: Within 48 hours of detecting an update, mass-deleting content or rewriting articles.

Why it fails: Premature action based on incomplete data causes more damage than the update did.

Fix: Respect the 72-hour hold. Gather data before acting.

12.2 Misdiagnosis

Anti-pattern: Assuming the update targeted thing X without checking the data, then remediating for thing X.

Why it fails: If the update actually targeted thing Y, your remediation doesn’t help — and it may hurt by introducing new issues.

Fix: Data-driven hypothesis formation. Validate hypothesis against patterns and external sources before acting.

12.3 Treating Updates as Penalties

Anti-pattern: Believing the site was “punished” and looking for what to “fix” to make Google “stop punishing.”

Why it fails: Updates re-evaluate quality holistically. Looking for a specific “violation” misses the structural nature of the change.

Fix: Treat updates as evaluative re-baselines. Improve the site genuinely, not as remediation theater.

12.4 Expecting Quick Recovery

Anti-pattern: Running emergency remediation hoping for recovery within weeks.

Why it fails: Recovery typically takes 90+ days minimum, often 6-12 months. Expecting faster sets up false hope and premature additional changes.

Fix: Realistic recovery expectations. Plan for the long game.

12.5 Single Update Focus

Anti-pattern: Treating each update as isolated event, not learning across them.

Why it fails: Misses pattern recognition. Sites that don’t learn keep getting hit by similar update types.

Fix: Cross-update pattern analysis. Build institutional learning.

12.6 Tracker Chasing

Anti-pattern: Reacting to daily volatility tracker fluctuations as if every spike is a major update.

Why it fails: Most volatility is noise. Reacting to noise causes thrashing.

Fix: Trust multi-source confirmation before treating something as a major update.

12.7 Ignoring Foundational Frameworks

Anti-pattern: Trying to recover from an update without ever auditing E-E-A-T, HCS, YMYL, or SQRG compliance.

Why it fails: Updates reward sites that comply with foundational frameworks. Skipping them limits recovery.

Fix: Use update events as forcing function for foundational framework audits.

12.8 Stakeholder Pressure-Driven Decisions

Anti-pattern: Making changes because a client or executive demands action, not because data supports it.

Why it fails: Pressure-driven changes often hurt more than help.

Fix: Educate stakeholders on the 72-hour hold, the diagnostic process, and realistic recovery timelines. Hold the line on data-driven response.

12.9 Ignoring Spam Update vs Core Update Distinction

Anti-pattern: Treating a spam update like a core update or vice versa.

Why it fails: Different remediation protocols. Spam violations need direct remediation; core update issues need quality improvement.

Fix: Identify which type of update is occurring before responding.

12.10 Over-Documenting While Under-Acting

Anti-pattern: Spending all energy documenting impact and analyzing patterns, never actually executing remediation.

Why it fails: Analysis paralysis prevents recovery.

Fix: Documentation supports action, doesn’t replace it. After 7-14 days of analysis, execute remediation in parallel with continued monitoring.

13. Maintenance Schedule

13.1 Daily

• Monitor SERP volatility trackers
• Check GSC for traffic anomalies
• Watch @SearchLiaison and industry news for update mentions

13.2 Weekly

• Review tracked keyword positions for unusual movement
• Check brand search results for new negative content
• Monitor traffic patterns for trend shifts

13.3 Monthly

• Review crawl stats for unusual patterns
• Check for new manual actions or security issues
• Assess content portfolio quality distribution

13.4 Quarterly

• Full resilience audit (Section 8.5)
• Foundational framework compliance refresh (E-E-A-T, HCS, YMYL, SQRG)
• Cross-incident pattern review
• Update institutional knowledge base

13.5 Annually

• Comprehensive year-in-review of all updates and impacts
• Strategic resilience planning for upcoming year
• Framework document revisions based on year’s learning
• Stakeholder education on update reality

13.6 During Active Update

• 24-hour intervals during first week
• 72-hour intervals during weeks 2-4
• Weekly during recovery monitoring (months 2-6)

14. Implementation/Audit Report Templates

14.1 Post-Update Analysis Report Template

# Post-Update Analysis: {{UPDATE_NAME}}

## Update Identification
- Update name: {{NAME}}
- Detected: {{DATETIME}}
- Confirmed by Google: {{DATETIME}}
- Rollout completed: {{DATETIME}}
- Industry consensus on focus: {{SUMMARY}}

## Impact on This Site
- Total traffic change: {{PERCENTAGE}}
- Direction: {{LOSS/GAIN/MIXED}}
- Pages with >25% loss: {{COUNT}}
- Pages with >25% gain: {{COUNT}}
- Average position change: {{NUMBER}}
- Magnitude classification: {{MINIMAL/MODERATE/SIGNIFICANT/CATASTROPHIC}}

## Pages Most Affected
### Largest Losses
{{TABLE_OF_TOP_10_LOSSES}}

### Largest Gains
{{TABLE_OF_TOP_10_GAINS}}

## Pattern Analysis
{{IDENTIFIED_PATTERNS_ACROSS_AFFECTED_PAGES}}

## Hypothesis
**Primary hypothesis**: {{H1_DESCRIPTION}}
**Evidence supporting**: {{EVIDENCE}}
**Counter-evidence**: {{COUNTER_EVIDENCE}}

**Alternative hypothesis**: {{H2_DESCRIPTION}}
**Evidence supporting**: {{EVIDENCE}}

**Hypothesis confidence**: {{LOW/MEDIUM/HIGH}}

## Remediation Plan
### Phase 1 (Immediate)
{{ACTIONS}}

### Phase 2 (30 days)
{{ACTIONS}}

### Phase 3 (90 days)
{{ACTIONS}}

## Recovery Tracking
- 30-day check-in: {{SCHEDULED_DATE}}
- 60-day check-in: {{SCHEDULED_DATE}}
- 90-day check-in: {{SCHEDULED_DATE}}

## Lessons for Future Updates
{{INSIGHTS_TO_INTEGRATE}}

## Sign-Off
{{ANALYST_NAME}}, {{DATE}}

14.2 Algorithm Update Audit Report Template

# Algorithm Update Preparedness Audit

**Site**: {{BUSINESS_NAME}}
**Audit Date**: {{TODAY}}

## Resilience Score
{{X}}/30 — {{RESILIENT/AT_RISK/VULNERABLE}}

## Foundational Framework Status
- E-E-A-T: {{SCORE}}/130
- HCS: {{SCORE}}/54
- YMYL: {{SCORE}}/48 (if applicable)
- SQRG: {{ESTIMATED_RATING}}

## Monitoring Infrastructure Status
{{LIST_WITH_STATUS}}

## Response Capability Status
{{LIST_WITH_STATUS}}

## Past Update Impact History
{{TABLE_OF_PAST_UPDATES}}

## Risk Assessment
{{ASSESSMENT_OF_LIKELY_VULNERABILITIES}}

## Recommended Resilience Improvements
{{PRIORITIZED_LIST}}

## Sign-Off

End of Framework Document

Document version: 1.0
Last updated: 2026-04-29
Maintained by: ThatDeveloperGuy

Core updates are the most disruptive periodic events in SEO. The frameworks in this document — combined with foundational compliance with E-E-A-T, HCS, YMYL, SQRG, and entity-based authority — create resilience. Sites that build resilience proactively spend less time in reactive recovery. Sites that wait for updates to expose weaknesses spend significant time in recovery cycles.

The most important truth about core updates: the best response is not having needed one in the first place. Build sites that earn their rankings through genuine quality. Audit continuously. Improve continuously. Don’t wait for updates to reveal what was always going to be revealed.

Companion documents:

• framework-eeat.md
• framework-ymyl.md
• framework-hcs.md
• framework-sqrg.md
• framework-infogain.md
• framework-entitysalience.md
• framework-knowledgegraph.md
• framework-aicitations.md

About this framework library

This article is the Dev.to republish of a framework reference document from ThatDevPro’s SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-coreupdates/

ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio operating from Cassville, Missouri. The studio runs the full 14-tier Engine Optimization stack and ships open-source tooling for AI citation engineering.

Companion 14-tier Engine Optimization stack (each tier is its own article):

1. Tier 1 — Foundation
2. Tier 2 — Search Visibility
3. Tier 3 — AI Domination
4. Tier 4 — Entity and Authority
5. Tier 5 — Local Domination
6. Tier 6 — Content and Multimedia
7. Tier 7 — Social and Community
8. Tier 8 — Data, Analytics, Conversion
9. Tier 9 — Monitoring and Intelligence
10. Tier 10 — Workflow and Operations
11. Tier 11 — Marketplace and Retail
12. Tier 12 — International
13. Tier 14 — Advanced and Immersive

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

Originally published at thatdevpro.com. Part of ThatDevPro’s open SEO + AI framework library. ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio. Open-source AI citation toolkit: github.com/Janady13/aio-surfaces.

Establishing Entities in Google’s Knowledge Graph — Wikidata, Wikipedia, and the Entity Web

A comprehensive installation and audit reference for establishing a business and its key entities in Google’s Knowledge Graph, claiming and managing the Knowledge Panel, building reciprocal entity reconciliation across the web, and maintaining the entity authority that compounds across rankings, AI engines, and brand search results. This document is dual-purpose: installation manual and audit document.

Cross-stack implementation note: the code samples in this framework are written in plain HTML for clarity. For React, Vue, Svelte, Next.js, Nuxt, SvelteKit, Astro, Hugo, 11ty, Remix, WordPress, Shopify, and Webflow equivalents of every pattern below, see framework-cross-stack-implementation.md. For pure client-rendered SPAs (no SSR/SSG) see framework-react.md. For Tailwind-specific concerns (purge, dynamic classes, dark-mode CLS, focus accessibility) see framework-tailwind.md.

1. Document Purpose & How to Use This Document

1.1 What This Document Is

This is the canonical reference for establishing entities in Google’s Knowledge Graph (KG). The Knowledge Graph is Google’s database of entities and their relationships — people, places, organizations, products, concepts, events. When Google recognizes an entity in its Knowledge Graph, that recognition manifests as Knowledge Panels in search results, populates AI Overviews, drives entity-based ranking, and feeds the data that LLMs train on.

This framework specifies how to assess current entity recognition status, how to build the foundation for entity recognition (Wikidata being the primary path), how to pursue Wikipedia inclusion when notability supports it, how to claim and optimize the Knowledge Panel when it appears, and how to maintain entity authority over time. It also specifies entity reconciliation — the process by which Google associates external profiles, references, and data points with the canonical entity in its Knowledge Graph.

Entity authority compounds. Every authoritative reference, every Wikidata property added, every Wikipedia mention, every reciprocal external link reinforces Google’s confidence in the entity. Conversely, weak or fragmented entity signals leave Google uncertain — and uncertain entities don’t get Knowledge Panels, don’t rank as authoritatively, and don’t get cited by AI engines.

1.2 Three Operating Modes

Mode A — Install Mode: Building entity recognition from scratch or adding to existing presence. Follow Sections 2 → 14.

Mode B — Audit Mode: Evaluating existing Knowledge Graph status. Skip to Section 11.

Mode C — Hybrid Mode: Audit then install for gaps.

1.3 How Claude Code CLI Should Consume This Document

1. Read Section 2 — collect client variables, especially existing entity references
2. Read Section 3 — understand the Knowledge Graph and entity ecosystem
3. Run Section 4 — assess current entity recognition status
4. Install Sections 5-9 — Wikidata first, then external reconciliation, then Wikipedia if notable, then Knowledge Panel claim
5. Validate — Section 11
6. Generate report — Section 14

1.4 Conflict Resolution Rules

1.5 Required Tools

• Wikidata — wikidata.org — primary platform for entity creation and management
• Wikipedia — wikipedia.org — for notable entities
• Google Search Console — to verify Knowledge Panel claim eligibility
• Google Knowledge Graph Search API — developers.google.com/knowledge-graph — to verify entity recognition
• OpenRefine — openrefine.org — for batch entity reconciliation
• Wikidata Query Service — query.wikidata.org — for testing Wikidata entries

2. Client Variables Intake

# ============================================
# KNOWLEDGE GRAPH FRAMEWORK CLIENT VARIABLES
# ============================================

# --- Business Entity (REQUIRED) ---
business_name: ""                    # Canonical name as entity
business_alternate_names: []         # All variations
business_legal_name: ""              # If different from canonical
business_type: ""                    # Schema.org type
business_founded_year: ""
business_founder_names: []
business_founder_qids: []            # Wikidata QIDs if exist
business_industry: ""
business_industry_qid: ""            # Wikidata industry classification
business_headquarters_city: ""
business_headquarters_country: ""
business_official_website: ""

# --- Existing Entity Recognition Status (REQUIRED) ---
business_in_knowledge_graph: false   # Use Knowledge Graph Search API to check
business_knowledge_panel_appears: false  # Search business name; does panel appear?
business_wikidata_qid: ""            # Existing Wikidata entry if any
business_wikipedia_article_exists: false
business_wikipedia_article_url: ""

# --- Founder Entity (REQUIRED) ---
founder_full_name: ""
founder_alternate_names: []
founder_birth_year: ""               # Optional but helps disambiguation
founder_credentials: []
founder_employer_qid: ""             # Wikidata QID for current/founded business
founder_in_knowledge_graph: false
founder_wikidata_qid: ""
founder_wikipedia_article_exists: false

# --- Notability Assessment (REQUIRED for Wikipedia) ---
business_independent_secondary_sources: []  # URLs of substantial coverage in independent publications
business_passes_wikipedia_notability_test: false
founder_independent_secondary_sources: []
founder_passes_wikipedia_notability_test: false

# --- External Profile Inventory (REQUIRED for sameAs reconciliation) ---
business_linkedin_url: ""
business_x_url: ""
business_facebook_url: ""
business_youtube_url: ""
business_github_org_url: ""
business_crunchbase_url: ""
business_bbb_url: ""
business_chamber_of_commerce_url: ""
business_industry_directory_urls: []

founder_linkedin_url: ""
founder_x_url: ""
founder_github_url: ""
founder_huggingface_url: ""
founder_orcid: ""
founder_personal_site_url: ""
founder_other_profile_urls: []

# --- Topical Entity Coverage (RECOMMENDED) ---
primary_topical_entities: []         # Topics covered with topical hub pages
topical_entity_qids: {}              # Existing Wikidata QIDs for major topics

# --- Knowledge Graph Strategy Status (REQUIRED) ---
has_strategy_for_kg_inclusion: false
plans_to_pursue_wikipedia_inclusion: ""  # "yes_now", "yes_when_notable", "no", "uncertain"
plans_to_create_wikidata_entries: false
has_kg_inclusion_timeline: false

# --- Entity Maintenance (REQUIRED ongoing) ---
wikidata_last_reviewed: ""
wikipedia_last_monitored: ""
knowledge_panel_last_audited: ""
external_profile_last_audited: ""

3. What the Knowledge Graph Is

Google’s Knowledge Graph is a database of entities and their relationships. Launched in 2012, it powers:

• Knowledge Panels in search results (the boxes on the right side showing entity information)
• Featured snippets and rich results for entity-related queries
• AI Overview source selection — AI Overviews preferentially cite Knowledge Graph entities
• Voice search and assistant responses (“Hey Google, who is…”)
• Entity-based ranking — pages associated with recognized entities benefit
• Disambiguation — when multiple entities share names, KG provides the disambiguation infrastructure

The Knowledge Graph contains hundreds of billions of facts about millions of entities. Most is automatically extracted from sources like Wikipedia, Wikidata, government databases, structured data on websites, and news mining. Some is manually curated.

Entity inclusion in the Knowledge Graph isn’t binary — it’s confidence-based. Google may have very high confidence in well-established entities (Apple Inc, Albert Einstein, Tokyo) and lower confidence in less-established entities. Confidence determines whether Knowledge Panels appear, how prominently the entity features in results, and how authoritatively the entity is treated in AI Overviews.

Entity confidence comes from:

1. Wikidata presence — Wikidata entries are direct input into Google’s Knowledge Graph. A complete, well-cited Wikidata entry is the strongest single signal for entity inclusion.

2. Wikipedia presence — Wikipedia articles flow into Wikidata and are direct sources for Knowledge Panels. Wikipedia coverage is a strong signal but has higher notability requirements than Wikidata.

3. Schema markup with sameAs — Schema on the entity’s official website that declares sameAs links to authoritative external profiles helps Google reconcile the entity.

4. Citation by other authoritative sources — When other recognized entities reference this entity, confidence increases.

5. Consistent factual data across sources — When the same facts appear across multiple authoritative sources, confidence increases.

6. Structured data accessibility — Sites that expose entity data via schema, API, or other structured formats are easier to ingest into KG.

The 2026 evolution of the Knowledge Graph is significant. AI engines (ChatGPT, Perplexity, Claude, Gemini) all rely on entity data overlapping with Google’s KG. Entities recognized in KG get cited more frequently across AI engines. The Knowledge Graph is no longer just for Google search — it’s foundational infrastructure for the entire AI search ecosystem.

For any business or individual seeking to be recognized as an authoritative entity in 2026, Knowledge Graph inclusion is foundational — not optional.

4. Current Entity Recognition Assessment

Before pursuing inclusion, understand current status.

4.1 Knowledge Graph Search API Check

Use Google’s Knowledge Graph Search API to check if entities are already recognized:

curl "https://kgsearch.googleapis.com/v1/entities:search?query={{ENTITY_NAME}}&key={{API_KEY}}&limit=10"

The response shows whether Google has the entity, its type, description, and confidence score. If the entity returns:

• Strong match (resultScore >100): Entity is well-recognized
• Weak match (resultScore <100): Some recognition but not strong
• No match: No KG presence

For this site’s primary entities (business, founder, key topics), document current status.

4.2 Knowledge Panel Search Test

In incognito mode, search for the entity name and document:

• Does a Knowledge Panel appear on the right side?
• What information is in the panel?
• Is the information accurate?
• Is the panel “claimed” (has owner verification)?
• What sources does the panel cite (Wikipedia, official website, etc.)?

Test variations:

• {{exact_business_name}}
• {{business_name}} {{location}}
• {{business_name}} {{founder_name}}
• {{founder_full_name}}
• who is {{founder_name}}

4.3 Wikidata Direct Search

Search Wikidata directly: wikidata.org/w/index.php?search={{ENTITY_NAME}}

Document:

• Existing entries that match
• Existing entries that conflict (other entities with same name)
• Whether existing entry is complete and accurate

4.4 Wikipedia Search

Search Wikipedia: en.wikipedia.org/w/index.php?search={{ENTITY_NAME}}

Document:

• Existing article if any
• Quality and completeness of article
• Whether the article links to the official website

4.5 External Profile Mapping

Document all existing external profiles for the entity. Each profile is a potential sameAs reconciliation point:

business_external_profiles:
  - platform: "LinkedIn"
    url: ""
    verified: false
    matches_official_data: true
  - platform: "X / Twitter"
    url: ""
    verified: false
    matches_official_data: true
  - platform: "Crunchbase"
    url: ""
    matches_official_data: true
  # ... etc

Identify any profiles with mismatched data (different addresses, different founding dates, etc.). These need correction before reconciliation, or they’ll undermine entity confidence.

4.6 Recognition Status Summary

After assessment, classify status:

• Established entity — Strong KG presence, accurate Knowledge Panel, complete Wikidata, possible Wikipedia. Focus on maintenance and refinement.
• Recognized but partial — Some KG presence, partial info, no Knowledge Panel or unclaimed panel. Focus on completion and claiming.
• Minimal recognition — Some external profiles but no KG presence. Focus on creating Wikidata entry and reconciliation.
• No recognition — No external profiles, no Wikidata, no KG. Foundation must be built from scratch.

The implementation path varies by status.

5. Wikidata Implementation (Foundation)

Wikidata is the primary path to Knowledge Graph inclusion. Wikidata has a lower notability bar than Wikipedia and is direct input to Google’s Knowledge Graph. Every entity that wants KG inclusion should have a Wikidata entry as foundation.

5.1 Wikidata Notability Requirements

To create a Wikidata entry, the entity must satisfy at least one notability criterion:

1. Has a Wikipedia article in any language (automatic notability)
2. Refers to an instance of a clearly identifiable conceptual or material entity (most businesses, people, places qualify)
3. Fulfills a structural need to make statements about other entities

For most businesses and individuals associated with businesses, criterion 2 applies. Notability bar is essentially: is this a real, identifiable entity that people might reasonably want to make statements about?

5.2 Wikidata Account Setup

Create a Wikidata account at wikidata.org. Use a real account with established edit history if possible — accounts with no history can have edits scrutinized more carefully.

Best practice: declare conflict of interest on user page if creating entry for own business or self.

5.3 Creating the Business Entity

Navigate to wikidata.org/wiki/Special:NewItem.

Required initial fields:

Label — {{business_name}} (canonical form, capitalized correctly)

Description — Concise (under 250 char), defining sentence. Examples:

• “American technology company headquartered in Cupertino, California” (Apple Inc.)
• “Service-Disabled Veteran-Owned web development and SEO firm based in Cassville, Missouri” (ThatDeveloperGuy)

Aliases — All alternate names. List every legitimate alternate spelling, abbreviation, DBA name.

After creating the basic entry, populate properties.

5.4 Required Wikidata Properties for Businesses

Add these properties (Wikidata uses property IDs like P31, P17 — find each on Wikidata’s property documentation):

Example of a populated business entry:

Item: Q138610626 (ThatDeveloperGuy)
Label (en): ThatDeveloperGuy
Description (en): Service-Disabled Veteran-Owned web development and SEO firm based in Cassville, Missouri

Statements:
- instance of (P31): business (Q4830453)
- country (P17): United States of America (Q30)
- headquarters location (P159): Cassville (Q...)
- founder (P112): Joseph Anady (Q... if created)
- inception (P571): 2020
- industry (P452): web development (Q386275)
- official website (P856): https://thatdeveloperguy.com
- coordinates (P625): 36.6770° N, 93.8730° W

External Identifiers:
- LinkedIn (P4264): {{linkedin_handle}}
- Crunchbase (P2087): {{crunchbase_id}}

5.5 Required References for Each Property

Every statement should be supported by a reference:

inception (P571): 2020
References:
- stated in: official website (P856) of subject
- reference URL: https://thatdeveloperguy.com/about/
- retrieved: 2026-04-29

Without references, statements can be challenged. With strong references, the entry is robust against editor revisions.

5.6 Creating the Founder Person Entity

Same process for founder. Required Person properties:

External Identifier properties for founder:

5.7 Topical Entity Wikidata Entries

For unique topical entities the site is the authority on (specific frameworks, methods, tools the site has created), create Wikidata entries. Most general topics already have entries.

For example, if the site has authored a specific framework called “SDVOSB Engine Optimization Methodology,” that could be a Wikidata entity:

Item: Q... (SDVOSB Engine Optimization Methodology)
Label (en): SDVOSB Engine Optimization Methodology
Description (en): A 14-tier framework for search engine and AI engine optimization developed by Joseph Anady at ThatDeveloperGuy

Statements:
- instance of (P31): methodology (Q1799072)
- developed by (P178): Joseph Anady (Q...)
- subclass of (P279): search engine optimization (Q180711)
- depicts (P180): 14-tier framework

5.8 Cross-Linking via External Identifiers

Wikidata’s external identifier properties allow direct linking to authoritative external databases. Add as many as apply:

For businesses:

• LinkedIn company ID (P4264)
• Crunchbase organization ID (P2087)
• BBB business profile (… if property exists)
• Industry-specific identifiers (BSI, NAICS code, etc.)

For people:

• LinkedIn personal ID (P6634)
• ORCID (P496)
• Google Scholar author ID (P1960)
• ResearchGate profile (P6178)
• GitHub username (P2037)

External identifiers strengthen entity reconciliation — they tell systems unambiguously that this Wikidata entity is the same entity as in those external sources.

5.9 Wikimedia Commons Logo Upload

Upload the business logo to Wikimedia Commons:

1. Visit commons.wikimedia.org/wiki/Special:UploadWizard
2. Confirm copyright (logo must be licensed permissively or be your own work you license)
3. Upload with descriptive filename: ThatDeveloperGuy-logo.svg
4. Add to Wikidata entry as logo image (P154)

The logo is then available for use in Knowledge Panels and other systems.

5.10 Patience for Wikidata Propagation

After creating Wikidata entries, allow time for propagation:

• 24-72 hours for community visibility
• 1-4 weeks for Google’s Knowledge Graph ingestion
• 1-3 months for stable Knowledge Panel appearance (typically requires multiple signals beyond Wikidata)

Don’t expect immediate Knowledge Panel from Wikidata alone. Wikidata is foundational; other signals build on it.

6. External Reconciliation Strategy

Beyond Wikidata, build the network of references that reinforce entity recognition.

6.1 Schema sameAs on Official Website

The official website’s Organization and Person schema must include sameAs links to all authoritative external profiles AND to the Wikidata entry:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://{{domain}}/#organization",
  "name": "{{business_name}}",
  "sameAs": [
    "https://www.wikidata.org/wiki/{{business_qid}}",
    "https://en.wikipedia.org/wiki/{{business_wiki_slug}}",
    "{{linkedin_company_url}}",
    "{{x_company_url}}",
    "{{facebook_url}}",
    "{{crunchbase_url}}",
    "{{bbb_url}}",
    "{{youtube_channel_url}}",
    "{{github_org_url}}",
    "{{industry_directory_urls}}"
  ]
}
</script>

This declares: “All these URLs refer to the same entity.” Google uses this for entity reconciliation.

6.2 Reciprocal sameAs from External Profiles

Where possible, add the website URL to external profiles so reconciliation is bidirectional:

• LinkedIn company page: lists official website
• X bio: includes website URL
• Crunchbase profile: official website field
• Personal LinkedIn: lists company and website
• GitHub org/user: website field

Some platforms allow rel="me" markup for verified mutual claiming. Where supported (Mastodon, personal sites), use rel="me" to formally declare the relationship.

6.3 Authority-Building Profile Coverage

Build presence on platforms that contribute to entity authority:

For businesses:

• LinkedIn Company Page
• Google Business Profile
• Crunchbase
• BBB (where applicable)
• Trustpilot
• Industry-specific directories (Clutch for B2B services, etc.)
• Local Chamber of Commerce
• State business registry (already exists if formally registered)

For founders:

• LinkedIn personal profile
• GitHub (for developers)
• Hugging Face (for AI work)
• ResearchGate or ORCID (for academics)
• Industry-specific profiles
• Personal domain with comprehensive bio

6.4 Industry-Specific Authoritative Listings

Each industry has authoritative directories Google trusts:

• Medical: NPI registry, state medical board, hospital staff directory
• Legal: Bar association directory, Avvo, Martindale-Hubbell
• Financial: BrokerCheck, SEC IAPD, Form ADV
• Real estate: NAR, state real estate licensing
• Construction: state contractor licensing, BBB

Listing on these sources contributes to entity authority and provides additional sameAs targets.

6.5 Earned Media Coverage

When the entity is featured in articles, news, or industry publications, ensure:

• The publication’s article links to the official website
• The article uses the canonical entity name
• The article references factual data consistent with Wikidata/official sources

Inconsistencies across earned media weaken entity confidence. Reach out to publications to correct factual errors when they appear.

6.6 Press Kit With Canonical Entity Data

Maintain a press kit at /press/ with canonical entity facts:

• Official entity name and acceptable abbreviations
• Founding year
• Founder names with correct spellings
• Headquarters location
• Industry classification
• Brief description (matching Wikidata description)
• High-resolution logos
• Founder photos
• Recent press releases

Make it easy for journalists to use correct facts. Inconsistent facts in earned media create entity confusion that takes time to resolve.

7. Wikipedia Strategy

Wikipedia has a higher notability bar than Wikidata. Don’t pursue Wikipedia until notability is genuinely demonstrable.

7.1 Wikipedia Notability Test

Wikipedia’s notability requirement: “significant coverage in independent reliable secondary sources.”

Tests:

• Significant coverage — multiple paragraphs about the entity, not just passing mention
• Independent — not the entity’s own marketing, press releases, or affiliated sources
• Reliable — established publications with editorial standards (newspapers, trade publications, academic journals, books)
• Secondary sources — not primary sources like the entity’s own website or interviews

For most businesses, Wikipedia notability requires:

• Coverage in 3+ independent reliable sources
• Coverage that’s substantive (not just listings or brief mentions)
• Coverage spanning more than a single time period

For most individuals, similar tests but framed around the person’s accomplishments, work, recognition.

If notability is genuinely there, Wikipedia inclusion follows. If it’s not, attempting to create a Wikipedia article will result in deletion, often with administrative rebuke that makes future attempts harder.

7.2 Don’t Create Your Own Wikipedia Article

Wikipedia has strong policies against creating articles about yourself or your business (conflict of interest). Articles created by COI editors are flagged, scrutinized, often deleted.

Better path:

1. Build genuine notability over time
2. Wait for organic article creation by an independent editor
3. If asked, provide factual support to editors but don’t draft the article

7.3 If You Must Create a Wikipedia Article

If notability is genuinely strong and no organic editor is creating an article, the legitimate path:

1. Disclose conflict of interest on user page
2. Use Articles for Creation process (en.wikipedia.org/wiki/Wikipedia:Articles_for_creation) rather than direct creation
3. Submit through draft review by uninvolved editors
4. Accept their feedback and revisions

The article must:

• Be written in encyclopedic tone, not promotional
• Cite multiple independent reliable sources
• Cover both achievements and any controversies fairly
• Avoid superlatives, marketing language, original research
• Use neutral point of view

7.4 Maintaining the Wikipedia Article

Once created, monitor the article but don’t edit it directly:

• Watch for changes via Wikipedia’s watchlist feature
• Use Talk page to suggest corrections with citations
• Engage with editors who request information
• Provide source materials when requested
• Accept that the article belongs to Wikipedia community, not the subject

Inappropriate editing of own Wikipedia article causes:

• Edit reverts
• Articles flagged for COI review
• Sometimes article deletion
• Editor account sanctions

7.5 What Wikipedia Inclusion Adds

When/if Wikipedia article exists:

• Knowledge Graph confidence increases dramatically
• Knowledge Panel typically appears in search results
• AI engines cite the entity more confidently
• The Wikipedia article becomes input into many derivative systems (LLM training data, AI knowledge bases, etc.)

Wikipedia is force-multiplying for entity authority. But it must be earned, not engineered.

8. Knowledge Panel Claiming

Once an entity has Knowledge Graph recognition, claim the Knowledge Panel for control.

8.1 Verifying Eligibility

Knowledge Panels can be claimed when:

• The entity is recognized in Google’s Knowledge Graph (Knowledge Panel appears)
• You can demonstrate official representation (own the website, are the entity, or are authorized representative)

To check if a Knowledge Panel exists for your entity, search the entity name in Google. The panel appears on the right side (desktop) or below results (mobile).

8.2 Claiming Process

If a Knowledge Panel exists:

1. Click “Claim this knowledge panel” link in the panel (typically at bottom)
2. Sign in with Google account
3. Verify ownership through one of:
   • Authorized social profile (verified Twitter/X, official LinkedIn, etc.)
   • YouTube channel
   • Official Twitter/X account
   • Other verified Google service
4. Wait for Google review (typically days to weeks)

Once claimed, you can:

• Suggest edits to information in the panel
• Add or update images
• Request corrections to factual errors
• Update social profile links

8.3 Maintaining the Knowledge Panel

After claiming:

• Monthly: review panel for accuracy
• After business changes (address, hours, name): suggest update
• After credentials/awards: suggest addition
• Quarterly: verify all linked profiles still active

8.4 What If No Knowledge Panel Exists

If no Knowledge Panel exists despite Wikidata presence and external profile coverage, possible reasons:

• Recognition exists but below threshold for panel display
• Entity is too new (give it 3-6 months after building foundation)
• Entity confusion (Google can’t disambiguate from other entities with same name)
• Insufficient cross-source consistency

Continue building entity signals: more authoritative external profiles, more earned media, more consistent factual data across sources, possibly Wikipedia inclusion if notability allows. Knowledge Panel typically follows when entity confidence reaches threshold.

9. Topical Entity Strategy

Beyond business and founder entities, topical entities matter.

9.1 Major Topic Wikidata Entries

Most major topics (web development, SEO, AI, etc.) already have Wikidata entries. Reference them in your content schema:

<script type="application/ld+json">
{
  "@type": "Article",
  "about": [
    {
      "@type": "Thing",
      "name": "Search engine optimization",
      "sameAs": "https://www.wikidata.org/wiki/Q180711"
    }
  ]
}
</script>

Topical hub pages similarly use the Wikidata QID for their primary topic.

9.2 Custom Methodology Entities

If the site has authored unique methodologies, frameworks, or tools, create Wikidata entries for them. See Section 5.7.

9.3 Person-Topic Affinity

Connect people entities to topical entities via Wikidata:

For founder entry, add:

• field of work (P101): SEO QID
• field of work (P101): Web development QID
• field of work (P101): AI optimization QID

This declares topical authority in Wikidata, which compounds with on-site knowsAbout schema.

10. Common Mistakes & Anti-Patterns

10.1 Self-Created Wikipedia Article

Anti-pattern: Creating own Wikipedia article without notability.

Why it fails: Almost certainly deleted. Editor account sanctioned. Future legitimate attempts harder.

Fix: Build notability first. Use Wikidata in the meantime. Wait for organic Wikipedia creation.

10.2 Inconsistent Entity Names Across Sources

Anti-pattern: “ThatDeveloperGuy” on website, “That Developer Guy LLC” on LinkedIn, “TDG Inc” on Crunchbase.

Why it fails: Google can’t reconcile these as the same entity. Entity confidence stays low.

Fix: Pick canonical name. Use consistently everywhere. Document acceptable variations as alternateName only.

10.3 Wikidata Without References

Anti-pattern: Wikidata entry created with statements but no supporting references.

Why it fails: Entry is fragile; community editors may revise or remove unsupported statements.

Fix: Cite sources for every statement.

10.4 No Schema sameAs

Anti-pattern: Site has Wikidata entry, but Organization schema doesn’t include sameAs link to Wikidata.

Why it fails: Google has to reconcile via other means; loses easy direct signal.

Fix: sameAs link to Wikidata in all relevant schema.

10.5 Sparse External Profile Coverage

Anti-pattern: Only website and one social profile. Nothing else.

Why it fails: Entity reconciliation needs multiple signals. Sparse coverage means low confidence.

Fix: Build coverage on 8-15 authoritative platforms.

10.6 Outdated Wikidata Information

Anti-pattern: Wikidata entry created years ago, never updated. Address has changed, founder roles changed, founding date inaccurate.

Why it fails: Inconsistent data across sources weakens entity confidence.

Fix: Quarterly Wikidata review; keep current.

10.7 Edit Warring on Wikipedia

Anti-pattern: Repeatedly editing your own Wikipedia article to add favorable content.

Why it fails: Article flagged for COI review. Editor account sanctioned. Trust damaged.

Fix: Use Talk page to suggest changes. Provide sources. Let community editors decide.

10.8 Knowledge Panel Errors Ignored

Anti-pattern: Knowledge Panel showing wrong information, no action taken.

Why it fails: Wrong information at the most prominent position in search results. Long-term reputation damage.

Fix: Claim panel; suggest corrections; provide source documentation for corrections.

10.9 Multiple Wikidata Entries for Same Entity

Anti-pattern: Creating new Wikidata entry without checking if one already exists, resulting in duplicates.

Why it fails: Confusion. Statements split across entries. Reconciliation issues.

Fix: Search before creating. If duplicates exist, use Wikidata’s merge process.

10.10 Trying to Game Knowledge Graph

Anti-pattern: Creating fake Wikipedia citations, manipulating Wikidata, fabricating earned media to inflate entity authority.

Why it fails: Detection by Wikipedia community is high. Wikidata has data quality processes. Fabricated earned media is detectable. Caught manipulation = catastrophic reputation damage.

Fix: Build genuine entity authority through real work, real notability, real recognition.

11. Audit Mode

11.1 Knowledge Graph Status Audit

Score: 15. World-class KG status: 13+/15.

11.2 Entity Authority Strength Score

For each primary entity (business, founder, key topics), score:

Per entity: 21 max. Strong entity: 18+/21.

12. Maintenance Schedule

12.1 Monthly

• Verify Wikidata entries still accurate; correct if facts changed
• Monitor Wikipedia article for changes (if exists)
• Check Knowledge Panel for accuracy
• Review external profiles for consistency

12.2 Quarterly

• Comprehensive entity authority audit
• Update press kit with new earned media, achievements
• Refresh photos and logos if updated
• Cross-check NAP across all profiles

12.3 Annually

• Strategic entity review
• Pursue new Wikipedia inclusion if notability has grown
• Add new topical entities as the site’s authority expands
• Update Wikidata with significant year’s developments

12.4 Event-Driven

• Address change → update everywhere within 7 days
• Founder change → update Wikidata, Knowledge Panel, schema
• New significant earned media → add to press kit, update Wikidata reference
• New award/certification → update credentials in Wikidata, schema, About page

13. Cross-Reference to the 14-Tier Framework

Knowledge Graph implementation touches:

• Tier 3 KGO — Knowledge Graph Optimization is named for this exact work
• Tier 3 WIK — Wikipedia & Wikidata Optimization is the foundational work this framework specifies
• Tier 1 SDO — Structured Data Optimization implements schema sameAs for KG reconciliation
• Tier 1 EEA — E-E-A-T Entity Optimization with Person/Organization schema
• Tier 4 PBO — Personal Brand Optimization extends founder entity work
• Tier 4 CHO — Citation/Honors Optimization documents the awards and recognitions that build entity authority

14. Implementation/Audit Report Templates

14.1 Implementation Report Template

# Knowledge Graph Implementation Report

**Site**: {{BUSINESS_NAME}}
**Implementation Date**: {{TODAY}}

## Wikidata Entries Created
- Business: {{QID}} — {{COMPLETENESS_PERCENTAGE}}% properties populated
- Founder: {{QID}} — {{COMPLETENESS_PERCENTAGE}}% properties populated
- Custom methodologies: {{LIST_OF_QIDS}}

## External Reconciliation Status
- Schema sameAs links: {{COUNT}}
- External profiles claimed: {{COUNT}}
- NAP consistency: {{PERCENTAGE}}% across all profiles

## Knowledge Panel Status
- Business: {{APPEARS/DOES_NOT_APPEAR}}, {{CLAIMED/UNCLAIMED}}
- Founder: {{APPEARS/DOES_NOT_APPEAR}}, {{CLAIMED/UNCLAIMED}}

## Wikipedia Status
- Notability assessment: {{ASSESSMENT}}
- Action: {{NONE/ARTICLE_CREATED/ARTICLE_AWAITED}}

## Topical Entity Coverage
{{LIST_OF_TOPICS_AND_QIDS}}

## Press Kit Established
{{STATUS}}

## Sign-Off

14.2 Audit Report Template

# Knowledge Graph Audit Report

**Site**: {{BUSINESS_NAME}}
**Audit Date**: {{TODAY}}

## Overall KG Status
{{ESTABLISHED / RECOGNIZED_PARTIAL / MINIMAL / NONE}}

## KG Status Score
{{X}}/15

## Entity Authority Strength
- Business: {{X}}/21
- Founder: {{X}}/21
- Primary topics: {{ASSESSMENT}}

## Wikidata Findings
{{DETAILED_FINDINGS}}

## Wikipedia Findings
{{DETAILED_FINDINGS}}

## External Reconciliation Findings
{{DETAILED_FINDINGS}}

## Knowledge Panel Findings
{{DETAILED_FINDINGS}}

## Critical Failures
{{LIST}}

## Recommended Implementation Order
{{PRIORITIZED_LIST}}

## Sign-Off

End of Framework Document

Document version: 1.0
Last updated: 2026-04-29
Maintained by: ThatDeveloperGuy

Knowledge Graph inclusion is foundational entity authority infrastructure for 2026. Without it, entities operate at a permanent confidence disadvantage in search rankings, AI citations, and brand recognition. With it, every other quality signal compounds — E-E-A-T is stronger when the entity is recognized, content ranks better when its primary entity is authoritative, AI engines cite the entity preferentially.

The work is methodical. Wikidata first. External reconciliation. Wikipedia when notable. Knowledge Panel claim. Then maintain. The compound returns over time are substantial.

Companion documents:

• framework-eeat.md
• framework-ymyl.md
• framework-hcs.md
• framework-sqrg.md
• framework-coreupdates.md
• framework-infogain.md
• framework-entitysalience.md
• framework-aicitations.md

About this framework library

This article is the Dev.to republish of a framework reference document from ThatDevPro’s SEO + AI engineering library. Canonical source: https://www.thatdevpro.com/insights/framework-knowledgegraph/

ThatDevPro is an SDVOSB-certified veteran-owned web + AI engineering studio operating from Cassville, Missouri. The studio runs the full 14-tier Engine Optimization stack and ships open-source tooling for AI citation engineering.

Companion 14-tier Engine Optimization stack (each tier is its own article):

1. Tier 1 — Foundation
2. Tier 2 — Search Visibility
3. Tier 3 — AI Domination
4. Tier 4 — Entity and Authority
5. Tier 5 — Local Domination
6. Tier 6 — Content and Multimedia
7. Tier 7 — Social and Community
8. Tier 8 — Data, Analytics, Conversion
9. Tier 9 — Monitoring and Intelligence
10. Tier 10 — Workflow and Operations
11. Tier 11 — Marketplace and Retail
12. Tier 12 — International
13. Tier 14 — Advanced and Immersive

Need this framework implemented on your site? See the Engine Optimization service or hire through ThatDevPro contact.

AI has become a normal part of how we write software. It reads code, suggests fixes, and explains things faster than most Stack Overflow answers. But there’s something it still can’t do on its own: look at your actual data.

That turns out to be a bigger problem than it sounds.

The bug assistant that can actually investigate

You get a Sentry alert. You paste the stack trace into Claude. The error, the params, the line numbers. It reads everything and takes a guess at what went wrong.

The problem is it’s just that. A guess. It doesn’t know what the user record looked like. It doesn’t know what state the associated objects were in. It doesn’t know if this is a one-off or whether a whole segment of users ends up here consistently.

So you become its hands. Run the queries, paste the results back, run a few more. It’s not the worst workflow, but the AI is doing half the job it could be doing.

With an MCP server wired into your Rails app, it can investigate on its own. It describes your models, pulls the relevant records, and comes back with something like: “Users hitting this error all have onboarding_completed_at null but subscription_active true. Looks like they’re skipping a step in the flow.” No back and forth. No copy-pasting query results.

Your AI-powered junior analyst

Same problem, different context: you shipped a feature three months ago and someone from product wants to know if it’s actually being used.

Normally that means writing a query, building a small report, or filing a ticket with whoever owns analytics. None of that is hard, but there’s enough friction that the question quietly dies more often than it gets answered.

With your data accessible via MCP, you just ask. “How many users have used the new export feature in the last 30 days? Break it down by plan.” It calls the right tools, counts, groups, and answers in seconds. No SQL, no dashboard, no waiting.

It’s the difference between an AI that knows your codebase and one that actually understands what’s running in production.

Why not just hand it the database URL?

Fair question. The short answer is that raw database access means raw SQL, and raw SQL means anything goes. Joins across tables you didn’t intend to expose, queries hitting your primary instead of your replica, no record of what was accessed.

activerecord-mcp gives the AI access through your application layer instead. Queries go through ActiveRecord with hash conditions validated against actual column names. Sensitive columns like password_digest, tokens, and secrets are blocked by regex deny lists before anything hits the database, and stripped from output after just in case. Everything runs against a read-only role by default. OAuth 2.1 tokens scope access so MCP credentials can’t bleed into anything else in your stack.

It’s the same access control you’d apply to any internal API, applied to your AI tooling.

Getting started

# Gemfile
gem "activerecord-mcp"
gem "doorkeeper"

bundle install
bin/rails generate doorkeeper:install
bin/rails generate doorkeeper:migration
bin/rails db:migrate
bin/rails generate rails_mcp:install

Restrict it to the models you want to expose, mount it, and connect:

claude mcp add --transport http my-app https://your-app.com/mcp 
  --header "Authorization: Bearer $MY_APP_TOKEN"

Full setup at github.com/pauloancheta/activerecord-mcp.