Skip to content

Domain Model and Aggregates

This document defines the key aggregate roots, entities, and value objects for the Personal Agents Platform domain. It is written for architects and engineers implementing the domain model.

The domain model follows Domain-Driven Design principles, with aggregates encapsulating invariants and business rules. This document provides a concrete model that can be implemented using ConnectSoft's microservice template.

Important

Critical Business Rules: 1. A User must have exactly one PersonalTenant 1. An AgentInstance must be associated with a User and an AgentTemplate 1. An AgentPack must contain at least one AgentInstance 1. An AgentRun must be associated with a User and either an AgentInstance or AgentPack 1. A Suggestion must be associated with an AgentRun 1. All external actions must start as Suggestions (no auto-execution) 1. Personal tenant isolation is enforced at the aggregate level 1. All domain operations must maintain data consistency within aggregates

Modeling Principles

DDD Alignment

  • Aggregates Encapsulate Invariants - Business rules enforced within aggregates
  • Use IDs - Use GUIDs/UUIDs rather than natural keys for aggregates
  • Value Objects - Use value objects for concepts without identity (Money, TimePeriod, AgentRunStatus)
  • Domain Events - Important state changes emit domain events
  • Bounded Contexts - Each context has its own domain model

See: Clean Architecture & DDD for architecture principles.

Aggregate Design

  • One Aggregate Root - Each aggregate has one root entity
  • Consistency Boundary - Invariants enforced within aggregate
  • Event Sourcing - Consider event sourcing for audit-heavy aggregates (AgentRun, Suggestion)
  • Optimistic Concurrency - Use version numbers for concurrency control

Key Aggregates by Context

Personal Identity & Profile Context

Aggregate Root Entity Description
User User Individual user account with personal tenant
PersonalTenant PersonalTenant Personal tenant for user isolation
UserProfile UserProfile User profile (timezone, language, preferences)
Subscription Subscription User subscription (Free, Pro, Family, Creator)

User Aggregate:

  • UserId (Guid) - Aggregate root ID
  • Email (string) - User email (unique)
  • PersonalTenantId (Guid) - Reference to PersonalTenant (1:1 relationship)
  • Status (UserStatus) - Active, Suspended, Deleted
  • CreatedAt (DateTime) - Creation timestamp
  • LastLoginAt (DateTime?) - Last login timestamp

PersonalTenant Aggregate:

  • PersonalTenantId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User (1:1 relationship)
  • SubscriptionId (Guid) - Reference to Subscription
  • Status (TenantStatus) - Active, Suspended, Cancelled
  • CreatedAt (DateTime) - Creation timestamp

UserProfile Aggregate:

  • UserProfileId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • Timezone (string) - User timezone (e.g., "America/New_York")
  • Language (string) - Preferred language (e.g., "en-US")
  • NotificationPreferences (NotificationPreferences) - Email, SMS, in-app preferences
  • PrivacySettings (PrivacySettings) - Privacy and data control settings

Subscription Aggregate:

  • SubscriptionId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • Tier (SubscriptionTier) - Free, PersonalPro, Family, Creator
  • Status (SubscriptionStatus) - Active, Cancelled, Expired
  • StartDate (DateTime) - Subscription start date
  • EndDate (DateTime?) - Subscription end date (null for active)
  • BillingCycle (BillingCycle) - Monthly, Annual

Agent Catalog Context

Aggregate Root Entity Description
AgentTemplate AgentTemplate Base agent definition (Inbox Agent, Planner Agent, etc.)
AgentInstance AgentInstance User-specific agent configuration
AgentArchetype AgentArchetype Agent archetype definitions

AgentTemplate Aggregate:

  • AgentTemplateId (Guid) - Aggregate root ID
  • Name (string) - Template name (e.g., "Inbox Agent")
  • Archetype (AgentArchetype) - Inbox, Planner, Finance, Learning, Family, Generic
  • Description (string) - Template description
  • DefaultConfig (AgentConfig) - Default configuration
  • RequiredTools (List) - Required tools (email, calendar, etc.)
  • IsBuiltIn (bool) - Whether template is built-in or user-created
  • CreatedAt (DateTime) - Creation timestamp

AgentInstance Aggregate:

  • AgentInstanceId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • AgentTemplateId (Guid) - Reference to AgentTemplate
  • Name (string) - Instance name (user-defined)
  • Config (AgentConfig) - User-specific configuration
  • Status (AgentInstanceStatus) - Active, Paused, Error
  • CreatedAt (DateTime) - Creation timestamp
  • LastRunAt (DateTime?) - Last execution timestamp

AgentArchetype Value Object:

  • ArchetypeId (string) - Archetype identifier
  • Name (string) - Archetype name
  • Description (string) - Archetype description
  • DefaultTools (List) - Default tools for archetype

Pack & Workflow Context

Aggregate Root Entity Description
AgentPack AgentPack Team of agents working together
AgentWorkflow AgentWorkflow Workflow definition (triggers, steps, parallel)
WorkflowTrigger WorkflowTrigger Trigger definition (schedule, manual, event)

