Agility CMS

Developer

Demo Site: Project Structure

This guide documents the codebase organization of the Demo Site. Understanding the project structure helps you navigate and contribute to the codebase effectively.

Directory Structure

Key Files

Middleware (src/middleware.ts)

Handles:

  • Preview mode detection
  • Redirect management
  • Locale routing
  • Search params encoding
  • Dynamic content redirects

Component Registration (src/components/agility-components/index.ts)

Registers all 20 Agility components:

  • allModules array contains component mappings
  • getModule() function finds components by name
  • Case-insensitive matching

CMS Utilities (src/lib/cms/)

Core CMS functions:

  • getAgilitySDK() - SDK initialization with preview mode
  • getContentItem() - Fetch single content item with caching
  • getContentList() - Fetch content list with caching
  • getAgilityPage() - Fetch page data with components

Environment Configuration (src/lib/env.ts)

Strongly-typed environment variables:

  • Validates required variables at runtime
  • Provides type-safe access
  • Throws errors for missing variables

Component Organization

Agility Components

Located in src/components/agility-components/:

  • Simple Components: Direct field mapping (Hero, RichTextArea)
  • List Components: Display content lists (PostListing, Testimonials)
  • Nested Components: Fetch nested content (BentoSection)
  • Client Components: Interactive components (Carousel, ContactUs)
  • Personalized Components: Audience/region filtering

Component Patterns

Server Component Pattern:

Server + Client Split:

API Routes

Preview Routes

  • /api/preview - Enable preview mode
  • /api/preview/exit - Exit preview mode

Revalidation Route

  • /api/revalidate - Webhook endpoint for cache invalidation

AI Routes

  • /api/ai/search - AI-powered search
  • /api/ai/agent - AI agent endpoint

Other Routes

  • /api/contact - Contact form submission
  • /api/search - Standard search
  • /api/dynamic-redirect - Dynamic content redirects

Type Definitions

TypeScript interfaces in src/lib/types/:

  • IPost.ts - Blog post structure
  • IAuthor.ts - Author information
  • ICategory.ts - Blog categories
  • ITag.ts - Blog tags
  • IAudience.ts - Audience targeting
  • IRegion.ts - Regional content
  • SitemapNode.ts - Sitemap structure

Build Process

Pre-build Step

Runs node/prebuild.ts to:

  • Rebuild redirect cache
  • Generate bloom filters
  • Prepare static data

Build

  • Generates static pages
  • Builds API routes
  • Optimizes assets

Development Workflow

  1. Start Development Server:

  2. Make Changes:

    • Edit components in src/components/agility-components/
    • Update types in src/lib/types/
    • Modify API routes in src/app/api/

  3. Test Changes:

    • Preview in browser
    • Test with different content
    • Verify caching behavior

  4. Build and Deploy:

Next: Content Models - Content model implementations