🔌 Adapter Generator Agent Specification¶

🎯 Purpose¶

The Adapter Generator Agent automates the creation of infrastructure adapters that implement the boundaries between the application layer (use cases) and the outside world — including:

Controllers (REST/gRPC)
Messaging consumers (event bus, service bus, Kafka, etc.)
Persistence adapters (repositories, blob access, NoSQL, SQL)
Outbound clients (HTTP, SOAP, gRPC, SDK-based integrations)

It transforms abstract port definitions from the Application Layer into production-grade, pluggable, observable code.

🧱 Why This Agent Is Critical¶

Without this agent:

Developers must manually write boilerplate for each port and external integration
Clean Architecture separation may be violated (logic leaking into controllers/repos)
Cross-cutting concerns like logging, retries, security, tracing may be forgotten
Testing and mocking of adapters becomes inconsistent
Infrastructure code diverges across microservices

With this agent:

✅ All external boundary implementations are consistent, observable, testable
✅ Adapters follow ConnectSoft’s Clean Architecture and domain-layer contracts
✅ Services are immediately runnable, with REST, gRPC, bus listeners, or repositories in place
✅ External system connectors (e.g., Stripe, Segment, Azure Blob, CRM) are auto-wired
✅ All adapters are span-traced, exception-logged, and resilience-enabled

🧠 Examples of Adapter Generation¶

Input	Output
`CreateUserUseCase` input port	`POST /users` controller with DI + validation
`GetInvoiceQuery` input port	`GET /invoices/{id}` handler
`SendEmailCommand` output port	`IEmailSender` → concrete SMTP or API client
`UserRegisteredEvent` input port	Kafka consumer + message mapper + forwarder
`UserRepository` output port	NHibernate-backed repository implementation
External CRM client	HTTP client with retry + circuit breaker adapter scaffolded

🧭 Architectural Placement¶

flowchart TD
    Domain --> Application
    Application --> AdapterGenerator
    AdapterGenerator --> Controllers
    AdapterGenerator --> EventConsumers
    AdapterGenerator --> Repositories
    AdapterGenerator --> ExternalClients

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

🔄 Adapter Generator’s Strategic Role¶

Area	Impact
Clean Architecture Enforcement	Adapters never leak domain/application logic
Microservice Readiness	Services have working endpoints and persistence from day one
Dev Acceleration	Eliminates repetitive boilerplate for every service
Platform Compliance	Tracing, logging, security, and testability are enforced
Extensibility	New adapters (e.g., Redis, third-party SaaS) added by plugin or template override

📡 Scope of Influence¶

The Adapter Generator Agent controls the generation of all infrastructure-side adapter implementations required to connect domain logic to external systems or transport layers.
It respects Clean Architecture boundaries by implementing input ports (infrastructure → application) and output ports (application → infrastructure).

🧱 What This Agent Owns¶

Adapter Type	Description
REST Controllers	ASP.NET Core HTTP endpoints for commands and queries
gRPC Services	Service handlers for gRPC-defined contracts
Message Consumers	MassTransit consumers, Azure Service Bus, Kafka listeners
Persistence Adapters	NHibernate/EF repositories, NoSQL clients, blob storage
API Clients	Typed HTTP clients with retry policies, OAuth2/OIDC, headers, and resilience
External SDK Adapters	Wrappers for third-party SDKs (Stripe, Segment, Hubspot)
Test Doubles & Mocks	In-memory or mock implementations of output ports

🧩 Adapter Placement in Clean Architecture¶

flowchart TD
    ExternalSystems[External Systems] --> InboundAdapters[Inbound Adapters: REST, gRPC, Kafka]
    InboundAdapters --> Application[Application Layer]
    Application --> OutboundAdapters[Outbound Adapters: Repos, Clients, Message Brokers]
    OutboundAdapters --> ExternalSystems

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

🧠 What This Agent Does Not Own¶

Component	Responsible Agent
Use case interactor logic	Application Architect Agent
Port interface definitions	Microservice Generator / App Layer
OpenAPI/gRPC contract generation	API Designer Agent
Infrastructure provisioning (DBs, endpoints)	Infrastructure Architect Agent
Domain modeling (Aggregates, Entities)	Domain Modeler Agent

☁️ Supported Transport & Infrastructure Types¶

Layer	Technologies
HTTP	ASP.NET Core MVC, REST, Swagger, OpenAPI
gRPC	gRPC ServiceHost in .NET
Messaging	MassTransit, Azure Service Bus, RabbitMQ, Kafka
Storage	NHibernate, Entity Framework, Dapper, MongoDB
File/Blob	Azure Blob Storage, Amazon S3
External APIs	HttpClientFactory, OpenIdConnect auth, SDK integration
Observability	Serilog, OTEL spans, resilience policies (Polly)

🧬 Adapter Classification (by Direction)¶

Type	Adapter Role
Input Adapters	Serve requests into the application: controllers, handlers, consumers
Output Adapters	Send messages, persist data, call external services
Hybrid Adapters	Perform both (e.g., message transformer + HTTP caller combo)

🔁 Dynamic Composition¶

Adapters are generated per:

Port → transport pair (GetUser → REST GET)
Configuration hints (requires OAuth2, retries: 3, emit_span: true)
Template selection (default, custom template override, plugin-bound)
Infrastructure capabilities (MassTransit, Serilog, Azure Blob, PostgreSQL)

📋 Core Responsibilities¶

The Adapter Generator Agent is responsible for transforming abstract port definitions from the application layer into ready-to-use infrastructure adapter implementations that align with Clean Architecture, support observability, and integrate seamlessly into the ConnectSoft microservice ecosystem.

✅ 1. Adapter Scaffolding from Port Definitions¶

Task	Output
Map `input-ports.json` to controllers, gRPC handlers, message consumers	e.g., `CreateUserCommand → POST /users`
Map `output-ports.json` to repositories, clients, message publishers	e.g., `IEmailSender → SMTPAdapter.cs`
Add DI container registrations, naming conventions, and interfaces	Updates `Startup.cs` or `AdaptersRegistry.cs`

🔌 2. Transport-Specific Adapter Generation¶

Transport	Output
HTTP/REST	ASP.NET Core controller with routing, model binding, validation
gRPC	gRPC service inheriting from generated base classes
Kafka / Service Bus / RabbitMQ	Message consumer using MassTransit handler
Azure Blob / S3	Adapter using blob client with injected configuration
OpenId Connect APIs	OAuth2-backed HttpClient using `ConnectSoft.Extensions.Http.OpenIdConnect`

🔄 3. Boundary Enforcement¶

Rule	Enforcement
Adapter must depend only on port (interface) — not domain or app internals	✅
No business logic in controllers or consumers	✅
All side effects (IO, messaging, calls) handled in adapter	✅
Port-based inversion: all outbound dependencies go through injected interfaces	✅

🔐 4. Cross-Cutting Concern Injection¶

All adapters must support:

✅ Structured logging (e.g., Serilog)
✅ OpenTelemetry spans and baggage propagation
✅ Polly-based retry, timeout, and circuit-breaker policies
✅ Security (e.g., authorization attributes, API keys, OAuth2 tokens)
✅ CancellationToken propagation and timeout enforcement
✅ Structured error handling (ProblemDetails for REST)

🔍 5. Testability Enforcement¶

Each adapter will generate or expose:

✅ Interface-first design (IUserRepository, IExternalCrmClient)
✅ In-memory or mockable implementations for test harnesses
✅ Unit test scaffold (if test generation is enabled)
✅ Fake data sources (for repositories and outbound services)

📦 6. Modular Output Integration¶

Generated adapters are:

🧩 Written into the Infrastructure project of the service
📁 Organized by port type (Controllers/, Consumers/, Persistence/, Clients/)
🔧 Registered via dependency injection templates or .AddAdapters() helpers
🧪 Optionally accompanied by test scaffolding and usage hints

🧠 Adapter Examples¶

Port	Adapter Generated
`ICustomerRepository`	`CustomerRepository.cs` (EF/NH + LINQ impl)
`IAnalyticsService`	`MixpanelAdapter.cs` with retry + circuit-breaker
`INotificationClient`	`HttpNotificationClient.cs` using typed HttpClient
`IUserCommandHandler`	`UsersController.cs` (REST) or `UserService.cs` (gRPC)

📈 Responsibility to Span Relationship¶

Responsibility	Span
Adapter generated	`adapter_generated`
Port matched	`adapter_port_resolved`
Transport resolved	`adapter_transport_matched`
Retry logic applied	`adapter_resilience_applied`
Controller/handler injected	`adapter_registered`

📤 Core Output Overview¶

The Adapter Generator Agent emits production-ready, testable, Clean Architecture-compliant code files that implement the input and output ports of the application layer — turning abstract contracts into operational interfaces.

Adapters are code-generated, observable, and optionally accompanied by unit test scaffolds, interface contracts, and DI wiring.

📦 Output Artifact Types¶

Type	Output
Input Adapters	REST controllers, gRPC handlers, MassTransit consumers, etc.
Output Adapters	HTTP clients, repository implementations, blob storage, SDK wrappers
Wiring Code	`AdaptersRegistry.cs`, DI entries, `IServiceCollection.AddAdapters()`
Policy Decorators	Retry handlers, Polly wrappers, circuit breakers
Tracing Hooks	`ActivitySource`-based span injection, baggage propagation
Tests (optional)	In-memory adapters, mocks, unit test templates
Manifest	`adapters-manifest.json`: maps port ↔ adapter ↔ file paths

📁 Example Output Directory Structure¶

/Infrastructure
  /Adapters
    /Controllers
      - UsersController.cs
      - InvoicesController.cs
    /Consumers
      - UserRegisteredConsumer.cs
    /Repositories
      - UserRepository.cs
    /Clients
      - CrmClient.cs
    /Blobs
      - UserPhotoBlobStorage.cs
  /Registrations
    - AdaptersRegistry.cs
/tests
  /Infrastructure.Adapters.Tests
    - UsersControllerTests.cs
    - CrmClientTests.cs

🧾 Sample: `UsersController.cs` (REST Input Adapter)¶

[ApiController]
[Route("api/users")]
public class UsersController : ControllerBase
{
    private readonly ICreateUserHandler _handler;

    public UsersController(ICreateUserHandler handler)
    {
        _handler = handler;
    }

    [HttpPost]
    public async Task<IActionResult> CreateUser([FromBody] CreateUserDto dto, CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("CreateUser");
        var result = await _handler.HandleAsync(dto, ct);
        return Ok(result);
    }
}

🧾 Sample: `CrmClient.cs` (Output Adapter)¶

public class CrmClient : ICrmClient
{
    private readonly HttpClient _httpClient;
    private readonly ILogger<CrmClient> _logger;

    public CrmClient(HttpClient httpClient, ILogger<CrmClient> logger)
    {
        _httpClient = httpClient;
        _logger = logger;
    }

    public async Task PostContactAsync(ContactDto contact, CancellationToken ct)
    {
        using var activity = ActivitySource.StartActivity("PostContactToCRM");
        var response = await _httpClient.PostAsJsonAsync("/contacts", contact, ct);
        response.EnsureSuccessStatusCode();
    }
}

📜 Sample: `adapters-manifest.json`¶

{
  "service": "UserService",
  "environment": "Production",
  "input_adapters": [
    {
      "port": "CreateUserCommand",
      "type": "REST",
      "file": "UsersController.cs"
    }
  ],
  "output_adapters": [
    {
      "port": "ICrmClient",
      "type": "REST",
      "file": "CrmClient.cs"
    }
  ],
  "generated_at": "2025-05-02T03:36:00Z",
  "trace_id": "trace-adapter-78210",
  "agent_version": "1.2.0"
}

📋 Output Validation Rules¶

Rule	Description
All generated files must include `trace_id` in metadata/header	✅
Controller and handler classes must respect port names	✅
REST/gRPC mappings must match route/method defined in OpenAPI	✅
Retry/timeout must match `adapter-policies.yaml`	✅
OTEL spans must be wrapped around all async entrypoints	✅

🧪 Optional Generated Tests¶

UsersControllerTests.cs — controller wiring, HTTP routing
CrmClientTests.cs — client mocking, HTTP expectation
UserRepositoryTests.cs — NHibernate test with in-memory DB

🧠 Knowledge Base Overview¶

The Adapter Generator Agent is backed by a structured and extensible knowledge base that enables it to:

Generate infrastructure adapters for a wide variety of transports and technologies
Apply consistent patterns across REST, gRPC, messaging, persistence, and client integrations
Enforce observability, error handling, retry, and Clean Architecture boundaries
Map abstract application ports to platform-aligned, testable implementations

📚 Adapter Template Knowledge Base¶

Category	Examples
REST Input	`ApiControllerTemplate`, `PostHandlerWithDTO`, `QueryControllerWithRouteBinding`
gRPC	`GrpcUnaryHandlerTemplate`, `GrpcStreamHandlerTemplate`
Messaging Consumers	`MassTransitConsumerTemplate`, `ServiceBusTriggerTemplate`, `KafkaConsumerTemplate`
Repositories	`NHibernateRepositoryTemplate`, `EfCoreRepositoryTemplate`, `MongoRepositoryTemplate`
External API Clients	`HttpClientAdapterTemplate`, `OAuthClientWithRetryTemplate`
Blob Storage	`AzureBlobAdapterTemplate`, `S3AdapterTemplate`
OpenTelemetry Integration	`TracingWrapperTemplate`, `SpanInjectedMethodBlock`
Unit Tests	`ControllerTestTemplate`, `HttpClientTestTemplate`, `RepositoryTestHarness`

🔌 Port-to-Template Matching Rules¶

Input Port Metadata	Mapped Template
`transport: REST` + `method: POST`	`PostHandlerWithDTO.cs.template`
`transport: Kafka` + `input: UserRegisteredMessage`	`MassTransitConsumerTemplate`
`outputPort.type: HttpClient` + `auth: OAuth2`	`OAuthClientWithRetryTemplate`
`outputPort.type: Persistence` + `type: NHibernate`	`NHibernateRepositoryTemplate`

