Solution Structure in ConnectSoft Microservice Template¶

Purpose & Overview¶

The Solution Structure of the ConnectSoft Microservice Template organizes projects following Clean Architecture principles, ensuring clear separation of concerns, dependency management, and modularity. The solution is designed to enforce architectural boundaries through both project organization and automated architecture tests, enabling teams to build maintainable, testable, and scalable microservices.

The solution structure provides:

Clean Architecture Enforcement: Projects organized by architectural layers with strict dependency rules
Modularity: Each feature area (persistence, messaging, actors, APIs) is a separate project
Technology Flexibility: Technology-specific implementations are isolated (e.g., NHibernate vs MongoDB)
Testability: Clear separation enables independent testing of each layer
Scalability: New features and technologies can be added without affecting existing code
Maintainability: Clear project organization makes it easy to understand and navigate the codebase

Solution Structure Philosophy

The solution structure is the foundation of Clean Architecture. Projects are organized by architectural layers, with dependencies flowing inward—presentation depends on application, application depends on domain, and infrastructure implements abstractions. This structure is enforced through automated architecture tests that prevent dependency violations at build time.

Solution Organization¶

High-Level Structure¶

The solution is organized into logical groups that align with Clean Architecture layers:

ConnectSoft.MicroserviceTemplate/
├── Common/              # Shared libraries (constants, options, metrics)
├── Domain/              # Domain layer (entities, domain logic)
├── Persistence/         # Persistence layer (repositories, migrations)
├── Messaging/           # Messaging layer (commands, events, sagas)
├── ActorModel/          # Actor model implementations
├── Scheduler/           # Background job scheduling
├── ServiceModel/        # Presentation layer (APIs, DTOs)
├── AI/                  # AI-driven features
├── Bot/                 # Microsoft Bot Framework
├── Application/         # Application host and DI configuration
├── Infrastructure/      # Infrastructure as Code
├── Testing/             # Test projects (unit, integration, architecture)
└── Architecture/        # Architecture modeling and diagrams

Solution File Structure¶

The solution contains multiple projects organized by architectural concerns:

ConnectSoft.MicroserviceTemplate.sln
├── ConnectSoft.MicroserviceTemplate (Base library)
├── ConnectSoft.MicroserviceTemplate.Options
├── ConnectSoft.MicroserviceTemplate.Metrics
├── ConnectSoft.MicroserviceTemplate.EntityModel
├── ConnectSoft.MicroserviceTemplate.DomainModel
├── ConnectSoft.MicroserviceTemplate.DomainModel.Impl
├── ConnectSoft.MicroserviceTemplate.PersistenceModel
├── ConnectSoft.MicroserviceTemplate.PersistenceModel.NHibernate
├── ConnectSoft.MicroserviceTemplate.PersistenceModel.MongoDb
├── ConnectSoft.MicroserviceTemplate.DatabaseModel.Migrations
├── ConnectSoft.MicroserviceTemplate.DatabaseModel.MongoDb.Migrations
├── ConnectSoft.MicroserviceTemplate.MessagingModel
├── ConnectSoft.MicroserviceTemplate.FlowModel
├── ConnectSoft.MicroserviceTemplate.FlowModel.MassTransit
├── ConnectSoft.MicroserviceTemplate.FlowModel.NServiceBus
├── ConnectSoft.MicroserviceTemplate.ActorModel
├── ConnectSoft.MicroserviceTemplate.ActorModel.Orleans
├── ConnectSoft.MicroserviceTemplate.ActorModel.Akka
├── ConnectSoft.MicroserviceTemplate.ActorModel.Dapr
├── ConnectSoft.MicroserviceTemplate.SchedulerModel
├── ConnectSoft.MicroserviceTemplate.SchedulerModel.Hangfire
├── ConnectSoft.MicroserviceTemplate.SchedulerModel.Quartz
├── ConnectSoft.MicroserviceTemplate.ServiceModel
├── ConnectSoft.MicroserviceTemplate.ServiceModel.RestApi
├── ConnectSoft.MicroserviceTemplate.ServiceModel.Grpc
├── ConnectSoft.MicroserviceTemplate.ServiceModel.GraphQL
├── ConnectSoft.MicroserviceTemplate.ServiceModel.SignalR
├── ConnectSoft.MicroserviceTemplate.ServiceModel.CoreWCF
├── ConnectSoft.MicroserviceTemplate.ServiceModel.ServiceFabric
├── ConnectSoft.MicroserviceTemplate.ServiceModel.AzureFunction
├── ConnectSoft.MicroserviceTemplate.BotModel
├── ConnectSoft.MicroserviceTemplate.AgentFramework
├── ConnectSoft.MicroserviceTemplate.AIModel
├── ConnectSoft.MicroserviceTemplate.ModelContextProtocol
├── ConnectSoft.MicroserviceTemplate.ApplicationModel
├── ConnectSoft.MicroserviceTemplate.Application
├── ConnectSoft.MicroserviceTemplate.DockerCompose
├── ConnectSoft.MicroserviceTemplate.InfrastructureModel
├── ConnectSoft.MicroserviceTemplate.AcceptanceTests
├── ConnectSoft.MicroserviceTemplate.UnitTests
├── ConnectSoft.MicroserviceTemplate.ArchitectureTests
├── ConnectSoft.MicroserviceTemplate.ArchitectureModel
└── ConnectSoft.MicroserviceTemplate.DiagramAsCodeModel

