Skip to content

High-Level Design

This document provides the high-level design (HLD) for the Personal Agents Platform, including system architecture, deployment architecture, data flows, and technology stack. It is written for architects and engineers designing and implementing the system.

The Personal Agents Platform is built as a microservices architecture, integrating with ConnectSoft Core Platform services and external connectors. This document provides the architectural foundation for development.

Important

Architecture Principles: 1. Microservices architecture with clear bounded contexts 1. Event-driven communication between services 1. Personal-tenant isolation at all layers 1. All external actions start as suggestions 1. Transparent logging and audit trails 1. Scalable and cost-effective agent execution

System Architecture Overview

graph TB
    subgraph Clients["Clients"]
        WebUI[Web UI<br/>app.connectsoft.me]
        Mobile[Mobile App<br/>Future]
        API_Client[API Clients]
    end

    subgraph Gateway["API Gateway"]
        APIGateway[API Gateway<br/>Authentication<br/>Rate Limiting<br/>Routing]
    end

    subgraph Services["Personal Agents Microservices"]
        PIP[Personal Identity<br/>& Profile Service]
        AC[Agent Catalog<br/>Service]
        PW[Pack & Workflow<br/>Service]
        AO[Agent Orchestration<br/>Service]
        SA[Suggestion & Approval<br/>Service]
        C[Connector<br/>Service]
        DA[Dashboard & Analytics<br/>Service]
    end

    subgraph Platforms["ConnectSoft Core Platform"]
        IDP[Identity Platform<br/>OAuth2/OIDC<br/>User Management]
        Audit[Audit Platform<br/>Event Logging<br/>Compliance]
        Config[Config Platform<br/>Settings<br/>Feature Flags]
        Docs[Documents Platform<br/>File Storage<br/>Versioning]
        Comm[Communications Platform<br/>Email, SMS, Notifications]
        Billing[Billing Platform<br/>Subscriptions<br/>Usage Tracking]
        AI[AI Gateway &<br/>Agent Runtime<br/>Model Routing<br/>Token Tracking]
    end

    subgraph External["External Services"]
        Gmail[Gmail API]
        Calendar[Google Calendar<br/>Outlook Calendar]
        Drive[Google Drive<br/>OneDrive<br/>Notion]
    end

    subgraph Storage["Data Storage"]
        SQL[(SQL Database<br/>User Data<br/>Agents, Packs)]
        Blob[(Blob Storage<br/>Files<br/>Documents)]
        Cache[(Redis Cache<br/>Sessions<br/>Snapshots)]
    end

    subgraph Messaging["Message Bus"]
        EventBus[Event Bus<br/>Azure Service Bus<br/>Event Streaming]
    end

    Clients --> APIGateway
    APIGateway --> Services

    Services --> IDP
    Services --> Audit
    Services --> Config
    Services --> Docs
    Services --> Comm
    Services --> Billing
    AO --> AI

    Services --> SQL
    Services --> Blob
    Services --> Cache
    Services --> EventBus

    C --> Gmail
    C --> Calendar
    C --> Drive

    style Clients fill:#e1f5ff
    style Services fill:#fff4e1
    style Platforms fill:#e8f5e9
    style External fill:#f3e5f5
    style Storage fill:#fff9c4
    style Messaging fill:#fce4ec
Hold "Alt" / "Option" to enable pan & zoom

Microservices Architecture

Service Responsibilities

Personal Identity & Profile Service:

  • User account management
  • Personal tenant management
  • User profile management
  • Subscription management (integration with Billing Platform)

Agent Catalog Service:

  • AgentTemplate management
  • AgentInstance management
  • Agent archetype definitions

Pack & Workflow Service:

  • AgentPack management
  • AgentWorkflow definitions
  • WorkflowTrigger management

Agent Orchestration Service:

  • AgentRun execution
  • Multi-agent workflow orchestration
  • Integration with AI Gateway
  • Token usage and cost tracking

