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.

I tried to build a SaaS. I’m shipping tiny libraries instead.

For 7 days I poured energy into ChatProof — a testing framework for AI chat UIs. The problem was real: every team building Claude/GPT wrappers hits the same streaming-render bugs, and existing e2e tools weren’t built for non-deterministic LLM output. I had a competitive analysis. I had a PRD. I even had a name.

Then I admitted something to myself: product/market work just isn’t my strength.

I’m a builder. I love writing TypeScript. I love designing APIs. I love npm test going green. I do not love writing cold DMs. I do not love figuring out which subreddit my ICPs hang out in. I do not love crafting positioning documents.

Once I named it, the pivot was obvious.

The pivot

Instead of one ambitious SaaS, I’d ship tiny zero-deps libraries that solve specific Anthropic SDK pain points I personally hit. Each one:

• < 500 lines of TypeScript
• Zero runtime dependencies
• MIT licensed
• Published to npm
• 1–2 weeks of work max

The goal isn’t to build a unicorn. It’s to leave a GitHub trail that demonstrates I can ship real code, get organic distribution through npm + search, and let the work compound over months.

The 5 days

Day 1 — claude-stream-collector

Consume Anthropic Messages streaming events into a typed CollectedResult. Handles tool_use input JSON delta accumulation (the SDK leaves this to you) and merges cache token usage across message_start + message_delta (the SDK overwrites). ~120 lines, 6 tests.

Day 3 — claude-retry

Smart retry for Anthropic API calls. Respects retry-after headers (which the SDK’s built-in retry doesn’t always honor), exponential backoff with jitter, custom retry predicates, AbortSignal support. ~180 lines, 25 tests.

Day 5 — claude-pricing

Calculate Claude API cost from token usage. Bundled pricing table with smart model-alias resolution (strips date suffixes), batch API discount, session CostTracker with budget alerts. ~180 lines, 19 tests.

Three packages, ~480 lines of code, 50 unit tests. All public. All on npm.

What I’m learning

1. Match the work to who you are, not who you think you should be.

Indie Hackers and Twitter are full of advice assuming you’re a generalist who loves every part of building a company. Many great engineers aren’t, and that’s fine. Tiny libraries are a perfectly valid path if you optimize for shipping over selling.

2. Zero-deps is a feature, not a constraint.

Every dependency is a future maintenance burden, a potential security issue, and a reason for someone to skip your package. For 100–500 line utilities, you almost never need anything but Node’s standard lib.

3. Series narratives compound.

Each package on its own is a small thing. But three packages with shared types (TokenUsage flows from claude-stream-collector → claude-pricing cleanly) form a tiny ecosystem. Each new package strengthens the others.

4. Build in public ≠ build for engagement.

I posted about each release on X and 即刻. Engagement so far: zero likes, zero replies. Downloads on the first package: 129 in 7 days. People install packages they discover via search and never engage with the announcement. That’s fine — the artifacts persist longer than any tweet.

5. Pivoting hurts less when you preserve learning.

ChatProof isn’t dead. The painpoint research, competitive analysis, and architecture thinking from those 7 days informed every package since. Especially: I knew the streaming pain because I’d done the homework.

What’s next

More small packages: claude-cache-helper, claude-tools-typed, maybe claude-prompt-toolkit. Same shape — small, focused, zero-deps. I’ll keep posting about them but won’t measure success in likes.

If you’re stuck on an indie project trying to be a “real founder,” maybe try shipping a single utility you’d actually use. You might find you ship four more before you’d have written a single landing page.

Three packages:

• claude-stream-collector — typed stream events
• claude-retry — smart retry + backoff
• claude-pricing — cost calc + tracker

Building in public: ship-log-2026

Introduction

ai-engineering-from-scratch is a hardcore and comprehensive curriculum for AI engineering. Instead of just teaching you how to call the OpenAI API, it takes you through the underlying mathematical principles, step-by-step, building Tokenizers, Backpropagation, Attention mechanisms, all the way to autonomous agent swarms.

The entire curriculum consists of 20 phases and 435 lessons, requiring approximately 320 hours of study. What makes it unique is that every lesson ships a reusable artifact: a prompt, a skill, an agent, or an MCP server that you can immediately plug into your daily workflow.

Core Features

• Build from Scratch Philosophy: Follows the principle that the best way to understand something is to build it by hand. You implement algorithms with raw math/Python before moving on to frameworks like PyTorch.
• Full Spectrum Coverage:
  • Math Foundations: Linear algebra to neural network first principles.
  • ML & DL Core: From classical ML to the evolution of Transformers.
  • Generative AI: Principles of image, video, and audio generation.
  • LLM Engineering: Training, fine-tuning, quantization, and production deployment.
  • Agent Engineering: ReAct loops, memory, multi-agent coordination, and autonomous systems.

