Onshore/Offshore Mode

Overview

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

In this mode:

• Onshore product managers or architects own the domain model.
• Onshore or offshore technical developers customize UserContext and define technical infrastructure.
• A larger group of offshore business 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 onshore model owners and offshore implementation teams.

---

Recommended Team Structure

Role	Location	Main Responsibility	TeaQL Focus
Product Manager	Onshore	Business requirements, workflows, vocabulary	Domain model
Architect	Onshore	Model boundaries, integration boundaries, technical direction	Domain model and architecture
Technical Developer	Onshore or Offshore	Runtime customization and infrastructure policy	CustomUserContext
Business Developer	Mostly Offshore	Business services, controllers, API implementation	Q, E, service, controller
Tech Lead	Onshore or Offshore	Review consistency and enforce patterns	Query utilities and service conventions

---

Role 1: Onshore Product Manager or Architect Owns Modeling

The onshore product manager or architect 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 offshore implementation. If the model is unclear, offshore delivery becomes slower and more expensive.

---

Role 2: Technical Developers Customize UserContext

Technical developers may be onshore or offshore, 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 offshore business developers.

---

Role 3: Offshore Business Developers Build Business APIs

Most offshore 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()
                .executeForList(userContext);
    }
}

Example controller:

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

---

Recommended Delivery Flow

1. Onshore product manager 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. Offshore business developers wrap Q/E into reusable functions
6. Offshore business developers implement services and controllers
7. Onshore reviewers validate business behavior and model fit
8. Technical reviewers validate context usage and infrastructure safety

---

Responsibility Boundaries

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

---

What Offshore Business Developers Should Avoid

Offshore business 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 offshore 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 offshore 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 Onshore/Offshore Delivery

TeaQL reduces ambiguity between teams:

• The model is owned by onshore decision makers.
• Generated APIs make the model executable.
• CustomUserContext centralizes technical policy.
• Offshore 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 offshore teams to deliver more APIs without multiplying infrastructure inconsistency.

---

Summary

Onshore/Offshore Mode works best when responsibilities are explicit:

• Onshore product managers or architects model the domain.
• Onshore or offshore technical developers customize UserContext and define infrastructure behavior.
• Offshore business 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.