Replacing Storyblok with an Owned Knowledge Center

Vue d'ensemble

Neuroframe's content ran on Storyblok. On paper the CMS solved content management; in practice the requirements outgrew what a headless CMS is good at, and the site's reliability was coupled to an API nobody on the team operated. This record documents the decisions behind the replacement, not its source code.

Ce qui a été construit

A Knowledge Center the company owns end to end: structured content versioned in Git, a registry that types every surface and its URL, a build that assembles and validates pages before they can ship, and server-side rendering on Neuroframe's own infrastructure. No external service sits in the render path. This is not an open-source project; what is documented here is the approach and its trade-offs.

À qui il s'adresse

Readers of neuroframe.com's industry guides, and the team that publishes them. The visitor sees faster, more reliable pages; the team gets an editorial pipeline with the same review discipline as code.

Contexte métier

This is not a story about Storyblok being bad. Every page render depended on an external API, outages arrived from outside our control, complex layouts fought the content model, and scaling toward thousands of highly structured articles priced against us. The honest conclusion was that the requirements had exceeded the category: what was needed was not a better CMS, it was ownership of the pipeline.

Architecture

One pipeline from a Git commit to a rendered page, with validation between authorship and publication. Nothing in the render path calls out.

Authoringstructured content + review, in Git

Registrytypes, taxonomy, URL architecture

Buildassembly from typed inputs

one pipeline, no external calls

Validationgates before anything publishes

RenderSSR on our own servers

Localesen · fr · de, one tree

Readerneuroframe.com/knowledge

Why ownership beat a better CMS

Two failure classes drove the shape. Reliability: when a third-party content API has an outage, your site has an outage, and no amount of caching discipline changes who gets paged. Structure: highly structured, cross-linked article libraries want types, invariants, and URL rules, and a generic block model fights all three. Moving content into Git and rendering on owned infrastructure removed the external dependency entirely and let the taxonomy become code that a build can verify, rather than convention that an editor must remember.

Composants

Nine decisions carry the system. Each is documented the same way: why it exists, how it is approached, what constrains it, and what it trades away. Deliberately absent: implementation detail that would reproduce the product.

›C1Content in Gitauthorship

Pourquoi il existe: The content is as load-bearing as the code, so it lives under the same discipline: versioned, reviewed, and deployed atomically with the site that renders it.
Architecture: Structured content files sit in the repository beside the code. Editorial changes travel as pull requests, so review, history, and rollback come free, and a page and the layout that renders it can never ship out of sync.
Contraintes: Every change goes through review; nothing publishes from a dashboard. Content and code share one deploy, so a content mistake rolls back the same way a code mistake does.
Cas limites: Non-technical contributors need a path that does not require Git fluency; drafts need somewhere to live without publishing; large media stays out of the repository.
Compromis: You give up the CMS editing experience, real-time preview for non-developers is work you now own. Taken deliberately: the review gate is worth more to this library than dashboard convenience.

›C2Typed taxonomy & URL architecturestructure

Pourquoi il existe: A knowledge library is not a pile of posts. Industries, categories, and guides are different types with different obligations, and the URL tree should promise only what actually exists.
Architecture: Content surfaces are typed, and the URL hierarchy mirrors the taxonomy: industry, category, guide. One rule governs depth: a URL level exists only if a real page serves users at that level. Low-count branches collapse rather than presenting empty shelves.
Contraintes: Every item has exactly one canonical home. Browsing surfaces never mix types; featured placements may cross them. One design grammar across the whole tree.
Cas limites: Categories with one or two guides, industries launching with zero articles (the surface states it honestly rather than padding), and legacy URLs from earlier structures.
Compromis: Types and rules make ad-hoc placement harder by design. The structure is the product; convenience placements erode it.

›C3Content registrysource of truth

