CMS boundaries

TL;DR

• Every Contentstack project is built on five primitives: stacks, content types, entries, assets, and environments
• Content types define the schema (API contract); entries are instances of that schema; assets are CDN-backed files with built-in image transformations
• Environments (development, staging, production) control where content is published and each has its own delivery token
• The fundamental loop is: model content types, create entries, publish to environments, deliver via API

Before you can model content, query APIs, or configure publishing workflows, you need a precise understanding of the five primitives that make up every Contentstack project. These are not abstract concepts - they are the concrete objects you create, configure, and interact with daily. Each one maps to a specific section of the Contentstack UI and a specific set of API endpoints. Getting these relationships clear now prevents confusion in every subsequent lesson.

Stacks

A stack is the top-level container in Contentstack. Everything you build - content types, entries, assets, environments, locales, workflows, branches, tokens - lives inside a stack. Think of a stack as a project boundary. It holds all the content and configuration for one project, and in some cases, for a set of closely related projects that share content models.

When you log into Contentstack and select a stack from the dashboard, you enter that stack's isolated environment. Each stack has its own:

• Content types and global fields: the schemas that define your content structure
• Entries: the content instances created from those schemas
• Assets: the files (images, documents, videos) uploaded to the stack
• Environments: the deployment targets content is published to
• Locales: the language and regional variants supported
• Branches: the parallel versions of content types for safe schema evolution
• Tokens: the API credentials (delivery tokens, management tokens, preview tokens) scoped to the stack
• Workflows: the content lifecycle stages configured for editorial processes
• Webhooks: the event notifications sent to external systems

In a typical organizational setup, you might have one stack per website, or one stack per brand, or one stack that serves multiple channels for a single product line. The decision of how to scope your stacks is an architectural one - a single stack for multiple sites enables content sharing but increases schema complexity, while separate stacks provide isolation but require cross-stack content strategies for shared content.

In the Contentstack UI, you select stacks from the organization dashboard. The left-hand navigation within a stack gives you access to all the primitives described in this lesson.

A concrete example

Imagine you are building the Veda: The Revival Collection storefront. You create a stack named veda-revival-web. This stack will contain content types for products, product lines, categories, pages, and global navigation. All content for the Veda storefront lives in this stack. If Veda later launches a mobile shopping companion or an in-store display experience, you can serve content from the same stack to those channels too - this is multi-channel delivery from a single content source.

Content types

A content type is a schema. It defines the structure of a specific kind of content by declaring what fields an entry of that type can have, what data type each field uses, and what validation rules apply.

If you think in API terms, a content type defines the shape of the JSON payload that the API will return for entries of that type. If you think in database terms, a content type is roughly analogous to a table schema - though Contentstack is not a relational database, and the analogy has limits.

Every content type has a unique identifier (UID), a display name, and a set of fields. Contentstack provides a visual content type builder in the UI where you drag and drop fields onto the schema. The field types available include:

• Single Line Textbox: short text strings (titles, labels)
• Multi Line Textbox: longer text without formatting
• Rich Text Editor / JSON Rich Text Editor: formatted content with embedded assets and references
• Number: numeric values
• Boolean: true/false toggles
• Date: date and datetime values
• File: attached assets (images, documents)
• Reference: links to entries of other content types
• Group: nested field containers within the same entry
• Modular Blocks: flexible, repeatable content sections where editors choose from predefined block types
• Global Field: reusable field groups shared across multiple content types
• URL: a field specifically for URL values
• Select: dropdown or radio selection from predefined options
• Link: hyperlink fields with title and URL
• Taxonomy: classification through hierarchical taxonomy terms

For the Veda example, you might create the following content types:

• Product: fields for title (single line), short_description (multi line), description (multi line), price (number), media (file, multiple), product_line (reference to Product Line), category (reference to Category)
• Product Line: fields for title (single line), url (URL), description (multi line), image (file), products (reference to Product)
• Category: fields for title (single line), url (URL), description (multi line), media (file), products (reference to Product)
• Page: fields for title (single line), url (URL), components (modular blocks allowing hero, list, rich text, and media sections)

Content types are versioned and managed through the content type builder, accessible via the left navigation under the content models section. Changes to content types affect all future entries of that type, and in some cases, require attention to existing entries.

Entries

An entry is an instance of a content type. If the content type is the schema, the entry is the data. When an editor clicks "Create Entry" and selects a content type, they get a form generated from that content type's field definitions. They fill in the fields, save the entry, and optionally publish it to one or more environments.

Each entry has:

• A UID: a unique identifier generated by Contentstack
• A title: the display name (pulled from a designated title field)
• A locale: the language variant this entry represents
• A workflow stage: the current position in the content lifecycle (e.g., Draft, Review, Published)
• A version history: every save creates a new version, and previous versions can be compared or restored

In the Veda example, entries might include:

• A Product entry with title "Matrix Link Bracelet," price 295, category references, and product media
• A Product Line entry with title "Digital Dawn," collection copy, and a hero image
• A Page entry with title "The Revival Collection" and a set of modular blocks composing the storefront homepage

Entries are managed in the Contentstack UI under the Entries section, which lists all entries across content types with filtering, sorting, and search capabilities. Each entry has its own editor view where fields are displayed according to the content type schema.

