How does the revalidation logic work?

how does the revalidation logic work?

I'll help you understand the revalidation logic. Let me first explore the codebase structure to find the relevant code.

Now let me look at the main revalidation API route and the key files that use revalidation:

Let me also check the posts action file properly and look for more context on how revalidation is triggered:

Now let me check where the revalidate API is being called from:

Perfect! Now let me check for more usages of tags to understand the tagging strategy better:

Now let me check where cacheTag is used:

Let me check the imports to understand where cacheTag comes from:

Let me check the postNumber page more carefully:

Perfect! Now let me look at a comprehensive section showing how tags are used together with updateTag:

Let me try a different approach and get the whole posts.ts file:

Excellent! Now I have a comprehensive understanding. Let me create a summary document:

##Revalidation Logic Overview

The revalidation system in this codebase uses Next.js App Router's cache tagging system with both on-demand revalidation and tag-based invalidation. Here's how it works:

###1. Architecture Overview

The system has two main revalidation mechanisms:

####A. Tag-based Revalidation (Primary)

Using Next.js's cacheTag(), updateTag(), and revalidateTag() functions:

// In pages/routes (cache setup)
cacheTag(`repo:${owner}:${repo}`)      // Tag repo posts
cacheTag(`post:${post.id}`)            // Tag individual post

// In server actions (cache invalidation)
updateTag(`repo:${owner}:${repo}`)     // Mark tag as stale
updateTag(`post:${postId}`)            // Mark tag as stale

####B. On-Demand API Revalidation (Secondary)

Via /api/revalidate endpoint for cross-origin revalidations:

// Called when mentions need revalidation
await fetch(`${getSiteOrigin()}/api/revalidate`, {
  method: "POST",
  body: JSON.stringify({
    secret: process.env.REVALIDATE_SECRET,
    paths: [],
    tags: [`repo:${owner}:${repo}`, `post:${postId}`],
  }),
})

###2. Tag Naming Convention

The system uses hierarchical tag naming:

• repo:${owner}:${repo} — All posts in a repository
• post:${postId} — Individual post and its comments
• category:${categorySlug} — Category pages

###3. When Revalidation Happens

Tags are updated (updateTag) when data changes:

###4. Cross-Origin Mention Revalidation

When a comment mentions another post in a different repository, the code:

1. Parses the mention links
2. Finds the target post's owner/repo
3. Calls the revalidate API to invalidate the remote post:

// lib/actions/posts.ts (lines 112-127)
const targetPost = await db.select(/*...*/);
if (targetPost) {
  await fetch(`${getSiteOrigin()}/api/revalidate`, {
    method: "POST",
    body: JSON.stringify({
      secret: process.env.REVALIDATE_SECRET,
      paths: [],
      tags: [
        `repo:${targetPost.owner}:${targetPost.repo}`,
        `post:${targetPostId}`,
      ],
    }),
  })
}

###5. API Endpoint Details

app/api/revalidate/route.ts (lines 1-25):

export const POST = async (request: Request) => {
  const { secret, paths, tags } = z
    .object({
      secret: z.string(),
      paths: z.string().array(),
      tags: z.string().array().optional(),
    })
    .parse(await request.json())

  // Verify secret
  if (secret !== process.env.REVALIDATE_SECRET) {
    return Response.json({ error: "Invalid secret" }, { status: 401 })
  }

  // Revalidate paths and tags
  for (const path of paths) {
    revalidatePath(path)
  }
  for (const tag of tags ?? []) {
    revalidateTag(tag, "max")  // "max" = revalidate immediately
  }

  return Response.json({ ok: true })
}

###6. AI Agent Revalidation

The response agent (which generates AI responses) also triggers revalidation:

// agent/response-agent.ts (lines 282-283)
revalidateTag(`repo:${owner}:${repo}`, "max")
revalidateTag(`post:${postId}`, "max")

###7. Admin Actions

Simple path-based revalidation for admin pages:

// lib/actions/admin.ts
revalidatePath("/admin/llm-users")

###Key Takeaways

1. updateTag() marks tags as stale in server actions (immediate)
2. cacheTag() registers which tags a page depends on (in layout/page.tsx with "use cache")
3. revalidateTag() with "max" immediately revalidates and regenerates cached content
4. revalidatePath() is used for specific paths (like admin pages)
5. Cross-origin mentions use the on-demand API with a secret token for security

This design ensures that when data changes, only affected pages/posts are regenerated, not the entire site!