BoutiqueDB Architecture

Deep dive into BoutiqueDB target modules, swift-structured-queries driver integration, and DatabaseActor thread isolation.

BoutiqueDB is organized into focused Swift targets, balancing SQLite-compatible C APIs with high-level Swift ergonomics.

---

Target Layer Architecture

BoutiqueDB/
├── Package.swift
├── Sources/
│   ├── BoutiqueDB/                     # Main public framework API & DatabaseActor
│   ├── TursoKit/                       # Native C ABI handles, Statement execution, CDC
│   ├── StructuredQueriesTurso/         # StructuredQueries driver integration
│   ├── TursoCKSync/                    # CKSyncEngine CloudKit synchronizer
│   └── TursoObservation/               # CDC change token invalidation engine
└── Vendor/
    └── TursoSDK.xcframework            # Prebuilt libturso_sdk_kit multi-arch binary

---

Component Responsibilities

BoutiqueDB Target

Public API umbrella containing BoutiqueDB, @LiveQuery, @LiveQueryOne, and @BoutiqueTable macro wrappers.

StructuredQueriesTurso

Swift driver mapping StructuredQueries expressions (@Table) to Turso SQLite database connections.

TursoObservation

Monitors turso_cdc table change counters and dispatches change token invalidations to active subscriber queries.

TursoCKSync

Serializes changed CDC rows into CloudKit CKRecord structures for CKSyncEngine processing.