Project Organization by Layer¶

Common Layer¶

Purpose: Shared libraries used across all layers.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate`	Base constants, exceptions, common helpers	None (base library)
`ConnectSoft.MicroserviceTemplate.Options`	Configuration options and structures	Base project
`ConnectSoft.MicroserviceTemplate.Metrics`	Domain metrics definitions	Base project

Characteristics: - No business logic - Framework-agnostic - Shared across all layers - Contains common constants, exceptions, and utilities

Domain Layer¶

Purpose: Core business logic and domain entities.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.EntityModel`	Entity contracts, aggregates, value objects, enumerations	Base project
`ConnectSoft.MicroserviceTemplate.DomainModel`	Domain interfaces, use case contracts, domain events	EntityModel
`ConnectSoft.MicroserviceTemplate.DomainModel.Impl`	Domain service implementations, processors, retrievers, validators	DomainModel, PersistenceModel (interfaces only)

Characteristics: - Zero dependencies on infrastructure - Pure business logic - Framework-agnostic - Testable in isolation

Project Structure:

EntityModel/
├── Entities/
│   └── MicroserviceAggregateRootEntity.cs
├── ValueObjects/
└── Enumerations/

DomainModel/
├── Interfaces/
│   ├── IMicroserviceAggregateRootsProcessor.cs
│   └── IMicroserviceAggregateRootsRetriever.cs
├── Input Models/
│   └── CreateMicroserviceAggregateRootInput.cs
├── Output Models/
└── Exceptions/

DomainModel.Impl/
├── Processors/
│   └── DefaultMicroserviceAggregateRootsProcessor.cs
├── Retrievers/
│   └── DefaultMicroserviceAggregateRootsRetriever.cs
└── Validators/
    └── CreateMicroserviceAggregateRootInputValidator.cs

Persistence Layer¶

Purpose: Data persistence and repository implementations.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.PersistenceModel`	Repository interfaces, specification contracts	DomainModel
`ConnectSoft.MicroserviceTemplate.PersistenceModel.NHibernate`	NHibernate-based repository implementations	PersistenceModel, EntityModel
`ConnectSoft.MicroserviceTemplate.PersistenceModel.MongoDb`	MongoDB-based repository implementations	PersistenceModel, EntityModel
`ConnectSoft.MicroserviceTemplate.DatabaseModel.Migrations`	SQL database migrations (FluentMigrator)	PersistenceModel
`ConnectSoft.MicroserviceTemplate.DatabaseModel.MongoDb.Migrations`	MongoDB migrations	PersistenceModel

Characteristics: - Implements interfaces defined in DomainModel - Technology-specific implementations isolated - No dependencies on presentation layer - Supports multiple persistence technologies

Project Structure:

PersistenceModel/
├── Repositories/
│   └── IMicroserviceAggregateRootsRepository.cs
└── Specifications/

PersistenceModel.NHibernate/
├── Repositories/
│   └── MicroserviceAggregateRootsRepository.cs
└── Mappings/
    └── MicroserviceAggregateRootEntityMap.cs

PersistenceModel.MongoDb/
├── Repositories/
│   └── MicroserviceAggregateRootsMongoDbRepository.cs
└── Mappings/
    └── MicroserviceAggregateRootEntityMap.cs

Messaging Layer¶

Purpose: Event-driven messaging and flow orchestration.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.MessagingModel`	Message contracts (commands, events, queries)	DomainModel
`ConnectSoft.MicroserviceTemplate.FlowModel`	Saga contracts and flow orchestration	MessagingModel
`ConnectSoft.MicroserviceTemplate.FlowModel.MassTransit`	MassTransit-based saga implementations	FlowModel
`ConnectSoft.MicroserviceTemplate.FlowModel.NServiceBus`	NServiceBus-based saga implementations	FlowModel

