mdxui

Nouns

Understanding the type system - things and entities in the business platform

Nouns

A Noun is a type - the things in the system. Every entity in the platform is a Noun with a corresponding Payload CMS collection.


The Noun Concept

Nouns represent the "what" in your business:

  • What products do you sell?
  • What services do you offer?
  • What customers do you serve?
  • What agents are working on tasks?

Each Noun is:

  1. Typed - Has a defined schema with validation
  2. Stored - Persisted in Payload CMS collections
  3. Queryable - Accessible via API, RPC, and MCP
  4. Relational - Can reference other Nouns
  5. Versioned - Changes tracked in git

Core Business Nouns

Organizations

NounPurposeExample
BusinessA company or business unitAcme Corp, Acme Labs
TeamGroup of people working togetherEngineering, Sales
OrgMulti-tenant organizationEnterprise parent org

Offerings

NounPurposeExample
ProductPhysical or digital productSaaS app, API, SDK
ServiceProfessional serviceConsulting, Support
OfferBundled offeringStarter Plan, Enterprise Package
PricePricing structure$99/month, $0.001/request
FeatureProduct capabilityAPI access, SSO, Analytics

Market Intelligence

NounPurposeExample
IndustryMarket verticalSaaS, E-commerce
ProductCategoryProduct classificationCRM, Analytics Platform
CompetitorCompetitive businessSalesforce, HubSpot
PositioningMarket positionEnterprise CRM for SMBs
BrandBrand identityLogo, colors, voice

People & Actors

Human Entities

NounPurposeExample
HumanPerson who performs tasksEmployee, contractor
FounderBusiness founderCEO, Co-founder
CustomerPaying customerEnterprise client
ContactPerson in your networkLead, prospect
CardholderPayment card holderAuthorized spender

Automated Actors

NounPurposeExample
AgentAI agent that performs tasksResearch agent, QA agent
WorkerAbstract task performerAgent or Human
ServiceAccountCode executorAPI service account
ModelLLM for generative tasksGPT-4, Claude

Work & Execution

Planning

NounPurposeExample
ProjectLarge initiativeQ1 Product Launch
GoalBusiness objective$1M ARR, 100 customers
MetricMeasurable KPIMRR, churn rate
ProcessRepeatable workflowOnboarding, invoicing

Execution

NounPurposeExample
TaskUnit of workWrite docs, review PR
IssueProblem to solveBug report, feature request
WorkflowState machineApproval flow, order processing
FunctionExecutable logicValidate email, send notification
ActionFunction invocationExecute on state transition

Products & Code

Interfaces

NounPurposeExample
APIREST API/api/v1/products
RPCRemote procedure calltRPC endpoints
MCPModel Context ProtocolClaude tools
SDKLanguage-specific clientnpm package, Python SDK
CLICommand-line interfacestripe, gh

Artifacts

NounPurposeExample
AppApplicationDashboard, mobile app
PackageCode packagenpm, PyPI package
ComponentUI componentButton, Card, Dialog
ArtifactGenerated outputScreenshot, report
TemplateReusable patternEmail template, doc template

Content & Communication

Documents

NounPurposeExample
DocumentWritten documentContract, spec
DocDocumentation pageAPI docs, guide
PostBlog postAnnouncement, tutorial
PageWeb pageLanding page, about page
PresentationSlide deckPitch deck, training
SpreadsheetTabular dataBudget, forecast

Communication

NounPurposeExample
MessageSingle messageChat message, email
DiscussionThreaded conversationIssue discussion, forum
SequenceMessage automationOnboarding drip campaign
SequenceStepStep in sequenceEmail 1, Email 2
EnrollmentUser in sequenceActive, paused, completed

Sales & Marketing

Pipeline

NounPurposeExample
LeadPotential customerInbound signup, referral
DealSales opportunity$50K enterprise deal
QuotePrice quoteProposal pricing
ProposalSales proposalSOW, MSA
ChannelDistribution channelDirect, partner, marketplace

Customer Journey

NounPurposeExample
CustomerSegmentCustomer cohortSMB, Enterprise, Startup
SubscriptionRecurring revenueMonthly plan, annual plan
ExperimentA/B testPricing page variant
HypothesisTestable assumptionLower price increases conversions