The critical concept is that entries exist independently of any page or rendering context. A Product entry is structured data. It becomes part of a web page only when your frontend application fetches it via API and renders it. The entry itself has no opinion about where or how it appears.

Assets

Assets are files stored in Contentstack's asset repository. Images, PDFs, videos, SVGs, font files - any file you upload becomes an asset in the stack. Each asset gets:

• A UID: unique identifier
• A URL: a CDN-backed URL for delivery
• Metadata: file name, file size, content type (MIME type), dimensions (for images)
• Tags: optional labels for organization and filtering
• Folders: assets can be organized into folder hierarchies

Contentstack's asset repository includes an image transformation pipeline. For image assets, you can append query parameters to the delivery URL to resize, crop, convert format, adjust quality, and apply other transformations on the fly. For example, adding ?width=400&format=webp to an image URL delivers a 400-pixel-wide WebP version of the original image. This means you do not need a separate image processing service for common transformations.

Assets can be referenced from entries through File fields or embedded in Rich Text Editor content. When an editor inserts an image into a rich text field or selects an image for a File field, they are creating a reference to an asset in the repository.

In the Contentstack UI, the Assets section provides a file manager interface with upload, folder management, search, and metadata editing. Bulk upload is supported, and assets can be organized across folders for manageability.

For the Veda example, assets would include product photography, collection hero images, the Veda brand logo, and campaign media used across landing pages and product experiences.

Environments

An environment represents a deployment target - a destination where content is published to and a specific API endpoint from which content is retrieved. Every stack has at least one environment, and most stacks have several.

Common environment configurations include:

• development: used during active development, published content available at a development-specific delivery URL
• staging: used for QA and editorial review before content goes live
• production: the live environment that serves content to end users

Each environment has:

• A name: a human-readable identifier (e.g., "production")
• A base URL: the URL associated with this environment (used in Live Preview and Visual Builder configuration)
• Deployment server URLs: optional server URLs for deploy-time actions
• Publishing rules: content can be published to specific environments independently

When an editor publishes an entry, they choose which environment(s) to publish to. An entry might be published to "staging" for review but not yet published to "production." This gives editorial teams control over content promotion - content moves through environments as it progresses through the review and approval process.

From the API perspective, each environment has its own delivery token. Your frontend application uses the delivery token for the appropriate environment to fetch content. Your production website uses the production delivery token. Your staging preview site uses the staging delivery token. This ensures that unpublished or staging-only content never leaks into the production experience.

In the Veda example, you might configure three environments:

• development: where developers test content rendering while building components
• staging: where the editorial team previews content before it goes live
• production: where the live Veda storefront fetches published content from

How these building blocks relate

The relationships between these five primitives form the operational model of every Contentstack project:

1. You create a stack as the project container.
2. Inside the stack, you define content types that describe the structure of your content.
3. Editors create entries based on those content types, filling in fields with content.
4. Editors upload assets (images, files) and reference them from entries.
5. Editors publish entries to environments, making content available through environment-specific delivery APIs.
6. Your frontend application queries the delivery API for a specific environment and renders the entries and assets as pages.

This is the fundamental loop: model, create, publish, deliver. Every other Contentstack feature - workflows, branches, locales, tokens, webhooks, Live Preview, Visual Builder - extends or refines this loop.

Additional primitives (brief introduction)

Several other Contentstack primitives build on the five core building blocks. Each is covered in detail in later lessons, but you should be aware of them now.

Locales: Language and regional variants for content. A stack can support multiple locales (e.g., en-us, fr-fr, de-de), and each entry can have locale-specific versions. Locales support fallback chains - if content does not exist in a specific locale, it can fall back to a parent locale.

Branches: Parallel versions of content types within a stack. Branches let you develop schema changes (add fields, modify content types) without affecting the main branch that editors are actively using. When the schema changes are ready, you compare and merge branches. This is conceptually similar to Git branches but for content type schemas rather than code.

Workflows: Configurable content lifecycle stages. A workflow defines the stages an entry moves through - for example, Draft, In Review, Approved, Published. Workflow stages can have assigned roles, automatic actions, and publishing restrictions.

Tokens: API credentials scoped to a stack. Delivery tokens authorize read access to published content for a specific environment. Management tokens authorize read-write access to the Content Management API. Preview tokens authorize access to draft content for preview purposes. Each token type has a different security profile and a different appropriate runtime context.

Common mistakes

Mistake 1: Confusing content types with pages

Content types define data schemas, not page templates. A content type called "Page" might define fields that represent a page, but the content type itself does not generate a page. Your frontend application decides how entries map to rendered pages. Multiple entries from different content types might compose a single page, and a single entry might appear on multiple pages.

Common Pitfall

Using a single environment for development, staging, and production removes your ability to preview and validate content before it reaches end users -- and risks leaking draft content to the live site.

Mistake 2: Using one environment for everything

Running development, staging, and production content through a single environment removes the ability to preview and validate content before it reaches end users. Separate environments give editors a safe space to publish and review content without affecting the live site.

Mistake 3: Treating assets as external files

Assets stored in Contentstack's repository get CDN delivery, image transformation capabilities, and metadata management. Hosting images on a separate file server and linking to them from text fields bypasses these capabilities and creates a management burden that grows with the number of assets.