Entity Reference

Full schemas and examples for every recommended bucket entity domain.

Users

users/

Every person in the org. This is the identity layer — all other entities reference users by ID.

// users/usr_xK9mR2.json
{
  "id": "usr_xK9mR2",
  "name": "Jeremy Davis",
  "email": "jeremy@acme.com",
  "role": "engineering_lead",
  "department": "engineering",
  "title": "VP Engineering",
  "avatar": "assets/uploads/avatars/usr_xK9mR2.png",
  "timezone": "America/New_York",
  "startDate": "2024-03-15",
  "status": "active",
  "reportsTo": "usr_abc123",
  "createdAt": "2024-03-15T10:00:00Z",
  "updatedAt": "2026-02-20T14:30:00Z"
}

Field	Type	Purpose
`id`	`string`	usr_ + nanoid
`name`	`string`	Display name
`email`	`email`	Primary email
`role`	`select`	Functional role in the org
`department`	`select`	Department or team
`title`	`string`	Job title
`status`	`select`	active, inactive, onboarding, offboarded
`reportsTo`	`relation`	User ID of manager

Service Registry

registry/services/

A dynamic catalog of external services the org depends on. Each entry can include an OpenAPI spec (or link to one) and default auth configuration for programmatic access.

// registry/services/svc_stripe.json
{
  "id": "svc_stripe",
  "name": "Stripe",
  "description": "Payment processing and billing",
  "category": "payments",
  "status": "active",
  "provider": "stripe.com",
  "apiBaseUrl": "https://api.stripe.com/v1",
  "docsUrl": "https://stripe.com/docs/api",
  "openapiSpec": "registry/services/specs/stripe-openapi.yaml",
  "auth": {
    "type": "bearer",
    "envVar": "STRIPE_SECRET_KEY",
    "testEnvVar": "STRIPE_TEST_KEY"
  },
  "usedBy": ["finance", "engineering"],
  "monthlySpend": 299,
  "contract": {
    "plan": "Scale",
    "renewalDate": "2027-01-15",
    "annualCost": 3588
  },
  "tags": ["critical", "payments", "billing"],
  "createdAt": "2025-01-10T10:00:00Z",
  "updatedAt": "2026-03-01T09:15:00Z"
}

Field	Type	Purpose
`id`	`string`	svc_ + slug or nanoid
`name`	`string`	Service display name
`category`	`select`	payments, analytics, communication, storage, ci_cd, monitoring, auth, crm
`status`	`select`	active, evaluating, deprecated, inactive
`openapiSpec`	`string`	Path to OpenAPI spec file in bucket, or external URL
`auth`	`object`	Auth config: type + env var names (never actual secrets)
`usedBy`	`multi_select`	Departments that use this service
`monthlySpend`	`number`	Monthly cost

Important: Auth credentials reference environment variable names, not actual secrets. Secrets live in your secrets manager (Vault, AWS Secrets Manager, etc.), not in the bucket.

OpenAPI specs can be stored alongside service entities:

registry/
└── services/
    ├── svc_stripe.json
    ├── svc_slack.json
    ├── svc_github.json
    └── specs/
        ├── stripe-openapi.yaml
        ├── slack-openapi.yaml
        └── github-openapi.yaml

CRM

crm/

Customer Relationship Management. Three core sub-entities: contacts (people), companies (organizations), and deals (revenue opportunities with pipeline tracking).

Contacts

crm/contacts/

Individual people the org has relationships with — prospects, customers, partners, vendors.

// crm/contacts/cont_xK9mR2.json
{
  "id": "cont_xK9mR2",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@bigco.com",
  "phone": "+1-555-0142",
  "title": "VP Operations",
  "companyId": "comp_abc123",
  "source": "inbound_demo",
  "ownerId": "usr_xK9mR2",
  "tags": ["decision-maker", "q1-target"],
  "lastContactedAt": "2026-02-28T16:00:00Z",
  "notes": "Interested in enterprise plan.",
  "status": "active",
  "createdAt": "2025-11-20T10:00:00Z",
  "updatedAt": "2026-02-28T16:00:00Z"
}