🧠 Semantic Memory Classification¶

Port metadata is stored in memory by:

Port type: input, output, event-driven
Transport: REST, gRPC, Kafka, ServiceBus, Storage, HttpClient
Domain entity: linked to aggregate, event, or value object
Policy tier: resilience: high, auth: none, timeout: strict, logging: verbose
Return semantics: async, task with result, void, event-only

💡 Inferred Behaviors from Memory¶

Heuristic	Result
Ports with `Create` or `Add` names → generate POST REST endpoint
`transport: REST` + `openapi.yaml` → route + HTTP status auto-aligned
If port returns `Task` and has no response DTO → assume `204 NoContent`
Output ports referencing `Blob` → generate Azure Blob client + interface
Any adapter using `HttpClient` → inject retry policy and circuit breaker

📁 Template Library Source¶

Templates are resolved from:

/Templates/Adapters/
  - Rest/
    - ApiControllerTemplate.cs
    - PostHandlerWithDTO.cs
  - Messaging/
    - MassTransitConsumerTemplate.cs
  - Persistence/
    - NHibernateRepositoryTemplate.cs
  - Clients/
    - HttpClientAdapterTemplate.cs
    - OAuthClientWithRetryTemplate.cs
  - Observability/
    - TracingWrapperTemplate.cs

Each template supports parameterized substitution of:

Class name
Port/interface name
DTOs
Transport-specific options (route, headers, topics, keys)
Span trace logic
DI and namespace imports

♻️ Versioned Knowledge Reuse¶

Mechanism	Example
Template versioning	`PostHandlerWithDTO.v2.cs.template`
Policy versioning	Retry policies based on `adapter-policies.yaml@1.2.0`
Transport fallback logic	If `gRPC` not enabled → fallback to REST controller template
DTO reuse	Types resolved from `api-library.csproj` or `domain-types.dtos.cs`

🧩 Extensibility¶

New templates can be added per team/domain (/Templates/Finance/KafkaInvoiceConsumer.cs.template)
Override templates per port if needed (custom-template-id: CrmRetryClientV3)
Injectable formatters for naming, test doubles, OpenAPI expectations

🔄 End-to-End Adapter Generation Flow¶

The Adapter Generator Agent executes a deterministic, policy-driven generation process that transforms abstract port declarations into fully functional adapter code — consistent with Clean Architecture and ConnectSoft platform standards.

This flow is observable, traceable, and testable end-to-end.

📋 Step-by-Step Generation Pipeline¶

1️⃣ Input Loading & Validation¶

Load:
- input-ports.json
- output-ports.json
- transport-config.yaml
- openapi.yaml (optional)
- adapter-policies.yaml
Validate:
- Port ↔ DTO match
- Supported transports enabled
- Forbidden adapter types blocked
- OpenAPI/gRPC routes and methods match expected format

2️⃣ Port Classification and Routing¶

Classification	Result
`CreateOrderCommand → REST`	REST controller template
`UserRegisteredEvent → Kafka`	Messaging consumer template
`ICustomerRepository → NHibernate`	Repository template
`IPaymentGatewayClient → REST (OAuth2)`	Client adapter with token injection

Each port is routed to the appropriate template generator.

3️⃣ Template Rendering¶

Resolve:
- DTOs and method signatures
- Transports (HTTP, Kafka, gRPC)
- Span injection (if otel_tracing: true)
- Retry/circuit breaker policies
- Naming and namespace conventions
Render output files:
- Controllers
- Repositories
- Clients
- Messaging consumers
- Test doubles

4️⃣ Infrastructure Wiring¶

Create or update:
- AdaptersRegistry.cs for DI container registration
- IServiceCollection.AddAdapters() method (auto-discovered adapters)
- Policy decorators for retries/timeouts
- Route mapping (if REST), topic binding (if Kafka), client settings (if HTTP)

5️⃣ Test Harness Injection (Optional)¶

Generate:
- Test class stubs per adapter (UsersControllerTests.cs)
- Mocks or in-memory fakes (FakeUserRepository.cs)
- Contract validation tests (e.g., OpenAPI-based verification)

6️⃣ Tracing and Observability Hooks¶

Inject:
- ActivitySource.StartActivity("AdapterX") in every entrypoint
- Baggage/context propagation
- Serilog logs and structured error handling
- Optional correlation ID headers or OTEL exporters

7️⃣ Manifest & Lifecycle Emission¶

Emit:
- adapters-manifest.json with all generated files
- AdapterGenerationPlanPublished event
- OTEL spans:
  - adapter_generated
  - adapter_transport_matched
  - adapter_policy_applied

🧠 Flowchart: Adapter Generation¶

flowchart TD
    A[Parse Port Definitions] --> B[Match Template]
    B --> C[Render Adapter Files]
    C --> D[Generate Registry & Wiring]
    D --> E[Add OTEL + Retry Policies]
    E --> F[Emit Manifest & Spans]
    F --> G[Publish Lifecycle Event]

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

🔁 Auto-Correction & Resilience Logic¶

Condition	Correction
No transport declared	Default to REST
Retry policy missing	Use platform default from `adapter-policies.yaml`
DTOs missing in API lib	Emit stub with TODO marker
Forbidden adapter type	Block and emit `AdapterGenerationBlocked`
OTEL not enabled but `inject_otel: true`	Inject default spans into controller + client

📈 Telemetry Spans Emitted¶

Span	Trigger
`adapter_generated`	Each adapter successfully scaffolded
`adapter_test_stub_created`	Test output included
`adapter_transport_mapped`	Transport matched and rendered
`adapter_resilience_applied`	Retry/timeouts inserted

🛠️ Semantic Kernel Skills Overview¶

The Adapter Generator Agent is composed of modular Semantic Kernel (.NET) skills that handle:

Port classification and template resolution
Adapter code generation and decoration
Policy injection
Observability wiring
Test scaffold emission
Manifest and trace reporting

All skills are observable, reusable, and configured through the ConnectSoft platform.

🧩 Core Skills Used¶

🧱 1. Port & Transport Mapping¶

Skill	Purpose
`PortClassifierSkill`	Determines if port is REST, gRPC, messaging, or persistence
`TransportTemplateRouterSkill`	Resolves the correct template for each adapter type
`DtoBinderSkill`	Finds and validates input/output DTO types for the adapter
`OpenApiRouteMapperSkill`	Extracts REST path/method from `openapi.yaml`

🧰 2. Adapter Generator Skills¶

Skill	Purpose
`RestControllerGeneratorSkill`	Generates controller from REST port
`GrpcHandlerGeneratorSkill`	Generates gRPC service with contract bindings
`MessagingConsumerGeneratorSkill`	Creates Kafka, MassTransit, or ServiceBus handlers
`RepositoryAdapterGeneratorSkill`	Implements abstract repositories using NHibernate or EF
`HttpClientAdapterGeneratorSkill`	Generates typed client with policies and auth decorators

