Skip to content

Bounded Contexts and Context Map

This document defines the bounded contexts and their relationships for the Personal Agents Platform domain. It is written for architects and engineers designing the domain boundaries and service architecture.

Bounded contexts define clear domain boundaries, ensuring each context has a single responsibility and well-defined integration points. This document maps the Personal Agents Platform domain into bounded contexts and shows how they interact.

Important

Each bounded context becomes a microservice generated by the Factory. Clear boundaries ensure maintainability, scalability, and independent evolution of services.

Bounded Contexts Overview

Context Name Responsibility Key Capabilities
Personal Identity & Profile Users, personal tenants, subscriptions User onboarding, profile management, subscription management, personal tenant isolation
Agent Catalog Agent templates and instances AgentTemplate management (base definitions), AgentInstance management (user-specific configurations), agent archetypes
Pack & Workflow Agent packs and workflows AgentPack management (teams of agents), AgentWorkflow definitions (triggers, sequences, parallel), WorkflowTrigger management
Agent Orchestration Agent execution and runs AgentRun execution and management, AgentRunStep logging, multi-agent workflow orchestration, AI Gateway integration
Suggestion & Approval Suggestions and approvals Suggestion management (actions proposed by agents), approval workflow, user inbox
Connector External service connectors ConnectorConfig management (authorized apps/links), connector execution (Email, Calendar, File upload, etc.), DataSnapshot management
Dashboard & Analytics Dashboards and analytics Dashboard generation, usage analytics, run history, cost tracking

Context Descriptions

Personal Identity & Profile

Purpose: Manages personal user accounts, personal tenant management, user profiles, and subscription management. Handles personal-tenant patterns distinct from organizational tenants.

Key Aggregates:

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

Integration Emphasis:

  • Provides user and tenant context to all other contexts
  • Integrates with Identity Platform for authentication
  • Integrates with Billing Platform for subscription management
  • Integrates with Config Platform for user preferences

Key Characteristics:

  • Personal-tenant model (one user = one personal tenant)
  • Subscription tied to personal tenant
  • Data isolation per user

Agent Catalog

Purpose: Manages agent templates (base definitions) and agent instances (user-specific configurations). Handles agent archetypes and configurations.

Key Aggregates:

  • AgentTemplate - Base agent definition (Inbox Agent, Planner Agent, Budget Agent, etc.)
  • AgentInstance - User-specific agent configuration
  • AgentArchetype - Agent archetype definitions (Inbox, Planner, Finance, Learning, Family, Generic)

Integration Emphasis:

  • Used by Pack & Workflow for pack composition
  • Used by Agent Orchestration for agent execution
  • Integrates with Config Platform for agent behavior configs

Key Characteristics:

  • AgentTemplate provides base definitions
  • AgentInstance is user-specific configuration
  • Supports custom agent creation (no-code builder in V2)

Pack & Workflow

Purpose: Manages agent packs (teams of agents) and workflows (triggers, sequences, parallel execution). Handles workflow definitions and triggers.

Key Aggregates:

  • AgentPack - Team of agents working together (Life Admin Pack, Budget Lite Pack, etc.)
  • AgentWorkflow - Workflow definition (triggers, steps, parallel paths, aggregator)
  • WorkflowTrigger - Trigger definition (schedule, manual, event)

Integration Emphasis:

  • Depends on Agent Catalog for agent definitions
  • Used by Agent Orchestration for workflow execution
  • Emits events for pack installation and workflow changes

Key Characteristics:

  • Packs group related agents
  • Workflows define execution patterns
  • Triggers determine when workflows run

Agent Orchestration

Purpose: Manages agent execution, agent runs, and multi-agent workflow orchestration. Integrates with AI Gateway for agent execution.

Key Aggregates:

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

Integration Emphasis:

  • Integrates with AI Gateway & Agent Runtime for agent execution
  • Integrates with Agent Catalog for agent definitions
  • Integrates with Pack & Workflow for workflow definitions
  • Emits events for run completion and results
  • Integrates with Audit Platform for run logging

Key Characteristics:

  • Handles both single-agent and multi-agent execution
  • Supports sequential and parallel workflows
  • Tracks token usage and costs per run

Suggestion & Approval

Purpose: Manages suggestions (actions proposed by agents) and approval workflow. Provides user inbox for reviewing and approving suggestions.

Key Aggregates:

  • Suggestion - Action proposed by agent (draft email, calendar event, task, etc.)
  • Approval - User decision to apply or ignore suggestion
  • SuggestionInbox - User inbox for suggestions

Integration Emphasis:

  • Consumes events from Agent Orchestration for new suggestions
  • Integrates with Communications Platform for notifications
  • Emits events for approval decisions
  • Integrates with Connector Service for executing approved actions

