Decision Matrix
Status
- document type: decision guide
- use code and
/platform/current-architectureto verify whether an entity already exists - rows marked
futuredescribe target architecture, not current runtime implementation
onelink?”
Default Decision Order
Use this order every time:- check whether an existing native entity already fits
- check whether notes, labels, custom attributes, settings, or Captain configuration are enough
- check whether a domain service, policy, workflow, or UI extension is enough
- add a new shared entity only if the lifecycle is stable across domains
- add a new domain-only entity only if the shared model is no longer semantically correct
Decision Table
| Requirement | Use first | Layer | Avoid |
|---|---|---|---|
| Need a workspace / tenant boundary | Account | Shared platform | Creating a second internal workspace model |
| Need a person record | Contact | Shared platform / shared CRM primitive | Creating separate patient/buyer/person core models too early |
| Need an organization or client company | Company | Shared platform / shared CRM primitive | Creating separate clinic/developer/customer company models too early |
| Need communication with a customer | Conversation + Inbox | Shared platform | Creating domain-specific messaging threads |
| Need internal notes about a person | Note | Shared platform | Creating a second note/comment system first |
| Need lightweight classification or segmentation | Label | Shared platform | Using labels as the only canonical workflow state |
| Need flexible additional fields on contacts | CustomAttributeDefinition + custom_attributes on Contact | Shared variability layer | Adding many nullable columns immediately |
| Need flexible additional fields on conversations | CustomAttributeDefinition + custom_attributes on Conversation | Shared variability layer | Encoding all variance in labels |
| Need assignment or grouped ownership | Team and existing assignee/inbox model | Shared platform | Inventing a new ownership model too early |
| Need reusable operator shortcuts | Macro | Shared platform | Rebuilding the same flow in a separate custom module |
| Need event-driven automation | AutomationRule | Shared platform | Hand-coding tenant-specific callbacks everywhere |
| Need a connected external app | Integrations::App + Integrations::Hook | Shared integration layer | Building a domain-only integration framework first |
| Need an AI-callable external action | Captain::CustomTool | Shared AI action layer | Treating every AI tool as a full integration lifecycle |
| Need domain-aware AI knowledge | Captain::Assistant + Captain::Document + scenarios/tools | Shared AI layer with domain config | Building separate AI systems per domain |
| Need shared pipeline-oriented sales/work entity | future Deal | Future shared CRM | Creating separate deal/project/case clones immediately |
| Need actionable follow-up work | future Task | Future shared CRM | Folding tasks into a generic overloaded record |
Domain Decision Rules
Generic
Prefer:- shared primitives with broad tenant configuration
- custom attributes
- labels
- Captain docs/tools for general business use
Healthcare
Prefer:Accountas workspaceCompanyfor clinic/insurer/employer/partnerContactfor patient or person-level actor- custom attributes for healthcare fields
- labels and notes for intake and operational state
- Captain documents/scenarios/tools for medical guidance and workflows
- creating
Patientas a separate core entity beforeContactis exhausted - creating
Clinicas a separate core organization beforeCompanyis exhausted
Construction
Prefer:Accountas workspaceCompanyfor developer/contractor/supplier/client orgContactfor buyer/manager/stakeholder- custom attributes for construction fields
- labels and notes for qualification and project coordination
- Captain documents/scenarios/tools for estimate/project support
- creating
BuyerContactorProjectContactas separate core entities too early - creating parallel organization models before
Companyis exhausted
When To Add A New Shared Entity
Add a new shared platform entity only when all of the following are true:- the lifecycle is stable
- the concept is needed in 2 or more domain profiles
- it has meaningful relationships, ownership, reporting, or permissions
- labels/custom attributes/notes are no longer sufficient
DealTask- later
Activity
When To Add A Domain-Only Entity
Add a domain-only entity only when all of the following are true:- the semantics are truly domain-specific
- the lifecycle is not correctly represented by current shared entities
- the domain behavior would otherwise distort the shared platform model
- healthcare appointment or treatment plan
- construction estimate or project object
Hard Stops
Do not do these by default:- do not add a second workspace model
- do not add a second person model before exhausting
Contact - do not add a second organization model before exhausting
Company - do not store critical workflow state only in labels
- do not force custom attributes to replace core relationships
- do not build a separate integration architecture for each domain
- do not build a separate AI architecture for each domain