• Output-Oriented: At the end of each lesson, you don’t just “learn” something; you gain a transferable tool (e.g., a .md skill file for Claude/Cursor).

• Multi-language Support: Primarily Python, but includes TypeScript, Rust, and Julia implementations.

How to Get Started

There are three ways to dive into the curriculum:

1. Online Reading: Browse all docs at aiengineeringfromscratch.com.

2. Clone & Run:

   git clone https://github.com/rohitg00/ai-engineering-from-scratch.git
   cd ai-engineering-from-scratch
   python phases/01-math-foundations/01-linear-algebra-intuition/code/vectors.py
   

3. Agent-Driven (Recommended): If you use Claude, Cursor, or any agent with the curriculum skills installed, run /find-your-level. A 10-question quiz will map your knowledge to a personalized starting phase.

Conclusion

If you’re tired of “one-minute prompt hacks” and want to truly master the underlying logic of AI while building your own arsenal of engineering tools, ai-engineering-from-scratch is the most thorough and high-quality resource available today.

Project URL: rohitg00/ai-engineering-from-scratch

Welcome to my homepage to find more useful knowledge and interesting products.

In fintech, notifications are not a “nice-to-have” feature.

They’re part of the product’s trust layer.

If a user transfers money and doesn’t get a confirmation, they panic.
If an OTP arrives 3 minutes late, login fails.
If price alerts come twice, users lose confidence fast.

At small scale, sending notifications feels simple:

Application → Twilio/SendGrid → Done

But once you’re dealing with millions of users, multiple channels, retries, provider outages, and traffic spikes… notification systems become distributed systems problems.

And distributed systems are mostly about handling failure gracefully.

Imagine a fintech platform sending:

• transaction alerts
• OTPs
• portfolio updates
• price alerts
• security notifications

…to over 1 million users across:

• Push notifications
• SMS
• Email

The challenge isn’t just “sending messages.”

The real challenge is making sure the system:

• doesn’t send duplicates
• doesn’t silently lose messages
• survives provider outages
• scales during spikes
• remains observable when things go wrong

Here’s the architecture I’d use.

High-Level Architecture

[App Service]
      │
      ▼
[Notification Queue (Redis Streams / SQS / Kafka)]
      │
      ▼
[Worker Pool]
      │
      ▼
[Provider Router]
      │
 ┌────┼───────────────────────────────┐
 ▼    ▼                               ▼
SMS  Email                           Push
 │      │                              │
 ▼      ▼                              ▼
Twilio SendGrid                      FCM/APNs
 │
 ▼
Fallback Providers
(Termii / Mailgun / Direct APNs)
      │
      ▼
[Delivery Log + Idempotency Store]
(PostgreSQL + Redis)

1. Queue-Based Architecture

One of the biggest mistakes teams make early on is sending notifications directly from the API request cycle.

That works… until traffic spikes.

Imagine Black Friday, a crypto market crash, or salary payment day.
Suddenly, millions of notifications need to go out almost at once.

If your application waits for Twilio or SendGrid to respond before returning a response to the user, your entire app becomes hostage to external providers.

That’s dangerous.

Instead, the API should do one thing:

Accept the request quickly and push a notification event into a queue.

From there, worker processes handle delivery asynchronously.

This changes the system completely.

Queues give you:

• horizontal scalability
• retry capability
• backpressure handling
• failure isolation

If providers slow down, the queue absorbs the spike instead of crashing your application.

At this scale, queues stop being optional infrastructure.
They become the safety buffer protecting the rest of your system.

Recommended technologies:

• Redis Streams
• AWS SQS
• Kafka (especially for very high throughput systems)

2. Reliability & Idempotency

The hardest problem in notification systems usually isn’t failed sends.

It’s duplicate sends.

Users are surprisingly tolerant of delayed notifications.
They are not tolerant of receiving the same debit alert three times.

Retries are where duplicates usually happen.

Example:

1. Worker sends SMS
2. Provider actually succeeds
3. Network timeout occurs before acknowledgment returns
4. Worker assumes failure
5. Worker retries
6. User receives duplicate SMS

To prevent this, every notification should carry an idempotency_key.

Before sending, workers check:

“Have we already processed this exact notification?”

Example constraint:

UNIQUE(user_id, notification_type, idempotency_key)

This is one of those small architectural decisions that saves massive operational pain later.

Even if retries happen multiple times, the database becomes the final protection layer against duplicates.

Every delivery attempt should also be logged.

Not just successes — everything.

notification_attempts

Including:

