Architecture Overview

This guide provides an architectural overview of Agility CMS, focusing on design principles, patterns, and strategic considerations for solution architects.

Headless Architecture

Headless Architecture Diagram

Agility CMS follows a headless architecture pattern that separates content management from content delivery.

Architectural Principles

  1. Separation of Concerns

    • Content management (backend) independent of presentation (frontend)
    • Content APIs provide data, not HTML
    • Frontend applications consume APIs and render content

  2. API-First Design

    • All content exposed via RESTful APIs
    • JSON-based data exchange
    • Stateless API interactions
    • GraphQL support for complex queries

  3. Multi-Channel Support

    • Same content APIs serve multiple frontends
    • Website, mobile apps, IoT devices consume same content
    • Channel-specific presentation logic in frontend

  4. CDN Integration

    • Assets delivered via Content Delivery Network
    • Optimized performance for global audiences
    • Automatic image optimization and resizing

Data Model Architecture

Data Model Diagram

The Agility data model uses a three-layer architecture:

Layer 1: Models (Schema Layer)

Purpose: Define structure and schema

  • Page Models: Define page structure (content zones, layout)
  • Component Models: Define reusable UI component structure
  • Content Models: Define reusable content item structure

Layer 2: Instances (Data Layer)

Purpose: Actual data instances

  • Pages: Page instances created from page models
  • Components: Component instances with actual data
  • Content Items: Standalone content pieces created from content models

Layer 3: Relationships (Reference Layer)

Purpose: Connect entities together

  • 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

Interface Organization

Agility Sections Diagram

The Agility CMS interface is organized into four main sections:

  • Content: Manage Lists and Items (reusable content)
  • Assets: Manage Files, Images, and PDFs (media library)
  • Pages: Manage Sitemap, Pages, and Components (page structure)
  • Web Studio: Preview content before publishing

Architectural Benefits

Flexibility

  • Change frontend without affecting content
  • Use any frontend framework or technology
  • Adapt presentation to different channels

Scalability

  • Scale CMS and frontend independently
  • Optimize each layer separately
  • Handle traffic spikes efficiently

Reusability

  • Content and components used across multiple pages/channels
  • Single source of truth for content
  • Consistent content across channels

Performance

  • CDN delivery for assets
  • Optimized caching strategies
  • Fast API responses

Developer Experience

  • Modern APIs and SDKs
  • TypeScript support
  • Comprehensive documentation

Architectural Decision Framework

When to Use Content Models vs Component Fields

Use Content Models When:

  • Content is reused across multiple pages/components
  • Content has relationships with other content
  • Content needs to be managed independently
  • Content supports personalization

Use Component Fields When:

  • Content is specific to one component instance
  • Content is simple (text, image, link)
  • Content doesn't need relationships

When to Use Content Items vs Content Lists

Use Content Items When:

  • Single, standalone piece of content
  • Example: Global Settings, Author profile

Use Content Lists When:

  • Collection of related items
  • Items need to be queried/filtered
  • Example: Blog Posts, Testimonials

Multi-Channel Architecture

Channel Types

  • Website: Traditional web pages
  • Mobile App: Native mobile applications
  • API: Custom integrations
  • Digital Displays: Kiosks, signage

Content Strategy

  • Design content models for reuse
  • Avoid presentation-specific fields
  • Plan for API consumption
  • Support multiple locales

Integration Architecture

Frontend Integration

  • SDKs: Framework-specific SDKs (Next.js, Gatsby, Nuxt, etc.)
  • APIs: RESTful and GraphQL APIs
  • Caching: Built-in caching strategies
  • Preview: Preview mode support

Third-Party Integrations

  • Analytics: PostHog, Google Analytics
  • Search: Algolia, custom search
  • AI: Azure OpenAI, custom AI services
  • CDN: Asset delivery optimization

Performance Architecture

Optimization Strategies

  1. CDN Delivery: Assets via CDN
  2. Image Optimization: Automatic resizing and formats
  3. Caching: Multi-layer caching strategy
  4. Static Generation: Pre-render pages at build time
  5. Incremental Regeneration: Update pages on-demand

Scalability Considerations

  • Horizontal Scaling: Scale frontend independently
  • Content Scaling: Efficient content querying
  • Asset Scaling: CDN for global delivery
  • API Scaling: Optimized API responses

Next: Data Model - Deep dive into the data model