🔐 3. Policy & Tracing Injectors¶

Skill	Purpose
`RetryPolicyDecoratorSkill`	Applies Polly-based retries and circuit breakers
`OtelSpanInjectorSkill`	Wraps key methods with `ActivitySource` spans
`AuthorizationWrapperSkill`	Adds attribute-based authorization for REST/gRPC
`ExceptionHandlerGeneratorSkill`	Generates try/catch + ProblemDetails responses

🧪 4. Test Scaffold and Fakes¶

Skill	Purpose
`TestStubWriterSkill`	Emits xUnit/MSTest/NUnit test templates per adapter
`FakeAdapterScaffolderSkill`	In-memory mocks for repositories and outbound clients
`ContractValidatorSkill`	Generates OpenAPI/gRPC test assertions for controllers and clients

📄 5. Metadata & Output Coordination¶

Skill	Purpose
`AdaptersManifestWriterSkill`	Emits `adapters-manifest.json` with output trace metadata
`LifecycleEventPublisherSkill`	Emits `AdapterGenerationPlanPublished` event
`TelemetrySpanEmitterSkill`	Traces key lifecycle events during generation
`OutputTraceTaggerSkill`	Injects headers into generated files (trace_id, environment, version)

🧠 Example: Semantic Memory Lookup¶

{
  "type": "input-port",
  "name": "GetUserByIdQuery",
  "transport": "REST",
  "method": "GET",
  "route": "/users/{id}",
  "dto": "UserDto",
  "tracing_enabled": true
}

→ Routed to: - RestControllerGeneratorSkill - OtelSpanInjectorSkill - OpenApiRouteMapperSkill

🔁 Fallback and Retry Behavior¶

Skill	Fallback Trigger	Recovery
`DtoBinderSkill`	DTO missing	Emit scaffold with `TODO` comment and warning
`HttpClientAdapterGeneratorSkill`	No retry config	Use default: 3 retries, 2s timeout
`GrpcHandlerGeneratorSkill`	gRPC not supported	Downgrade to REST controller
`TestStubWriterSkill`	Test output disabled	Skip generation without error

📈 Metrics Emitted Per Skill¶

Metric	Purpose
`adapters_generated_total`	Total generated input/output adapters
`transport_coverage_ratio`	% of ports with valid transport mapping
`otel_wrapped_adapter_ratio`	OTEL span coverage in adapters
`test_templates_emitted_total`	Total unit test stubs created

🧰 Technology Stack Overview¶

The Adapter Generator Agent produces real-world infrastructure adapters using technologies aligned with ConnectSoft’s clean architecture platform. These technologies ensure every adapter is secure, observable, testable, and deployment-ready — across multiple transports.

🌐 Supported Transport Technologies¶

Transport	Technology
REST (HTTP)	ASP.NET Core MVC Controllers, FluentValidation, ProblemDetails
gRPC	gRPC Service Bindings via `Grpc.AspNetCore.Server`
Messaging	MassTransit (Kafka, RabbitMQ, Azure Service Bus), AutoSubscriber, MessageConsumers
Blob/File	Azure Blob Storage SDK, S3 SDK (AWSSDK.S3), `ConnectSoft.BlobAdapter.*`
SQL/ORM	NHibernate, Entity Framework Core, Dapper
External APIs	`HttpClientFactory`, `Refit`, `ConnectSoft.Extensions.Http.OpenIdConnect`
NoSQL	MongoDB.Driver, CosmosDB SDK (planned)

🛠️ Core Libraries and Tools¶

Layer	Library / Tool
Dependency Injection	`Microsoft.Extensions.DependencyInjection`
Resilience	`Polly` for retries, timeouts, circuit breakers
Logging	`Serilog`, `ILogger<T>`, structured log fields
Tracing	`OpenTelemetry`, `ActivitySource`, `Baggage`, `TraceContextPropagator`
Configuration	`IOptions<T>`, environment config bindings
API Modeling	FluentValidation, `System.ComponentModel.DataAnnotations`
Security	`AuthorizeAttribute`, OIDC token handlers, OAuth2 client credentials

🧪 Testing Technologies¶

Type	Tool
Unit Testing	MSTest, xUnit, NUnit (templated)
Mocking	Moq, NSubstitute, in-memory test adapters
Contract Tests	`HttpClientMock`, OpenAPI verifiers (e.g., NSwag)
Integration Stubs	WireMock.Net, TestServer, Docker Compose for isolated adapters

📦 Code Generation and Output Format¶

Output	Details
Adapters	C# classes with DI-conformant constructor injection
Tests	Separate test project or folder, mocks, test harness
Manifests	`adapters-manifest.json` with trace_id, adapter paths, timestamps
Telemetry	Spans and logs embedded in adapters
DI Registration	`AdaptersRegistry.cs` or `.AddAdapters()` extension

🧩 Template Engine & DSLs¶

Component	Description
Template Format	Mustache / Razor Light / Scriban (plug-in support)
Parameter Substitution	Port name, DTOs, namespace, class suffixes
Policy Injection Points	Retry, circuit breaker, tracing, cancellation, auth decorators
Plugin Architecture	Custom template sets per domain/team/microservice cluster

🧬 Cross-Cutting Feature Support¶

Feature	Mechanism
Tracing	OpenTelemetry spans inside each method block
Retry	Polly wrapped inside HttpClientFactory or outbound adapter
Logging	`ILogger<T>` injected into each adapter
Cancellation	All async methods receive `CancellationToken`
Authentication	Adapters support API Key, OAuth2, Azure AD (per `adapter-policies.yaml`)
Output Traceability	Code comments include `trace_id`, `generated_at`, `agent_version`

✅ Integration Compatibility¶

Works With	Example
Microservice Template	Injected into Infrastructure layer (or `Adapters/`)
API Library Generator	Resolves DTOs/interfaces from shared NuGet/API project
DevOps Pipelines	Manifests emitted for test runs, traceability, regression
Observability Stack	Span context linked to service-wide OTEL collector
Adapter Registry	Uses reflection or convention-based scan to inject adapters

🔄 Resolution Algorithm Overview¶

1️⃣ Determine Direction¶

From Input	Result
`input-ports.json` → request entrypoints	→ Generate controller, gRPC handler, or consumer
`output-ports.json` → application dependencies	→ Generate repository, client, publisher, or blob adapter

2️⃣ Resolve Transport Type¶

From Input	Decision
`transport: REST` → controller or HTTP client
`transport: gRPC` → service handler or gRPC client
`transport: Kafka`, `ServiceBus`, etc. → MassTransit consumer
`transport: Persistence` → NHibernate or EF repository
`transport: Blob` → AzureBlob or S3 adapter
`transport: SDK` or `HttpClient` → typed client adapter

3️⃣ Map to Template Type¶