AgentPack Aggregate:

  • AgentPackId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User (pack owner)
  • Name (string) - Pack name (e.g., "Life Admin Pack")
  • Description (string) - Pack description
  • AgentInstances (List) - References to AgentInstances in pack
  • IsShared (bool) - Whether pack is shared (for Family tier)
  • IsPublic (bool) - Whether pack is public (for marketplace)
  • Status (PackStatus) - Active, Paused, Archived
  • CreatedAt (DateTime) - Creation timestamp

AgentWorkflow Aggregate:

  • AgentWorkflowId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • AgentPackId (Guid?) - Optional reference to AgentPack
  • Name (string) - Workflow name
  • Type (WorkflowType) - Sequential, Parallel, Hybrid
  • Steps (List) - Workflow steps (agent instances, conditions, aggregators)
  • Status (WorkflowStatus) - Active, Paused, Error
  • CreatedAt (DateTime) - Creation timestamp

WorkflowTrigger Aggregate:

  • WorkflowTriggerId (Guid) - Aggregate root ID
  • AgentWorkflowId (Guid) - Reference to AgentWorkflow
  • Type (TriggerType) - Schedule, Manual, Event
  • Schedule (Schedule?) - Cron expression or schedule definition (if schedule type)
  • EventFilter (EventFilter?) - Event filter definition (if event type)
  • Status (TriggerStatus) - Active, Paused
  • CreatedAt (DateTime) - Creation timestamp

Agent Orchestration Context

Aggregate Root Entity Description
AgentRun AgentRun One execution of an agent or pack
AgentRunStep AgentRunStep Step logs, inputs, outputs for agent runs
WorkflowExecution WorkflowExecution Multi-agent workflow execution state

AgentRun Aggregate:

  • AgentRunId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • AgentInstanceId (Guid?) - Reference to AgentInstance (if single agent run)
  • AgentPackId (Guid?) - Reference to AgentPack (if pack run)
  • AgentWorkflowId (Guid?) - Reference to AgentWorkflow (if workflow run)
  • TriggerType (RunTriggerType) - Manual, Scheduled, Event
  • Status (RunStatus) - Pending, Running, Completed, Failed, Cancelled
  • StartedAt (DateTime?) - Execution start timestamp
  • CompletedAt (DateTime?) - Execution completion timestamp
  • TokensUsed (int) - Total tokens used
  • Cost (Money) - Execution cost
  • Results (RunResults) - Execution results and outputs

AgentRunStep Aggregate:

  • AgentRunStepId (Guid) - Aggregate root ID
  • AgentRunId (Guid) - Reference to AgentRun
  • StepNumber (int) - Step number in workflow
  • AgentInstanceId (Guid) - Reference to AgentInstance
  • Status (StepStatus) - Pending, Running, Completed, Failed
  • Inputs (Dictionary) - Step inputs
  • Outputs (Dictionary) - Step outputs
  • TokensUsed (int) - Tokens used for this step
  • StartedAt (DateTime?) - Step start timestamp
  • CompletedAt (DateTime?) - Step completion timestamp

WorkflowExecution Aggregate:

  • WorkflowExecutionId (Guid) - Aggregate root ID
  • AgentWorkflowId (Guid) - Reference to AgentWorkflow
  • AgentRunId (Guid) - Reference to parent AgentRun
  • Status (ExecutionStatus) - Running, Completed, Failed
  • CurrentStep (int) - Current step number
  • StepResults (List) - Results from each step
  • FinalResult (object?) - Aggregated final result

Suggestion & Approval Context

Aggregate Root Entity Description
Suggestion Suggestion Action proposed by agent
Approval Approval User decision to apply or ignore suggestion
SuggestionInbox SuggestionInbox User inbox for suggestions

Suggestion Aggregate:

  • SuggestionId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • AgentRunId (Guid) - Reference to AgentRun that generated suggestion
  • Type (SuggestionType) - Email, Calendar, Task, ShoppingList, File, Other
  • Action (SuggestionAction) - Action details (draft email, calendar event, etc.)
  • Status (SuggestionStatus) - Pending, Approved, Rejected, Expired
  • Priority (Priority) - Low, Medium, High
  • CreatedAt (DateTime) - Creation timestamp
  • ExpiresAt (DateTime?) - Expiration timestamp (optional)

Approval Aggregate:

  • ApprovalId (Guid) - Aggregate root ID
  • SuggestionId (Guid) - Reference to Suggestion
  • UserId (Guid) - Reference to User
  • Decision (ApprovalDecision) - Approve, Reject, Edit
  • EditedAction (SuggestionAction?) - Edited action (if decision is Edit)
  • DecisionAt (DateTime) - Decision timestamp
  • ExecutedAt (DateTime?) - Execution timestamp (if approved)

SuggestionInbox Aggregate:

  • SuggestionInboxId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • Suggestions (List) - References to pending suggestions
  • UnreadCount (int) - Count of unread suggestions
  • LastUpdatedAt (DateTime) - Last update timestamp

Connector Context