Characteristics: - Message contracts defined in inner layers - Technology-specific implementations in separate projects - Supports multiple messaging frameworks

Actor Model Layer¶

Purpose: Virtual actor implementations for stateful, distributed computing.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.ActorModel`	Actor interfaces and contracts	DomainModel
`ConnectSoft.MicroserviceTemplate.ActorModel.Orleans`	Orleans grain implementations	ActorModel
`ConnectSoft.MicroserviceTemplate.ActorModel.Akka`	Akka.NET actor implementations	ActorModel
`ConnectSoft.MicroserviceTemplate.ActorModel.Dapr`	Dapr actor implementations	ActorModel

Characteristics: - Actor interfaces defined in ActorModel - Technology-specific implementations isolated - Supports multiple actor frameworks

Scheduler Layer¶

Purpose: Background job scheduling and execution.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.SchedulerModel`	Scheduler abstractions and contracts	DomainModel
`ConnectSoft.MicroserviceTemplate.SchedulerModel.Hangfire`	Hangfire-based job implementations	SchedulerModel
`ConnectSoft.MicroserviceTemplate.SchedulerModel.Quartz`	Quartz.NET-based job implementations	SchedulerModel

Characteristics: - Scheduler contracts defined in inner layers - Technology-specific implementations isolated - Supports multiple scheduling frameworks

Presentation Layer (Service Model)¶

Purpose: API endpoints, DTOs, and service contracts.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.ServiceModel`	Service DTOs and contracts	DomainModel
`ConnectSoft.MicroserviceTemplate.ServiceModel.RestApi`	REST API controllers	ServiceModel, ApplicationModel
`ConnectSoft.MicroserviceTemplate.ServiceModel.Grpc`	gRPC service implementations	ServiceModel, ApplicationModel
`ConnectSoft.MicroserviceTemplate.ServiceModel.GraphQL`	GraphQL schema and resolvers	ServiceModel, ApplicationModel
`ConnectSoft.MicroserviceTemplate.ServiceModel.SignalR`	SignalR hubs	ServiceModel, ApplicationModel
`ConnectSoft.MicroserviceTemplate.ServiceModel.CoreWCF`	CoreWCF SOAP services	ServiceModel, ApplicationModel
`ConnectSoft.MicroserviceTemplate.ServiceModel.ServiceFabric`	Service Fabric services	ServiceModel, ApplicationModel
`ConnectSoft.MicroserviceTemplate.ServiceModel.AzureFunction`	Azure Functions	ServiceModel, ApplicationModel

Characteristics: - Thin controllers/services that delegate to Application layer - Technology-specific API implementations - No direct access to persistence layer - DTOs for external communication

Project Structure:

ServiceModel/
├── DTOs/
│   └── MicroserviceAggregateRootDto.cs
└── Requests/
    └── CreateMicroserviceAggregateRootRequest.cs

ServiceModel.RestApi/
└── Controllers/
    └── MicroserviceAggregateRootsServiceController.cs

ServiceModel.Grpc/
└── Services/
    └── MicroserviceAggregateRootsService.cs

Application Layer¶

Purpose: Application host, DI configuration, and cross-cutting concerns.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.ApplicationModel`	DI registration, middleware, extensions	All layers (orchestration)
`ConnectSoft.MicroserviceTemplate.Application`	Host application (Program.cs, Startup)	ApplicationModel

