🔗 Integration Architect Agent Specification¶

🎯 Purpose¶

The Integration Architect Agent is responsible for designing and governing system integration patterns across the ConnectSoft AI Software Factory — covering ESB design, third-party API strategy, middleware selection, ETL/ELT pipeline design, and legacy system bridging.

Its mission is to translate inter-system communication requirements into contract-first, event-aware, and observable integration blueprints that ensure all external and internal data flows are reliable, secure, and maintainable.

💡 Why This Agent Matters¶

Without this agent:

Third-party integrations would be ad-hoc, fragile, and undocumented
Data pipelines would lack consistency in transformation, validation, and error handling
Legacy systems would be tightly coupled to modern services without proper abstraction
Middleware decisions would be inconsistent across teams and projects
Integration testing would be an afterthought rather than a first-class concern

With the Integration Architect Agent:

✅ All integrations follow contract-first design with versioned schemas ✅ Third-party APIs are accessed through standardized adapter layers with retry and circuit-breaking ✅ ETL/ELT pipelines are declaratively defined, observable, and recoverable ✅ Legacy systems are bridged via anti-corruption layers that protect domain integrity ✅ Middleware selection is governed by a pattern catalog aligned to platform standards

🧱 What This Agent Enables¶

Capability	Impact
🔌 Third-party API integration	Adapter generation, contract validation, rate limiting
🚌 ESB and message bus design	Topic/queue topology, routing rules, dead-letter handling
🔄 ETL/ELT pipeline design	Source-to-target mapping, transformation rules, scheduling
🏚️ Legacy system bridging	Anti-corruption layers, protocol translation, data mapping
📋 Integration pattern catalog	Canonical patterns for sync, async, batch, and streaming
🧪 Integration testing strategy	Contract tests, stub generation, end-to-end flow validation
📡 Observable data flows	Span-instrumented pipelines with error tracking and alerting

🧭 Role in the Platform¶

The Integration Architect Agent sits within the Enterprise and System Architecture cluster, bridging the gap between high-level solution design and implementation-level service communication.

flowchart TD
    SolutionArchitect[Solution Architect Agent]
    IntegrationArchitect[🔗 Integration Architect Agent]
    APIDesigner[API Designer Agent]
    EventDriven[Event-Driven Architect Agent]
    DataArchitect[Data Architect Agent]
    BackendDev[Backend Developer Agent]
    DevOps[DevOps Architect Agent]

    SolutionArchitect --> IntegrationArchitect
    IntegrationArchitect --> APIDesigner
    IntegrationArchitect --> EventDriven
    IntegrationArchitect --> DataArchitect
    IntegrationArchitect --> BackendDev
    IntegrationArchitect --> DevOps

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

📡 Triggering Events¶

The Integration Architect Agent is activated by the following platform events:

Event	Source	Description
`architecture_blueprint_created`	Solution Architect Agent	New system blueprint requires integration topology design
`third_party_integration_requested`	Product Owner / Tech Lead Agent	External API or service must be integrated
`data_pipeline_required`	Data Architect Agent	ETL/ELT pipeline needed for data movement or transformation
`legacy_system_bridge_requested`	Enterprise Architect Agent	Existing legacy system must connect to modern platform
`integration_pattern_review_requested`	Code Reviewer Agent	Existing integration needs architectural review or upgrade
`message_bus_topology_change`	Event-Driven Architect Agent	Topic/queue structure requires redesign

📋 Core Responsibilities¶

🔧 Responsibilities Overview¶

#	Responsibility	Description	Output
1	Integration pattern selection	Choose appropriate patterns (request/reply, pub/sub, saga, choreography) for each integration point	`integration-pattern-catalog.yaml`
2	Middleware architecture	Design message broker topology, ESB routing, and middleware component selection	`middleware-architecture.yaml`
3	API gateway strategy for external systems	Define gateway routing, rate limiting, authentication, and transformation rules for third-party APIs	`api-gateway-integration-config.yaml`
4	ETL/ELT pipeline design	Define data extraction sources, transformation logic, load targets, scheduling, and error handling	`pipeline-definition.yaml`
5	Legacy system bridging	Design anti-corruption layers, protocol adapters, and data mapping for legacy connectivity	`legacy-bridge-spec.yaml`
6	Integration testing strategy	Define contract tests, stub/mock services, and end-to-end integration validation flows	`integration-test-strategy.yaml`
7	Contract-first integration design	Ensure all integrations start with schema/contract definitions before implementation	`integration-contracts/`

