Skip to main content

UserContext – Customizable Core Runtime of TeaQL

Overview​

UserContext is the central runtime context of the TeaQL framework.
It represents a rich, request-scoped execution environment that unifies data access, request/response handling, validation, internationalization, concurrency control, logging, caching, and UI feedback.

In practice, UserContext functions as a combination of:

  • Application Context
  • Request Context
  • Unit of Work
  • Infrastructure Facade

It is the backbone that allows TeaQL to remain domain-centric and framework-agnostic.

Key Responsibilities​

1. Query Execution & Data Access Hub​

UserContext is the primary entry point for executing TeaQL requests and entity operations:

  • Execute SearchRequest for single entity, list, or stream
  • Perform aggregation queries
  • Persist entity graphs
  • Reload entities from persistence

This centralizes all runtime execution logic and decouples domain logic from repositories.

2. Repository & Metadata Resolution​

Through TQLResolver, UserContext dynamically resolves:

  • Repositories
  • Entity descriptors and metadata
  • Framework-managed beans

This design avoids direct dependency on Spring and enables TeaQL to run in different environments.

3. Request & Response Abstraction​

UserContext abstracts HTTP-level details by delegating to RequestHolder and ResponseHolder:

  • HTTP method, headers, parameters, and body
  • Client IP and proxy chain resolution
  • Response header manipulation
  • UI commands (toast, back, home)

Business logic remains independent of the underlying web framework.

4. Local Context Storage (Request Scope)​

A built-in local storage provides request-scoped state management:

  • Temporary data sharing
  • Validation error accumulation
  • Deduplication and flags

This replaces ad-hoc ThreadLocal or request attributes with a structured API.

5. Trusted Identity, Tenancy, and Request Policy​

UserContext is the single runtime home for the authoritative tenant, authenticated actor, permissions, and the request policy selected by the application. Authentication middleware, a service identity, or another trusted server adapter initializes that state before business code executes.

Tenant isolation is enforced by context-installed runtime policy at the final query and mutation boundary. A controller or service may add a tenant-derived filter to further narrow a business operation, but that filter is not the security boundary and forgetting it must not broaden access.

Raw request JSON, ordinary headers, entity fields, generated API parameters, and federation payloads cannot supply or replace authoritative tenant, permissions, or policy. If a protected operation has no trusted tenant or no required policy, execution must fail closed.

6. Entity Validation & Error Translation​

UserContext orchestrates the full validation pipeline:

  • Entity-specific Checker execution
  • Batch and single-entity validation
  • Precise error location tracking
  • Natural language error translation

Validation errors are translated into human-readable messages and raised as structured exceptions.

7. Natural Language Translation & i18n​

Validation errors and messages support multilingual output:

  • English by default
  • Chinese view-oriented translation when configured
  • Pluggable translator mechanism

This operates at the domain semantic level, not just UI text.

8. Concurrency Control & Task Execution​

UserContext provides built-in task execution with locking semantics:

  • Local locks and distributed locks
  • Synchronous and asynchronous execution
  • Single-instance task execution (non-reentrant)

Typical use cases include scheduled jobs, idempotent actions, and background processing.

9. Centralized Logging Facade​

Logging methods automatically resolve the caller class:

  • Supports INFO / DEBUG / WARN / ERROR levels
  • Marker-aware logging
  • Eliminates repetitive logger definitions

This simplifies consistent logging across the system.

10. UI Feedback & Flow Control​

The context supports UI-oriented feedback mechanisms:

  • Toast notifications
  • Navigation commands (back, home)
  • Duplicate form submission protection
  • Business-level error messaging

These features enable smooth integration with front-end clients without tight coupling.

11. Lifecycle Hooks & Extensibility​

UserContext defines extensibility points for future evolution:

  • beforeCreate / beforeUpdate / beforeDelete
  • afterLoad
  • Event dispatch hooks

These hooks support auditing, domain events, and cross-cutting concerns.

Architectural Significance​

From an architectural perspective, UserContext acts as:

The runtime container and execution boundary of TeaQL

It allows:

  • Entities to remain persistence-agnostic
  • Requests to be transport-agnostic
  • Business logic to be infrastructure-agnostic

All infrastructure concerns are centralized and accessed through a single, coherent abstraction.

Summary​

Without UserContext, TeaQL would be merely a DSL.
With UserContext, TeaQL becomes a complete, executable runtime framework.

UserContext enables TeaQL to scale from simple CRUD to complex, distributed, and multilingual enterprise systems while maintaining clean domain boundaries.