Characteristics: - Orchestrates all layers - Dependency injection configuration - Middleware pipeline setup - Application startup and configuration

AI Layer¶

Purpose: AI-driven features and integrations.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.AgentFramework`	Microsoft Agent Framework for AI-driven features and multi-agent workflows	DomainModel
`ConnectSoft.MicroserviceTemplate.AIModel`	AI model abstractions and contracts	DomainModel
`ConnectSoft.MicroserviceTemplate.ModelContextProtocol`	Model Context Protocol (MCP) integration	DomainModel

Bot Layer¶

Purpose: Microsoft Bot Framework integration.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.BotModel`	Bot Framework controllers, dialogs, and handlers	ServiceModel, ApplicationModel

Infrastructure Layer¶

Purpose: Infrastructure as Code and container orchestration.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.InfrastructureModel`	Infrastructure as Code (Pulumi)	Application
`ConnectSoft.MicroserviceTemplate.DockerCompose`	Docker Compose configuration	Application

Testing Layer¶

Purpose: Automated tests for validation and quality assurance.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.UnitTests`	Unit tests for individual components	All projects (test references)
`ConnectSoft.MicroserviceTemplate.AcceptanceTests`	Integration and acceptance tests	Application
`ConnectSoft.MicroserviceTemplate.ArchitectureTests`	Architecture enforcement tests	All projects (test references)

Characteristics: - Tests organized by testing type - Architecture tests enforce Clean Architecture - Integration tests use real components - Unit tests use mocks and test doubles

Architecture Layer¶

Purpose: Architecture modeling and documentation.

Project	Purpose	Dependencies
`ConnectSoft.MicroserviceTemplate.ArchitectureModel`	Visual Studio Code Maps (DGML)	All projects (reference for visualization)
`ConnectSoft.MicroserviceTemplate.DiagramAsCodeModel`	Python-based diagramming as code	All projects (reference for visualization)

Dependency Flow¶

Clean Architecture Dependency Rules¶

Dependencies flow inward—outer layers depend on inner layers, never the reverse:

Presentation Layer (ServiceModel.*)
    ↓ depends on
Application Layer (ApplicationModel)
    ↓ depends on
Domain Layer (DomainModel, DomainModel.Impl)
    ↑ implements
Infrastructure Layer (PersistenceModel.*, MessagingModel, ActorModel.*)

Dependency Matrix¶

Layer	Can Depend On	Cannot Depend On
Presentation	ApplicationModel, ServiceModel, DomainModel	PersistenceModel.*, Infrastructure implementations
Application	DomainModel, PersistenceModel (interfaces)	PersistenceModel.* (implementations), ServiceModel
Domain	EntityModel, Base project	Nothing (zero dependencies)
Infrastructure	DomainModel (via abstractions)	Presentation, Application implementations

Architecture Enforcement¶

Dependency rules are enforced through automated architecture tests:

// EnforcingLayeredArchitectureUnitTests.cs
[TestMethod]
public void ControllersShouldNotDirectlyReferencePersistenceModel()
{
    // Ensures REST controllers cannot directly access repositories
}

[TestMethod]
public void DomainModelImplementorsShouldReferenceOnlyPersistenceModelContractsAndNotImplementations()
{
    // Ensures domain layer only uses interfaces, never implementations
}

See Architecture for detailed information on architecture enforcement.

Naming Conventions¶

Project Naming¶

Projects follow the pattern: ConnectSoft.MicroserviceTemplate.{Layer}[.{Technology}]

Pattern	Example	Description
`ConnectSoft.MicroserviceTemplate`	Base project	Common code, constants, exceptions
`ConnectSoft.MicroserviceTemplate.{Layer}`	`EntityModel`, `DomainModel`, `ServiceModel`	Layer-specific projects
`ConnectSoft.MicroserviceTemplate.{Layer}.{Technology}`	`PersistenceModel.NHibernate`, `ServiceModel.RestApi`	Technology-specific implementations
`ConnectSoft.MicroserviceTemplate.{Layer}.Impl`	`DomainModel.Impl`	Implementation projects (separated from contracts)

