Distributed Delivery Mode

Overview

Distributed Delivery Mode is designed for teams that split product ownership, architecture, infrastructure decisions, and large-scale business implementation across locations.

In this mode:

• Model owners own the domain model.
• Central or delivery-side technical developers customize UserContext and define technical infrastructure.
• A larger group of delivery developers use generated Q and E APIs to implement business services and controllers.

TeaQL helps this model because the generated Java API becomes a shared contract between model owners, technical leads, and delivery teams.

---

Recommended Team Structure

Role	Team Position	Main Responsibility	TeaQL Focus
Product Manager	Model owner	Business requirements, workflows, vocabulary	Domain model
Architect	Model owner / technical lead	Model boundaries, integration boundaries, technical direction	Domain model and architecture
Technical Developer	Platform or delivery team	Runtime customization and infrastructure policy	CustomUserContext
Business Developer	Delivery team	Business services, controllers, API implementation	Q, E, service, controller
Tech Lead	Platform or delivery team	Review consistency and enforce patterns	Query utilities and service conventions

---

Role 1: Product Manager or Architect Owns Modeling

The model owner should own the model because they are closest to business intent and stakeholder communication.

They define:

• Domain entities
• Entity relationships
• Business vocabulary
• Required fields
• Status lifecycle
• Reference models
• Key scenarios
• API expectations
• Compliance-sensitive concepts

The model is the foundation for distributed implementation. If the model is unclear, distributed delivery becomes slower and more expensive.

---

Role 2: Technical Developers Customize UserContext

Technical developers may sit in the platform team or the delivery team, but they should work from a single architecture direction.

Their job is to make CustomUserContext the technical foundation for the project.

They define:

• Tenant isolation
• Permission model
• Internal ID generation
• Common ID generation
• Cache strategy
• i18n strategy
• Logging and trace IDs
• Distributed locking
• Read/write splitting
• Audit trail
• Database routing
• Integration adapters

Example:

public class CustomUserContext extends UserContext {

    public String currentTenantCode() {
        return currentUser().getTenantCode();
    }

    public boolean canOperate(String operation, Object target) {
        return permissionPolicy().canOperate(currentUser(), operation, target);
    }

    public void withBusinessLock(String key, Runnable task) {
        distributedLockService().executeWithLock(currentTenantCode() + ":" + key, task);
    }
}

This makes infrastructure decisions reusable by all delivery developers.

---

Role 3: Delivery Developers Build Business APIs

Most delivery developers should focus on business delivery.

They should use generated Q and E APIs to:

• Build reusable query utility functions
• Implement business services
• Add controller APIs
• Compose workflows
• Apply existing context policies
• Avoid reinventing infrastructure code

Recommended pattern:

Q/E wrapper function -> Service method -> Controller API

Example query wrapper:

public class CustomerQueryUtil {

    public static CustomerRequest visibleCustomers(CustomUserContext userContext) {
        return Q.customers().withStatusIsActive()
                .filterByTenantCode(userContext.currentTenantCode());
    }
}

Example service:

public class CustomerService {

    public List<Customer> listVisibleCustomers(CustomUserContext userContext) {
        return CustomerQueryUtil.visibleCustomers(userContext)
                .orderByNameAscending()
                .comment("Query customers").purpose("Load data")
                .executeForList(userContext);
    }
}

Example controller:

@GetMapping("/customers")
public Object customers(@TQLContext CustomUserContext userContext) {
    return customerService.listVisibleCustomers(userContext);
}

---

Recommended Delivery Flow

1. Model owner or architect defines the domain model
2. TeaQL generates the Java domain API
3. Technical developers customize CustomUserContext
4. Tech lead publishes query/service/controller conventions
5. Delivery developers wrap Q/E into reusable functions
6. Delivery developers implement services and controllers
7. Model owners validate business behavior and model fit
8. Technical reviewers validate context usage and infrastructure safety

---

Responsibility Boundaries

Work Item	Owner
Domain vocabulary	Model owner
Entity model	Model architect
Model review	Model owner + architect
CustomUserContext	Technical developers
Infrastructure policy	Technical developers
Query utility conventions	Tech lead
Business service implementation	Delivery developers
Controller APIs	Delivery developers
Business acceptance	Model owner
Code consistency review	Tech lead

---

What Delivery Developers Should Avoid

Delivery developers should normally avoid:

• Creating their own infrastructure adapters
• Bypassing CustomUserContext
• Writing raw SQL for normal domain queries
• Implementing their own permission logic
• Creating inconsistent ID generation logic
• Accessing cache providers directly
• Adding controller-level business complexity

Instead, they should ask for missing UserContext capabilities or missing reusable query functions.

---

What Technical Developers Should Provide

Technical developers should provide stable foundations:

• CustomUserContext methods with clear names
• Permission helper methods
• Tenant helper methods
• Common ID and internal ID generation
• Locking helpers
• Cache helpers
• Audit helpers
• Read/write routing helpers
• Logging and trace helpers
• Example service templates

Good context methods make distributed implementation much safer.

---

Review Checklist

For model review:

• Does the model match business vocabulary?
• Are entity relationships clear?
• Are status transitions represented correctly?
• Are required fields and lifecycle rules clear?

For technical review:

• Does service code use CustomUserContext?
• Are Q and E expressions wrapped in reusable functions?
• Are controllers thin?
• Are permission and tenant checks centralized?
• Are infrastructure decisions kept out of business services?

For distributed delivery review:

• Is the API behavior correct?
• Are query utilities reusable?
• Is raw SQL avoided?
• Are services easy to read?
• Are tests focused on business scenarios?

---

Why This Works for Distributed Delivery

TeaQL reduces ambiguity between teams:

• The model is owned by model owners.
• Generated APIs make the model executable.
• CustomUserContext centralizes technical policy.
• Delivery developers can focus on business behavior.
• Reviewers can inspect readable Q and E expressions instead of low-level SQL and repository code.

This allows large distributed teams to deliver more APIs without multiplying infrastructure inconsistency.

---

Summary

Distributed Delivery Mode works best when responsibilities are explicit:

• Model owners model the domain.
• Platform or delivery-side technical developers customize UserContext and define infrastructure behavior.
• Delivery developers use Q and E wrapper functions to implement services and controllers that expose APIs.

TeaQL makes this division practical by turning the domain model into a readable Java API and by making CustomUserContext the shared technical foundation.