jaunty Architecture › Architecture Visual Guide

Architecture Visual Guide

Visual diagrams and illustrations for understanding Jaunty's architecture.

System Architecture Overview

User Code

Database

DbConnection

DbCommand

DbDataReader

Parameter System

SqlParameterParser

ParameterBinder

ParameterCache

Metadata System

MetadataCache

MetadataBuilder

Compiled Setters

Core Execution

QueryCore

ExecuteReader

DrDispatcher

Public API Layer

Query()

QueryPartial()

Insert()

Update()

Delete()

IDbConnection.Query()

Query Execution Lifecycle

DBParamMetaCoreAPIUserDBParamMetaCoreAPIUserValidate argumentsCheck connectionManage connection stateOpen if closedParse SQL for @paramsBind to DbCommandExecute SQLReturn DataReaderCheck custom mapperCheck special typesBuild from MetadataCacheReceive mapped entitiesQuery<Product>(sql, params)QueryCore<T>(sql, params)Extract & bind parametersExecuteReader()IDataReaderDrDispatcher.Resolve<T>()Func<IDataReader, T>while reader.Read()map(reader)List<T>List<T>

Metadata Initialization Flow

No

Yes

Yes

Yes

No

First Query()

MetadataCache
initialized?

Static constructor runs

Use cached metadata

MetadataBuilder.Build()

Read [Table], [Column] attributes

Apply JauntyConfig resolvers

Create EntityMetadata

For each property

Build expression tree

Compile to delegate

Create PropertyContext

Add to ColumnToIndex

More properties?

NET8_0_OR_GREATER?

ToFrozenDictionary()

ToDictionary()

MetadataCache ready

Execute query

Return List

Parameter Binding Flow

Mismatch

Match

Extraction

State machine
Skip comments, strings

Extract @param names

Deduplicate

SQL with @params

SqlParameterParserCache

Validate count

Throw ArgumentException

ParameterBinder

Get object properties

For each property

Create DbParameter

Set Value or DBNull

Add to DbCommand

Execute command

Error returned

Connection State Management

CheckState

CheckClose

connection.State

true

false

connection.Open()

wasClosed && stillOpen

true

false

connection.Close()

WasClosed

OpenIfNeeded

ExecuteDirect

Open

Execute

CreateCommand

BindParams

ExecuteReader

ReadResults

ShouldClose

Close

LeaveOpen

Jaunty respects connection state:
- Opens if closed
- Closes if it opened
- Leaves open if already open

Mapper Resolution Priority

Yes

No

Yes

No

Yes

No

Yes

No

DrDispatcher.Resolve()

options.Mapper
not null?

Use options.Mapper

Special type?
Dictionary, ExpandoObject

Use special mapper

MappedCache.Mapper
not null?

Use IMapped mapper

MetadataCache
available?

Build from MetadataCache

Throw: no mapper available

MetadataCache.GetSetters()

Create mapper function

Return Func

Performance Hot Paths

Allocations

Entity instances

List

Minimal (cached rest)

Hot Path (Per-query)

Dictionary lookup O(1)

Delegate invocation

Property setting

Cold Path (One-time)

Metadata build

Expression compilation

Dictionary creation

Cold Path (runs once per type):

  • Metadata building: ~1-5ms
  • Expression compilation: ~1-10ms
  • Dictionary creation: ~0.1-1ms

Hot Path (runs per query):

  • Dictionary lookup: ~10ns
  • Delegate invocation: ~50ns
  • Property setting: ~100ns per property

Error Flow

Query execution

Error type?

ArgumentNullException

ArgumentException

InvalidOperationException

DbException

Null required argument

Parameter mismatch
Invalid parameter type

Strict mapping failure
No results / Multiple results
NULL to non-nullable

Database error
SQL syntax error

Format error message
with context

Pass through as-is

Throw exception

Multi-Targeting Architecture

Yes

No

netstandard2.0 Compatibility

Dictionary

Task

String concatenation

Substring()

Manual character search

net8.0 Optimizations

FrozenDictionary

ValueTask

string.Create()

Span/ReadOnlySpan

SearchValues

Source Code

#if NET8_0_OR_GREATER?

Build net8.0

Build netstandard2.0

Jaunty.dll (net8.0)

Jaunty.dll (netstandard2.0)

Extrode.Jaunty NuGet package

See Also

Document Purpose
architecture-specification.md Complete architecture spec
metadata-system-spec.md Metadata system details
parameter-binding-spec.md Parameter binding details
performance-spec.md Performance guide
← prev Jaunty Architecture Specification next → Bulk Copy Architecture