Suggestion & Approval Service:

  • Suggestion management
  • Approval workflow
  • User inbox management

Connector Service:

  • ConnectorConfig management
  • External service integration
  • DataSnapshot management
  • OAuth authorization flows

Dashboard & Analytics Service:

  • Dashboard generation
  • Usage analytics
  • Run history
  • Cost tracking

Deployment Architecture

graph TB
    subgraph Azure["Azure Cloud"]
        subgraph Frontend["Frontend Layer"]
            WebApp[Azure App Service<br/>Web UI<br/>Static Site]
            APIGW[API Gateway<br/>Azure API Management<br/>or App Gateway]
        end

        subgraph Services["Microservices Layer"]
            PIP_App[Personal Identity<br/>App Service]
            AC_App[Agent Catalog<br/>App Service]
            PW_App[Pack & Workflow<br/>App Service]
            AO_App[Agent Orchestration<br/>App Service]
            SA_App[Suggestion & Approval<br/>App Service]
            C_App[Connector<br/>App Service]
            DA_App[Dashboard & Analytics<br/>App Service]
        end

        subgraph Platform["Platform Services"]
            IDP_Service[Identity Platform<br/>Service]
            Audit_Service[Audit Platform<br/>Service]
            Config_Service[Config Platform<br/>Service]
            Docs_Service[Documents Platform<br/>Service]
            Comm_Service[Communications Platform<br/>Service]
            Billing_Service[Billing Platform<br/>Service]
            AI_Service[AI Gateway<br/>Service]
        end

        subgraph Data["Data Layer"]
            SQL_DB[(Azure SQL<br/>User Data<br/>Agents, Packs)]
            Blob_Storage[(Azure Blob Storage<br/>Files, Documents)]
            Redis_Cache[(Azure Cache for Redis<br/>Sessions, Snapshots)]
        end

        subgraph Messaging["Messaging Layer"]
            ServiceBus[Azure Service Bus<br/>Event Bus<br/>Message Queue]
        end

        subgraph Monitoring["Monitoring"]
            AppInsights[Application Insights<br/>Logging, Metrics, Tracing]
            Monitor[Azure Monitor<br/>Alerts, Dashboards]
        end
    end

    WebApp --> APIGW
    APIGW --> Services
    Services --> Platform
    Services --> Data
    Services --> Messaging
    Services --> Monitoring

    style Frontend fill:#e1f5ff
    style Services fill:#fff4e1
    style Platform fill:#e8f5e9
    style Data fill:#fff9c4
    style Messaging fill:#fce4ec
    style Monitoring fill:#f3e5f5
Hold "Alt" / "Option" to enable pan & zoom

Agent Execution Flow

sequenceDiagram
    participant User
    participant UI as Web UI
    participant API as API Gateway
    participant AO as Agent Orchestration Service
    participant AIG as AI Gateway
    participant AR as Agent Runtime
    participant Conn as Connector Service
    participant Ext as External Service
    participant SA as Suggestion & Approval Service
    participant Audit as Audit Platform

    User->>UI: Trigger Agent Run
    UI->>API: POST /orchestration/runs
    API->>AO: ExecuteAgentRun()
    AO->>Audit: Log AgentRunCreated
    AO->>AO: Create AgentRun
    AO->>AIG: ExecuteAgent(config, inputs)
    AIG->>AR: Run Agent
    AR->>Conn: Access Connector (Email)
    Conn->>Ext: Read Inbox
    Ext-->>Conn: Email Data
    Conn-->>AR: Data
    AR->>AR: Process & Generate Results
    AR->>AR: Create Suggestions
    AR-->>AIG: Results + Suggestions
    AIG-->>AO: Execution Results
    AO->>AO: Store Results<br/>(tokens, cost, outputs)
    AO->>Audit: Log AgentRunCompleted
    AO->>SA: Emit SuggestionCreated Events
    SA->>SA: Create Suggestions
    AO-->>API: Run Complete
    API-->>UI: Response
    UI-->>User: Show Results
