Apply when creating, moving, adding, or searching files to maintain the Dependency Rule and separation of concerns across all development activities.
Based on Uncle Bob Martin's Clean Architecture, this structure enforces:
Presentation → Application → Domain ← Persistence
↓ ↓ ↑ ↓
Base ←──────────┴────────────┴─────────┘
Allowed Dependencies:
Forbidden Dependencies:
Key Rules for Code Generation:
Layer | Can Depend On
----------------|------------------
Presentation | Application, Base
Application | Domain, Contracts, Base
Domain | Base (minimal)
Contracts | Domain, Base
Persistence | Domain, Contracts, Base
Tests | Anything (for testing)
Important Note on Contracts → Domain Dependency: Contracts referencing Domain is CORRECT in this architecture because:
IRepository<Document>)✓ Framework Independence: Can swap ASP.NET for another framework ✓ Database Independence: Can swap SQL Server for PostgreSQL, Cosmos DB, etc. ✓ UI Independence: Can add mobile app without changing business logic ✓ Testability: Can test business rules without UI, database, or frameworks ✓ Maintainability: Clear boundaries make changes predictable ✓ Azure Migration Friendly: Can modernize infrastructure without touching domain ✓ Vector Store Agnostic: Can switch between Azure AI Search, Pinecone, Weaviate, etc.
Purpose: Cross-cutting concerns and shared abstractions used across layers. Keep minimal to avoid coupling.
Project: MotorcycleRAG.Core
Clean Architecture Alignment: This is infrastructure for all layers but must not contain business logic or create circular dependencies.
Contents:
Constants, EnumsUtilitiesExceptionsResultsAbstractions/LoggingAbstractions/External⚠️ Warning: This layer should contain NO implementations that depend on external frameworks (EF Core, Azure SDK, etc.). Only abstractions and pure utilities.
Minimize dependencies on this layer to prevent tight coupling across your architecture.
Purpose: Entry point for external interactions. This is the outermost layer where delivery mechanisms live.
Projects: MotorcycleRAG.Api, MotorcycleRAG.UI, or MotorcycleRAG.Web
Clean Architecture Alignment: Frameworks and Drivers layer - contains delivery mechanisms (web, API) as details that can be swapped.
Contents:
ControllersHubsMiddlewareModels or ViewModelsMapperswwwroot or PagesDependencies: Application, Base Dependency Rule: ✓ Points inward to Application
Key Principle: Controllers are thin adapters. They receive requests, call Application use cases, and format responses. No business logic here.
Purpose: Contains application-specific business rules. Orchestrates the flow of data between entities and implements use cases.
Project: MotorcycleRAG.Application
Clean Architecture Alignment: Use Cases layer - implements all application-specific business rules.
Contents:
Features/{FeatureName}/Commands, Features/{FeatureName}/Queries
Example: Features/Documents/Commands/IndexDocument/IndexDocumentCommand.csServicesDTOs or within feature foldersValidators or within feature foldersAuthorizationInterfacesEventsDependencyInjection.csDependencies: Domain, Base Dependency Rule: ✓ Points inward to Domain
Critical Rules:
Use Case Pattern: Each use case handles one specific application action (IndexDocument, SearchMotorcycles, RetrieveContext). Use cases call domain entities to execute business rules and use interfaces to persist changes.
Purpose: Pure business logic and rules. The heart of the application. Enterprise-wide business rules that could be shared across applications.
Projects:
MotorcycleRAG.Domain → Concrete domain models and logicMotorcycleRAG.Contracts → Shared interfaces that domain definesClean Architecture Alignment: Entities layer (innermost circle) - most stable, highest-level policies.
Contents:
Entities
Example: Document.cs, MotorcycleManual.cs, VectorChunk.cs
Rule: Rich domain models with behavior, not anemic data bagsValueObjects
Example: DocumentMetadata.cs, Embedding.cs, SearchQuery.csServices
Example: DocumentChunkingService.csEvents
Example: DocumentIndexedEvent.csSpecificationsFactoriesExceptionsExceptionsDependencies: Base (minimal - only utilities/enums) Dependency Rule: ✓ No outward dependencies. Most stable layer.
Contents:
Repository Interfaces: Persistence contracts defined by domain needs
Folder: Repositories
Example: IDocumentRepository.cs, IVectorStoreRepository.cs
External Service Interfaces: Contracts for external dependencies
Folder: Services
Example: IEmbeddingService.cs, ILlmService.cs
Factories (Domain Contracts): Factory abstractions for creating aggregates/value objects while enforcing invariants
Folder: Factories
Example names: IDocumentFactory, IMotorcycleManualFactory, IVectorChunkFactory
Rule: MotorcycleRAG.Contracts contains interfaces only (no DTOs/models)
Dependencies: Domain, Base
Why Contracts → Domain is Correct:
Task<Document> GetDocumentAsync(Guid id) requires Document from DomainCritical Rules:
Key Principle: If you removed all outer layers (UI, DB, frameworks), your domain layer should still compile and contain all core business rules. This is the "screaming architecture" - the domain tells you what the system does.
Purpose: Implements data storage and retrieval. A detail that can be swapped.
Project: MotorcycleRAG.Persistence
Clean Architecture Alignment: Frameworks and Drivers layer - infrastructure detail.
Contents:
Contexts
File: MotorcycleRAGDbContext.csConfigurations
Example: DocumentConfiguration.csRepositories
Rule: Implement interfaces from Domain.ContractsMigrationsSeedReadModelsVectorStoresDependencyInjection.csDependencies: Domain, Contracts, Base Dependency Rule: ✓ Points inward to Domain
Critical Rules:
Dependency Inversion: Domain defines
IDocumentRepository, Persistence implements it. Application depends on the interface, not the implementation. This allows the database to be swapped without changing business logic.
Purpose: Comprehensive testing at all levels, proving independence of frameworks and testability.
Projects:
MotorcycleRAG.Domain.Tests → Unit tests for domain logicMotorcycleRAG.Application.Tests → Unit tests for use casesMotorcycleRAG.Api.Tests → Integration tests for API endpointsMotorcycleRAG.IntegrationTests → Full integration tests with databaseMotorcycleRAG.Playwright-UI.Tests → End-to-end UI testsTest Strategy:
Domain Tests (Unit):
Application Tests (Unit):
Integration Tests:
API Tests:
UI Tests (E2E):
Contents:
BuildersFixturesMocksClean Architecture Benefit: Because business logic is decoupled from infrastructure, you can test most of your system without databases, APIs, or UI frameworks.
Purpose: Internal documentation, architectural decisions, and design rationale.
architecture-general.md - This fileadr/ - Architecture Decision Recordsdiagrams/ - System diagrams (C4 model, sequence diagrams)rag-pipeline.md - RAG pipeline documentationPurpose: CI/CD scripts, containerization, infrastructure as code.
Contents:
docker/
Files: Dockerfile, docker-compose.ymlinfrastructure/.github/workflows/ or azure-pipelines.ymlscripts/Azure SKU Rule: When deploying to Azure, use free tier SKUs from the 1-year Azure free account:
Clean Architecture Benefit: Your deployment choices are details. You can deploy to Azure App Service, Container Apps, AKS, or even AWS without changing your application code.