Field	Type	Purpose
`companyId`	`relation`	Links to crm/companies/
`source`	`select`	inbound_demo, outbound_cold, referral, event, website, partner
`ownerId`	`relation`	Links to users/ — who owns this relationship
`status`	`select`	active, inactive, do_not_contact

Companies

crm/companies/

Organizations the business sells to, partners with, or buys from.

// crm/companies/comp_abc123.json
{
  "id": "comp_abc123",
  "name": "BigCo Industries",
  "domain": "bigco.com",
  "industry": "manufacturing",
  "size": "500-1000",
  "annualRevenue": 50000000,
  "address": {
    "street": "100 Industrial Blvd",
    "city": "Chicago",
    "state": "IL",
    "country": "US",
    "zip": "60601"
  },
  "website": "https://bigco.com",
  "ownerId": "usr_xK9mR2",
  "tier": "enterprise",
  "status": "customer",
  "tags": ["manufacturing", "midwest"],
  "createdAt": "2025-06-01T10:00:00Z",
  "updatedAt": "2026-02-15T11:20:00Z"
}

Field	Type	Purpose
`industry`	`select`	Vertical classification
`size`	`select`	1-10, 11-50, 51-200, 201-500, 500-1000, 1000+
`tier`	`select`	startup, smb, mid_market, enterprise
`status`	`select`	prospect, customer, churned, partner, vendor

Deals

crm/deals/

Revenue opportunities tracked through a pipeline. This is where the business tracks what it expects to close, when, and for how much.

// crm/deals/deal_xyz789.json
{
  "id": "deal_xyz789",
  "title": "BigCo Enterprise License",
  "companyId": "comp_abc123",
  "contactIds": ["cont_xK9mR2"],
  "ownerId": "usr_xK9mR2",
  "stage": "offered",
  "expectedValue": 120000,
  "currency": "USD",
  "probability": 60,
  "expectedCloseDate": "2026-04-15",
  "actualCloseDate": null,
  "lostReason": null,
  "pipeline": "sales",
  "source": "inbound_demo",
  "products": ["prod_enterprise_annual"],
  "notes": "Sent proposal 2/25. Waiting on legal review.",
  "activities": [
    { "date": "2026-02-25", "type": "proposal_sent", "note": "Enterprise annual proposal" },
    { "date": "2026-02-20", "type": "demo", "note": "Product demo with VP Ops + CTO" },
    { "date": "2026-02-10", "type": "discovery", "note": "Initial discovery call" }
  ],
  "createdAt": "2026-02-10T14:00:00Z",
  "updatedAt": "2026-02-25T10:30:00Z"
}

Field	Type	Purpose
`stage`	`select`	Pipeline stage (see below)
`expectedValue`	`number`	Projected revenue if closed
`probability`	`number`	Win likelihood (0-100%)
`expectedCloseDate`	`date`	Target close date
`pipeline`	`select`	sales, partnerships, renewals, upsells
`lostReason`	`select`	If closed-lost: budget, competitor, timing, no_need, no_response

Deal Pipeline Stages

Stage	Description	Probability
`lead`	Initial interest, not yet qualified	10%
`qualified`	Confirmed budget, authority, need, timeline	30%
`offered`	Proposal/quote sent, in negotiation	60%
`closed_won`	Deal signed, revenue recognized	100%
`closed_lost`	Deal lost, record reason	0%

A board view grouped by stage gives you the classic sales pipeline Kanban. A table view sorted by expectedValue shows the weighted forecast.

Product Development

issues/

Issue tracking for daily progress reporting. Every individual contributor logs work done toward the roadmap as issues. Issues represent discrete units of work — bugs, features, tasks, improvements.

