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
  -> MySQL / PostgreSQL / SQLite / Memory / Edge / Agent

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 provider direction:

Provider	Best for
SQLx PostgreSQL	Production-grade server backends, complex queries, transactions, aggregation
SQLx MySQL	Enterprise MySQL systems and migration scenarios
SQLx SQLite	Local-first apps, tests, lightweight services
rusqlite SQLite	Embedded devices, edge deployments, synchronous execution, small dependency profile
MemoryRepository	Unit tests, no-database demos, fast model validation

See Rust database providers for provider selection details.

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