• provider used
• response status
• retry count
• timestamps
• provider error payloads

Because when something goes wrong in production, you want evidence, not guesses.

3. Provider Routing & Fallbacks

A reality every senior engineer eventually learns:

Third-party providers fail more often than you expect.

Twilio can degrade.
SendGrid can throttle requests.
FCM can delay pushes.

The mistake is designing systems that assume providers are always available.

Reliable systems assume failure is normal.

So instead of hardcoding a single provider, introduce a provider routing layer.

Example Routing Strategy

The worker flow becomes:

1. Attempt primary provider
2. Detect timeout or failure
3. Retry intelligently
4. Automatically fail over if necessary

Users shouldn’t notice your provider had a bad day.

That’s the goal.

4. Retry Strategy

Retries sound simple until they start causing damage.

Bad retry systems can:

• spam users
• overload providers
• amplify outages
• generate huge costs

A common mistake is retrying too aggressively.

If Twilio is already struggling, hammering it with thousands of immediate retries only makes things worse.

Instead, use exponential backoff.

Example:

Retry #1 → 30 seconds
Retry #2 → 2 minutes
Retry #3 → 10 minutes

This gives providers time to recover while keeping pressure manageable.

And after maximum retries?

Move the message into a Dead Letter Queue (DLQ).

That queue is basically your “something unusual happened here” bucket.

At that point, engineers should be alerted.

5. Reconciliation Jobs

One subtle issue in distributed systems:

Sometimes providers say “accepted” even though delivery eventually fails.

That creates dangerous blind spots.

A notification may look successful internally while the user never actually receives it.

This is why reconciliation jobs matter.

Every few minutes, background jobs should scan for suspicious states:

Notifications stuck in "pending" for too long

Then:

→ Re-query provider APIs
→ Update delivery status
→ Retry if needed

These jobs quietly save systems from edge cases caused by:

• webhook failures
• transient outages
• network interruptions
• delayed provider processing

A lot of reliability engineering is really just building systems that continuously self-correct.

6. User Preferences & Rate Limiting

Good notification systems are not just reliable.

They’re respectful.

Users should control how they’re contacted.

Examples:

• disable marketing SMS
• mute non-critical notifications after 10PM
• push-only preferences
• email digests instead of instant alerts

Simple table:

user_notification_settings

…can dramatically improve user experience.

Rate limiting matters too.

Without it, bugs or loops can become expensive very quickly.

Imagine accidentally sending OTPs in a retry loop to thousands of users.

Redis-based limits help protect against this.

Example:

Max 3 SMS/hour/user

That protects:

• users from spam
• providers from overload
• the business from runaway costs

7. Monitoring & Observability

At scale, invisible systems are dangerous systems.

You need to know:

• Are queues growing?
• Are workers failing?
• Which provider is slowing down?
• Which region is affected?

The most important metrics are usually boring operational ones.

Golden Signals

• queue latency
• queue depth
• worker error rate
• provider response times

Then business-level metrics:

• delivery success rate
• percentage delivered within 30 seconds
• provider costs
• user opt-out rates

And finally: alerts.

Example:

Alert if SMS failure rate exceeds 5% for 2 minutes

The earlier you detect degradation, the smaller the incident becomes.

8. Testing Failure Scenarios

The biggest difference between systems that look reliable and systems that are reliable is failure testing.

Because everything works in happy-path demos.

The real question is:

What happens when dependencies misbehave?

One useful strategy is shadow testing.

Route a tiny percentage of production traffic through a new provider and compare results safely.

Example:

• compare latency
• compare delivery rates
• validate formatting consistency

Chaos testing is also incredibly valuable.

Example:

Intentionally fail 10% of Twilio requests in staging

That sounds scary initially.

But it validates whether:

• retries actually work
• failovers trigger correctly
• reconciliation jobs recover messages

Reliable systems are engineered through controlled failure exposure.

Why This Architecture Works

What makes this architecture resilient is that it assumes bad things will happen.

Because eventually:

• providers fail
• queues spike
• retries happen
• networks become unreliable

The system survives because reliability is built into the architecture itself.

By combining:

• queues
• idempotency
• retries
• fallback providers
• reconciliation jobs
• observability

…the platform continues operating even during partial outages and heavy traffic spikes.

And in fintech, reliability isn’t just infrastructure quality.

It directly affects user trust.

Tech Stack Example

Final Thoughts

Most notification systems work during normal traffic.

That’s not the hard part.

The hard part is surviving:

• provider outages
• duplicate retry scenarios
• partial failures
• sudden spikes in traffic

That’s where architecture starts to matter.

Because users rarely remember the notifications that worked.

They remember the moments when communication failed during something important.