Pourquoi il existe: Navigation, sitemaps, related-content, and hub pages must never disagree about what exists. A single registry answers that question for every consumer.
Architecture: One typed registry maps every piece of content to its surface, locale, and URL. Menus, directories, feeds, and cross-links derive from it at build time instead of being maintained by hand in parallel.
Cas limites: Content present on disk but not registered, registered but unpublished, and items moving between categories without breaking their history.
Compromis: A registry is a second place a new article must be declared. Accepted: the declaration is what makes every downstream surface derivable and verifiable.

›C4Owned rendering pipelineSSR

Pourquoi il existe: Complex editorial layouts were the point of friction with the block model. Owning the render layer turns layouts into components with the full power of the framework.
Architecture: Pages render server-side on Neuroframe's own infrastructure from the built content. Editorial designs, galleries, story arcs, and structured hubs, are components in code, not compositions of generic CMS blocks.
Contraintes: The render path makes no external API calls. Performance budgets and the design grammar bind every template.
Cas limites: Long-tail pages that must render well without bespoke attention; the tension between one grammar and per-page art direction.
Compromis: Layout freedom for developer involvement: new layout species need an engineer. For a library where layout is brand, that is the correct side of the trade.

›C5Localizationi18n

Pourquoi il existe: The Knowledge Center serves more than one market, and half-translated surfaces damage trust more than English-only ones.
Architecture: One content tree carries every locale with English as the source of truth. Translation happens once, at copy freeze, never incrementally against moving copy. Locale routing, alternates, and sitemaps derive from the same registry as everything else.
Contraintes: No locale strings for work-in-progress surfaces. A translated label must never point at an untranslated page.
Cas limites: Content that exists in one locale only, and locale-specific URL forms that still need the redirect discipline below.
Compromis: Slower to light up a new language, immune to the half-translated state readers actually notice.

›C6Migration & redirect disciplineURL integrity

Pourquoi il existe: The move retired an entire URL scheme. Links from outside do not know your architecture changed, and a redirect graph with a cycle takes pages down as surely as an outage.
Architecture: Every retired URL gets a permanent redirect into the new tree, and the full redirect graph is kept acyclic by rule: every chain terminates at a page that answers 200 in one hop wherever possible.
Contraintes: Redirects are declared beside the routes they protect and documented with their invariant, so a future change can see the graph it is editing.
Cas limites: Locale-prefixed variants of retired pages, wildcard moves that must preserve the deep path, and redirects interacting with earlier generations of redirects.
Compromis: Redirect rules accumulate and must be maintained. The alternative is link rot and loops, which are worse than the bookkeeping.

›C7The Decision Engineinternal system

Pourquoi il existe: Producing many highly structured pages by hand does not scale, and hand-produced structure drifts. An internal system assembles structured pages from typed inputs so the library can grow without proportional editorial cost.
Architecture: Described here only at the level of what it does: the Decision Engine takes typed inputs and produces candidate structured pages through the same validation gates as everything else; nothing it produces can publish without passing them, and the surrounding pipeline treats its output exactly like human-authored content. Its internals are deliberately not documented in this record.
Cas limites: Output that passes validation but reads generically, which is a quality-bar question, not a correctness one, and inputs the type system cannot yet express.
Compromis: Publishing this section at all trades some mystique for credibility; publishing more would trade away the advantage. The line is drawn at behavior and guarantees.

›C8Build pipeline & verificationquality gates

Pourquoi il existe: When content, taxonomy, and redirects are all code, the build can verify promises a CMS could only hope editors kept.
Architecture: The build assembles pages from the registry and then verifies the result: routes resolve, redirect chains terminate, locale surfaces agree with the registry, and rendered output passes structural checks. A failed check fails the deploy.
Contraintes: Checks run on every build, not on a schedule. New surface types must arrive with their checks.
Cas limites: Checks that pass locally against stale artifacts, which taught the team to distrust warm dev servers and verify against clean builds.
Compromis: Builds are slower and stricter than pushing to a CMS. That strictness is the reliability story.

›C9Retiring the CMSmigration

