Design

Design your Business-as-Code and Services-as-Software with semantic patterns.

Overview

The Design phase is where you transform business ideas into executable specifications. Using the .do platform's semantic patterns and Business-as-Code paradigm, you'll model your business logic, data structures, and service interfaces before writing any implementation code.

This phase emphasizes:

• Semantic Clarity: Every entity, relationship, and operation is explicitly defined
• Business Alignment: Technical designs directly map to business concepts
• Composability: Designs are modular and can be combined in multiple ways
• Executability: Designs aren't just documentation—they're executable code

Core Design Areas

Business Modeling

Define your business entities, relationships, and operations using the Business Model Canvas and semantic patterns. Model customer segments, value propositions, revenue streams, and key resources as executable code.

Learn more about Business Modeling →

Service Architecture

Design your service interfaces, APIs, and integrations. Define clear boundaries, contracts, and communication patterns for Services-as-Software.

Learn more about Service Architecture →

Data Modeling

Structure your data using semantic types from vocabularies like Schema.org, NAICS, O*NET, and custom ontologies. Create rich, meaningful data models that carry business context.

Learn more about Data Modeling →

Workflow Design

Plan your business processes and automations. Define triggers, actions, conditions, and integrations that orchestrate your business operations.

Learn more about Workflow Design →

Semantic Patterns

Master the $.Subject.predicate.Object pattern that provides consistency and clarity across all business logic. Learn how to model any business concept using this universal pattern.

Learn more about Semantic Patterns →

Design Principles

1. Business-First Thinking

Start with business concepts, not technical implementations. Ask:

• What are we trying to achieve?
• What are the key business entities?
• How do they relate to each other?
• What operations does the business perform?

2. Semantic Precision

Use precise, unambiguous terms from established vocabularies. Prefer $.Organization.employs.Person over vague relationships like $.Company.has.User.

3. Composable Design

Create modular designs that can be:

• Reused across multiple contexts
• Combined in new ways
• Extended without breaking existing code
• Deployed independently

4. Type Safety

Leverage TypeScript and semantic types to catch errors at design time:

import { Organization, Person } from 'schema.org.ai'
import { NAICS } from 'naics.org.ai'

// Type-safe business definition
const business: Organization = {
  $type: 'Organization',
  name: 'Acme Inc',
  industry: NAICS.Software_Publishers_511210,
  employees: [] as Person[],
}

The Design Process

1. Discovery

• Interview stakeholders
• Map existing processes
• Identify pain points
• Define success metrics

2. Modeling

• Choose appropriate vocabularies
• Define core entities
• Map relationships
• Specify operations

3. Validation

• Review with stakeholders
• Test with real data
• Verify business logic
• Iterate based on feedback

4. Documentation

• Generate schema documentation
• Create usage examples
• Document design decisions
• Establish patterns

Design Tools

CLI Tools

# Generate business model from template
do generate business --template saas

# Validate semantic patterns
do validate design/business.mdx

# Generate TypeScript types from schema
do generate types --from schema.org.ai

Visual Tools

• Schema Explorer: Browse and visualize entity relationships
• Workflow Designer: Visual workflow creation and editing
• Data Modeler: Interactive data schema design
• Pattern Library: Reusable design patterns and templates

Design Patterns

Entity-Relationship Patterns

// One-to-many relationship
$.Organization.employs.Person
$.Product.belongsTo.Category

// Many-to-many relationship
$.Person.hasMembership.Organization
$.Product.hasTag.Tag

// Hierarchical relationship
$.Organization.hasSubOrganization.Organization
$.Category.hasParentCategory.Category

Event-Driven Patterns

// Event emission
on($.Order.created, async (order) => {
  await send($.Email.order_confirmation, order)
  await send($.Inventory.reserve, order.items)
})

// Event composition
on([$.User.registered, $.User.verified], async (user) => {
  await send($.Onboarding.start, user)
})

State Machine Patterns

// Order lifecycle
const OrderStateMachine = {
  initial: 'draft',
  states: {
    draft: { on: { submit: 'pending_payment' } },
    pending_payment: { on: { pay: 'processing', cancel: 'cancelled' } },
    processing: { on: { fulfill: 'completed', fail: 'failed' } },
    completed: { on: { return: 'returned' } },
    cancelled: {},
    failed: {},
    returned: {},
  },
}

Best Practices

Do's

• Use established vocabularies (Schema.org, NAICS, O*NET)
• Follow semantic patterns consistently
• Model the business domain accurately
• Keep designs simple and focused
• Document design decisions
• Test designs with real data

Don'ts

• Don't use vague or ambiguous terms
• Don't mix technical and business concerns
• Don't create complex hierarchies unnecessarily
• Don't skip stakeholder validation
• Don't ignore existing standards
• Don't over-engineer early

From Design to Implementation

Once your design is complete, you'll:

1. Build: Implement the design using the SDK
2. Deploy: Deploy to production infrastructure
3. Observe: Monitor the implementation
4. Launch: Release to users
5. Grow: Optimize and experiment
6. Scale: Handle increasing complexity

Getting Started

Ready to start designing? Begin with:

1. Business Modeling → - Learn to model your business
2. Semantic Patterns → - Master the core patterns
3. Examples → - See complete design examples

Design Tip: Great designs are simple, semantic, and directly map to business concepts. If your design is hard to explain, it's probably too complex.