Hold "Alt" / "Option" to enable pan & zoom

Multi-Agent Workflow Orchestration Flow

flowchart TD
    Start([Workflow Triggered]) --> Validate{Validate Request<br/>Subscription, Limits}
    Validate -->|Valid| CreateRun[Create AgentRun<br/>& WorkflowExecution]
    Validate -->|Invalid| Error[Return Error]

    CreateRun --> CheckType{Workflow Type}

    CheckType -->|Sequential| Sequential[Sequential Execution]
    CheckType -->|Parallel| Parallel[Parallel Execution]

    Sequential --> Step1[Execute Agent A]
    Step1 --> Step1Result[Store Step 1 Results]
    Step1Result --> Step2[Execute Agent B<br/>with Step 1 Results]
    Step2 --> Step2Result[Store Step 2 Results]
    Step2Result --> Step3[Execute Agent C<br/>with Step 2 Results]
    Step3 --> Step3Result[Store Step 3 Results]
    Step3Result --> Aggregate[Aggregate Results]

    Parallel --> ParStep1[Execute Agent A]
    Parallel --> ParStep2[Execute Agent B]
    Parallel --> ParStep3[Execute Agent C]
    ParStep1 --> Wait[Wait for All]
    ParStep2 --> Wait
    ParStep3 --> Wait
    Wait --> Coordinator[Execute Coordinator Agent<br/>with All Results]
    Coordinator --> Aggregate

    Aggregate --> CreateSuggestions[Create Suggestions]
    CreateSuggestions --> Complete[Complete WorkflowExecution]
    Complete --> Notify[Notify User]

    style Start fill:#e1f5ff
    style Sequential fill:#fff4e1
    style Parallel fill:#e8f5e9
    style Aggregate fill:#f3e5f5
    style Complete fill:#fff9c4
Hold "Alt" / "Option" to enable pan & zoom

Data Flow Diagram

flowchart LR
    subgraph UserActions["User Actions"]
        CreateAgent[Create Agent]
        InstallPack[Install Pack]
        TriggerRun[Trigger Run]
        ApproveSuggestion[Approve Suggestion]
    end

    subgraph Services["Microservices"]
        PIP_Service[Personal Identity<br/>Service]
        AC_Service[Agent Catalog<br/>Service]
        PW_Service[Pack & Workflow<br/>Service]
        AO_Service[Agent Orchestration<br/>Service]
        SA_Service[Suggestion & Approval<br/>Service]
        C_Service[Connector<br/>Service]
    end

    subgraph Platforms["Core Platforms"]
        IDP_Platform[Identity Platform]
        Audit_Platform[Audit Platform]
        Config_Platform[Config Platform]
        Docs_Platform[Documents Platform]
        Billing_Platform[Billing Platform]
        AI_Platform[AI Gateway]
    end

    subgraph Storage["Storage"]
        SQL_DB[(SQL Database)]
        Blob_Store[(Blob Storage)]
        Cache_Store[(Redis Cache)]
    end

    CreateAgent --> AC_Service
    InstallPack --> PW_Service
    TriggerRun --> AO_Service
    ApproveSuggestion --> SA_Service

    AC_Service --> SQL_DB
    AC_Service --> Config_Platform
    AC_Service --> Audit_Platform

    PW_Service --> SQL_DB
    PW_Service --> Config_Platform
    PW_Service --> Audit_Platform

    AO_Service --> AI_Platform
    AO_Service --> C_Service
    AO_Service --> SQL_DB
    AO_Service --> Audit_Platform
    AO_Service --> Billing_Platform

    SA_Service --> C_Service
    SA_Service --> SQL_DB
    SA_Service --> Audit_Platform

    C_Service --> Docs_Platform
    C_Service --> Cache_Store
    C_Service --> SQL_DB

    PIP_Service --> IDP_Platform
    PIP_Service --> Billing_Platform
    PIP_Service --> SQL_DB

    style UserActions fill:#e1f5ff
    style Services fill:#fff4e1
    style Platforms fill:#e8f5e9
    style Storage fill:#fff9c4
