Skip to main content

Service Behind the Scenes

TeaQL looks simple from the application code side because a lot of work is handled by the runtime and the generated library behind the scenes.

This chapter explains the moving parts at a practical level so teams know what is generated, what is runtime behavior, and what they are expected to customize.

The main layers​

A typical TeaQL-based service has these layers:

  1. Model definition
    • KSML or XML-style model files describe entities, relations, constants, and view objects.
  2. Generated library
    • TeaQL generates entity classes, request classes, controllers/processors for view objects, metadata, and helper APIs.
  3. Runtime services
    • The TeaQL runtime provides persistence integration, graph loading, expression execution, validation, metadata handling, and schema support.
  4. Project customization
    • Your project adds CustomUserContext, request wrappers, processors, services, controllers, and integration adapters.

What the generated library usually contains​

From a user point of view, the generated code often includes:

  • entity classes,
  • request classes used through Q,
  • expression access used through E,
  • metadata constants,
  • graph save/load support,
  • service-request view objects,
  • generated controller/processor pairs for server-driven UI scenarios.

The practical result is that a lot of repetitive application code is avoided:

  • fewer handwritten repositories,
  • fewer handwritten mapping layers,
  • fewer duplicated query fragments,
  • fewer one-off DTOs for internal workflows.

What the runtime is responsible for​

The runtime is where TeaQL becomes an execution platform rather than just a code generator.

Typical responsibilities include:

  • executing generated requests,
  • translating filters, sorting, paging, and joins,
  • loading object graphs across levels,
  • evaluating safe expressions,
  • handling entity save/update semantics,
  • integrating with supported databases,
  • supporting ensure schema and ensure index,
  • exposing extension points through UserContext.

In practice, application code should not re-implement these core behaviors. It should compose them.

Where UserContext fits​

UserContext is the runtime boundary that gives TeaQL its strong customization model.

It is commonly used to provide:

  • current user and tenant,
  • permission checks,
  • translator and natural language behavior,
  • database routing,
  • logging,
  • cache integration,
  • distributed locking,
  • audit behavior,
  • environment-specific technical services.

This is why TeaQL can keep query code small while still supporting large enterprise requirements. The request API stays readable, while technical variation moves into UserContext.

Typical request flow​

A common request path looks like this:

HTTP / RPC -> Controller -> Service -> Util / Processor -> Q / E -> TeaQL Runtime -> Database

For server-driven UI scenarios, the path often becomes:

Frontend -> Generated Controller -> Custom Processor -> TeaQL Runtime -> Database / External Services

The important design point is that the business-facing code is still small:

  • Controllers adapt protocol.
  • Services define orchestration and transaction boundaries.
  • Utils and Processors contain business behavior.
  • TeaQL runtime handles data-access mechanics.

What teams usually customize first​

Most teams do not need to change generation logic first. They usually start with:

  1. CustomUserContext
  2. domain-specific request wrappers
  3. service methods built on top of Q and E
  4. server-driven UI processors if there is workflow UI
  5. project-specific controllers or APIs

That sequence gives the fastest return because it works with the generated system instead of fighting it.

Why this matters when evaluating TeaQL​

If you only read a few query examples, TeaQL can look like a fluent query API. That is incomplete.

What makes TeaQL different is the combination of:

  • generated business-shaped APIs,
  • runtime graph and expression support,
  • service-request and view-object workflow support,
  • heavy customization through UserContext.

That combination is what reduces repetitive code and improves consistency for larger teams.

Now that the runtime shape is clear, the next step is to build from a small starter model:

Those pages focus on how to define a domain model before generating APIs from it.