📦 Deliverables¶

Artifact	Format	Purpose
`integration-architecture.yaml`	YAML	Master integration topology with all endpoints, patterns, and flows
`integration-pattern-catalog.yaml`	YAML	Catalog of selected patterns mapped to integration points
`middleware-architecture.yaml`	YAML	Message broker, ESB, and middleware component definitions
`pipeline-definition.yaml`	YAML	ETL/ELT pipeline specs with source, transform, and target stages
`legacy-bridge-spec.yaml`	YAML	Anti-corruption layer and adapter definitions for legacy systems
`integration-contracts/`	OpenAPI / AsyncAPI / JSON Schema	Versioned contract definitions for all integration points
`integration-test-strategy.yaml`	YAML	Test plan covering contract, stub, and end-to-end validation
`integration-topology.mmd`	Mermaid	Visual diagram of all integration flows and dependencies
`IntegrationArchitecturePlanPublished`	JSON (Event)	Lifecycle event emitted on successful plan generation

🔌 1. Integration Pattern Selection¶

Pattern	When Used	Example
Request/Reply	Synchronous API calls with immediate response needed	Payment gateway validation
Publish/Subscribe	Event-driven decoupling between bounded contexts	Order placed → Inventory updated
Saga (Orchestration)	Long-running distributed transactions	Multi-step onboarding workflow
Saga (Choreography)	Loosely coupled multi-service workflows	Event chain across microservices
Batch / ETL	Scheduled bulk data movement or transformation	Nightly data warehouse load
Streaming	Real-time continuous data flow	IoT telemetry or log aggregation
Anti-Corruption Layer	Isolating modern domain from legacy data models	ERP system bridging

🚌 2. Middleware Architecture¶

Component	Technology Options	Selection Criteria
Message Broker	Azure Service Bus, RabbitMQ, Kafka	Throughput, ordering, durability needs
API Gateway	Azure API Management, Kong, Ocelot	Rate limiting, transformation, auth
ESB Layer	MassTransit, NServiceBus, Azure Logic Apps	Routing complexity, saga support
Integration Runtime	Azure Data Factory, custom .NET workers	ETL/ELT scheduling and orchestration
Protocol Adapter	gRPC-REST bridge, SOAP-REST translator	Legacy protocol compatibility

🔄 3. ETL/ELT Pipeline Design¶

Stage	Responsibility	Output
Extract	Define source connections, authentication, polling/webhook triggers	Source connector configs
Transform	Map fields, apply business rules, validate schemas, handle nulls	Transformation rule definitions
Load	Target database/warehouse insertion, upsert strategies, conflict resolution	Load target configurations
Schedule	Cron-based or event-triggered execution windows	Pipeline schedule definitions
Error Handling	Dead-letter queues, retry policies, alerting on failure	Error handling policies

🏚️ 4. Legacy System Bridging¶

Technique	Description	When Used
Anti-Corruption Layer	Translate legacy data models to domain models	Domain integrity protection
Protocol Translation	Convert SOAP/XML to REST/JSON or gRPC	Legacy API modernization
Data Synchronization	Bi-directional sync with conflict resolution	Gradual migration scenarios
Strangler Fig Pattern	Incrementally replace legacy with modern services	Long-term modernization
Event Sourcing Bridge	Capture legacy mutations as domain events	Event-driven migration

🤝 Collaboration Interfaces¶

🔼 Upstream Providers¶

Agent	Input Artifact
Solution Architect Agent	`solution-architecture.md` — system boundaries and integration requirements
Enterprise Architect Agent	Enterprise integration standards and legacy system inventory
Data Architect Agent	Data models, retention policies, and warehouse schemas
Event-Driven Architect Agent	Event catalog, topic taxonomy, and message schemas

🔽 Downstream Consumers¶

Agent	Consumes
API Designer Agent	Integration contracts for external API design alignment
Backend Developer Agent	Adapter implementations, pipeline worker scaffolding
DevOps Architect Agent	Middleware infrastructure provisioning requirements
Test Automation Engineer Agent	Integration test strategy and contract test definitions
Observability Engineer Agent	Pipeline span definitions and integration health metrics

📡 Integration Flow¶

flowchart TD
    SolutionArchitect --> IntegrationArchitect
    EnterpriseArchitect --> IntegrationArchitect
    DataArchitect --> IntegrationArchitect
    EventDrivenArchitect --> IntegrationArchitect

    IntegrationArchitect --> APIDesigner
    IntegrationArchitect --> BackendDeveloper
    IntegrationArchitect --> DevOpsArchitect
    IntegrationArchitect --> TestAutomation
    IntegrationArchitect --> ObservabilityEngineer

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

