Skip to content

ConnectSoft Company Documentation

Processes and Flows

ConnectSoft Company

Processes and Flows¶

This document defines the key business processes and flows for the Personal Agents Platform domain. It is written for architects, product managers, and engineers understanding how the system operates.

The Personal Agents Platform orchestrates complex workflows involving agent execution, multi-agent coordination, suggestion management, and user approvals. This document describes these processes with sequence and flow diagrams.

Important

Core Process Principles: 1. All external actions start as suggestions (no auto-execution) 1. User must explicitly approve actions before execution 1. Agent runs are logged and audited for transparency 1. Multi-agent workflows support both sequential and parallel execution 1. Workflow triggers can be manual, scheduled, or event-based

Key Business Processes¶

1. Agent Execution Flow (Manual)¶

Process: User manually triggers an agent or pack execution.

Steps:

User requests agent execution via API/UI
Agent Orchestration Service validates request (user subscription, agent status, usage limits)
Agent Orchestration Service creates AgentRun
Agent Orchestration Service invokes AI Gateway with agent configuration
AI Gateway executes agent using Agent Runtime
Agent accesses connectors (Email, Calendar, Files) as needed
Agent generates results and suggestions
Agent Orchestration Service stores run results
Agent Orchestration Service emits events for suggestions
Suggestion & Approval Service creates Suggestions
User receives notifications (email, in-app)

sequenceDiagram
    participant User
    participant UI as Web UI / API
    participant AO as Agent Orchestration Service
    participant AIG as AI Gateway
    participant AR as Agent Runtime
    participant Conn as Connector Service
    participant SA as Suggestion & Approval Service
    participant Comm as Communications Platform

    User->>UI: Trigger Agent Run
    UI->>AO: ExecuteAgentRun(userId, agentId)
    AO->>AO: Validate Request<br/>(subscription, limits, status)
    AO->>AO: Create AgentRun
    AO->>AIG: ExecuteAgent(agentConfig)
    AIG->>AR: Run Agent
    AR->>Conn: Access Connectors<br/>(Email, Calendar, Files)
    Conn-->>AR: Return Data
    AR->>AR: Process & Generate Results
    AR-->>AIG: Agent Results & Suggestions
    AIG-->>AO: Run Results
    AO->>AO: Store Run Results<br/>(tokens, cost, outputs)
    AO->>SA: Emit SuggestionCreated Events
    SA->>SA: Create Suggestions
    SA->>Comm: Send Notification<br/>(Email, In-App)
    Comm-->>User: Notification
    AO-->>UI: Run Complete
    UI-->>User: Show Results

Hold "Alt" / "Option" to enable pan & zoom

2. Agent Execution Flow (Scheduled)¶

Process: Scheduled workflow trigger automatically executes agents.

Steps:

WorkflowTrigger fires based on schedule (cron expression)
Pack & Workflow Service identifies triggered workflows
Pack & Workflow Service emits WorkflowTriggered event
Agent Orchestration Service receives event
Agent Orchestration Service validates and creates AgentRun
Agent Orchestration Service executes workflow (sequential or parallel)
Results aggregated and suggestions created
User receives notifications

sequenceDiagram
    participant Scheduler
    participant PW as Pack & Workflow Service
    participant AO as Agent Orchestration Service
    participant AIG as AI Gateway
    participant SA as Suggestion & Approval Service
    participant Comm as Communications Platform
    participant User

    Scheduler->>PW: Trigger Fired<br/>(Schedule)
    PW->>PW: Find Active Workflows
    PW->>AO: Emit WorkflowTriggered Event
    AO->>AO: Validate & Create AgentRun
    AO->>AIG: Execute Workflow
    AIG->>AIG: Execute Agents<br/>(Sequential/Parallel)
    AIG-->>AO: Workflow Results
    AO->>AO: Aggregate Results
    AO->>SA: Emit SuggestionCreated Events
    SA->>SA: Create Suggestions
    SA->>Comm: Send Notification
    Comm-->>User: Notification

Hold "Alt" / "Option" to enable pan & zoom

3. Multi-Agent Workflow Orchestration (Sequential)¶

Process: Execute multiple agents in sequence, where each agent uses output from previous agent.

Steps:

Workflow triggered (manual or scheduled)
Agent Orchestration Service creates WorkflowExecution
Execute Agent A with initial inputs
Store Agent A results
Execute Agent B with Agent A results as input
Store Agent B results
Execute Agent C with Agent B results as input
Aggregate final results
Create suggestions from final results

