# ratanachh/dapperx architecture

> Architecture diagram of the GitHub repository ratanachh/dapperx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ratanachh/dapperx
- Repository: https://github.com/ratanachh/dapperx

## Overview

DapperX is a compile-time source-generator-powered .NET data-access framework: developers declare mapped entities and repository interfaces, then use generated repositories for database operations. The generator models mappings and emits SQL-backed repository code; runtime query and execution layers handle requests against one of four providers. The README documents additional batch/graph, relationship, lifecycle, tenancy, auditing, and query-language capabilities; their internal wiring is not fully shown in the sampled source, so those links are marked unverified where appropriate.

Main entry points: [`src/DapperX.Generator/Models/EntityModel.cs`](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Models/EntityModel.cs) (Entity metadata), [`src/DapperX/Runtime/Execution/DbExecutor.cs`](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Execution/DbExecutor.cs) (Database executor), [`src/DapperX.Generator/Emitters/RepositoryEmitter.cs`](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Emitters/RepositoryEmitter.cs) (Repository emission), [`src/DapperX/Runtime/Repositories/DapperXRepositoryBase.cs`](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Repositories/DapperXRepositoryBase.cs) (Repository runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Declarations and metadata"]
  node_entity_def["Entity declarations<br/>[EntityAttribute.cs]"]
  node_repo_def["Repository contract"]
end

subgraph group_generation["Compile-time generation"]
  node_entity_model["Entity metadata<br/>[EntityModel.cs]"]
  node_source_generator["Source generator"]
  node_repository_emitter["Repository emission"]
  node_sql_builder["SQL generation<br/>[SqlBuilder.cs]"]
  node_derived_query["Derived queries"]
  node_cpql["CPQL queries<br/>[CpqlGenerator.cs]"]
  node_cross_features["Mapping and policies<br/>[Generators]"]
  node_batch_graph["Batch and graph ops<br/>[GraphGenerator.cs]"]
end

subgraph group_runtime["Repository runtime"]
  node_generated_repository["Generated repository"]
  node_repository_base["Repository runtime"]
  node_query_api["Fluent query API<br/>[RepositoryQuery.cs]"]
  node_query_executor["Query execution<br/>[QueryExecutor.cs]"]
  node_db_executor["Database executor<br/>[DbExecutor.cs]"]
  node_sql_logging["SQL logging"]
end

subgraph group_storage["Database providers"]
  node_provider_factory["Provider selection"]
  node_provider_impl["Provider dialects"]
end

node_developer(("Application developer"))
node_database[("Relational database")]

node_developer -->|"declares mappings"| node_entity_def
node_developer -->|"declares repository"| node_repo_def
node_entity_def -.->|"triggers generation"| node_source_generator
node_repo_def -.->|"triggers generation"| node_source_generator
node_source_generator -.->|"builds metadata"| node_entity_model
node_entity_model -->|"informs emission"| node_repository_emitter
node_repository_emitter -->|"builds SQL"| node_sql_builder
node_repository_emitter -->|"emits repository"| node_generated_repository
node_entity_model -->|"supports parsing"| node_derived_query
node_derived_query -->|"uses SQL builder"| node_sql_builder
node_entity_model -.->|"provides entity context"| node_cpql
node_entity_model -.->|"configures capabilities"| node_cross_features
node_entity_model -.->|"configures graph operations"| node_batch_graph
node_generated_repository -->|"extends runtime"| node_repository_base
node_repository_base -->|"executes SQL"| node_db_executor
node_repository_base -.->|"creates query API"| node_query_api
node_query_api -->|"executes query"| node_query_executor
node_query_api -->|"executes commands"| node_db_executor
node_query_executor -.->|"runs SQL"| node_db_executor
node_db_executor -->|"logs statements"| node_sql_logging
node_provider_factory -->|"selects provider"| node_provider_impl
node_db_executor -->|"executes commands"| node_database
node_developer -->|"uses generated API"| node_generated_repository
node_provider_impl -.->|"accesses database"| node_database

click node_entity_def "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Core/Attributes/Entity/EntityAttribute.cs"
click node_repo_def "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Core/Attributes/Query/RepositoryAttribute.cs"
click node_entity_model "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Models/EntityModel.cs"
click node_source_generator "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/DapperXSourceGenerator.cs"
click node_repository_emitter "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Emitters/RepositoryEmitter.cs"
click node_sql_builder "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Builders/SqlBuilder.cs"
click node_derived_query "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Generators/DerivedQueryGenerator.cs"
click node_cpql "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Generators/CpqlGenerator.cs"
click node_cross_features "https://github.com/ratanachh/dapperx/tree/main/src/DapperX.Generator/Generators"
click node_batch_graph "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Generators/GraphGenerator.cs"
click node_generated_repository "https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Emitters/RepositoryEmission.cs"
click node_repository_base "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Repositories/DapperXRepositoryBase.cs"
click node_query_api "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Query/RepositoryQuery.cs"
click node_query_executor "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Query/QueryExecutor.cs"
click node_db_executor "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Execution/DbExecutor.cs"
click node_sql_logging "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Logging/SqlExecutionLogger.cs"
click node_provider_factory "https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Provider/Common/DatabaseProviderFactory.cs"
click node_provider_impl "https://github.com/ratanachh/dapperx/tree/main/src/DapperX/Provider"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entity_def,node_repo_def toneBlue
class node_entity_model,node_source_generator,node_repository_emitter,node_sql_builder,node_derived_query,node_cpql,node_cross_features,node_batch_graph,node_database toneAmber
class node_generated_repository,node_repository_base,node_query_api,node_query_executor,node_db_executor,node_sql_logging toneMint
class node_provider_factory,node_provider_impl toneRose
class node_developer toneIndigo
```

## Components

### Declarations and metadata

- [Entity declarations](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Core/Attributes/Entity/EntityAttribute.cs): `src/DapperX/Core/Attributes/Entity/EntityAttribute.cs`
- [Repository contract](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Core/Attributes/Query/RepositoryAttribute.cs): `src/DapperX/Core/Attributes/Query/RepositoryAttribute.cs`

### Compile-time generation

- [Entity metadata](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Models/EntityModel.cs): `src/DapperX.Generator/Models/EntityModel.cs`
- [Source generator](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/DapperXSourceGenerator.cs): `src/DapperX.Generator/DapperXSourceGenerator.cs`
- [Repository emission](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Emitters/RepositoryEmitter.cs): `src/DapperX.Generator/Emitters/RepositoryEmitter.cs`
- [SQL generation](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Builders/SqlBuilder.cs): `src/DapperX.Generator/Builders/SqlBuilder.cs`
- [Derived queries](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Generators/DerivedQueryGenerator.cs): `src/DapperX.Generator/Generators/DerivedQueryGenerator.cs`
- [CPQL queries](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Generators/CpqlGenerator.cs): `src/DapperX.Generator/Generators/CpqlGenerator.cs`
- [Mapping and policies](https://github.com/ratanachh/dapperx/tree/main/src/DapperX.Generator/Generators): `src/DapperX.Generator/Generators`
- [Batch and graph ops](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Generators/GraphGenerator.cs): `src/DapperX.Generator/Generators/GraphGenerator.cs`

### Repository runtime

- [Generated repository](https://github.com/ratanachh/dapperx/blob/main/src/DapperX.Generator/Emitters/RepositoryEmission.cs): `src/DapperX.Generator/Emitters/RepositoryEmission.cs`
- [Repository runtime](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Repositories/DapperXRepositoryBase.cs): `src/DapperX/Runtime/Repositories/DapperXRepositoryBase.cs`
- [Fluent query API](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Query/RepositoryQuery.cs): `src/DapperX/Runtime/Query/RepositoryQuery.cs`
- [Query execution](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Query/QueryExecutor.cs): `src/DapperX/Runtime/Query/QueryExecutor.cs`
- [Database executor](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Execution/DbExecutor.cs): `src/DapperX/Runtime/Execution/DbExecutor.cs`
- [SQL logging](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Runtime/Logging/SqlExecutionLogger.cs): `src/DapperX/Runtime/Logging/SqlExecutionLogger.cs`

### Database providers

- [Provider selection](https://github.com/ratanachh/dapperx/blob/main/src/DapperX/Provider/Common/DatabaseProviderFactory.cs): `src/DapperX/Provider/Common/DatabaseProviderFactory.cs`
- [Provider dialects](https://github.com/ratanachh/dapperx/tree/main/src/DapperX/Provider): `src/DapperX/Provider`

### Other components

- **Application developer**
- **Relational database**

## Connections

- Application developer → Entity declarations: declares mappings (evidence: `README.md`)
- Application developer → Repository contract: declares repository (evidence: `README.md`)
- Entity declarations → Source generator: triggers generation
- Repository contract → Source generator: triggers generation
- Source generator → Entity metadata: builds metadata
- Entity metadata → Repository emission: informs emission (evidence: `src/DapperX.Generator/Emitters/RepositoryEmitter.cs`)
- Repository emission → SQL generation: builds SQL (evidence: `src/DapperX.Generator/Emitters/RepositoryEmitter.cs`)
- Repository emission → Generated repository: emits repository (evidence: `src/DapperX.Generator/Emitters/RepositoryEmitter.cs`)
- Entity metadata → Derived queries: supports parsing (evidence: `src/DapperX.Generator/Generators/DerivedQueryGenerator.cs`)
- Derived queries → SQL generation: uses SQL builder (evidence: `src/DapperX.Generator/Generators/DerivedQueryGenerator.cs`)
- Entity metadata → CPQL queries: provides entity context
- Entity metadata → Mapping and policies: configures capabilities (evidence: `src/DapperX.Generator/Generators/DerivedQueryGenerator.cs`)
- Entity metadata → Batch and graph ops: configures graph operations
- Generated repository → Repository runtime: extends runtime (evidence: `src/DapperX.Generator/Emitters/RepositoryEmitter.cs`)
- Repository runtime → Database executor: executes SQL (evidence: `src/DapperX/Runtime/Repositories/DapperXRepositoryBase.cs`)
- Repository runtime → Fluent query API: creates query API
- Fluent query API → Query execution: executes query (evidence: `src/DapperX/Runtime/Query/RepositoryQuery.cs`)
- Fluent query API → Database executor: executes commands (evidence: `src/DapperX/Runtime/Query/RepositoryQuery.cs`)
- Query execution → Database executor: runs SQL
- Database executor → SQL logging: logs statements (evidence: `src/DapperX/Runtime/Execution/DbExecutor.cs`)
- Provider selection → Provider dialects: selects provider (evidence: `src/DapperX/Provider/Common/DatabaseProviderFactory.cs`)
- Database executor → Relational database: executes commands (evidence: `src/DapperX/Runtime/Execution/DbExecutor.cs`)
- Application developer → Generated repository: uses generated API (evidence: `README.md`)
- Provider dialects → Relational database: accesses database
