# dotnetcore/freesql architecture

> Architecture diagram of the GitHub repository dotnetcore/freesql, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dotnetcore/freesql
- Repository: https://github.com/dotnetcore/freesql

## Overview

##### Project Type and Purpose
- This is a monolithic, modular .NET ORM framework (FreeSql) designed as a library/SDK rather than a standalone application.
- Purpose: Provide a unified O/RM abstraction over multiple databases (MySQL, SQL Server, PostgreSQL, SQLite, Oracle, ClickHouse, etc.), plus optional higher-level patterns (DbContext, Repository/UnitOfWork), code generation, and extension points.

##### File Structure
- Top-level Modules:
- FreeSql (core engine)
- Providers (one subfolder per database provider)
- Extensions (AggregateRoot, BaseEntity, EFModel, JsonMap, LazyLoading, ZeroEntity, Generator)
- FreeSql.DbContext, FreeSql.Repository, FreeSql.All (package orchestrators)
- Examples (usage demos per pattern)
- Tests (unit/functional tests organized by feature and provider)
- Build & CI: Directory.Build.props, .github/workflows/docfx.yml (documentation), gitee-mirror.yml.
- Docs: README.md, README.zh-CN.md.

##### README for Insights
- Confirms core features: CodeFirst, DbFirst, advanced mapping, Expression analysis, navigation properties, read/write separation, filters, optimistic/pessimistic locks.
- Highlights supported databases and optional modules: Repository/UnitOfWork, BaseEntity, Generator tool.

a. Main Components
1. Consumer Layer
- Examples & End User Applications call into FreeSql APIs.
2. FreeSql Core
- FreeSqlBuilder, IFreeSql, key abstractions (Interfaces, DataAnnotations, Internal engines).
3. Provider Layer
- FreeSql.Provider.* (MySql, SqlServer, PostgreSQL, Oracle, etc.)
- Implements IAdo, IAop, ICodeFirst, IDbFirst, IFreeSql interfaces.
4. Extensions Layer
- FreeSql.Extensions.* (AggregateRoot, BaseEntity, EFModel, JsonMap, LazyLoading, ZeroEntity)
- FreeSql.Generator (code-gen tooling).
5. Higher-Level Patterns
- FreeSql.DbContext (Repository + UnitOfWork wrapper)
- FreeSql.Repository (generic repository)
- FreeSql.All (umbrella package)
6. Persistence Targets
- Relational Databases (MySQL, PostgreSQL, SQL Server, SQLite, etc.)
- NoSQL/Time Series (ClickHouse, TDengine, QuestDB)
7. Supporting Components
- Tests (unit and provider-specific tests)
- Documentation (DocFX pipeline)
- CI/CD (GitHub Actions).

b. Relationships & Data Flow
- Consumer Layer → FreeSqlBuilder (core API)
- FreeSqlBuilder configures:
- Selected Provider (e.g., .UseConnectionString(DataType.MySql, …))
- Optional Extensions/Plugins (e.g., UseAutoSyncStructure, AOP hooks)
- Core API invokes Extension hooks (Global filters, AOP delegates).
- Core dispatches SQL generation calls down into the selected Provider.
- Provider maps to AdoProvider → AdoCommand → AdoConnection → DB
- Higher-Level Patterns (DbContext, Repository) sit atop Core, orchestrating transactions and object graph persistence.
- Generator tool introspects database schema via Provider layer and emits model classes (DbFirst).

c. Architectural Patterns & Design Principles
- Layered Architecture: clear separation of Core, Provider, Extensions, and Consumer layers.
- Dependency Inversion: interfaces in Core, implementations in Providers & Extensions.
- Plugin/Extension points: Extensions and Providers loaded via DI or builder pattern.
- Repository & UnitOfWork patterns in FreeSql.DbContext module.
- Single Responsibility: each package/project has narrow focus (Core vs. Provider vs. Extension).

