Core Concepts

The Big Idea

Governance, not generation.

Contentrain is not an AI content generator — there are dozens of those. Contentrain is the infrastructure that governs what happens after AI generates content: validation, structure, review, approval, and delivery.

Most content tools ask you to learn their system — their dashboard, their API, their markup syntax. Contentrain inverts this: your AI agent already understands your codebase, so let it manage your content. Contentrain provides the deterministic infrastructure (MCP tools, validation, Git transactions) while the agent provides the intelligence (what to extract, how to structure, where to replace).

Agent generates. Human approves. System standardizes.

The result is a content pipeline with full auditability:

Agent generates → MCP validates → Human reviews → Git commits → Content delivered

Every step is a git diff. Nothing reaches production without your approval.

The Agent-Driven Content Model

Contentrain AI inverts the traditional CMS workflow:

Traditional CMS	Contentrain AI
Human opens dashboard	Human talks to AI agent
Human creates schema manually	Agent creates models via MCP
Human types content in forms	Agent writes content to Git
Content stored in database	Content stored as files in .contentrain/
API calls to read content	Plain JSON files — read from any language, optional typed SDK
Deploys need API availability	Static files — works offline, zero runtime deps, any platform

Three Layers

1. MCP (Infrastructure)

13 tools that AI agents call to manage content:

• Read: contentrain_status, contentrain_describe, contentrain_content_list, contentrain_scan
• Write: contentrain_model_save, contentrain_content_save, contentrain_apply, contentrain_bulk
• Workflow: contentrain_validate, contentrain_submit

MCP is deterministic infrastructure — it doesn't make content decisions. The agent decides what to create; MCP executes it.

2. Agent (Intelligence)

The AI agent (Claude, GPT, etc.) is the intelligence layer:

• Understands your codebase structure
• Evaluates which strings are user-facing content
• Chooses the right model kind for each content group
• Determines framework-specific replacement patterns
• Manages the review workflow with the developer

3. Serve UI (Review Surface)

A local web UI for developers to:

• Monitor: browse models, content, validation, history
• Approve: review and merge agent-created branches
• Prompt: copy pre-built prompts to paste into their agent

The UI never triggers mutations directly — all actions go through the agent.

Model Kinds

Contentrain supports four content model kinds:

Collection

Multiple entries with the same field schema. Each entry has an auto-generated ID.

// .contentrain/content/marketing/faq/en.json
{
  "abc123": { "question": "What is Contentrain?", "answer": "..." },
  "def456": { "question": "How does it work?", "answer": "..." }
}

Use for: blog posts, FAQ items, team members, testimonials, pricing plans.

Singleton

A single entry per locale with structured fields.

// .contentrain/content/marketing/hero/en.json
{ "title": "Build Faster", "subtitle": "With AI", "cta_text": "Get Started" }

Use for: hero sections, site settings, navigation config, footer content.

Dictionary

Flat key-value pairs — all values are strings. No field schema.

// .contentrain/content/system/ui-labels/en.json
{ "nav.home": "Home", "nav.about": "About", "error.required": "This field is required" }

Use for: UI labels, button text, error messages, validation messages, i18n strings.

Parameterized Templates

Dictionary values support {placeholder} syntax:

dictionary('ui-labels').locale('en').get('welcome', { name: 'Ahmet' })
// "Hello, {name}!" → "Hello, Ahmet!"

Document

Markdown files with frontmatter metadata.

---
title: Getting Started
category: guides
---

# Getting Started

This is the markdown body content...

Use for: blog articles, documentation pages, changelogs, legal pages.

Domains

Models are organized by domain — a logical grouping:

.contentrain/content/
  marketing/     ← hero, pricing, testimonials
  blog/          ← blog-post, author
  system/        ← navigation, ui-labels

Domains are configured in .contentrain/config.json.

Locales & i18n

Every model can be i18n-enabled (i18n: true). Content is stored per locale:

.contentrain/content/marketing/hero/
  en.json    ← English
  tr.json    ← Turkish

Any platform can read the locale files directly. The TypeScript SDK adds convenience:

// Option 1: Read JSON directly (any language)
// Just read .contentrain/content/marketing/hero/tr.json

// Option 2: TypeScript SDK (optional)
singleton('hero').locale('tr').get()  // typed, with query API

Git Workflow

Every write operation creates a Git commit on a namespaced branch:

contentrain/model/hero-section        ← model changes
contentrain/content/blog-post         ← content changes
contentrain/normalize/extract/...     ← normalize extraction
contentrain/normalize/reuse/...       ← source patching

Branches are auto-merged or held for review depending on your workflow config.

How It Compares

	Contentrain AI	Headless CMS (Sanity, Strapi)	Git CMS (Tina, Decap)
Content source	Your codebase or agent-created from scratch	External dashboard	Markdown/JSON in repo
AI integration	Native (MCP tools)	Manual API calls	None
Extract from code	Yes (normalize flow)	No	No
Vendor lock-in	None (plain files + Git)	API dependency	Editor dependency
Type safety	Generated SDK (optional)	Manual types	Manual types
i18n	Built-in (per-locale files)	Plugin/addon	Plugin/addon
Review workflow	Git branches + local UI	Dashboard roles	PR-based
Runtime dependency	Zero (static files)	API availability	Build-time

No Lock-In

Contentrain stores everything as plain JSON and Markdown files in your Git repo. If you stop using Contentrain tomorrow, your content is still there — readable, portable, yours.

Beyond Web: Content CDN

Web projects deploy content with git push — no extra infrastructure needed. But non-web platforms (iOS, Android, React Native, Flutter, desktop apps, game engines, IoT) can't read from a git repo at runtime.

For these use cases, Contentrain publishes merged content to a CDN (cdn.contentrain.io), delivering the same structured JSON your SDK queries — just over HTTP instead of the filesystem.

Git repo → merge → CDN publish → iOS/Android/Flutter fetch → typed response

This means one content source powers your website, mobile app, and any other platform — all governed by the same review workflow.

Contentrain Studio

Contentrain Studio is the hosted governance UI that complements the local CLI and MCP tools. While the open-source packages handle local operations, Studio adds:

• Chat-first interface — talk to your agent through a web UI with full MCP access
• Team collaboration — invite editors and reviewers with role-based access
• Visual diff review — approve or reject content changes with a proper diff viewer
• GitHub integration — connect your repo, manage branches, track PRs
• Content CDN — publish merged content for non-web platforms

The local tools and Studio share the same MCP server — same tools, same behavior, different context.