Business-as-Code

Business-as-Code is an approach to defining businesses declaratively in code - using structured data, content, logic, and UI components in a single source of truth. Instead of building businesses through fragmented tools and platforms, you define your entire business model, operations, and user interfaces in MDXLD documents that can be versioned, tested, and deployed like code.

The Core Idea

Traditional business operations require:

• Separate tools for documentation, workflows, and interfaces
• Manual coordination between teams and systems
• Duplication of business logic across platforms
• Complex integrations and data synchronization

Business-as-Code unifies all of this into declarative MDXLD documents that:

• Define structured business data (entities, relationships)
• Include human-readable documentation
• Embed executable logic and workflows
• Specify UI components for rendering
• Support multi-target rendering (web, API, AI tools, CLI)

What is MDXLD?

MDXLD = MDX + Linked Data

MDXLD is the document format that makes Business-as-Code possible. It combines four layers in a single file:

Example: A Startup Defined in MDXLD

---
$context: https://schema.org.ai
$type: Startup
$id: https://startups.studio
name: Startups.Studio
tagline: AI-operated venture studio
stage: Growth
---

# {name}

{tagline}

We build **autonomous businesses** powered by AI agents.

export const metrics = await fetchMetrics()

<Hero title={name} subtitle={tagline} />
<Stats metrics={metrics} />
<StoryBrand />
<Team display="cards" />

This single document:

• Defines the startup as structured data ($type: Startup)
• Includes marketing copy and documentation
• Fetches live metrics via code
• Specifies how to render the UI

Learn more: MDXLD Format

Foundational Vocabulary

Business-as-Code uses a consistent vocabulary based on Nouns and Verbs:

Nouns and Verbs

• Noun = A type or entity in the system (Business, Product, Agent, Task, Person)
• Verb = A complete action grammar with all linguistic forms (actor, act, action, result, event, reverse)

This enables consistent naming across all layers:

• Events: TaskCreated, InvoiceApproved
• Relations: createdBy, approvedBy
• Actions: create, approve
• Results: creation, approval

Actors and Workers

Four types of Actors execute functions in the system:

Workers are a special subset - Agents and Humans that "perform Tasks":

interface Worker {
  ask(prompt: string): Promise<Response>
  do(task: Task): Promise<Result>
}

class Agent implements Worker { ... }
class Human implements Worker { ... }

Workers are interchangeable. A Task can be performed by either an Agent or Human, enabling hybrid human-AI workflows.

Learn more: Core Concepts

The Power of YAMLLD ($-Properties)

MDXLD uses YAMLLD - a variant of JSON-LD that uses $ instead of @ for special properties:

Why $ instead of @?

• Valid in YAML without quoting
• Valid as JavaScript/TypeScript identifiers
• Works in MDX expressions: <Card type={$type} />

The Triple Entendre of $context

$context serves three purposes simultaneously:

1. JSON-LD Context - Defines the schema vocabulary for interpreting properties
2. AI/LLM Context - Tells agents how to understand and work with the document
3. Namespace - Creates domain-specific vocabularies for your business

This triple meaning makes MDXLD documents simultaneously machine-readable, AI-understandable, and domain-specific.

Learn more: MDXLD Format

Multi-Target Rendering

The same MDXLD document renders to multiple targets without modification:

import { renderHTML, renderMarkdown, renderMCP, renderJSON } from 'mdxui'

const doc = await load('startup.mdx')

renderHTML(doc)      // Web page for humans
renderMarkdown(doc)  // Context for AI agents
renderMCP(doc)       // Tools for AI systems
renderJSON(doc)      // API response
renderSlack(doc)     // Slack UI for HumanTasks
renderInk(doc)       // CLI interface

The component declares what (semantic structure). The renderer determines how (output format).

This means:

• Your website and your API share the same source
• Agents receive the same data structure humans see
• Documentation and implementation never drift
• Changes propagate to all targets automatically

How It All Fits Together

1. Define your business in MDXLD documents using schema.org.ai types
2. Use consistent vocabulary from Nouns and Verbs for all entities and actions
3. Specify actors (ServiceAccounts, Models, Agents, Humans) to execute functions
4. Build workflows that coordinate Code, Generative, Agentic, and Human functions
5. Render to any target - web UI, API, AI tools, CLI - from the same source

Example workflow:

---
$type: Workflow
$id: https://yourapp.com/workflows/invoice-approval
name: Invoice Approval
---

# Invoice Approval Workflow

1. **Receive** invoice (Code function via ServiceAccount)
2. **Extract** data using OCR (Generative function via Model)
3. **Validate** against policies (Code function via ServiceAccount)
4. **Approve** or reject (Human function via Worker)
5. **Process** payment (Code function via ServiceAccount)
6. **Notify** stakeholders (Code function via ServiceAccount)

<Workflow states={['pending', 'validated', 'approved', 'paid']} />

This single document:

• Defines the workflow structure
• Documents each step for humans
• Specifies which actor type handles each function
• Provides a UI component for visualization
• Renders to web, API, MCP tools, and more

Getting Started

Ready to build with Business-as-Code?

1. Installation - Set up mdxui in your project
2. Core Concepts - Learn the foundational vocabulary
3. MDXLD Format - Master the document format

Why Business-as-Code?

Version Control - Track business changes in git like code

Type Safety - TypeScript types for all business entities and workflows

Single Source of Truth - No drift between docs, code, and UI

Multi-Target - Same definition renders everywhere

AI-Native - Agents understand and operate on your business

Composable - Build complex businesses from reusable components

Business-as-Code turns business operations into a codebase you can version, test, deploy, and scale.