Finance & Operations

Financial Records

NounPurposeExample
InvoiceBill for paymentMonthly invoice, one-time charge
PaymentMoney receivedStripe payment, wire transfer
RefundMoney returnedCancellation refund
TransferMoney movedPayout, top-up
FinancialAccountBank accountChecking, savings
CardPayment cardVirtual card, physical card

Accounting

NounPurposeExample
ChartOfAccountAccount structureAssets, liabilities
JournalEntryAccounting transactionDebit/credit entry
PeriodAccounting periodQ1 2024, Jan 2024
AccountLedger accountCash, revenue
AuthorizationPayment authorizationPending charge

System & Infrastructure

Platform

NounPurposeExample
SiteWebsiteMarketing site, docs site
BlogBlog collectionCompany blog
DirectoryListing directoryAgent directory
MarketplaceMulti-vendor platformPlugin marketplace
ListingDirectory entryAgent listing, tool listing

Integration

NounPurposeExample
WebhookEvent callbackStripe webhook, GitHub webhook
TriggerEvent listenerOn payment, on signup
ProviderExternal serviceStripe, OpenAI, GitHub
ToolMCP toolSearch tool, calculator
EventSystem eventPaymentSucceeded, TaskCompleted

Contact Info

NounPurposeExample
EmailAddressEmail contactsupport@acme.com
PhoneNumberPhone contact+1-555-0100
DomainInternet domainacme.com, api.acme.com

Meta Nouns

Ontology

NounPurposeExample
NounType definitionBusiness, Product, Agent
VerbAction grammarcreate, approve, complete
ThingGeneric entityAny schema.org Thing
ActionGeneric actionAny schema.org Action

Market Data

NounPurposeExample
OccupationJob typeSoftware Engineer, Designer
JobTitleSpecific titleSenior Engineer, VP Sales
SkillCompetencyReact, Python, Sales
ActivityTask typeCoding, reviewing, testing
OccupationTaskJob-specific taskWrite code, design UI
MarketProcessIndustry processSoftware development, accounting
MarketToolIndustry toolFigma, GitHub, Salesforce

Startup Lifecycle

NounPurposeExample
LabResearch labInnovation lab
IdeaBusiness ideaSaaS for dentists
ConceptDeveloped conceptMVP spec
ProblemCustomer problemManual data entry
StartupEarly-stage companyPre-seed startup

Schema & Validation

Every Noun has:

  1. TypeScript interface - Generated from Payload schema (/packages/db.sb/src/payload-types.ts)
  2. Zod schema - Runtime validation
  3. JSON-LD context - Schema.org compatibility
  4. GraphQL type - Query interface
  5. SQL table - PostgreSQL storage

Example TypeScript interface:

export interface Product {
  id: string
  name: string
  business?: string | Business
  type: 'API' | 'App' | 'CLI' | 'SDK' | 'MCP' | 'Agent' | 'Platform'
  stripeProductId?: string | null
  description?: string | null
  isActive?: boolean | null
  industries?: (string | Industry)[] | null
  productCategories?: (string | ProductCategory)[] | null
  features?: {
    docs?: (string | Feature)[]
    hasNextPage?: boolean
    totalDocs?: number
  }
}

Relationships

Nouns connect through typed relationships:

PatternExample
Has manyBusiness has many Products
Belongs toProduct belongs to Business
Many-to-manyProduct has many Industries, Industry has many Products
PolymorphicActor can be Agent, Human, or ServiceAccount
Self-referentialBusiness can have parent Business

Querying Nouns

REST API

GET /api/products?where[business][equals]=123
GET /api/products/abc123
POST /api/products
PATCH /api/products/abc123
DELETE /api/products/abc123

GraphQL

query {
  Products(where: { business: { equals: "123" } }) {
    docs {
      id
      name
      business {
        name
      }
    }
  }
}

MCP Tools

// Exposed as Claude tools
const tools = [
  { name: "list_products", schema: ProductQuerySchema },
  { name: "get_product", schema: ProductGetSchema },
  { name: "create_product", schema: ProductCreateSchema },
]

Next Steps

  • Read Verbs to understand actions on Nouns
  • See MDXLD for declarative Noun definitions
  • Explore Types for the type system

On this page