// issues/iss_q7wP3x.json
{
  "id": "iss_q7wP3x",
  "title": "Add export to CSV from data table views",
  "description": "Users need to export filtered data table results as CSV.",
  "type": "feature",
  "status": "in_progress",
  "priority": "high",
  "assigneeId": "usr_xK9mR2",
  "reporterId": "usr_abc123",
  "projectId": "proj_roadmap_q1",
  "labels": ["data-tables", "export"],
  "milestone": "v1.2",
  "estimate": 5,
  "timeSpent": 3,
  "dueDate": "2026-03-10",
  "parentIssueId": null,
  "blockedBy": [],
  "blocks": ["iss_r8xQ4y"],
  "dailyLog": [
    {
      "date": "2026-03-03",
      "userId": "usr_xK9mR2",
      "hours": 3,
      "note": "Built CSV serializer, started wiring to table toolbar"
    },
    {
      "date": "2026-03-02",
      "userId": "usr_xK9mR2",
      "hours": 2,
      "note": "Researched CSV libs, chose papaparse"
    }
  ],
  "createdAt": "2026-03-01T09:00:00Z",
  "updatedAt": "2026-03-03T17:00:00Z"
}

Field	Type	Purpose
`type`	`select`	feature, bug, task, improvement, epic
`status`	`select`	backlog, todo, in_progress, in_review, done, cancelled
`priority`	`select`	critical, high, medium, low
`assigneeId`	`relation`	Who is doing the work (users/)
`projectId`	`relation`	Which project/roadmap initiative
`estimate`	`number`	Story points or hours
`dailyLog`	`array`	IC progress entries for standup/reporting
`blockedBy`	`relation[]`	Issues that block this one

Board view grouped by status = Kanban for sprint work.

Table view filtered by assigneeId = "my work" for daily standups.

Table view grouped by milestone = roadmap progress.

Marketing & Advertising

marketing/

Marketing tracks campaigns and channels that drive customer acquisition, and conversions that measure the result. The goal: invest in activities that produce customer conversions, sales, and repeat sales.

Campaigns

marketing/campaigns/

A campaign is a coordinated marketing effort — a product launch, a seasonal promotion, an ad flight, a content series.

// marketing/campaigns/camp_spring26.json
{
  "id": "camp_spring26",
  "name": "Spring 2026 Product Launch",
  "type": "product_launch",
  "status": "active",
  "ownerId": "usr_mkt_lead",
  "startDate": "2026-03-01",
  "endDate": "2026-04-30",
  "budget": 25000,
  "spent": 8500,
  "channels": ["google_ads", "linkedin", "email", "content"],
  "targetAudience": "B2B SaaS founders, 10-100 employees",
  "goals": {
    "impressions": 500000,
    "clicks": 15000,
    "leads": 500,
    "conversions": 50,
    "revenue": 150000
  },
  "actuals": {
    "impressions": 180000,
    "clicks": 5200,
    "leads": 175,
    "conversions": 12,
    "revenue": 36000
  },
  "tags": ["launch", "q1"],
  "createdAt": "2026-02-15T10:00:00Z",
  "updatedAt": "2026-03-04T08:00:00Z"
}

Field	Type	Purpose
`type`	`select`	product_launch, seasonal, evergreen, event, referral, partnership
`status`	`select`	draft, active, paused, completed, cancelled
`budget`	`number`	Allocated spend
`spent`	`number`	Actual spend to date
`goals / actuals`	`object`	Target vs actual KPIs (impressions, clicks, leads, conversions, revenue)

Channels

marketing/channels/

Where campaigns run. Each channel has its own performance characteristics and cost model.

