Architecture Principles¶
These principles are non-negotiable across all twelve platforms. They are the ConnectSoft principles applied to an AI-native software factory. The existing Core Design Principles describe them in depth; this page states how they bind the final-state architecture.
The principles¶
| Principle | What it means for the factory |
|---|---|
| Clean Architecture | Every factory and generated service uses the MicroserviceTemplate layering: domain at the core, dependencies pointing inward. |
| Domain-Driven Design | Each platform is decomposed into bounded contexts with explicit aggregate roots, ubiquitous language, and context maps. |
| Event-Driven Architecture | Meaningful actions emit events in the canonical envelope on MassTransit / Azure Service Bus. |
| Observability-First | Logs, metrics, and traces are designed in; every action carries traceId. See Observability Architecture. |
| Cloud-Native | Horizontally scalable, self-healing, distributed; AKS / Container Apps / Functions on Azure. |
| Multi-Tenant SaaS | Tenant isolation and quotas are built into every platform via ConnectSoft.Extensions.Saas.*. |
| Security-First | OAuth2/JWT, RBAC/ABAC, tenant guards, secret references, audit on every sensitive action. |
| Modular, composable, reusable | Everything reusable becomes a module; templates and libraries are first-class. |
| Agentic AI orchestration | Specialized agents collaborate through tasks, events, artifacts, memory, and governance. |
| Traceability idea → runtime feedback | A single traceId spans the whole lifecycle and closes the improvement loop. |
Technology grounding¶
The principles are realized with the real ConnectSoft stack:
| Concern | Choice | Grounding |
|---|---|---|
| Runtime | .NET 10, ASP.NET Core | MicroserviceTemplate |
| Messaging | MassTransit on Azure Service Bus (NServiceBus supported alternative) | FlowModel.*, ConnectSoft.Extensions.MessagingModel.* |
| Agent runtime | Microsoft Agent Framework + Microsoft.Extensions.AI + MCP | AgentTemplate, ConnectSoft.Extensions.AI.AgentsFramework |
| Frontend | Blazor MFE (Shell + Microfrontend Library + UIKit); MAUI mobile | ConnectSoft.Blazor.*, ConnectSoft.MauiBaseTemplate |
| Identity | OpenIddict | ConnectSoft.AuthorizationServerTemplate, IdentityTemplate |
| Persistence | NHibernate on Azure SQL/PostgreSQL; Cosmos for documents; Blob for artifacts; Redis for hot cache | ConnectSoft.Extensions.PersistenceModel.* |
| Vector memory | Qdrant (primary), Azure AI Search (managed alternative) | Knowledge Platform |
| Observability | Serilog + OpenTelemetry + Application Insights | ConnectSoft.Extensions.Observability |
| GitOps | Azure DevOps (primary), GitHub (optional) | ConnectSoft.AzurePipelines |
| IaC | Pulumi | DevOps / GitOps Platform |
Implementation Notes
Microsoft Agent Framework (Microsoft.Agents.AI.*) is the agent runtime — not Semantic Kernel. IaC is Pulumi — Bicep appears only where legacy infrastructure still uses it. These choices are canonical across all final-state docs.
API and worker principles¶
- REST for management APIs, gRPC for internal high-throughput service-to-service calls, events for async workflows.
- OpenAPI for REST docs, ProblemDetails for errors, idempotency keys for worker-triggered operations.
- Every worker documents trigger, input, idempotency, retry, poison handling, output events, telemetry, and owned state. See Documentation Standards.