Case Study: Documenting a Composable Cloud Platform with Four Views

The best way to understand an architecture documentation approach is to see it applied to a realistic system. This article walks through a worked case study: a retailer replacing an all-in-one website platform with a modern, composable one. It builds on our introductions to the C4 model and the System Context diagram, and shows how four connected views can describe a system that mixes SaaS, PaaS, IaaS and on-premises parts.

A note on the case. Harbor & Pine Outfitters is a fictional organization. The system is a composite built from common patterns in cloud enterprise projects and does not represent any real company, client or project. The case comes from my doctoral research, which extends the C4 model to give consistent documentation for cloud-based enterprise systems.

The scenario

Harbor & Pine is a regional outdoor-equipment retailer with about 120 stores. It is replacing an aging, all-in-one web content management system with a composable, or “headless”, platform in which content is managed separately from how it is displayed. The program has these goals:

  • Marketing can publish and update content without developer involvement, subject to brand and legal approval.
  • Pages are assembled from a shared library of React components, so the brand looks the same everywhere.
  • Content is managed separately from presentation, so it can be reused across channels.
  • The existing ERP remains the system of record for products, prices and inventory.
  • Customer personal data is protected, and analytics are collected only with consent.
  • Website sign-ups flow automatically to the CRM and marketing automation, with consent recorded.

The platform deliberately combines all the hosting models architects meet today:

  • SaaS: Contentful (content), Auth0 (customer identity), Algolia (search), Dynamics 365 (CRM), Klaviyo (marketing automation), Cloudinary (digital assets) and GitHub (source control).
  • PaaS: Vercel, which hosts the Next.js web front end and serverless functions.
  • IaaS: a Node.js Experience API running in containers on AWS EC2.
  • On-premises: the existing ERP.

View 1: System Context

The context view shows the platform as a single box with six groups of people (customers, content editors, brand and legal reviewers, marketing managers, customer care and the digital product team) and eight external systems around it. At a glance, a business owner can see who depends on the platform, which capabilities are bought (SaaS) rather than built, and which team owns which system. As with any level 1 diagram, there are no technology details here, just people, systems and the relationships between them.

View 2: Container

Zooming in, the platform breaks into five deployable building blocks:

Building blockWhat it doesTechnologyHosting model
Web Front EndRenders pages from CMS content, media and product dataNext.js (React), VercelPaaS
Content Event FunctionsRefresh pages and the search index when content is publishedNode.js, Vercel FunctionsPaaS
Contentful SpaceContent model, entries, editorial workflowContentfulSaaS
Experience APIOne secured API for product, account and sign-up dataNode.js (Fastify), Docker on AWS EC2IaaS
Preferences DatabaseSaved stores and wish lists (personal data)Amazon RDS for PostgreSQLManaged database

The key insight at this level is the separation of content from presentation: editors work in Contentful, the front end renders what they publish, and the Experience API sits between the front end and the CRM, marketing automation and ERP. Each element is colour-coded by hosting model (green for SaaS, blue for PaaS, amber for IaaS, grey for on-premises), so the mix of responsibilities is visible without reading a word.

View 3: Component

Two component views open up the parts of the system where developers do the most work:

  • Web Front End: edge middleware for locale routing and experiments, page routes and layouts, a resolver that maps each CMS content type to a React component, a shared design-system library, a preview handler so editors can see unpublished content, and a revalidation endpoint that refreshes cached pages when content changes.
  • Experience API: API routes, token validation, and separate services for product and inventory, customer preferences, and sign-up and consent.

These views answer questions such as “how does CMS content become a page?” and “where are customer tokens validated?”

View 4: Deployment (Cloud Governance)

This is where the case departs from classic C4, which uses its fourth level for code. Code-level detail is valuable for developers, but it does little for the people who must answer questions like “who is responsible for patching this?” or “where does personal data live?”. The deployment view for governance shows:

  • where each building block runs, including the provider and hosting model
  • network boundaries: in AWS only the load balancer is internet-facing, the Experience API and database sit in private subnets, and the ERP is reachable only through a site-to-site VPN
  • environment separation: a second view shows that preview and staging are isolated from production, with separate accounts, tenants and test instances, and no real customer data
  • where personal data lives, tagged in the model: identities in Auth0, preferences in the database, customer and loyalty records in the CRM, and subscribers in marketing automation

Shared responsibility by hosting model

A table supplements the deployment view. “Shared” means the provider and the organization each hold part of the responsibility. A condensed version for this case:

Responsibility areaSaaSPaaS (Vercel)IaaS (AWS EC2)On-premises (ERP)
Physical facilities and hardwareProviderProviderProviderHarbor & Pine
Operating system and patchingProviderProviderHarbor & PineHarbor & Pine
Runtime and platform softwareProviderProviderHarbor & Pine (Node.js, Docker)Harbor & Pine
Application code and configurationHarbor & Pine (data model, roles, settings)Harbor & PineHarbor & PineHarbor & Pine
Identity and access to the serviceHarbor & PineHarbor & PineHarbor & PineHarbor & Pine
Secrets and API keysHarbor & PineHarbor & Pine (environment variables)Harbor & Pine (AWS Secrets Manager)Harbor & Pine
Backup and recoveryShared: provider backups, H&P exportsShared: stateless, redeploy from GitHarbor & Pine (rebuild from image)Harbor & Pine
Availability and scalingProviderProviderShared: H&P configures auto scalingHarbor & Pine

Two patterns stand out. The further down the stack you go from SaaS toward IaaS and on-premises, the more the organization owns. And even in pure SaaS, identity, secrets, configuration and data protection stay with the customer, a point that is easy to miss when a service looks fully managed.

An example flow: publishing a page

  1. A Content Editor drafts a page in Contentful, picks approved images from the DAM, and opens a preview link.
  2. The Brand & Legal Reviewer approves it in the Contentful workflow and the editor publishes it.
  3. Contentful sends a signed publish event to the Content Event Functions.
  4. The functions refresh the affected cached pages in the Web Front End and update the search index.
  5. Customers see the new page within seconds, with no developer or code deployment involved.

Walking one business flow across the views is a good test: if each view tells the same story from a different angle, the documentation is consistent.

What the case shows

  • The views are platform-agnostic. The same four views were also applied to a program built on a single configured SaaS platform, and the structure held. The technology changes; the questions each audience asks do not.
  • One model keeps views consistent. All diagrams are generated from a single model maintained as code (using the open-source LikeC4 tool), so a change made once appears everywhere.
  • Colour and tagging carry meaning. Hosting model and data classification are part of the model, not decoration.
  • The hardest governance question differs by system. Here it is who owns personal data spread across several SaaS tools; elsewhere it might be where vendor responsibility ends when custom code runs on a vendor platform.

Try it on your own system

  1. Draw a context diagram and ask someone outside the team to explain it back to you.
  2. Break the system into containers and mark each with its hosting model.
  3. Draw component views only for the containers that are complex or change often.
  4. Add a deployment view that shows environments, network boundaries and where personal data lives.
  5. Fill in a shared responsibility table so ownership of each area is explicit.

I would value your feedback on this case study and on the four-view approach: what was clear, what was not, and what you would change. Leave a comment below or get in touch through our contact page.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top