System Architecture

Architecture Blueprint

Technical specifications of a serverless, multi-tenant Git-backed Headless CMS running entirely in V8 sandbox isolates on Cloudflare's serverless edge infrastructure.

01 / SYSTEM TOPOLOGY

Serverless Edge-Native Architecture

Pouta is built on a serverless edge-native architecture using Cloudflare Pages, Cloudflare Workers, and SQLite at the Edge (Cloudflare D1). It combines static-first marketing pages with server-side rendered (SSR) admin API routes executing globally on Cloudflare’s Edge network inside lightweight V8 isolates.

Data Flow Relationships

Pouta decouples static delivery from server compute. It handles dynamic draft caching inside local Cloudflare D1 SQLite replicas globally. When a collaborator publishes, the system translates the BlockNote ProseMirror JSON block array into GFM Markdown with YAML frontmatter and commits it directly to your remote repository via the GitHub API.

02 / EDGE SESSION CRYPTOGRAPHY

Stateless Session Seals (AES-GCM)

To eliminate edge database lookup overhead and ensure zero cold-start delay, Pouta uses stateless secure session seals placed directly into an HTTP-only, secure cookie (pouta_session) using the Web Crypto API.

A. Key Derivation & Cryptographic Import

A high-entropy symmetric AES-GCM key is dynamically derived from the environment variable SESSION_SECRET. The passphrase is encoded to UTF-8 bytes and imported into the Web Crypto API context:

const rawSecret = new TextEncoder().encode(env.SESSION_SECRET);
const keyDigest = await crypto.subtle.digest('SHA-256', rawSecret);
const cryptoKey = await crypto.subtle.importKey(
  'raw',
  keyDigest,
  { name: 'AES-GCM' },
  false,
  ['encrypt', 'decrypt']
);

B. The Encryption Cycle (Sealing)

During OAuth token exchanges, an ephemeral 12-byte Initialization Vector (IV) is generated:

const iv = crypto.getRandomValues(new Uint8Array(12));

The payload is encrypted via crypto.subtle.encrypt, converted to Base64, and serialized into a single string formatted as ivBase64:ciphertextBase64 in a secure SameSite=Lax cookie.

03 / EDGE RS256 JWT

Edge-Native JWT Signers

Pouta writes files using temporary GitHub App Installation Access Tokens instead of permanent personal tokens. The App private key is Base64 encoded inside environment variables (GITHUB_APP_PRIVATE_KEY_B64) to prevent PEM spacing issues in serverless sandboxes.

PKCS#8 RSA Key Import

The private key string is parsed, stripped of boundaries, decoded from Base64 into an ArrayBuffer, and imported dynamically into the V8 sandbox isolate:

const privateCryptoKey = await crypto.subtle.importKey(
  'pkcs8',
  binaryKeyBuffer,
  {
    name: 'RSASSA-PKCS1-v1_5',
    hash: { name: 'SHA-256' },
  },
  false,
  ['sign']
);

Using the imported private key, Pouta signs dynamic JWT claims (iss, iat, exp) to authenticate as the App itself. It sends this JWT in an HTTP POST request to GitHub's installations token exchange endpoint to fetch a highly restricted 1-hour Installation Access Token.

04 / TENANCY GATES

Multi-Tenant Isolation Gates

Multi-tenancy security is enforced at the edge. A request cannot read, write, upload, or save any draft without successfully clearing three strict validation gates:

GATE 1 Cryptographic Verification

The sealed session cookie must decrypt using the edge node's secret key, verifying the caller has a valid, untampered signature.

GATE 2 Push Collaborator Check

Queries the repository metadata dynamically. Rejects requests with a 403 Forbidden if permissions.push !== true.

GATE 3 SQLite Query Scoping

All database cache updates and queries are strictly scoped: WHERE repo_owner = ? AND repo_name = ?

05 / CONFIGURATION SCHEMA

Dynamic Schema-Agnostic Configs

Pouta is entirely schema-agnostic. It stores no database structure schemas locally. Every target repository controls its own content structures directly inside its codebase via a pouta.config.json file in the repository root.

When a writer logs in, Pouta fetches and parses the remote configuration. The visual dashboard dynamically loops over the JSON fields array to render the matching form controls (covers, tags, text fields, booleans):

{
  "contentTypes": [
    {
      "type": "blog",
      "label": "Blog Posts",
      "writePath": "src/content/blog/{slug}.md",
      "fields": [
        { "name": "featured_image", "label": "Cover", "type": "image" },
        { "name": "description", "label": "Meta Description", "type": "textarea" },
        { "name": "pinned", "label": "Pinned Post", "type": "boolean" }
      ]
    }
  ]
}

06 / GFM CONTENT PIPELINE

JSON to Markdown Serialization

Content is drafted using ProseMirror-based BlockNote json blocks. When publishing, the edge engine compiles metadata into a YAML Frontmatter block and recursively translates content block arrays into GitHub Flavored Markdown (GFM).

Block Type	JSON Payload Example	Output GFM Markdown
heading	`{"type":"heading","props":{"level":2},"content":[...]}`	`## Heading Title\n\n`
paragraph	`{"type":"paragraph","content":[...]}`	`Paragraph text\n\n`
checkListItem	`{"type":"checkListItem","props":{"checked":true},...}`	`- [x] Checked Task\n`
codeBlock	`{"type":"codeBlock","props":{"language":"ts"},...}`	`\`\`\`ts\nconst x = 1;\n\`\`\``