📚 Memory and Knowledge¶

🕐 Short-Term (Session) Memory¶

Key	Purpose
`trace_id`	Tracks all outputs and events for the current integration design cycle
`integration_scope`	Identifies which systems, APIs, and data flows are in scope
`pattern_selections[]`	Records pattern choices made during this session
`middleware_stack`	Selected middleware components for the current architecture
`pipeline_definitions[]`	ETL/ELT pipelines defined in this session

🧠 Long-Term Semantic Memory¶

Data	Used For
Previous integration architectures	Reuse proven patterns and avoid known anti-patterns
Third-party API behavior profiles	Rate limits, reliability history, schema change frequency
Legacy system interface catalogs	Known adapters, protocol requirements, data format mappings
Pipeline execution history	Optimize scheduling, identify bottleneck stages, tune error handling
Integration failure patterns	Proactive circuit-breaking and fallback design

🧠 Knowledge Base¶

Domain	Content
Integration Patterns	Enterprise Integration Patterns (EIP) catalog with ConnectSoft-specific guidance
Middleware Selection Matrix	Decision framework mapping requirements to middleware choices
Contract Standards	OpenAPI 3.x, AsyncAPI 2.x, JSON Schema conventions
ETL Best Practices	Idempotency, exactly-once delivery, backpressure handling
Legacy Bridging Playbooks	Proven strategies for SOAP, FTP, mainframe, and ERP integration
ConnectSoft Platform Standards	Naming, observability, tracing, and security conventions for integrations

✅ Validation and Correction¶

🔍 Validation Rules¶

Rule	Description	Severity
All integration points must have a defined contract (OpenAPI/AsyncAPI)	Contract-first enforcement	Critical
Message broker topics must follow platform naming conventions	`{domain}.{entity}.{action}` format	High
ETL pipelines must define error handling and dead-letter policies	No silent failures allowed	Critical
Legacy adapters must use anti-corruption layers	Domain model protection	High
All integration flows must include trace_id propagation	End-to-end observability	Critical
Rate limiting must be configured for all external API calls	Third-party protection	High
Integration tests must cover happy path and failure scenarios	Test completeness	Medium

🔁 Auto-Correction Behaviors¶

Condition	Correction
Missing dead-letter queue config	Inject default DLQ with retry policy
Topic name violates convention	Auto-format to `{domain}.{entity}.{action}`
No trace_id in pipeline definition	Inject trace propagation middleware
Missing rate limiter on external call	Apply default rate limit (100 req/min)
Contract version not specified	Default to `v1` with deprecation policy

📈 Observability Spans¶

Span Name	Trigger
`integration_architecture_started`	Agent begins design cycle
`pattern_catalog_generated`	Pattern selection completed
`pipeline_definition_created`	ETL/ELT pipeline defined
`legacy_bridge_designed`	Anti-corruption layer specified
`integration_plan_published`	All artifacts emitted successfully

📢 Lifecycle Events¶

Event	Trigger	Payload
`IntegrationArchitecturePlanPublished`	Successful plan generation	Full artifact list, trace_id, scope
`IntegrationPatternSelected`	Pattern chosen for an integration point	Pattern type, endpoints, rationale
`PipelineDefinitionCreated`	ETL/ELT pipeline fully specified	Pipeline ID, stages, schedule
`LegacyBridgeDesigned`	Anti-corruption layer defined	Legacy system, adapter type, protocol
`IntegrationValidationFailed`	Validation rules not met	Failed rules, affected artifacts

✅ Summary¶

The Integration Architect Agent ensures that all inter-system communication in the ConnectSoft platform is:

Capability	Status
🔌 Contract-first integration design	✅
🚌 Governed middleware and message bus architecture	✅
🔄 Declarative ETL/ELT pipeline definitions	✅
🏚️ Legacy system bridging with anti-corruption layers	✅
📋 Standardized pattern catalog	✅
🧪 Integration testing strategy	✅
📡 Observable and traceable data flows	✅
🔐 Secure third-party API integration with rate limiting	✅

"The Integration Architect Agent guarantees that every data flow, API call, and system bridge in the ConnectSoft platform follows enterprise integration best practices — ensuring reliability, observability, and maintainability across all integration boundaries."