Namespace Naming¶

Namespaces match project structure exactly:

// Project: ConnectSoft.MicroserviceTemplate.EntityModel
namespace ConnectSoft.MicroserviceTemplate.EntityModel
{
    public class MicroserviceAggregateRootEntity { }
}

// Project: ConnectSoft.MicroserviceTemplate.ServiceModel.RestApi
namespace ConnectSoft.MicroserviceTemplate.ServiceModel.RestApi
{
    public class MicroserviceAggregateRootsServiceController { }
}

Project Structure Details¶

Common Projects¶

ConnectSoft.MicroserviceTemplate (Base) - Constants - Base exceptions - Common utilities - Shared helpers

ConnectSoft.MicroserviceTemplate.Options - Configuration options classes - Options pattern implementations - Validation attributes

ConnectSoft.MicroserviceTemplate.Metrics - Prometheus metrics definitions - OpenTelemetry metrics - Custom metrics

Domain Projects¶

ConnectSoft.MicroserviceTemplate.EntityModel - Entity classes - Aggregate roots - Value objects - Enumerations

ConnectSoft.MicroserviceTemplate.DomainModel - Domain service interfaces - Use case interfaces - Domain events - Input/Output models - Domain exceptions

ConnectSoft.MicroserviceTemplate.DomainModel.Impl - Domain service implementations - Processors (mutations) - Retrievers (queries) - FluentValidation validators

Persistence Projects¶

ConnectSoft.MicroserviceTemplate.PersistenceModel - Repository interfaces - Specification interfaces - Unit of Work interfaces

ConnectSoft.MicroserviceTemplate.PersistenceModel.NHibernate - NHibernate repository implementations - NHibernate class mappings - NHibernate-specific queries

ConnectSoft.MicroserviceTemplate.PersistenceModel.MongoDb - MongoDB repository implementations - MongoDB class mappings - MongoDB-specific queries

ConnectSoft.MicroserviceTemplate.DatabaseModel.Migrations - FluentMigrator migration scripts - SQL schema migrations - Database versioning

ConnectSoft.MicroserviceTemplate.DatabaseModel.MongoDb.Migrations - MongoDB migration scripts - Schema evolution - Data migrations

Service Model Projects¶

ConnectSoft.MicroserviceTemplate.ServiceModel - Request DTOs - Response DTOs - Service contracts

ConnectSoft.MicroserviceTemplate.ServiceModel.RestApi - REST API controllers - REST-specific middleware - OpenAPI/Swagger integration

ConnectSoft.MicroserviceTemplate.ServiceModel.Grpc - gRPC service definitions (.proto) - gRPC service implementations - gRPC interceptors

ConnectSoft.MicroserviceTemplate.ServiceModel.GraphQL - GraphQL schema definitions - GraphQL resolvers - GraphQL middleware

ConnectSoft.MicroserviceTemplate.ServiceModel.SignalR - SignalR hubs - SignalR groups - Real-time messaging

Application Projects¶

ConnectSoft.MicroserviceTemplate.ApplicationModel - Dependency injection extensions - Middleware registration - Service registration helpers - Cross-cutting concerns

ConnectSoft.MicroserviceTemplate.Application - Program.cs (entry point) - appsettings.json - Startup configuration - Host application

Folder Organization¶

Logical Grouping¶

Projects are organized into logical folders in the solution:

Solution Folders:
├── Common/
│   ├── ConnectSoft.MicroserviceTemplate
│   ├── ConnectSoft.MicroserviceTemplate.Options
│   └── ConnectSoft.MicroserviceTemplate.Metrics
├── Domain/
│   ├── ConnectSoft.MicroserviceTemplate.EntityModel
│   ├── ConnectSoft.MicroserviceTemplate.DomainModel
│   └── ConnectSoft.MicroserviceTemplate.DomainModel.Impl
├── Persistence/
│   ├── ConnectSoft.MicroserviceTemplate.PersistenceModel
│   ├── ConnectSoft.MicroserviceTemplate.PersistenceModel.NHibernate
│   ├── ConnectSoft.MicroserviceTemplate.PersistenceModel.MongoDb
│   ├── ConnectSoft.MicroserviceTemplate.DatabaseModel.Migrations
│   └── ConnectSoft.MicroserviceTemplate.DatabaseModel.MongoDb.Migrations
├── Messaging/
│   ├── ConnectSoft.MicroserviceTemplate.MessagingModel
│   ├── ConnectSoft.MicroserviceTemplate.FlowModel
│   ├── ConnectSoft.MicroserviceTemplate.FlowModel.MassTransit
│   └── ConnectSoft.MicroserviceTemplate.FlowModel.NServiceBus
├── ActorModel/
│   ├── ConnectSoft.MicroserviceTemplate.ActorModel
│   ├── ConnectSoft.MicroserviceTemplate.ActorModel.Orleans
│   ├── ConnectSoft.MicroserviceTemplate.ActorModel.Akka
│   └── ConnectSoft.MicroserviceTemplate.ActorModel.Dapr
├── Scheduler/
│   ├── ConnectSoft.MicroserviceTemplate.SchedulerModel
│   ├── ConnectSoft.MicroserviceTemplate.SchedulerModel.Hangfire
│   └── ConnectSoft.MicroserviceTemplate.SchedulerModel.Quartz
├── ServiceModel/
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.RestApi
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.Grpc
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.GraphQL
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.SignalR
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.CoreWCF
│   ├── ConnectSoft.MicroserviceTemplate.ServiceModel.ServiceFabric
│   └── ConnectSoft.MicroserviceTemplate.ServiceModel.AzureFunction
├── AI/
│   ├── ConnectSoft.MicroserviceTemplate.AgentFramework
│   ├── ConnectSoft.MicroserviceTemplate.AIModel
│   └── ConnectSoft.MicroserviceTemplate.ModelContextProtocol
├── Bot/
│   └── ConnectSoft.MicroserviceTemplate.BotModel
├── Application/
│   ├── ConnectSoft.MicroserviceTemplate.ApplicationModel
│   └── ConnectSoft.MicroserviceTemplate.Application
├── Infrastructure/
│   ├── ConnectSoft.MicroserviceTemplate.DockerCompose
│   └── ConnectSoft.MicroserviceTemplate.InfrastructureModel
├── Testing/
│   ├── ConnectSoft.MicroserviceTemplate.UnitTests
│   ├── ConnectSoft.MicroserviceTemplate.AcceptanceTests
│   └── ConnectSoft.MicroserviceTemplate.ArchitectureTests
└── Architecture/
    ├── ConnectSoft.MicroserviceTemplate.ArchitectureModel
    └── ConnectSoft.MicroserviceTemplate.DiagramAsCodeModel

Navigating the Solution¶

Finding Components¶

To find a domain service: 1. Look in DomainModel for the interface 2. Look in DomainModel.Impl for the implementation

To find a repository: 1. Look in PersistenceModel for the interface 2. Look in PersistenceModel.NHibernate or PersistenceModel.MongoDb for implementation

To find an API endpoint: 1. Look in ServiceModel.RestApi for REST controllers 2. Look in ServiceModel.Grpc for gRPC services 3. Look in ServiceModel.GraphQL for GraphQL resolvers

To find a configuration option: 1. Look in Options project for options classes 2. Look in Application project for appsettings.json

To find a test: 1. Look in UnitTests for unit tests 2. Look in AcceptanceTests for integration tests 3. Look in ArchitectureTests for architecture tests

Understanding Dependencies¶

Visual Studio Solution Explorer: - Shows project references - Indicates dependency relationships - Helps understand project dependencies

Architecture Tests: - Validate dependency rules - Fail builds on violations - Provide clear error messages

Code Maps (ArchitectureModel): - Visual representation of dependencies - Interactive exploration - Architecture documentation

Adding New Projects¶

When to Add a New Project¶

Add a new project when: - Technology-specific implementation: Different technology needs separate project (e.g., PersistenceModel.EF for Entity Framework) - New architectural layer: New layer that doesn't fit existing projects - Optional feature: Feature that may not be used in all scenarios - Test isolation: Separate test project for different test types

Project Creation Guidelines¶