Pourquoi il existe: The riskiest day of an architecture replacement is the cutover. The migration was staged so no reader ever saw the seam.
Architecture: Content was frozen, ported into the typed tree, and verified surface by surface while the CMS still served production. The switch was a routing change with the redirect graph already in place, and the external API left the render path the same day.
Compromis: A staged migration takes longer than a rewrite-and-swap. It also never took the site down, which was the entire point.

Rendu visuel

Exhibits from the live Knowledge Center. Slots below await real captures; nothing is mocked.

The knowledge directory

Typed industry surfaces from one registry.

Screenshot slot · /knowledge directory

C2 · Taxonomy & URLs

An industry library

The library-first hub: lead story, browse, and filters on one page.

Screenshot slot · industry library

C2 · Taxonomy & URLs

A structured guide

An editorial layout that the block model could not carry, built as components.

Screenshot slot · guide page

C4 · Owned rendering

Locale parity

One tree, three languages, no half-translated surfaces.

Screenshot slot · fr/de locale views

C5 · Localization

Build verification

The gate that fails a deploy before it fails a reader.

Screenshot slot · build checks output

C8 · Build pipeline

Impact

What ownership changed, by audience.

Business: Site reliability no longer depends on a third-party content service.
Cost stops scaling per article against an external platform as the library grows.
Client: Faster first paint from owned SSR with no external API in the path.
Richer editorial layouts than a block model could express.
Opérations: One deploy carries code and content; one rollback covers both.
Outage exposure from the content layer went to zero by construction.
Ingénierie: Taxonomy and URL rules became code the build verifies, not conventions editors remember.
Editorial changes gained code review, history, and atomic rollback.
The Decision Engine can grow the library without proportional hand-assembly.
Échelle: Three locales from one content tree.
An architecture sized for thousands of structured articles before it strains.

Documents techniques

Documents this record seeds. Each becomes a dated entry as it is written.

—DecisionContent belongs in GitWhy editorial went through pull requests, and what the CMS dashboard was traded for.—DecisionA URL level exists only if a real page serves itThe rule that killed placeholder hierarchy levels.—NoteAcyclic redirect graphsRetiring a URL scheme without loops or link rot; every chain terminates at a 200.—DecisionEnglish first, translate at copy freezeWhy incremental translation against moving copy was banned.—NoteWhen a headless CMS stops fittingThe signals that requirements have exceeded the category, told without vendor blame.—Long-formOwning the rendering pipelineWhat changes when layouts are components and the render path calls no one.

Étude de cas

The complete arc, compressed.

Problème: Every page render depended on an external CMS API: outages outside the team's control, layouts fighting a generic block model, and per-article costs that scaled against a library meant to reach thousands of structured articles.
Objectif: Complete ownership of the content pipeline, from authorship to rendered page, with reliability, structure, and localization as build-verified properties rather than editorial conventions.
Contraintes: No external service in the render path; a migration that never takes the site down; a URL tree that promises only what exists; and a public record that documents decisions without reproducing the product.
Approche: Move content into Git under code review, type the taxonomy and URL architecture in a single registry, assemble and validate pages at build time, render server-side on owned infrastructure, and localize once at copy freeze. Stage the migration behind an acyclic redirect graph and cut over as a routing change.
Architecture: Git authorship, a typed registry, a validating build, owned SSR, one tree for three locales, with the internal Decision Engine assembling structured pages through the same gates as human-authored content.
Compromis: No CMS editing experience, stricter and slower builds, redirect bookkeeping, and developer involvement for new layout species, each accepted deliberately and named in this record.
Résultat: The Knowledge Center runs in production on neuroframe.com with zero external APIs in the render path. The CMS is retired, the redirect graph holds, and the library has room to compound.
Enseignements: Requirements can outgrow a category; the fix is ownership, not a better vendor.
Structure that lives as code can be verified; structure that lives as convention decays.
A migration's success is measured by what readers never noticed.
You can document engineering honestly without publishing the product.
Suite: Real captures for the exhibits above, the seeded journal entries as dated documents, and the library growth the architecture was sized for.