Port Metadata	Template Used
`method: POST`, `dto: CreateUserDto`	`PostHandlerWithDTO`
`type: NHibernate`, `entity: Invoice`	`NHibernateRepositoryTemplate`
`auth: OAuth2`, `base_url:`	`OAuthClientWithRetryTemplate`
`transport: Kafka`, `topic:`	`MassTransitConsumerTemplate`

4️⃣ Inject Decorators Based on Policy¶

Adapter Hint	Decorator
`otel_tracing: true`	Inject `ActivitySource` span blocks
`retries > 0`	Wrap outbound calls with Polly retry logic
`timeout_seconds > 0`	Add timeout wrapper with cancellation
`auth: OAuth2`	Add token handler via `ConnectSoft.Extensions.Http.OpenIdConnect`
`logging_enabled: true`	Inject `ILogger<T>` and structured logs

🧠 Resolution Example¶

{
  "name": "SendInvoiceCommand",
  "transport": "REST",
  "method": "POST",
  "route": "/invoices/send",
  "input": "SendInvoiceDto",
  "output": "InvoiceDto",
  "otel_tracing": true,
  "retries": 2,
  "timeout_seconds": 10
}

→ Results in:

Template: PostHandlerWithDTO
Output: InvoicesController.cs
Decorators: OTEL spans + retry wrapper + timeout token
Registered in: AdaptersRegistry.cs and adapters-manifest.json

🧾 Resolution Manifest Snapshot¶

{
  "port": "ICrmClient",
  "transport": "REST",
  "type": "outbound",
  "template_used": "OAuthClientWithRetryTemplate",
  "policy_applied": ["retry", "timeout", "auth"],
  "generated_file": "CrmClient.cs",
  "trace_id": "trace-adapter-88319"
}

📦 Class Name & File Path Conventions¶

Rule	Format
REST controller → input port `CreateUser`	`UsersController.cs` under `Adapters/Controllers/`
gRPC service → port `GetOrders`	`OrdersGrpcService.cs` under `Adapters/Grpc/`
Kafka consumer → port `OrderPlacedEvent`	`OrderPlacedConsumer.cs` under `Adapters/Consumers/`
Repo → output port `IUserRepository`	`UserRepository.cs` under `Adapters/Repositories/`
Client → output port `INotificationClient`	`NotificationClient.cs` under `Adapters/Clients/`

📐 Output Naming Variants¶

Source Port	Output Adapter
`IInvoiceRepository`	`InvoiceRepository.cs`
`IPaymentProcessor`	`PaymentProcessorClient.cs`
`CreateUserCommand`	`UsersController.cs`
`UserRegisteredEvent`	`UserRegisteredConsumer.cs`
`IBlobStorageAdapter`	`UserBlobStorage.cs`

🧱 Scaffolding Strategy Overview¶

The Adapter Generator Agent emits adapters following a strict directory structure, naming pattern, and Clean Architecture layering — ensuring that:

Each adapter is placed in the right infrastructure folder
All adapters implement a port interface defined in the application layer
DI registration is clean, grouped, and auto-resolvable
Output code is testable, traceable, and extensible

📁 Directory & Namespace Structure¶

🗂️ Standard Folder Layout (within `Infrastructure/Adapters/`)¶

Subfolder	Content
`Controllers/`	REST API controllers for input ports
`Grpc/`	gRPC service handlers
`Consumers/`	Messaging event consumers
`Repositories/`	Concrete implementations of repositories (NHibernate, EF)
`Clients/`	External service API clients
`Blob/`	Adapters for blob/file storage
`Mocks/`	In-memory fakes for testing or sandbox
`Registrations/`	DI container registration (`AdaptersRegistry.cs`)

🧭 Namespace Structure¶

For a service named BillingService:

namespace BillingService.Infrastructure.Adapters.Controllers
{
    public class InvoicesController : ControllerBase { ... }
}

This ensures:

Logical grouping of all adapter types
Easy discoverability for developers and tools
Compatibility with ConnectSoft reflection-based .AddAdapters() loaders

🧩 Class Naming Conventions¶

Port Type	Adapter Class Name
Input port → `CreateUserCommand`	`UsersController` (REST) or `UserService` (gRPC)
Output port → `IUserRepository`	`UserRepository`
Output port → `ICrmClient`	`CrmClient`
Event → `UserRegisteredEvent`	`UserRegisteredConsumer`
Output → `IBlobStorageService`	`UserPhotoBlobAdapter`

🪄 Internal Class Template Structure¶

Every generated adapter follows this internal structure:

// Header
// trace_id, generated_by, timestamp

namespace BillingService.Infrastructure.Adapters.Repositories
{
    public class UserRepository : IUserRepository
    {
        private readonly ISession _session;
        private readonly ILogger<UserRepository> _logger;

        public UserRepository(ISession session, ILogger<UserRepository> logger)
        {
            _session = session;
            _logger = logger;
        }

        public async Task<User?> FindByIdAsync(Guid id, CancellationToken ct)
        {
            using var span = ActivitySource.StartActivity("UserRepository.FindByIdAsync");
            return await _session.GetAsync<User>(id, ct);
        }
    }
}

🛠️ Constructor Pattern (DI-Ready)¶

All adapters are constructor-injected:

Required dependencies (e.g., ILogger<T>, HttpClient, ISession)
Policy-wrapped clients (IPolicyWrappedHttpClient)
DTO mappers, value resolvers
Token providers, cache accessors if needed

🔧 Registration Strategy¶

Mechanism	Output
`AdaptersRegistry.cs`	Explicit `.AddTransient<IUserRepository, UserRepository>()`
`.AddAdapters()` extension	Auto-scans namespace and registers adapters by convention
`adapters-manifest.json`	Lists DI registrations for audit and downstream CI/CD injection

🧾 Sample: `AdaptersRegistry.cs`¶

public static class AdaptersRegistry
{
    public static IServiceCollection AddAdapters(this IServiceCollection services)
    {
        services.AddTransient<IUserRepository, UserRepository>();
        services.AddHttpClient<ICrmClient, CrmClient>();
        services.AddMassTransitConsumer<UserRegisteredConsumer>();
        return services;
    }
}

📁 Optional: Test Folder Strategy¶

Adapters may generate test stubs into:

/tests
  /BillingService.Infrastructure.Adapters.Tests
    - UsersControllerTests.cs
    - CrmClientTests.cs
    - UserRepositoryTests.cs

🔍 Output Metadata & Tracing¶

Each adapter includes a header block like:

// Generated by Adapter Generator Agent v1.2.0
// trace_id: trace-adapter-55191
// service: BillingService
// environment: Production
// generated_at: 2025-05-02T03:45:00Z

🔄 Extensibility Strategy¶

The Adapter Generator Agent is designed to support extensibility at multiple levels, enabling teams to introduce:

New transport types (e.g., Redis Pub/Sub, MQTT, GraphQL)
Custom organization-specific templates
Domain-specific adapter variants (e.g., healthcare, finance)
Runtime or compile-time overrides (plugin-based injection)

This ensures ConnectSoft’s AI Software Factory can adapt across industries, teams, and cloud environments.

🧩 Adapter Plugin Architecture¶

📦 Plugin Format¶