sequenceDiagram
    participant AO as Agent Orchestration Service
    participant WE as WorkflowExecution
    participant AIG as AI Gateway
    participant AgentA as Agent A
    participant AgentB as Agent B
    participant AgentC as Agent C
    participant SA as Suggestion & Approval Service

    AO->>WE: Create WorkflowExecution
    AO->>AIG: Execute Agent A
    AIG->>AgentA: Run with Initial Inputs
    AgentA-->>AIG: Results A
    AIG-->>AO: Agent A Results
    AO->>WE: Store Step 1 Results
    AO->>AIG: Execute Agent B
    AIG->>AgentB: Run with Results A
    AgentB-->>AIG: Results B
    AIG-->>AO: Agent B Results
    AO->>WE: Store Step 2 Results
    AO->>AIG: Execute Agent C
    AIG->>AgentC: Run with Results B
    AgentC-->>AIG: Results C
    AIG-->>AO: Agent C Results
    AO->>WE: Aggregate Final Results
    AO->>SA: Create Suggestions from Results

Hold "Alt" / "Option" to enable pan & zoom

4. Multi-Agent Workflow Orchestration (Parallel)¶

Process: Execute multiple agents in parallel, then aggregate results with coordinator agent.

Steps:

Workflow triggered
Agent Orchestration Service creates WorkflowExecution
Execute Agent A, Agent B, and Agent C in parallel
Wait for all agents to complete
Execute Coordinator Agent with all results
Coordinator Agent aggregates and summarizes
Create suggestions from aggregated results

sequenceDiagram
    participant AO as Agent Orchestration Service
    participant WE as WorkflowExecution
    participant AIG as AI Gateway
    par Parallel Execution
        AIG->>AgentA: Execute Agent A
        AIG->>AgentB: Execute Agent B
        AIG->>AgentC: Execute Agent C
    end
    AgentA-->>AIG: Results A
    AgentB-->>AIG: Results B
    AgentC-->>AIG: Results C
    AIG-->>AO: All Results
    AO->>WE: Store All Step Results
    AO->>AIG: Execute Coordinator Agent
    AIG->>Coordinator: Aggregate Results<br/>(A + B + C)
    Coordinator-->>AIG: Final Aggregated Results
    AIG-->>AO: Final Results
    AO->>SA: Create Suggestions

Hold "Alt" / "Option" to enable pan & zoom

5. Suggestion and Approval Workflow¶

Process: User reviews and approves suggestions generated by agents.

Steps:

Agent generates suggestion during execution
Suggestion & Approval Service creates Suggestion
User receives notification (email, in-app)
User views suggestion in inbox
User makes decision: Approve, Reject, or Edit
If Approved: Connector Service executes action
If Rejected: Suggestion marked as rejected
If Edit: User modifies action, then approves
Execution result stored and user notified

sequenceDiagram
    participant Agent
    participant SA as Suggestion & Approval Service
    participant Comm as Communications Platform
    participant User
    participant UI as Web UI
    participant Conn as Connector Service
    participant Ext as External Service

    Agent->>SA: Generate Suggestion
    SA->>SA: Create Suggestion
    SA->>Comm: Send Notification
    Comm-->>User: Notification (Email/In-App)
    User->>UI: View Suggestions
    UI->>SA: Get Suggestions
    SA-->>UI: Suggestions List
    User->>UI: Approve/Reject/Edit Suggestion
    UI->>SA: Submit Decision

    alt Approve
        SA->>SA: Create Approval (Approve)
        SA->>Conn: Execute Action
        Conn->>Ext: Perform Action<br/>(Send Email, Create Event, etc.)
        Ext-->>Conn: Result
        Conn-->>SA: Execution Result
        SA->>SA: Update Suggestion Status
        SA->>Comm: Send Confirmation
        Comm-->>User: Confirmation
    else Reject
        SA->>SA: Create Approval (Reject)
        SA->>SA: Update Suggestion Status
    else Edit
        SA->>SA: Create Approval (Edit)
        SA->>SA: Update Suggestion with Edit
        SA->>Conn: Execute Edited Action
        Conn->>Ext: Perform Action
        Ext-->>Conn: Result
        Conn-->>SA: Execution Result
        SA->>SA: Update Suggestion Status
    end

Hold "Alt" / "Option" to enable pan & zoom

6. Pack Installation and Configuration¶