Key Characteristics:

  • All external actions start as suggestions
  • User must explicitly approve actions
  • Supports bulk approval operations

Connector

Purpose: Manages external service connectors (Email, Calendar, File upload, Notion, Google Drive, OneDrive). Handles connector authorization and execution.

Key Aggregates:

  • ConnectorConfig - Authorized app/link configuration
  • DataSnapshot - Cached metadata from external services
  • ConnectorExecution - Connector execution log

Integration Emphasis:

  • Integrates with external services (Email, Calendar, File storage, etc.)
  • Used by Agent Orchestration for data access
  • Used by Suggestion & Approval for executing approved actions
  • Integrates with Documents Platform for file storage

Key Characteristics:

  • Pluggable connector architecture
  • OAuth-based authorization for external services
  • Read-only connectors preferred
  • Cached metadata snapshots

Dashboard & Analytics

Purpose: Aggregates data from other contexts to provide dashboards, usage analytics, run history, and cost tracking.

Key Aggregates:

  • Dashboard - Dashboard definition and configuration
  • UsageAnalytics - Usage metrics and analytics
  • RunHistory - Agent run history and summaries
  • CostTracking - Token usage and cost tracking

Integration Emphasis:

  • Consumes events from all contexts
  • Queries Audit Platform for audit data
  • Provides analytics APIs for dashboards
  • Aggregates data from Agent Orchestration and Suggestion & Approval

Key Characteristics:

  • Read-only aggregation context
  • Real-time and historical analytics
  • Cost tracking per user and per run

Context Map (Relationships)

flowchart TD
    PIP[Personal Identity<br/>& Profile] --> AC[Agent Catalog]
    PIP --> PW[Pack & Workflow]
    PIP --> AO[Agent Orchestration]
    PIP --> SA[Suggestion<br/>& Approval]
    PIP --> C[Connector]

    AC --> PW
    PW --> AO
    AO --> SA
    AO --> C
    SA --> C
    AO --> DA[Dashboard<br/>& Analytics]
    SA --> DA
    PW --> DA

    style PIP fill:#e1f5ff
    style AC fill:#fff4e1
    style PW fill:#e8f5e9
    style AO fill:#f3e5f5
    style SA fill:#fff4e1
    style C fill:#e8f5e9
    style DA fill:#f3e5f5
Hold "Alt" / "Option" to enable pan & zoom

Relationship Types

Upstream/Downstream:

  • Personal Identity & Profile → Upstream (provides user and tenant context to all)
  • Agent Catalog → Downstream from Personal Identity & Profile
  • Pack & Workflow → Downstream from Personal Identity & Profile and Agent Catalog
  • Agent Orchestration → Downstream from Personal Identity & Profile, Agent Catalog, and Pack & Workflow
  • Suggestion & Approval → Downstream from Agent Orchestration
  • Connector → Downstream from Personal Identity & Profile, used by Agent Orchestration and Suggestion & Approval
  • Dashboard & Analytics → Downstream from all contexts (read-only aggregation)

Integration Patterns:

  • Events - Most contexts communicate via events (agent run completion, suggestion created, approval decision)
  • APIs - Direct API calls for synchronous operations (get agent definition, execute connector)
  • Shared Data - User and tenant context shared across all contexts
  • Query - Dashboard & Analytics queries data from other contexts and Audit Platform

See: Event-Driven Mindset for event patterns.

Mapping to Factory-Generated Services

Service Mapping:

Bounded Context Microservice Name Template
Personal Identity & Profile PersonalIdentity.Service Microservice Template
Agent Catalog AgentCatalog.Service Microservice Template
Pack & Workflow PackWorkflow.Service Microservice Template
Agent Orchestration AgentOrchestration.Service Microservice Template (with Agent Template overlay)
Suggestion & Approval SuggestionApproval.Service Microservice Template
Connector Connector.Service Microservice Template
Dashboard & Analytics DashboardAnalytics.Service Microservice Template

MVP: Combined Services (Alternative)

For MVP, consider combining:

  • Personal Identity & Profile → PersonalIdentityService
  • Agent Catalog + Pack & Workflow → AgentCatalogService
  • Agent Orchestration → AgentOrchestrationService (core, keep separate)
  • Suggestion & Approval → SuggestionService
  • Connector → ConnectorService
  • Dashboard & Analytics → DashboardService

Rationale:

  • Faster initial delivery
  • Fewer services to manage
  • Can split later as needed
  • Agent Orchestration should remain separate due to complexity and AI Gateway integration

See: Microservice Template for template details.

See: Getting Started with Factory for Factory usage.