A plugin is a self-contained directory with:

/Plugins/CustomKafkaAdapter/
  - template.cs               # The code template
  - metadata.yaml             # Port/transport match rules
  - decorators.cs             # Optional behavior injection

📘 `metadata.yaml` Example¶

transport: kafka
port_suffix: Event
custom_namespace: Acme.Finance.Adapters
target_template: CustomKafkaConsumerTemplate.cs
decorators:
  - tracing
  - json-deserialization
  - error-logging

🔌 Supported Extension Points¶

Layer	Extensible?	Mechanism
Templates	✅	Plug-in folders or template registry
Decorator behavior	✅	Decorator chain injected before rendering
DI registration logic	✅	Plugin can override `.AddAdapters()` entries
Port-to-transport mapping	✅	Metadata rules or YAML configuration
DTO formatting or binding	✅	Pluggable DTO formatters
Test strategy	✅	Custom `TestStubWriterSkill` injection

🛠️ Transport Type Extensions (Examples)¶

Transport	Plugin Type	Notes
Redis Streams	`RedisConsumerTemplate`	Used for telemetry events
GraphQL	`GraphQLMutationControllerTemplate`	Maps `Create*Command` ports to mutations
MQTT	`MqttHandlerTemplate`	Supports IoT adapters in medical and smart building microservices
AWS Lambda	`LambdaFunctionTemplate`	Generates handler for serverless mode
Azure Functions	`ServiceBusTriggerFunctionTemplate`	Used in cost-optimized async pipelines

🧬 Template Override Rules¶

Behavior	Rule
Global override	`override_template: true` in `adapter-policies.yaml`
Per-port override	`template_id: CustomKafkaInvoiceConsumer` in `output-ports.json`
Per-service plugin path	`plugins: ["./Plugins/Healthcare/"]` in `transport-config.yaml`
Environment-specific	Fallback to dev template if `env != Production`

🧪 Dynamic Template Evaluation (If Enabled)¶

Supports Scriban or RazorLight engines
Can evaluate conditionals: {{ if transport == "Kafka" }} ... {{ end }}
DTOs, method names, and policy values passed as variables
Enables on-the-fly template mutation based on policy metadata

🧱 Custom Transport Definition Example¶

custom_transports:
  - name: redis-pubsub
    input_type: RedisMessage
    adapter_template: RedisPubSubConsumerTemplate.cs
    options:
      deserialize_json: true
      span_wrapping: true
      ack_mode: manual

🧰 Adapter Test Strategy Extensions¶

Option	Description
`generate_test_stubs: true`	Default behavior — emits MSTest/xUnit files
`template_id: InMemoryClientTestTemplate`	Uses domain-specific test format
`plugin_test_writer: HealthcareContractValidator`	Injects external test strategy
`mocking_framework: NSubstitute`	Overrides default `Moq` usage

🧩 Collaboration With Plugin Registry¶

Adapters can register plugin templates centrally using:
- plugin-registry.yaml (global across platform)
- Per-domain plugin packs (e.g., /Finance/, /EHR/, /Retail/)

✅ Validation and Test-Readiness Overview¶

The Adapter Generator Agent enforces rigorous validation and emits test-scaffolded, production-grade infrastructure adapters. Its goal is to ensure that every adapter:

Implements a valid application port
Matches the declared transport and method
Compiles cleanly and passes linting/static analysis
Is unit-testable by design
Optionally includes test harnesses, mocks, or contract tests

🧪 Validation Phases¶

1️⃣ Port & Transport Validation¶

Rule	Check
Port exists in application layer	✅ Interface resolved
Transport is supported and enabled	✅ Checked against `transport-config.yaml`
Method/route matches OpenAPI (if REST)	✅ Route → controller signature verification
Input/Output DTOs are valid and serializable	✅ Reflection-based check if DTOs are found in API/library

2️⃣ Template & Decorator Resolution¶

Rule	Check
Template file exists and matches transport	✅ Enforced before render
Required decorators (span, retry, etc.) are injectable	✅ Checked against `adapter-policies.yaml`
OTEL span wrapping adheres to platform format	✅ `ActivitySource` injection validated

3️⃣ Code Safety Rules¶

Rule	Enforced Behavior
Constructor DI only — no static or service locator	✅ Template-generated only via DI
Exception handling required on all outbound I/O	✅ Try-catch + `ProblemDetails` required for REST
CancellationToken must be propagated	✅ All methods check `ct.IsCancellationRequested`
Logging via `ILogger<T>` is structured	✅ All logs use `LogContext`, `Serilog` formatting

📄 Testability Checks¶

Validation	Description
Adapter implements testable interface	e.g., `IUserRepository`, `ICrmClient`
Mockable dependencies injected via DI	No static clients or `new` calls inside
DTOs are POCO and serializer-safe	Checks JSON compatibility and constructor validity
Span names are stable and traceable	e.g., `UserRepository.FindById` should emit OTEL span with tag `adapter_name`
Retry/circuit-breaker parameters mockable	All resilience features testable with mocks or overrides

🧪 Optional: Test Stub Emission¶

Feature	Output
Unit Test Class	xUnit/MSTest/NUnit stub with `[Fact]` / `[TestMethod]`
Fake Repository	`InMemoryUserRepository.cs` for in-memory persistence
Mock Registration	`services.AddMock<ICrmClient>(new CrmClientStub());`
TestData DTO	`SampleUserDtoFactory.cs` for test models

🧾 Sample: `UsersControllerTests.cs`¶

[TestClass]
public class UsersControllerTests
{
    [TestMethod]
    public async Task CreateUser_ShouldReturnOk()
    {
        var mockHandler = new Mock<ICreateUserHandler>();
        mockHandler.Setup(x => x.HandleAsync(It.IsAny<CreateUserDto>(), It.IsAny<CancellationToken>()))
            .ReturnsAsync(new UserDto());

        var controller = new UsersController(mockHandler.Object);
        var result = await controller.CreateUser(new CreateUserDto(), CancellationToken.None);

        Assert.IsInstanceOfType(result, typeof(OkObjectResult));
    }
}

📋 Manifest Validation Example¶

{
  "port": "ICrmClient",
  "status": "validated",
  "test_ready": true,
  "compiled": true,
  "otel_wrapped": true,
  "trace_id": "trace-adapter-99333"
}

🧠 Auto-Correction Examples¶

Validation Failure	Auto-Fix
Missing retry policy	Inject default from `adapter-policies.yaml`
Port not found in app layer	Emit warning + skip adapter
DTO not found	Emit placeholder DTO with `// TODO: Implement`
gRPC not enabled	Fallback to REST controller adapter
CancellationToken not passed	Auto-inject into method signature

📡 Observability Strategy¶

The Adapter Generator Agent injects OpenTelemetry spans, structured logging, and resilience telemetry into every generated adapter — enabling full end-to-end traceability across microservices, message pipelines, and third-party integrations.

It ensures adapters are not black boxes, but fully instrumented infrastructure boundaries.

📈 OpenTelemetry Span Injection¶