Hold "Alt" / "Option" to enable pan & zoom

Technology Stack

Backend Services

  • .NET 9 - Primary runtime for all microservices
  • ASP.NET Core - Web framework for REST APIs
  • gRPC - Internal service-to-service communication
  • Entity Framework Core - ORM for database access
  • Azure Service Bus - Message bus for event-driven communication
  • Semantic Kernel - AI agent framework (via Agent Template)

Data Storage

  • Azure SQL Database - Primary database for user data, agents, packs, workflows
  • Azure Blob Storage - File storage for documents and agent outputs
  • Azure Cache for Redis - Caching for sessions, data snapshots, performance

Frontend

  • React / Next.js - Web UI framework (or preferred frontend framework)
  • TypeScript - Type-safe frontend development
  • Material UI / Tailwind CSS - UI component library

Infrastructure

  • Azure App Service - Hosting for microservices and web UI
  • Azure API Management - API Gateway (or Azure Application Gateway)
  • Azure Application Insights - Logging, metrics, distributed tracing
  • Azure Monitor - Monitoring and alerting

Integration

  • OAuth2/OIDC - Authentication via Identity Platform
  • REST APIs - External API communication
  • gRPC - Internal service communication
  • Event Bus - Event-driven communication

Infrastructure Requirements

Compute

  • Microservices: Azure App Service (Standard tier minimum)
  • Web UI: Azure App Service or Azure Static Web Apps
  • API Gateway: Azure API Management or Application Gateway

Storage

  • SQL Database: Azure SQL Database (Standard tier)
  • Blob Storage: Azure Blob Storage (Standard tier)
  • Cache: Azure Cache for Redis (Basic tier minimum)

Networking

  • VNet Integration: For secure service-to-service communication
  • Private Endpoints: For platform service access (if needed)
  • CDN: For static assets and web UI

Monitoring

  • Application Insights: For application logging and metrics
  • Azure Monitor: For infrastructure monitoring
  • Log Analytics: For log aggregation and analysis

Scalability Considerations

Horizontal Scaling

  • Microservices: Scale independently based on load
  • Agent Orchestration Service: Scale based on concurrent agent runs
  • Connector Service: Scale based on connector usage
  • Stateless Services: All services designed to be stateless for easy scaling

Caching Strategy

  • Redis Cache: Cache frequently accessed data (agent configs, user preferences, data snapshots)
  • CDN: Cache static assets and web UI
  • Database Query Caching: Cache common queries

Performance Optimization

  • Async Processing: Agent runs processed asynchronously
  • Batch Operations: Bulk suggestion operations
  • Connection Pooling: Database connection pooling
  • Token Caching: OAuth token caching

Security Considerations

Authentication and Authorization

  • OAuth2/OIDC: All API access authenticated via Identity Platform
  • Personal-Tenant Isolation: All resources scoped to user's personal tenant
  • API Tokens: Service-to-service authentication using client credentials

Data Protection

  • Encryption at Rest: All data encrypted at rest (SQL, Blob Storage)
  • Encryption in Transit: TLS/HTTPS for all communications
  • Personal Data: Strict privacy controls, user data export/deletion

Audit and Compliance

  • Audit Logging: All operations logged to Audit Platform
  • Transparent Logging: Users can view what agents did
  • Data Retention: Configurable data retention policies

Cost Optimization

AI Costs

  • Token Tracking: Track tokens per run for cost management
  • Usage Limits: Enforce usage limits based on subscription tier
  • Model Selection: Use cost-effective models where appropriate
  • Caching: Cache agent results to reduce redundant executions

Infrastructure Costs

  • Auto-Scaling: Scale down during low usage periods
  • Reserved Instances: Use reserved instances for predictable workloads
  • Storage Tiering: Use appropriate storage tiers (hot, cool, archive)