Architecture Overview

TeaQL is not just an ORM. It is a generated business API layer built from your domain model.

The architecture has four stable layers:

Domain Model
  -> TeaQL Generator
  -> Generated Q API
  -> Runtime Provider
  -> PostgreSQL / MySQL / SQLite / Meilisearch / Memory

Domain Model

The domain model describes entities, fields, relations, child lists, validation expectations, and data-service targets. Existing model docs remain the best place to start:

• Start from an example
• KSML quick guide
• KSML annotations

TeaQL Generator

The generator turns the model into typed APIs. For Java, that includes entities, request objects, Q expressions, E expressions, selectors, filters, validators, and save helpers.

The generated API is intentionally readable. It gives humans and AI tools a stable business vocabulary instead of forcing them to infer database shape from SQL strings or mapper code.

Generated Q API

Q APIs are generated from the model and used to express:

• Selection and nested association loading
• Filtering by fields and references
• have / haveNo style list-existence queries
• Count, group by, and dashboard statistics
• Sorting, pagination, and reusable business query fragments

Read the existing TeaQL query quick guide for concrete Java examples.

Runtime Provider

Runtime providers execute the generated request against a storage backend or in-memory repository. This is where TeaQL separates business API design from storage implementation.

Current Rust provider families:

Provider family	Current evidence boundary
teaql-provider-postgres	Documented/source family; no maintained database execution result yet.
teaql-provider-mysql	Documented/source family; no maintained database execution result yet.
teaql-provider-sqlite	Version 4.1.1 with rusqlite 0.32 passed the maintained SQLite Golden Path.
teaql-provider-meilisearch	Documented search-provider family; semantics and server version remain unverified.
MemoryRepository	Documented in-memory path; SQL-provider parity remains unverified.

Provider names describe architecture, not support commitments. See Rust database providers for selection details and Database Provider Compatibility for the required adoption evidence.

Runtime Context

In Java, UserContext is the primary runtime boundary. It centralizes query execution, repository resolution, validation, i18n, logging, caching, locking, transactions, and request-scoped behavior.

Read the reused UserContext guide for details.

Why This Matters for AI

AI tools are good at composing application logic, but they are unreliable when forced to guess schema, SQL semantics, relationship loading, and runtime policy from scattered code.

TeaQL gives AI tools a deterministic API surface:

• Stable generated methods
• Explicit field and relation names
• Runtime boundaries controlled by the application
• Provider choices hidden below business intent