CMS → Next: live content revalidation

1Goal

Editor saves in Filament → the change is live on all Next pods within seconds, across all 26 sites, with no downtime and the CMS database hit only a small bounded number of times per save.

2Architecture

The spine is Kairo's original sequence: back-end pushes a "you're stale" signal → front-end flips a flag in shared Redis → lazy regeneration on the next request. The webhook carries no content — Next pulls fresh data itself, lazily, so no user ever waits behind a rebuild.

End-to-end flow

System topology

Every Next pod is identical and serves all 26 domains (resolved per-request from the host header — D30). They share one Dragonfly, so a tag invalidation written by any pod is seen by all, and a single regen populates the cache for the whole fleet. That shared cache is what makes the design work; it isn't future-proofing.

Two Redis instances (D20)

• FE Redis — Dragonfly, in-kube. Shared across all Next pods via @fortedigital/nextjs-cache-handler (master-replica, node-redis). Holds rendered pages, the data cache, and tag-staleness state. CMS never touches it.
• CMS Redis — vanilla, VM-local. On the CMS VM, localhost-bound, provisioned via the C5 Ansible MR (no manual apt install on prod — house policy). Backs both the Laravel content cache (cms.content.{id}.v{gen}) and the Horizon queue, on separate DB indexes. Protects the DB from concurrent regens.

Cloudflare is deliberately not in front (D21) — Fortedigital + Dragonfly is the L1 cache, and Cloudflare wouldn't resolve the concurrent-regen race the way shared Redis does.

Request & cache resolution

3The contract

The cross-team boundary — the one thing that must not drift silently. Two bearer-auth endpoints. domainId is the underscored canonical form on the wire (D38) so CMS tags and Next page tags always match. The webhook is idempotent, at-least-once, order-insensitive.

# CMS → Next : "you're stale" — invalidation only, no payload
POST {NEXT_REVALIDATE_URL}/api/revalidate
  Authorization: Bearer ${CMS_REVALIDATE_SECRET}
  { "domainId": "balticlei_ee" }      // or null = global-default save
  → 200 { revalidated, tag, now }
  → 400 bad body · 401 bad bearer · 403 domainId not in allowlist · 500 unexpected

# Next → CMS : pull fresh content for ONE domain (lazy, on regen)
GET {CMS_API_BASE_URL}/api/content/{domainId}
  Authorization: Bearer ${CMS_CONTENT_TOKEN}
  → { sites: { "balticlei_ee": { block_groups, blog_posts } } }

# Tags & keys
Next page cache tags : ['cms', 'cms:'+domainId]
CMS BE cache key     : cms.content.{domainId}.v{gen}   // version-keyed (D39)
global-default save  : domainId = null → tag 'cms' → forget all 26

4Data model & the global default

CMS content is group → block → translations[lang], enumerated from config('blocks.groups') (56 translation models). For every block, ensureDefaultRows() seeds a default row with domain = null per language; each site inherits that default until it sets its own override. So a NULL-row save legitimately invalidates every domain (D8/D27/D37).

5Workstreams

Each task cites the decisions behind it (full rationale in §9). Three streams, built in slices (§6).

Ablei-cms — Laravel 12 + Filament → main

Bblei-next — Next 16 App Router → develop

CInfra / shared — Erki

6Delivery slices & milestones

Each slice ships independently; pause for human review at every boundary.

Execution milestones & parallel lanes

The slices above are the what. For execution, work is organized into milestones (each = one mergeable, review-gated MR) holding slices (one cohesive test-then-build loop each; a slice never spans two MRs). Tasks build ping-pong TDD (failing test → pass → commit). Sessions persist across milestones — the review gate is also the natural compaction checkpoint.

Parallel lanes: cms-lane (M2→M3a→M3b) ‖ next-lane (M1→M4a→M4b) — serial within a lane, parallel across (~2× throughput). 3 sync points (not MRs): SYNC 0 = Slice-0 gate (handler + cross-pod proof) · SYNC A = pin the cross-repo contract before Slice-2 build · SYNC B = Slice-2 e2e (CMS deploys first, D41).

7Verification runbook

Manual multi-pod check for Slice 2 sign-off (Steven runs this personally before prod).

# 1. Local Redis
docker run -p 6379:6379 redis:7 redis-server --notify-keyspace-events Egx

# 2. CMS locally with: REDIS_CLIENT=phpredis, CACHE_DRIVER=redis, REVALIDATION_ENABLED=true,
#    NEXT_REVALIDATE_URL=http://host.docker.internal:3000/api/revalidate, CMS_REVALIDATE_SECRET, CMS_CONTENT_TOKEN

# 3. Two Next pods sharing one Redis
PORT=3000 REDIS_URL=redis://localhost:6379 CMS_API_BASE_URL=http://localhost:8090 … npm run build && npm run start &
PORT=3001 REDIS_URL=redis://localhost:6379 …                                          npm run start &

# 4. Warm both pods   5. Trigger:  docker exec blei-cms-app php artisan cms:revalidate balticlei_ee
curl :3000/balticlei_ee/et   # serves stale, triggers regen
sleep 5 ; curl :3001/balticlei_ee/et   # fresh, from shared cache

8Reference tables

Cache layers

Environment & secrets

Failure modes

9Decision log

Why each call. The full record (with reversal history) is in DECISIONS.md.

Design principles

1. Config-driven. Code shouldn't know which fields/blocks/domains exist — iterate config('blocks.groups'), getFillable(), query DomainLanguage.
2. Idempotent + retry-safe. Webhooks may arrive more than once; revalidateTag is naturally idempotent.
3. Lazy where possible. Signal → flag → lazy regen. Don't pre-render unless evidence shows the lazy path hurts UX.
4. Kill switches over rollbacks. Minimal pre-launch (one flag).
5. Defer until measured. No caches/locks/coordination until evidence shows they're needed.
6. Invalidation granularity = fetch granularity. Tags no finer than the URL granularity. NULL = the global scope by data definition.

Locked decisions

Reversed / superseded

R1–R12 cleared earlier drafts (per-domain tags, single-tag day-1, dedicated cache stores, three kill switches, debounce-by-marker, per-domain webhook URLs…). R13: supervisord queue:work → Horizon (D35). R14: the 'use cache' flip → rejected, unstable_cache stands (D36).

10Open items