✅ Core Behavior¶

Adapter Type	Span Behavior
Controllers	Wrap HTTP handler in `ActivitySource.StartActivity()`
gRPC Handlers	Trace `UnaryServerMethod<T>` via `Activity`
Message Consumers	Trace `ConsumeContext<T>` from MassTransit or Kafka
Repositories	Trace each method (`FindByIdAsync`, `SaveAsync`) with entity tag
API Clients	Trace each outbound call, including retries and circuit breakers
Blob Storage	Span for `UploadAsync`, `DownloadAsync`, tagged with blob type/key

📊 Span Fields¶

Each span includes:

{
  "adapter_name": "UserRepository",
  "adapter_type": "repository",
  "transport": "persistence",
  "port": "IUserRepository",
  "trace_id": "trace-adapter-11209",
  "retry_attempts": 1,
  "circuit_open": false,
  "duration_ms": 17,
  "otel_status": "OK"
}

🔖 Tags Applied¶

Tag	Source
`service.name`	Microservice context
`adapter.name`	Class name
`adapter.port`	Port interface
`adapter.transport`	REST, Kafka, Persistence, etc.
`span.kind`	`server` or `client`
`trace_id`	From `input-ports.json` or injected

📜 Structured Logging¶

Logger injected into every adapter via ILogger<T>
Logs tagged with:
- trace_id, span_id
- adapter_name, port_name
- correlation_id (if inbound message has one)

_logger.LogInformation("Sending invoice to CRM {@InvoiceId}", invoice.Id);

🧪 Tracing for Resilience Features¶

Feature	Span Annotation
Retry	`retry_attempts`, `retry_policy_name`
Timeout	`timeout_duration`, `cancelled`
Circuit Breaker	`circuit_open: true/false`
Failure	`otel_status: Error`, with exception details

🧠 Sample: Adapter-Level Span in Controller¶

using var activity = ActivitySource.StartActivity("CreateUserHandler");
activity?.SetTag("adapter.name", "UsersController");
activity?.SetTag("port", "CreateUserCommand");
activity?.SetTag("transport", "REST");

🔁 Output Integration¶

otel-agent-config.yaml updated with required exporters if missing
Adapters respect existing Activity.Current → preserve parent span from upstream requests
Logs/metrics sent to:
- OTLP exporter (default)
- Azure Monitor / Application Insights (via OTEL bridge)
- Custom sinks if declared in policies

📋 Validation & Auto-Correction¶

Check	Behavior
Span missing in method	Auto-inject `ActivitySource` block
No `ILogger<T>` present	Inject logger + log startup and error
Missing correlation ID	Attempt to extract from headers/context
OTEL exporter not defined	Inject default OTLP export config into `otel-agent-config.yaml`
Retry not emitting span	Wrap retry in span child block with attempt counter

📢 Span Emission Lifecycle¶

Event	Span
Adapter generation complete	`adapter_generated`
Span successfully injected	`adapter_span_ready`
Retry triggered	`adapter_retry_attempted`
Failure captured	`adapter_error`

✅ Output Guarantees¶

Feature	Included
`ActivitySource` span in each adapter	✅
`ILogger<T>` for all logging	✅
Policy telemetry via OTEL	✅
Structured logging fields	✅
Optional integration to App Insights / Grafana / Jaeger	✅ (via config)

🤝 Collaboration Overview¶

The Adapter Generator Agent sits at the convergence point between architecture (ports) and infrastructure (transport). It collaborates with upstream agents to resolve ports and policies, and serves downstream agents by delivering adapters ready for execution, testing, deployment, and tracing.

🔼 Upstream Collaborators¶

Agent	Provides
Application Architect Agent	`input-ports.json`, `output-ports.json`, domain boundaries
API Designer Agent	`openapi.yaml`, `grpc.proto`, transport surface hints
Library Generator Agent	DTOs and interfaces used inside adapters
Solution Architect Agent	Environment-level policies and `transport-config.yaml`
Security Architect Agent	Authentication strategy (e.g., OAuth2, API Key), scope injection
Observability Agent	OTEL config, span routing strategy
Platform Configuration Service	Default retry/timeouts from `adapter-policies.yaml`

🔽 Downstream Consumers¶

Agent	Consumes
Microservice Generator	Integrates generated adapters into Infrastructure project layout
DevOps Architect Agent	Uses `adapters-manifest.json` for test validation, CI/CD injection
Observability Agent	Extends or adjusts OTEL span mapping, trace IDs, exporters
Test Generator Agent	Uses adapter metadata to generate or validate test coverage
Runtime Orchestrator	Auto-registers adapters via `.AddAdapters()` or reflection scanning
Security Compliance Agent	Audits outbound adapters for token usage, scope policies

🧠 Shared Artifacts & Interfaces¶

Artifact	Shared With
`AdaptersRegistry.cs`	DevOps, Runtime Agent
`adapters-manifest.json`	DevOps, Test Agent, Observability Agent
`otel-agent-config.yaml` (extended)	Observability Agent
`trace_id` in file headers	Used by all tracing + validation agents
`controller`, `repository`, and `client` class names	Used by Microservice Generator for integration

🧭 Agent Integration Flow¶

flowchart TD
    AppArchitect --> AdapterGen
    ApiDesigner --> AdapterGen
    SolutionArchitect --> AdapterGen
    SecurityArchitect --> AdapterGen
    ObservabilityAgent --> AdapterGen

    AdapterGen --> MicroserviceGenerator
    AdapterGen --> DevOpsAgent
    AdapterGen --> ObservabilityAgent
    AdapterGen --> TestGeneratorAgent

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

🧩 DI Integration Points¶

Mechanism	Used By
`AdaptersRegistry.cs`	Service-level composition root
`.AddAdapters()`	Reflection-based scanning of namespace
`IServiceCollection.AddHttpClient<T>`	Outbound adapter registration
`services.AddMassTransitConsumer<T>()`	Message consumer registration
`ConfigureAdapterPolicies()`	Injects retry/timeouts per policy YAML

📢 Event Signals & Span Interfaces¶

Signal	Sent To
`AdapterGenerationPlanPublished`	Orchestrator, DevOps
`AdapterTransportMismatch`	Validation and API Designer Agent
`AdapterTraceInjected`	Observability and OTEL Agent
`AdapterTestReady`	Test Generator Agent

🔄 Traceability & Cross-Agent Flow¶

Every adapter includes:

trace_id (aligned across lifecycle)
agent_version
generated_at
port → adapter → file mapping
registered_services metadata

📡 Observability & Oversight¶

The Adapter Generator Agent is fully instrumented and monitored through OpenTelemetry, event signals, and metadata tracking, ensuring all infrastructure adapters are:

Traceable
Testable
Auditable
Recoverable
CI/CD-ready

📈 Spans Emitted During Execution¶

Span	Description
`adapter_generated`	Emitted per adapter created (controller, consumer, repo, client)
`adapter_template_matched`	Logs the port-to-template mapping decision
`adapter_retry_policy_applied`	Marks retry/circuit injection in outbound adapters
`adapter_tracing_wrapped`	Confirms OTEL `ActivitySource` inserted
`adapter_manifest_emitted`	When `adapters-manifest.json` is created and validated