d. Technologies & Frameworks
- C#/.NET Standard libraries
- GitHub Actions (CI: DocFX documentation publishing, NuGet packaging)
- DocFX for docs site
- Fody in Examples (transaction weaving)
- Razor (in Generator module) for code templates

##### Detailed Capture
- Core components: list sub-modules (DataAnnotations, Interface, Internal, Extensions folder under FreeSql).
- Provider component for each supported DB family.
- Extension modules as optional plugins.
- FreeSql.All as meta-package that brings Core, Providers, Extensions together.
- CI/CD and docs pipeline as side processes, not in data path but in lifecycle.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumer Layer
    Examples["Examples/Consumers"]:::consumer
    Tests["FreeSql.Tests"]:::consumer

    %% Core Layer
    subgraph "FreeSql Core" 
        CoreBuilder["FreeSqlBuilder"]:::core
        CoreUtil["FreeUtil"]:::core
        DataAnnotations["DataAnnotations"]:::core
        Interface["Interface"]:::core
        Internal["Internal"]:::core
    end

    %% Extensions Layer
    subgraph "Extensions Layer"
        ExtAggregate["FreeSql.Extensions.AggregateRoot"]:::extension
        ExtBaseEntity["FreeSql.Extensions.BaseEntity"]:::extension
        ExtEFModel["FreeSql.Extensions.EFModel"]:::extension
        ExtJsonMap["FreeSql.Extensions.JsonMap"]:::extension
        ExtLazy["FreeSql.Extensions.LazyLoading"]:::extension
        ExtLinq["FreeSql.Extensions.Linq"]:::extension
        ExtZero["FreeSql.Extensions.ZeroEntity"]:::extension
        Generator["FreeSql.Generator"]:::extension
    end

    %% Providers Layer
    subgraph "Providers Layer"
        ProvMySql["FreeSql.Provider.MySql"]:::provider
        ProvSqlServer["FreeSql.Provider.SqlServer"]:::provider
        ProvPostgres["FreeSql.Provider.PostgreSQL"]:::provider
        ProvSqlite["FreeSql.Provider.Sqlite"]:::provider
        ProvOracle["FreeSql.Provider.Oracle"]:::provider
        ProvClickHouse["FreeSql.Provider.ClickHouse"]:::provider
        ProvTDengine["FreeSql.Provider.TDengine"]:::provider
    end

    %% High-Level Patterns
    subgraph "High-Level Patterns"
        DbContext["FreeSql.DbContext"]:::high
        Repository["FreeSql.Repository"]:::high
        MetaPackage["FreeSql.All"]:::high
    end

    %% Persistence Targets
    RelationalDB[("Relational DB")]:::db
    TimeSeriesDB[("NoSQL/Time Series DB")]:::db

    %% Relationships
    Examples -->|"uses"| CoreBuilder
    Tests -->|"validates"| CoreBuilder

    CoreBuilder -->|"loads"| DataAnnotations
    CoreBuilder -->|"loads"| Interface
    CoreBuilder -->|"loads"| Internal
    CoreBuilder -->|"invokes"| ExtAggregate
    CoreBuilder -->|"invokes"| ExtBaseEntity
    CoreBuilder -->|"invokes"| ExtEFModel
    CoreBuilder -->|"invokes"| ExtJsonMap
    CoreBuilder -->|"invokes"| ExtLazy
    CoreBuilder -->|"invokes"| ExtLinq
    CoreBuilder -->|"invokes"| ExtZero

    CoreBuilder -->|"dispatches to"| ProvMySql
    CoreBuilder -->|"dispatches to"| ProvSqlServer
    CoreBuilder -->|"dispatches to"| ProvPostgres
    CoreBuilder -->|"dispatches to"| ProvSqlite
    CoreBuilder -->|"dispatches to"| ProvOracle
    CoreBuilder -->|"dispatches to"| ProvClickHouse
    CoreBuilder -->|"dispatches to"| ProvTDengine

    DbContext -->|"depends on"| CoreBuilder
    Repository -->|"depends on"| CoreBuilder
    MetaPackage -->|"bundles"| CoreBuilder
    MetaPackage -->|"bundles"| ProvMySql
    MetaPackage -->|"bundles"| ExtAggregate

    Generator -->|"uses"| CoreBuilder
    Generator -->|"uses"| ProvMySql
    Generator -->|"emits models"| DataAnnotations

    ProvMySql -->|"connects to"| RelationalDB
    ProvSqlServer -->|"connects to"| RelationalDB
    ProvPostgres -->|"connects to"| RelationalDB
    ProvSqlite -->|"connects to"| RelationalDB
    ProvOracle -->|"connects to"| RelationalDB
    ProvClickHouse -->|"connects to"| TimeSeriesDB
    ProvTDengine -->|"connects to"| TimeSeriesDB

    %% Click Events
    click CoreBuilder "https://github.com/dotnetcore/freesql/blob/master/FreeSql/FreeSqlBuilder.cs"
    click CoreUtil "https://github.com/dotnetcore/freesql/blob/master/FreeSql/FreeUtil.cs"
    click DataAnnotations "https://github.com/dotnetcore/freesql/tree/master/FreeSql/DataAnnotations"
    click Interface "https://github.com/dotnetcore/freesql/tree/master/FreeSql/Interface"
    click Internal "https://github.com/dotnetcore/freesql/tree/master/FreeSql/Internal"
    click ProvMySql "https://github.com/dotnetcore/freesql/blob/master/Providers/FreeSql.Provider.MySql"
    click ProvSqlServer "https://github.com/dotnetcore/freesql/blob/master/Providers/FreeSql.Provider.SqlServer"
    click ProvPostgres "https://github.com/dotnetcore/freesql/blob/master/Providers/FreeSql.Provider.PostgreSQL"
    click ProvSqlite "https://github.com/dotnetcore/freesql/blob/master/Providers/FreeSql.Provider.Sqlite"
    click ProvOracle "https://github.com/dotnetcore/freesql/blob/master/Providers/FreeSql.Provider.Oracle"
    click ProvClickHouse "https://github.com/dotnetcore/freesql/blob/master/Providers/FreeSql.Provider.ClickHouse"
    click ProvTDengine "https://github.com/dotnetcore/freesql/blob/master/Providers/FreeSql.Provider.TDengine"
    click ExtAggregate "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Extensions.AggregateRoot"
    click ExtBaseEntity "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Extensions.BaseEntity"
    click ExtEFModel "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Extensions.EFModel"
    click ExtJsonMap "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Extensions.JsonMap"
    click ExtLazy "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Extensions.LazyLoading"
    click ExtLinq "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Extensions.Linq"
    click ExtZero "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Extensions.ZeroEntity"
    click Generator "https://github.com/dotnetcore/freesql/blob/master/Extensions/FreeSql.Generator"
    click DbContext "https://github.com/dotnetcore/freesql/blob/master/FreeSql.DbContext/DbContext/DbContext.cs"
    click Repository "https://github.com/dotnetcore/freesql/blob/master/FreeSql.Repository/FreeSql.Repository.csproj"
    click MetaPackage "https://github.com/dotnetcore/freesql/blob/master/FreeSql.All/FreeSql.All.csproj"
    click Examples "https://github.com/dotnetcore/freesql/tree/master/Examples/"
    click Tests "https://github.com/dotnetcore/freesql/tree/master/FreeSql.Tests/"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#2274A5,color:#000
    classDef provider fill:#DAF7DC,stroke:#28A745,color:#000
    classDef extension fill:#FFE5B4,stroke:#FFA500,color:#000
    classDef high fill:#E5D4ED,stroke:#800080,color:#000
    classDef consumer fill:#E0E0E0,stroke:#666,color:#000
    classDef db fill:#FFF4E6,stroke:#CC5500,color:#000 shape:database
```
