For Addiction Education Society (AES), we modeled resources, stories, and core pages in Contentful so staff could update the public site without developer support. The team now publishes changes in minutes rather than days. For CrewAI, we mapped reusable page components to Contentful models, then built a separate handoff that turns published Ghost articles into Contentful drafts. Both projects used the same content management system (CMS). The useful engineering decision was where to place editorial control, rendering rules, and the final publication gate.
A headless CMS stores structured content separately from the code that renders it. That separation helps only when the content model reflects what editors need to create and what engineers need to keep consistent. These projects exposed 3 questions worth answering before migrating a page: What is reusable content? Which system owns each step of publication? Which existing systems should stay in place?
Model the things editors actually manage
At AES, the main requirement was editorial independence. Staff needed to maintain information as the nonprofit's education and outreach work grew. We created Contentful models for resources, stories, and core pages. Those categories gave the team structured material to build and update pages independently, including for time-sensitive initiatives. The AES case study reports that updates which took days can now be published in minutes.
CrewAI needed a different level of composition. Its previous CMS could no longer support the website it needed. We designed reusable components in Figma, including hero layouts, pricing sections, feature grids, statistics modules, and tabbed content. Each component mapped to a structured Contentful model. Marketing could assemble pages from those blocks, while developers rendered the layouts through GraphQL with strong type safety. In the CrewAI case study, the shift from individual templates to reusable sections is the mechanism behind that division of work.
The model therefore served as a contract. An editor could choose and populate a supported section; engineering owned how that section rendered and how it fit with analytics, search optimization, and integrations. Contentful's reference based type system makes these relationships possible, but the types still have to be designed. A collection of loosely related entries would give editors fields to fill without giving the site a dependable composition system. That is the modeling cost we account for up front.
Draw the migration boundary around the work
AES also shows why a CMS migration does not have to mean replacing every application under a domain. Its WordPress learning system supported active educational programs. Rebuilding that system along with the marketing site would have risked downtime or lost functionality. We launched a new marketing platform using Astro and Contentful alongside the existing learning system. Public pages, articles, and donation flows were modernized while the programs continued. Visitors still had an experience under one domain, and AES retained a path to migrate more functionality later.
That boundary mattered operationally. Staff gained control of public content without waiting for the learning platform to be rebuilt. The Contentful work solved a publishing problem; the surrounding architecture kept an existing program available. The project also used Contentful's pro bono program, which made the platform accessible to this qualifying nonprofit. Pricing was part of the platform decision, even though the implementation followed the same content modeling discipline as a larger site.
CrewAI crossed a different boundary. We moved its site away from page specific templates toward structured sections in Contentful, but kept Ghost for article writing. Treating every existing tool as something to replace would have disrupted a workflow the editorial team already valued. The two projects suggest a practical migration exercise: list the tasks people perform in each system, then move only the tasks the new architecture is meant to improve.
Make the publication gate explicit
CrewAI's writers publish articles in Ghost. An automated workflow converts each published Ghost article into a draft in Contentful. It stops there deliberately. Marketing then reviews the content, adds metadata, adjusts page composition, schedules it, and publishes it to the public site. Ghost owns the writing experience; Contentful owns the website release decision.
The draft state is the critical part of that integration. If the handoff went straight to public publication, the team would lose the documented review and enrichment step. If writers had to repeat their work manually in Contentful, the handoff would become another editorial bottleneck. The Contentful project page describes this pipeline as the integration point; the case study shows the specific roles on each side of it.
This is a useful question for any CMS integration: does an upstream “published” event mean ready for the public website, or ready for the next team to review? In CrewAI's workflow, those are separate states. Naming them in the architecture gives both teams a clear handoff and lets each keep the tool suited to its work.
Choose the platform with its constraints visible
Contentful gave AES structured content and staff publishing control; it gave CrewAI reusable page composition and a controlled handoff from Ghost. Neither outcome came from installing a CMS alone. We had to define content types, decide which existing systems would remain, and specify the point where a draft becomes public.
The platform also has costs. Its type system rewards careful modeling, and the Contentful project page notes both the budget impact and the absence of a built-in visual canvas for page building. For a small team with simple pages, that may be more structure than the work requires. For a site where several teams need to assemble pages and govern releases, the structure has a clear job. Start the architecture discussion with the editorial handoffs and the content that must be reused; they reveal whether the CMS belongs at the center, alongside another tool, or only on one part of the site.
Top comments (0)