All spans include:

trace_id
agent_version
port_name, adapter_type, transport
duration_ms, template_id, output_path

📄 Lifecycle Event Signals¶

Event	Consumers
`AdapterGenerationPlanPublished`	Microservice Generator, DevOps Agent
`AdapterTransportMismatch`	API Designer Agent (surface mismatch)
`AdapterGenerationBlocked`	Platform Orchestrator (e.g., forbidden adapter type)
`AdapterTestStubEmitted`	Test Generator Agent
`AdapterOTELTraceReady`	Observability Agent
`AdapterValidationSummaryReady`	DevOps Pipeline Validator

🧪 CI/CD Pipeline Integration¶

adapters-manifest.json included in build artifacts
Each adapter file stamped with:
- trace_id
- generated_at
- port_name
- agent_version
Supports:
- Code diff detection
- Test stub matching
- Span continuity validation

📊 Dashboard Integration¶

Metric	Visualization
Adapters by transport type	Pie or stacked bar chart
Retry/circuit-breaker coverage	Ratio, trendline
Adapter test readiness score	Pass/fail by adapter
OTEL span coverage	% of adapters wrapped
Compliance adapters generated	Count by auth method (API Key, OAuth2, etc.)

🛡️ Security Oversight¶

Adapter policies enforce authentication decorators ([Authorize], OAuth2Handler)
Logs redacted of sensitive info (PII, secrets)
Adapters generating external calls include:
- Token injection tracing
- Endpoint logging with domain-level tagging
- Enforced timeouts and circuit policies

📋 Example Audit Trace (Snippet)¶

{
  "trace_id": "trace-adapter-44418",
  "port": "ICrmClient",
  "adapter_class": "CrmClient",
  "transport": "REST",
  "template": "OAuthClientWithRetryTemplate",
  "otel_wrapped": true,
  "retries": 3,
  "test_stub_created": true,
  "status": "success"
}

✅ Agent Impact Summary¶

Capability	Delivered
🔧 Clean Architecture adapter generation	✅
🔌 REST, gRPC, Kafka, Storage, API clients	✅
🔁 Retry, circuit breaker, timeout injection	✅
📈 Full OTEL and structured logging support	✅
🧪 Testability and CI/CD integration	✅
📢 Lifecycle events and traceability	✅
⚙️ Plugin-based extensibility and overrides	✅
🧩 DI, manifest, and environment readiness	✅

🧭 Final Thought¶

The Adapter Generator Agent enables the ConnectSoft platform to produce fully connected, policy-compliant, and infrastructure-ready microservices — transforming abstract ports into production-ready, test-validated adapters across protocols, clouds, and integration boundaries.

It acts as the bridge between clean architecture and real-world deployment — ensuring consistency, resilience, and observability at scale.

🔌 Adapter Generator Agent Specification¶

🎯 Purpose¶

🧱 Why This Agent Is Critical¶

🧠 Examples of Adapter Generation¶

🧭 Architectural Placement¶

🔄 Adapter Generator’s Strategic Role¶

📡 Scope of Influence¶

🧱 What This Agent Owns¶

🧩 Adapter Placement in Clean Architecture¶

🧠 What This Agent Does Not Own¶

☁️ Supported Transport & Infrastructure Types¶

🧬 Adapter Classification (by Direction)¶

🔁 Dynamic Composition¶

📋 Core Responsibilities¶

✅ 1. Adapter Scaffolding from Port Definitions¶

🔌 2. Transport-Specific Adapter Generation¶

🔄 3. Boundary Enforcement¶

🔐 4. Cross-Cutting Concern Injection¶

🔍 5. Testability Enforcement¶

📦 6. Modular Output Integration¶

🧠 Adapter Examples¶

📈 Responsibility to Span Relationship¶

📤 Core Output Overview¶

📦 Output Artifact Types¶

📁 Example Output Directory Structure¶

🧾 Sample: UsersController.cs (REST Input Adapter)¶

🧾 Sample: CrmClient.cs (Output Adapter)¶

📜 Sample: adapters-manifest.json¶

📋 Output Validation Rules¶

🧪 Optional Generated Tests¶

🧠 Knowledge Base Overview¶

📚 Adapter Template Knowledge Base¶

🔌 Port-to-Template Matching Rules¶

🧠 Semantic Memory Classification¶

💡 Inferred Behaviors from Memory¶

📁 Template Library Source¶

♻️ Versioned Knowledge Reuse¶

🧩 Extensibility¶

🔄 End-to-End Adapter Generation Flow¶

📋 Step-by-Step Generation Pipeline¶

1️⃣ Input Loading & Validation¶

2️⃣ Port Classification and Routing¶

3️⃣ Template Rendering¶

4️⃣ Infrastructure Wiring¶

5️⃣ Test Harness Injection (Optional)¶

6️⃣ Tracing and Observability Hooks¶

7️⃣ Manifest & Lifecycle Emission¶

🧠 Flowchart: Adapter Generation¶

🔁 Auto-Correction & Resilience Logic¶

📈 Telemetry Spans Emitted¶

🛠️ Semantic Kernel Skills Overview¶

🧩 Core Skills Used¶

🧱 1. Port & Transport Mapping¶

🧰 2. Adapter Generator Skills¶

🔐 3. Policy & Tracing Injectors¶

🧪 4. Test Scaffold and Fakes¶

📄 5. Metadata & Output Coordination¶

🧠 Example: Semantic Memory Lookup¶

🔁 Fallback and Retry Behavior¶

📈 Metrics Emitted Per Skill¶

🧰 Technology Stack Overview¶

🌐 Supported Transport Technologies¶

🛠️ Core Libraries and Tools¶

🧪 Testing Technologies¶

📦 Code Generation and Output Format¶

🧩 Template Engine & DSLs¶

🧬 Cross-Cutting Feature Support¶

✅ Integration Compatibility¶

🔄 Resolution Algorithm Overview¶

1️⃣ Determine Direction¶

2️⃣ Resolve Transport Type¶

3️⃣ Map to Template Type¶

4️⃣ Inject Decorators Based on Policy¶

🧠 Resolution Example¶

🧾 Resolution Manifest Snapshot¶

📦 Class Name & File Path Conventions¶

📐 Output Naming Variants¶

🧱 Scaffolding Strategy Overview¶

📁 Directory & Namespace Structure¶

🗂️ Standard Folder Layout (within Infrastructure/Adapters/)¶

🧾 Sample: `UsersController.cs` (REST Input Adapter)¶

🧾 Sample: `CrmClient.cs` (Output Adapter)¶

📜 Sample: `adapters-manifest.json`¶

🗂️ Standard Folder Layout (within `Infrastructure/Adapters/`)¶

🧾 Sample: `AdaptersRegistry.cs`¶

📘 `metadata.yaml` Example¶

🧾 Sample: `UsersControllerTests.cs`¶