# Core CMS Concepts

> Source: https://agilitycms.com/docs/training-guide/concepts

> Understanding the fundamental concepts and architecture of Agility CMS

This section explains the core concepts and mental models that underpin Agility CMS. These guides help you understand **why** Agility CMS works the way it does, not just **how** to use it.

## Table of Contents

1. [Agility Data Model](#1-agility-data-model)
2. [Headless Architecture](#2-headless-architecture)
3. [Agility Sections](#3-agility-sections)

---

## 1. Agility Data Model

![Agility Data Model Diagram](https://cdn.aglty.io/agility-cms-docs/images/training-guide/assets/concepts/Agility%20Data%20Model.png)

### Overview

The Agility Data Model illustrates how content, presentation, and navigation are structured and related in Agility CMS. It shows the separation between **models** (schemas/definitions) and **instances** (actual data), and how they connect through references.

### Key Concepts

#### Three-Layer Architecture

**1. Models (Schema Layer)**
- **Page Model**: Defines the structure for pages
- **Component Model**: Defines the structure for reusable UI components
- **Content Model**: Defines the structure for reusable content items

Models are like blueprints—they define what fields exist and what types of data they hold, but don't contain actual content.

**2. Instances (Data Layer)**
- **Pages**: Actual page instances created from page models
- **Components**: Component instances with actual data
- **Content Items**: Standalone content pieces created from content models

Instances are the actual data—the filled-out forms, the real content.

**3. Relationships (Reference Layer)**
- **Sitemap**: Organizes pages and defines URLs
- **Page → Components**: Pages contain references to components
- **Component → Content**: Components display content items
- **Content → Content**: Content items can link to other content items

### How It Works

#### Sitemap Structure

The sitemap is the navigation backbone of your site:

```
/home: 1                    → Points to Page ID 1
/about-us: 2                → Points to Page ID 2
/blog: 3                    → Points to Page ID 3
/blog/first-post: 4, content: 6  → Page ID 4, displays Content ID 6
```

Each sitemap entry maps a URL path to a page, and optionally to specific content.

#### Page Structure

A page is a container that:
- Has metadata (title, description, path)
- References multiple components
- Can be organized in a sitemap hierarchy

**Example Page:**
```json
{
  "pageID": 2,
  "name": "home",
  "path": null,
  "title": "Home",
  "menuText": "Home",
  "pageType": "static",
  "templateName": "Main Template",
  "zones": {
    "main-content-zone": [
      {
        "module": "PersonalizedBackgroundHero",
        "item": {
          "contentID": 186,
          "properties": {
            "state": 2,
            "referenceName": "home_personalizedbackgroundh48f36e",
            "definitionName": "PersonalizedBackgroundHero"
          },
          "fields": {
            "heading": "Close Every Deal",
            "description": "Galaxy Tech helps you sell more...",
            "cta1": {
              "href": "/contact-us",
              "text": "Get started"
            }
          }
        }
      },
      {
        "module": "BentoSection",
        "item": {
          "contentID": 27,
          "properties": {
            "referenceName": "home_bentosection",
            "definitionName": "BentoSection"
          },
          "fields": {
            "heading": "Know everything your customers do...",
            "bentoCards": {
              "referencename": "home_bentosection_bentocard",
              "fulllist": true
            }
          }
        }
      }
    ]
  }
}
```

#### Component Structure

Components are reusable UI building blocks. When placed on a page, they appear in the `zones` array:

**Example Component (BentoSection):**
```json
{
  "contentID": 27,
  "properties": {
    "state": 2,
    "referenceName": "home_bentosection",
    "definitionName": "BentoSection",
    "itemOrder": 0
  },
  "fields": {
    "subheading": "Sales",
    "heading": "Know everything your customers do and so much more",
    "bentoCards": {
      "referencename": "home_bentosection_bentocard",
      "fulllist": true
    }
  }
}
```

Components define **how** content is presented, not **what** content is shown.

#### Content Structure

Content items are standalone, reusable pieces of data:

**Example Content (Post):**
```json
{
  "contentID": 204,
  "properties": {
    "state": 2,
    "modified": "2025-12-08T15:12:10.883",
    "versionID": 1287,
    "referenceName": "posts",
    "definitionName": "Post",
    "itemOrder": 22
  },
  "fields": {
    "heading": "Changed Heading",
    "slug": "future-of-retail-ai-customer-intelligence",
    "postDate": "2025-10-08T04:00:00+00:00",
    "category": {
      "contentID": 61,
      "properties": {
        "referenceName": "categories",
        "definitionName": "Category"
      },
      "fields": {
        "name": "Knowledge"
      }
    },
    "categoryID": "61",
    "categoryName": "Knowledge",
    "tags": [
      {
        "contentID": 8,
        "fields": {
          "name": "A.I."
        }
      }
    ],
    "author": {
      "contentID": 59,
      "fields": {
        "name": "Emily Selman",
        "headShot": {
          "url": "https://cdn.agilitycms.com/...",
          "label": null
        }
      }
    },
    "content": "<p>The retail landscape has undergone...</p>",
    "image": {
      "label": "Man at a computer",
      "url": "https://cdn.agilitycms.com/..."
    }
  }
}
```

Content items define **what** data exists, independent of **where** it's displayed.

### Relationships and Flow

1. **Sitemap → Page**: Each URL maps to a page
2. **Page → Components**: Pages contain multiple components
3. **Component → Content**: Components display content items
4. **Content → Content**: Content items can reference other content items

### Why This Model?

**Separation of Concerns:**
- Content (data) is separate from Components (presentation)
- Pages (navigation) are separate from Content (data)
- This allows maximum flexibility and reusability

**Reusability:**
- Content items can be used in multiple components
- Components can be used on multiple pages
- Update content once, see changes everywhere

**Flexibility:**
- Change presentation without changing content
- Change content without changing pages
- Support multiple frontends from one CMS

### Real-World Example

**Blog Post Scenario:**

1. **Content Model**: "Post" defines fields (title, date, author, content)
2. **Content Item**: A specific blog post (e.g., "First Post", ID: 6)
3. **Component Model**: "PostDetails" defines how to display a post
4. **Component Instance**: A PostDetails component that displays Post ID: 6
5. **Page**: A page model that includes the PostDetails component
6. **Sitemap**: `/blog/first-post` maps to the page, which displays Post ID: 6

**Benefits:**
- The same Post content can be displayed in different components
- The same PostDetails component can display different posts
- Posts can be reused in listings, featured sections, etc.

---

## 2. Headless Architecture

![Headless Architecture Diagram](https://cdn.aglty.io/agility-cms-docs/images/training-guide/assets/concepts/Agility%20Headless%20Architecture.png)

### Overview

Headless architecture separates content management from content delivery. Content is managed in one place (the CMS) but can be consumed by any number of frontend applications through APIs.

### Architecture Components

#### Backend (Agility CMS)

**Content Manager**
- Web-based interface for content editing
- Where content editors create and manage content
- Provides preview and publishing workflows

**Content APIs**
- RESTful APIs that expose content as JSON
- Standard HTTP methods (GET, POST, etc.)
- Stateless, cacheable API endpoints
- Supports filtering, sorting, pagination

**Asset CDN**
- Content Delivery Network for media assets
- Optimized image delivery
- Automatic resizing and format conversion
- Global distribution for performance

#### Frontend Applications

**Website**
- Traditional web application (e.g., Next.js, React)
- Consumes content via Content APIs
- Renders HTML for browsers
- Can be statically generated or server-rendered

**Apps**
- Mobile applications (iOS, Android)
- Desktop applications
- IoT devices
- Any application that can consume APIs

#### End-User Devices

**Devices**
- Desktop browsers
- Mobile browsers
- Native mobile apps
- Smart TVs, IoT devices
- Any device that can access the frontend applications

### Data Flow

1. **Content Creation**: Editors create content in Content Manager
2. **API Exposure**: Content is automatically exposed via Content APIs
3. **Frontend Consumption**: Website/Apps fetch content via APIs
4. **Asset Delivery**: Images/assets served directly from CDN
5. **User Access**: Users access rendered content on their devices

### Why Headless?

#### Multi-Channel Publishing

**Same Content, Multiple Channels:**
- Website: Next.js application
- Mobile App: React Native application
- Kiosk: Custom display application
- All consume the same Content APIs

**Benefits:**
- Create content once, publish everywhere
- Consistent content across channels
- Channel-specific presentation

#### Technology Freedom

**Frontend Flexibility:**
- Use any frontend framework (React, Vue, Angular, etc.)
- Use any programming language
- Deploy anywhere (Vercel, AWS, Azure, etc.)
- No vendor lock-in for frontend

**Developer Experience:**
- Modern development tools
- Version control for frontend code
- CI/CD pipelines
- Testing frameworks

#### Performance

**CDN Delivery:**
- Assets served from edge locations
- Reduced latency globally
- Automatic optimization

**Caching:**
- API responses can be cached
- Static site generation
- Incremental static regeneration

**Scalability:**
- Scale CMS and frontend independently
- Handle traffic spikes efficiently
- Optimize each layer separately

#### Future-Proofing

**New Channels:**
- Add new frontends without changing CMS
- Support emerging platforms
- Adapt to new technologies

**Content Reuse:**
- Content remains valuable as technology changes
- No need to migrate content for new frontends
- Long-term content investment

### Comparison: Traditional vs Headless

**Traditional CMS (Monolithic):**
```
CMS → HTML → Browser
```
- CMS generates HTML
- Tightly coupled
- Limited flexibility

**Headless CMS:**
```
CMS → APIs → Frontend → HTML → Browser
```
- CMS provides data
- Loosely coupled
- Maximum flexibility

### Real-World Example

**E-commerce Scenario:**

1. **Content Manager**: Product information, descriptions, images
2. **Content APIs**: Expose products, categories, reviews
3. **Website**: Next.js e-commerce site consuming APIs
4. **Mobile App**: React Native app consuming same APIs
5. **Admin Dashboard**: Custom admin interface consuming APIs
6. **Asset CDN**: Product images served via CDN

**Benefits:**
- Product data managed once
- Consistent across all channels
- Each channel optimized for its platform
- Easy to add new channels (voice assistant, AR, etc.)

---

## 3. Agility Sections

![Agility Sections Diagram](https://cdn.aglty.io/agility-cms-docs/images/training-guide/assets/concepts/Agility%20Sections.png)

### Overview

The Agility Sections diagram illustrates the four main functional areas of the Agility CMS interface. Each section serves a specific purpose in the content management workflow.

### The Four Sections

#### 1. Content Section

**Purpose**: Manage reusable content items and lists

**Contains**: Lists / Items

**What You Do Here:**
- Create and edit content items (e.g., Blog Posts, Authors, Categories)
- Organize content into lists
- Manage relationships between content items
- Set up content models and fields

**Key Concepts:**
- **Content Items**: Single, standalone pieces of content
- **Content Lists**: Collections of related content items
- **Content Models**: Templates that define content structure

**Example Workflows:**
- Creating a new blog post
- Adding an author profile
- Organizing posts by category
- Setting up product catalogs

#### 2. Assets Section

**Purpose**: Manage digital media files

**Contains**: Files / Images / PDFs

**What You Do Here:**
- Upload images, documents, videos
- Organize assets in folders
- Manage asset metadata
- Optimize and resize images

**Key Concepts:**
- **Media Library**: Centralized storage for all assets
- **CDN Delivery**: Assets served via Content Delivery Network
- **Automatic Optimization**: Images automatically optimized

**Example Workflows:**
- Uploading hero images
- Organizing product photos
- Managing document downloads
- Adding alt text for accessibility

#### 3. Pages Section

**Purpose**: Manage website structure and page content

**Contains**: Sitemap, Pages, Components

**What You Do Here:**
- Build and organize pages in the sitemap
- Add components to pages
- Configure page models
- Set up dynamic page routing

**Key Concepts:**
- **Sitemap**: Navigation structure of your site
- **Pages**: Individual web pages
- **Components**: Reusable UI building blocks
- **Content Zones**: Areas where components can be placed

**Example Workflows:**
- Creating a new page
- Adding a hero component to a page
- Organizing pages in the sitemap
- Setting up blog post detail pages

#### 4. Web Studio Section

**Purpose**: Preview and test content before publishing

**Contains**: Preview

**What You Do Here:**
- Preview pages and content
- Test responsive designs
- Review content before publishing
- Debug layout issues

**Key Concepts:**
- **Live Preview**: See how content will appear
- **Device Testing**: Preview on different screen sizes
- **Draft Preview**: Preview unpublished content

**Example Workflows:**
- Previewing a new page design
- Testing mobile responsiveness
- Reviewing content before publishing
- Checking component layouts

### How Sections Work Together

**Typical Workflow:**

1. **Assets**: Upload images needed for content
2. **Content**: Create content items (e.g., blog posts) using those images
3. **Pages**: Build pages using components that display the content
4. **Web Studio**: Preview the pages to see how everything looks

**Example: Creating a Blog Post**

1. **Assets**: Upload featured image for the post
2. **Content**: Create a new Post content item, add text, link to the image
3. **Pages**: The blog listing page automatically shows the new post (if using dynamic routing)
4. **Web Studio**: Preview the post to see how it looks

### Section Relationships

**Content ↔ Assets:**
- Content items reference assets (images, documents)
- Assets are managed separately but used in content

**Pages ↔ Content:**
- Pages use components that display content items
- Content items can be used on multiple pages

**Pages ↔ Components:**
- Pages are built from components
- Components define how content is presented

**Web Studio ↔ Everything:**
- Web Studio previews the final result
- Shows how all sections come together

### Mental Model

Think of Agility CMS like building a house:

- **Content**: The materials (wood, bricks, etc.) - reusable resources
- **Assets**: The tools and supplies (images, documents) - supporting materials
- **Pages**: The rooms (pages) built from components (walls, doors, windows)
- **Web Studio**: The blueprint preview - see how everything looks before building

### Best Practices

**Content Section:**
- Create reusable content items
- Organize content logically
- Use relationships to connect related content

**Assets Section:**
- Organize assets in folders
- Use descriptive filenames
- Optimize images before uploading

**Pages Section:**
- Plan page structure in sitemap
- Use components consistently
- Keep page models organized

**Web Studio Section:**
- Always preview before publishing
- Test on multiple devices
- Review content for accuracy

---

## Understanding the Big Picture

These three concepts work together:

1. **Data Model** explains **how** content is structured
2. **Headless Architecture** explains **why** this structure exists
3. **Sections** explain **where** you work with content

**Together, they form a complete picture:**
- Content is structured for flexibility (Data Model)
- Content is delivered via APIs for multi-channel support (Headless Architecture)
- Content is managed through organized sections (Sections)

Understanding these concepts helps you:
- Make better decisions about content structure
- Plan for multi-channel publishing
- Work more efficiently in the CMS
- Troubleshoot issues more effectively

---

## Next Steps

After understanding these concepts:
1. Review the role-specific guides with this context
2. Apply these concepts to your content strategy
3. Design content models with reusability in mind
4. Plan for multi-channel content delivery

**You understand Agility CMS when you can:**
- Explain why content is separate from presentation
- Design content models that support multiple channels
- Navigate the CMS sections with purpose
- Make architectural decisions based on these principles