Aggregate Root Entity Description
ConnectorConfig ConnectorConfig Authorized app/link configuration
DataSnapshot DataSnapshot Cached metadata from external services
ConnectorExecution ConnectorExecution Connector execution log

ConnectorConfig Aggregate:

  • ConnectorConfigId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • ConnectorType (ConnectorType) - Email, Calendar, FileUpload, Notion, GoogleDrive, OneDrive
  • Authorization (Authorization) - OAuth tokens, API keys, etc.
  • Status (ConnectorStatus) - Active, Expired, Revoked
  • Permissions (List) - Granted permissions (read, write, etc.)
  • CreatedAt (DateTime) - Creation timestamp
  • LastUsedAt (DateTime?) - Last usage timestamp

DataSnapshot Aggregate:

  • DataSnapshotId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • ConnectorConfigId (Guid) - Reference to ConnectorConfig
  • DataType (DataType) - Email, CalendarEvent, File, Document
  • Metadata (Dictionary) - Cached metadata
  • SnapshotAt (DateTime) - Snapshot timestamp
  • ExpiresAt (DateTime) - Expiration timestamp

ConnectorExecution Aggregate:

  • ConnectorExecutionId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • ConnectorConfigId (Guid) - Reference to ConnectorConfig
  • Operation (ConnectorOperation) - Read, Write, List, etc.
  • Status (ExecutionStatus) - Success, Failed, Partial
  • ExecutedAt (DateTime) - Execution timestamp
  • Result (ExecutionResult) - Execution result

Dashboard & Analytics Context

Aggregate Root Entity Description
Dashboard Dashboard Dashboard definition and configuration
UsageAnalytics UsageAnalytics Usage metrics and analytics
RunHistory RunHistory Agent run history and summaries

Dashboard Aggregate:

  • DashboardId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • Name (string) - Dashboard name
  • Widgets (List) - Dashboard widgets (packs, agents, runs, suggestions, usage)
  • Layout (Layout) - Dashboard layout configuration
  • CreatedAt (DateTime) - Creation timestamp

UsageAnalytics Aggregate:

  • UsageAnalyticsId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • Period (TimePeriod) - Analytics period (day, week, month)
  • RunsCount (int) - Number of agent runs
  • TokensUsed (int) - Total tokens used
  • Cost (Money) - Total cost
  • SuggestionsCount (int) - Number of suggestions generated
  • ApprovalsCount (int) - Number of approvals
  • CalculatedAt (DateTime) - Calculation timestamp

RunHistory Aggregate:

  • RunHistoryId (Guid) - Aggregate root ID
  • UserId (Guid) - Reference to User
  • AgentRunId (Guid) - Reference to AgentRun
  • Summary (string) - Run summary
  • Status (RunStatus) - Run status
  • TokensUsed (int) - Tokens used
  • Cost (Money) - Cost
  • CompletedAt (DateTime) - Completion timestamp

Value Objects

Money

  • Amount (decimal) - Monetary amount
  • Currency (string) - Currency code (USD, EUR, etc.)

TimePeriod

  • StartDate (DateTime) - Period start
  • EndDate (DateTime) - Period end

AgentConfig

  • BehaviorRules (Dictionary) - Agent behavior rules
  • ToolConfigs (Dictionary) - Tool configurations
  • PromptTemplates (Dictionary) - Prompt templates

NotificationPreferences

  • EmailEnabled (bool) - Email notifications enabled
  • SMSEnabled (bool) - SMS notifications enabled
  • InAppEnabled (bool) - In-app notifications enabled
  • Frequency (NotificationFrequency) - Notification frequency

PrivacySettings

  • DataRetentionDays (int) - Data retention period
  • AutoDeleteEnabled (bool) - Auto-delete enabled
  • ExportEnabled (bool) - Data export enabled

Aggregate Relationships

erDiagram
    User ||--|| PersonalTenant : has
    User ||--|| UserProfile : has
    User ||--|| Subscription : has
    User ||--o{ AgentInstance : owns
    User ||--o{ AgentPack : owns
    User ||--o{ AgentWorkflow : owns
    User ||--o{ AgentRun : executes
    User ||--o{ Suggestion : receives
    User ||--o{ ConnectorConfig : configures

    AgentTemplate ||--o{ AgentInstance : instantiates
    AgentInstance ||--o{ AgentPack : "part of"
    AgentPack ||--o{ AgentWorkflow : "has workflow"
    AgentWorkflow ||--|| WorkflowTrigger : "has trigger"

    AgentInstance ||--o{ AgentRun : executes
    AgentPack ||--o{ AgentRun : executes
    AgentWorkflow ||--o{ AgentRun : executes
    AgentRun ||--o{ AgentRunStep : contains
    AgentRun ||--o{ Suggestion : generates
    AgentRun ||--|| WorkflowExecution : "has execution"

    Suggestion ||--o| Approval : "has decision"
    ConnectorConfig ||--o{ DataSnapshot : "has snapshots"
    ConnectorConfig ||--o{ ConnectorExecution : "has executions"
Hold "Alt" / "Option" to enable pan & zoom