Skip to main content

Documentation Index

Fetch the complete documentation index at: https://avocadostudioai.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
Pages, Blocks, and Props

Avocado Studio manages website content as structured data, not raw HTML.
  • Page (PageDoc) — A single page on your website (e.g., /about, /pricing). Contains metadata (title, slug) and an ordered list of blocks.
  • Block (BlockInstance) — A content section on a page. Each block has a type (e.g., Hero, CTA, FAQAccordion) and props — the structured data that controls what it renders.
  • Props — The fields that make up a block’s content. A Hero block has heading, subheading, imageUrl, imageAlt, ctaText, and ctaHref (plus a few optional fields). Every prop is defined by a Zod schema, so the system knows exactly what values are valid.
PageDoc
├── slug: "/about"
├── title: "About Us"
└── blocks:
    ├── BlockInstance { type: "Hero", props: { heading: "About Us", ... } }
    ├── BlockInstance { type: "FeatureGrid", props: { items: [...] } }
    └── BlockInstance { type: "CTA", props: { label: "Get Started", ... } }

​
Operations

An operation is a structured, schema-validated edit action. When a user says “change the hero heading to Welcome”, the AI doesn’t modify HTML — it generates an operation like: 
{
  "op": "update_props",
  "pageSlug": "/about",
  "blockId": "hero-1",
  "patch": { "heading": "Welcome" }
}
Operations are the unit of change in Avocado Studio. They can be:
OperationWhat it does
add_blockInsert a new block at a specific position
update_propsChange one or more props on an existing block
remove_blockDelete a block from the page
move_blockReorder a block within the page
duplicate_blockCopy a block within or across pages
add_itemAdd an item to a list field (e.g. a new testimonial)
update_itemUpdate a list item by index
remove_itemDelete a list item by index
move_itemReorder a list item
create_pageCreate a new page
duplicate_pageCopy an existing page
rename_pageChange a page’s slug and/or title
remove_pageDelete a page
move_pageReorder a page in the site nav
update_page_metaUpdate SEO meta fields (title, description, ogImage)
update_site_configUpdate global site settings (name, logo, nav)
Every operation is validated against the block’s Zod schema before it’s applied. If the AI generates an invalid edit (e.g., setting a heading to a number), it’s rejected automatically.

​
Plans and Approval

When a user sends a chat message, the AI generates an edit plan — a list of one or more operations. The plan is presented to the user for review before it’s applied. 
User: "Add a testimonials section below the hero with 3 customer quotes"

→ Edit Plan:
  1. add_block { type: "Testimonials", position: after "hero-1", props: { items: [...] } }

→ User approves → Operations applied → Live preview updates
Plans can be approved, rejected, or modified. The user always has the final say.

​
Draft Mode

Draft mode is how the Content Studio shows unpublished changes on your live site. When the Content Studio is active, the site switches into draft mode — it fetches the latest draft content from the orchestrator instead of the published content.
  • Published content — What your visitors see. Stored in your CMS, database, or static files.
  • Draft content — What you see in the Content Studio. Stored in the orchestrator’s session state. Not visible to site visitors.
  • Publishing — Promoting draft content to published. Triggered by the user after reviewing changes.
Draft mode uses Next.js cookies under the hood. The Content Studio iframe sets the cookie automatically — your site just needs to check for it and fetch from the orchestrator when present.

​
The Three Services

Avocado Studio runs as three services that communicate via HTTP and postMessage:
ServiceRoleTech
OrchestratorThe brain. Handles AI planning, operation validation, session state, undo/redo, and publishing.Fastify API
Content StudioThe UI. Chat interface, model picker, plan review, and settings. Embeds the site in an iframe.Vite + React
SiteYour website. Renders pages from block data. In draft mode, fetches content from the orchestrator.Next.js
The Content Studio embeds your site in an iframe. When the user clicks a block, the site sends a postMessage to the Content Studio identifying which block was selected. When an operation is applied, the orchestrator notifies the site to re-fetch and re-render.

​
Block Manifest

When the Content Studio connects to your site, it fetches the block manifest from /api/editor/blocks. This tells the Content Studio what block types are available and what props each one accepts. 
{
  "version": 1,
  "blocks": [
    {
      "type": "Hero",
      "displayName": "Hero",
      "editablePaths": ["heading", "subheading", "imageUrl", "ctaText", "ctaHref"],
      "propsSchema": {
        "type": "object",
        "properties": {
          "heading":    { "type": "string" },
          "subheading": { "type": "string" },
          "imageUrl":   { "type": "string" },
          "ctaText":    { "type": "string" },
          "ctaHref":    { "type": "string" }
        },
        "required": ["heading", "ctaText", "ctaHref"]
      },
      "defaultProps": {
        "heading": "Welcome",
        "ctaText": "Get started",
        "ctaHref": "/contact"
      }
    }
  ]
}
The AI planner uses the manifest to understand what blocks exist and what edits are possible. This is why every block needs a complete schema — it’s not just for validation, it’s the AI’s instruction manual.

​
Multi-Model AI

The orchestrator supports three AI providers:
  • Anthropic — Claude Haiku (fast), Sonnet (balanced), Opus (complex reasoning). Most battle-tested.
  • OpenAI — GPT-4o-mini (fast), GPT-4o (balanced), o1/o3 (reasoning).
  • Google Gemini — Gemini Flash (fast), Gemini Pro (reasoning).
Users select the provider and model tier in the Content Studio’s settings panel. The orchestrator routes the request to the appropriate provider. You can also override model names via environment variables for each tier.