Follow Naming Conventions: Use ConnectSoft.MicroserviceTemplate.{Layer}[.{Technology}] pattern
Match Namespace: Namespace should match project name
Enforce Dependencies: Ensure dependencies follow Clean Architecture rules
Add Architecture Tests: Add tests to enforce dependency rules
Update Documentation: Document the new project in solution structure

Example: Adding a New Persistence Technology¶

1. Create project: ConnectSoft.MicroserviceTemplate.PersistenceModel.EF
2. Add reference to: PersistenceModel (interfaces)
3. Implement: Repository interfaces from PersistenceModel
4. Add architecture tests: Ensure EF project doesn't reference ServiceModel
5. Update DI: Register EF implementations in ApplicationModel

Best Practices¶

Do's¶

Follow Clean Architecture Rules
Dependencies flow inward
Domain layer has zero dependencies
Infrastructure implements abstractions
Use Project Naming Conventions
Follow {Layer}[.{Technology}] pattern
Use descriptive names
Match namespace to project name
Keep Projects Focused
One responsibility per project
Clear purpose and boundaries
Minimal dependencies
Separate Contracts from Implementations
Interfaces in contract projects
Implementations in separate projects
Technology-specific implementations isolated
Test Architecture
Write architecture tests for new projects
Enforce dependency rules
Catch violations at build time

Don'ts¶

Don't Violate Dependency Rules
Don't let outer layers reference inner layers
Don't let domain depend on infrastructure
Don't let controllers access repositories directly
Don't Create Circular Dependencies
Projects should have clear dependency direction
Avoid bidirectional dependencies
Use dependency inversion
Don't Mix Concerns
Don't mix API and persistence in one project
Don't mix domain and infrastructure
Keep projects focused
Don't Skip Architecture Tests
Always test architectural rules
Don't bypass enforcement
Fix violations, don't ignore them

Architecture: Architecture model and enforcement
Clean Architecture: Architectural principles and patterns
Domain-Driven Design: Domain layer organization
Startup and Warmup: Startup patterns and application initialization

Summary¶

The solution structure in the ConnectSoft Microservice Template provides:

✅ Clean Architecture Enforcement: Projects organized by layers with strict dependency rules
✅ Modularity: Each feature area is a separate, focused project
✅ Technology Flexibility: Technology-specific implementations isolated
✅ Testability: Clear separation enables independent testing
✅ Scalability: Easy to add new features and technologies
✅ Maintainability: Clear organization makes codebase easy to navigate
✅ Automated Enforcement: Architecture tests prevent violations

By following this structure, teams can:

Build Maintainable Services: Clear organization makes code easy to understand and modify
Enforce Architecture: Automated tests prevent architectural violations
Scale Efficiently: Add new features without affecting existing code
Test Independently: Test each layer in isolation
Swap Technologies: Replace implementations without changing business logic

The solution structure is the foundation that enables Clean Architecture, making it possible to build robust, maintainable, and scalable microservices.

Solution Structure in ConnectSoft Microservice Template¶

Purpose & Overview¶

Solution Organization¶

High-Level Structure¶

Solution File Structure¶

Project Organization by Layer¶

Common Layer¶

Domain Layer¶

Persistence Layer¶

Messaging Layer¶

Actor Model Layer¶

Scheduler Layer¶

Presentation Layer (Service Model)¶

Application Layer¶

AI Layer¶

Bot Layer¶

Infrastructure Layer¶

Testing Layer¶

Architecture Layer¶

Dependency Flow¶

Clean Architecture Dependency Rules¶

Dependency Matrix¶

Architecture Enforcement¶

Naming Conventions¶

Project Naming¶

Namespace Naming¶

Project Structure Details¶

Common Projects¶

Domain Projects¶

Persistence Projects¶

Service Model Projects¶

Application Projects¶

Folder Organization¶

Logical Grouping¶

Navigating the Solution¶

Finding Components¶

Understanding Dependencies¶

Adding New Projects¶

When to Add a New Project¶

Project Creation Guidelines¶

Example: Adding a New Persistence Technology¶

Best Practices¶

Do's¶

Don'ts¶

Related Documentation¶

Summary¶