// marketing/channels/ch_google_ads.json
{
  "id": "ch_google_ads",
  "name": "Google Ads",
  "type": "paid_search",
  "status": "active",
  "monthlyBudget": 10000,
  "costModel": "cpc",
  "avgCPC": 2.50,
  "avgConversionRate": 3.2,
  "avgCAC": 78,
  "serviceId": "svc_google_ads",
  "accountId": "ads-123-456-789",
  "tags": ["paid", "search"],
  "createdAt": "2025-06-01T10:00:00Z",
  "updatedAt": "2026-03-01T09:00:00Z"
}

Conversions

marketing/conversions/

A conversion records when a marketing-sourced lead becomes a paying customer, makes a purchase, or takes a high-value action. This closes the loop from campaign spend to revenue.

// marketing/conversions/conv_xK9mR2.json
{
  "id": "conv_xK9mR2",
  "type": "new_customer",
  "contactId": "cont_xK9mR2",
  "companyId": "comp_abc123",
  "dealId": "deal_xyz789",
  "campaignId": "camp_spring26",
  "channelId": "ch_google_ads",
  "revenue": 120000,
  "isRepeatPurchase": false,
  "attributionModel": "last_touch",
  "touchpoints": [
    { "date": "2026-02-05", "channel": "google_ads", "action": "ad_click" },
    { "date": "2026-02-10", "channel": "website", "action": "demo_request" },
    { "date": "2026-02-20", "channel": "email", "action": "proposal_opened" }
  ],
  "convertedAt": "2026-03-01T14:00:00Z",
  "createdAt": "2026-03-01T14:00:00Z"
}

Field	Type	Purpose
`type`	`select`	new_customer, upsell, repeat_purchase, subscription_renewal, referral
`revenue`	`number`	Revenue attributed to this conversion
`isRepeatPurchase`	`checkbox`	Returning customer?
`campaignId`	`relation`	Which campaign drove this
`channelId`	`relation`	Which channel
`dealId`	`relation`	Links to crm/deals/
`attributionModel`	`select`	first_touch, last_touch, linear, weighted

Table view of conversions with campaign grouping = ROI by campaign.

Board view grouped by type = conversion types at a glance.

Customer Service

support/tickets/

Customer service issue tracking, separate from product development issues. Tickets track customer-reported problems, questions, and requests through resolution.

// support/tickets/tkt_r8xQ4y.json
{
  "id": "tkt_r8xQ4y",
  "subject": "Cannot export data from dashboard",
  "description": "When I click Export, nothing happens. Chrome 120, macOS.",
  "contactId": "cont_xK9mR2",
  "companyId": "comp_abc123",
  "status": "in_progress",
  "priority": "high",
  "category": "bug_report",
  "assigneeId": "usr_support_1",
  "channel": "email",
  "relatedIssueId": "iss_q7wP3x",
  "firstResponseAt": "2026-03-03T10:15:00Z",
  "resolvedAt": null,
  "satisfaction": null,
  "slaBreached": false,
  "tags": ["export", "dashboard"],
  "messages": [
    {
      "from": "contact",
      "at": "2026-03-03T09:00:00Z",
      "body": "Export button not working..."
    },
    {
      "from": "agent",
      "at": "2026-03-03T10:15:00Z",
      "body": "Thanks for reporting. We've identified the issue..."
    }
  ],
  "createdAt": "2026-03-03T09:00:00Z",
  "updatedAt": "2026-03-03T10:15:00Z"
}

Field	Type	Purpose
`status`	`select`	new, awaiting_response, in_progress, waiting_on_customer, resolved, closed
`priority`	`select`	urgent, high, medium, low
`category`	`select`	bug_report, feature_request, how_to, billing, account, other
`channel`	`select`	email, chat, phone, social, in_app
`relatedIssueId`	`relation`	Links to issues/ if it spawned a dev issue
`satisfaction`	`select`	great, okay, bad (post-resolution survey)
`slaBreached`	`checkbox`	Did response time exceed SLA?

Board view grouped by status = support queue Kanban.

Table view filtered by slaBreached: true = SLA violations requiring attention.

Table view grouped by category = issue type distribution.