Process: User installs a prebuilt pack or creates a custom pack.

Steps:

User browses available packs (prebuilt or marketplace)
User selects pack to install
System validates user subscription (pack limits, agent limits)
System creates AgentPack
System creates AgentInstances for each agent in pack
System configures default settings
User can customize agent configurations
Pack ready for use

sequenceDiagram
    participant User
    participant UI as Web UI
    participant AC as Agent Catalog Service
    participant PW as Pack & Workflow Service
    participant PIP as Personal Identity Service
    participant Config as Config Platform

    User->>UI: Browse Packs
    UI->>AC: Get Available Packs
    AC-->>UI: Packs List
    User->>UI: Install Pack
    UI->>PIP: Validate Subscription<br/>(limits, quotas)
    PIP-->>UI: Validation Result
    UI->>PW: Install Pack(userId, packTemplateId)
    PW->>PW: Create AgentPack
    PW->>AC: Create AgentInstances<br/>(for each agent in pack)
    AC->>AC: Create AgentInstances
    AC->>Config: Store Default Configs
    Config-->>AC: Config Stored
    AC-->>PW: Instances Created
    PW->>PW: Configure Pack Settings
    PW-->>UI: Pack Installed
    UI-->>User: Pack Ready

Hold "Alt" / "Option" to enable pan & zoom

7. Connector Authorization Flow¶

Process: User authorizes external service connector (Email, Calendar, Google Drive, etc.).

Steps:

User initiates connector authorization
System redirects to OAuth provider
User authorizes on provider site
Provider redirects back with authorization code
System exchanges code for access token
System stores ConnectorConfig with tokens
System performs initial data sync
System creates DataSnapshots
Connector ready for use

sequenceDiagram
    participant User
    participant UI as Web UI
    participant Conn as Connector Service
    participant OAuth as OAuth Provider<br/>(Google, Microsoft, etc.)
    participant Ext as External Service<br/>(Gmail, Calendar, etc.)

    User->>UI: Authorize Connector
    UI->>Conn: Initiate Authorization
    Conn->>OAuth: Redirect to OAuth
    OAuth->>User: Authorization Page
    User->>OAuth: Authorize
    OAuth->>Conn: Redirect with Code
    Conn->>OAuth: Exchange Code for Token
    OAuth-->>Conn: Access Token & Refresh Token
    Conn->>Conn: Store ConnectorConfig
    Conn->>Ext: Initial Data Sync
    Ext-->>Conn: Data
    Conn->>Conn: Create DataSnapshots
    Conn-->>UI: Connector Ready
    UI-->>User: Connector Authorized

Hold "Alt" / "Option" to enable pan & zoom

Event Flows Between Contexts¶

Agent Run Completion Event Flow¶

flowchart LR
    AO[Agent Orchestration<br/>AgentRun Completed] -->|Event| SA[Suggestion & Approval<br/>Create Suggestions]
    AO -->|Event| DA[Dashboard & Analytics<br/>Update Metrics]
    AO -->|Event| Audit[Audit Platform<br/>Log Run]
    SA -->|Event| Comm[Communications Platform<br/>Send Notification]
    SA -->|Event| DA

Hold "Alt" / "Option" to enable pan & zoom

Suggestion Approval Event Flow¶

flowchart LR
    SA[Suggestion & Approval<br/>Approval Decision] -->|Event| Conn[Connector Service<br/>Execute Action]
    SA -->|Event| Audit[Audit Platform<br/>Log Approval]
    SA -->|Event| DA[Dashboard & Analytics<br/>Update Metrics]
    Conn -->|Event| SA[Update Suggestion Status]

Hold "Alt" / "Option" to enable pan & zoom

Pack Installation Event Flow¶

flowchart LR
    PW[Pack & Workflow<br/>Pack Installed] -->|Event| AC[Agent Catalog<br/>Create Instances]
    PW -->|Event| Config[Config Platform<br/>Store Configs]
    PW -->|Event| Audit[Audit Platform<br/>Log Installation]
    AC -->|Event| DA[Dashboard & Analytics<br/>Update Dashboard]

Hold "Alt" / "Option" to enable pan & zoom

Domain Overview - Domain overview
Domain Vision and Scope - Vision and scope
Bounded Contexts and Context Map - Domain boundaries
Domain Model and Aggregates - Domain model
API and Integration View - API design
High-Level Design - System architecture
Reporting and Analytics - KPIs and analytics
Event-Driven Mindset - Event patterns