YAML Frontmatter Example:

---
id: "8c7d8a9f-4b2a-4c8d-b3e1-3e4b7c8d9e0f"
type: "blog"
slug: "my-first-post"
title: "My First Post"
featured_image: "https://images.unsplash.com/..."
created_at: "2026-05-26T18:00:00.000Z"
published_at: "2026-05-26T18:15:00.000Z"
---

During publishes, Pouta fetches the existing file SHA first. If found, it appends the SHA into the subsequent PUT request to prevent merge conflicts or accidental overwrite cycles between writers.

07 / SYSTEM WORKFLOWS

Workflow Pipelines

Pouta uses a high-speed, asynchronous event sequence to complete dynamic operations at the edge:

1. OAuth & Initialization Sequence

A. User requests sign-in and is routed to GitHub's authorization consent screen.
B. Callback endpoint exchanges code for user OAuth Access Token.
C. Token is encrypted into a sealed secure cookie via AES-GCM.
D. Dashboard queries active installations and renders matching scopes.

2. Save & Publish Sequence

A. ProseMirror captures typing changes and sends delta updates to the Edge API.
B. Edge API checks session signature and caches draft inside local Cloudflare D1.
C. Publish trigger reads blocks, compiles GFM, and verifies remote SHA hashes.
D. Commit is pushed via Github App. SQLite cache is updated to "published".

08 / IMAGE PIPELINE

Serverless R2 Media Buckets

Pouta manages media uploads directly at the Edge using Cloudflare R2 Object Storage, isolating folders cleanly and bypassing third-party CDN egress fees.

Type & Size Safety Files are restricted to a maximum of 5MB and limited strictly to safe web MIME types (JPEG, PNG, GIF, WebP, SVG, AVIF) to prevent server-side injection.

Isolated Namespace Images are stored under keys prefixed by the collaborator scope to enforce clean tenant boundaries: uploads/{owner}/{repo}/{uuid}-name

Zero-Egress Delivery Served via custom domains mapped directly to the R2 bucket, resolving paths locally without routing through server compute, guaranteeing zero egress costs.

09 / CLOUDFLARE WORKERS AI

Edge-Level AI Coprocessing

Pouta integrates context-aware AI capabilities using Cloudflare Workers AI. Rather than relying on high-latency third-party external APIs, it utilizes local models running on Cloudflare's serverless GPU network.

Accessibility Alt-Text Generator (Llama 3.2 Vision)

Upon uploading an image, the raw binary buffer is parsed ephemerally by @cf/meta/llama-3.2-11b-vision-instruct to produce highly optimized, 15-word descriptive alt tags. If execution fails, the system automatically falls back to @cf/llava-hf/llava-1.5-7b-hf before defaulting to sanitized filenames.

Content Optimization & Translation (Llama 3 8B)

Performs inline block copyediting, translations, SEO descriptions, and category tag extraction using @cf/meta/llama-3-8b-instruct. During heavy GPU load, it implements an automated failover loop routing to @cf/meta/llama-2-7b-chat-fp16 in less than 200ms transparently.

10 / STRIPE PAYWALL GATE

SaaS Monetization Gates

Pouta comes equipped with an edge-caching Paywall & Billing System utilizing Stripe webhooks to verify active subscriptions.

Edge Stripe Signature Verification

Stripe payloads are validated using high-speed HMAC SHA-256 Web Crypto functions rather than heavy Node SDK libraries:

const signatureKey = await crypto.subtle.importKey(
  'raw',
  new TextEncoder().encode(env.STRIPE_WEBHOOK_SECRET),
  { name: 'HMAC', hash: { name: 'SHA-256' } },
  false,
  ['verify']
);

Localized D1 Sync Updates local multi-tenant subscriptions tables immediately upon receiving Stripe checkout success or cancellation events, keeping status records in sync at the edge.

Edge Paywall Validation When paywall is active, advanced API features automatically run a database lookup, blocking unauthenticated endpoints with a 402 Payment Required payload.

11 / INCLUSIVE ACCESSIBILITY

Inclusive Design & First-Class A11y

Pouta CMS ensures that the entire editor workspace respects visual, keyboard, and screen reader guidelines out of the box, obtaining a perfect 100% Lighthouse rating and 10/10 WAVE scanner score.

Semantic Visual-to-DOM Landmarks

Single-page apps are notoriously difficult to navigate via assistive tools. Pouta enforces distinct semantic wrappers:

Editor Elevation: Converted the central workspace area from a generic <section> container to a native <main id="main-editor-canvas"> to index it as the main landmark.
Stateless Media Query Support: Visual selectors are given explicit aria-label declarations to remain readable even when hidden on mobile viewports.

AAA Contrast Skip Links A visually-hidden link anchors at the top of the DOM structure. When selected via keyboard tab routing, it animates smoothly into focus using high-contrast slate and warm orange outlines, achieving a contrast ratio of over 15:1 to exceed WCAG AAA minimums.

BlockNote DOM Attribute Hooks Pouta injects descriptive accessibility cues directly onto ProseMirror's contenteditable DOM elements dynamically during initial state setups, assuring clear box and editor role titles for screen readers.