Internal Team Mode

Overview

Internal Team Mode is designed for small and focused product teams, typically 5 to 10 people.

In this mode, TeaQL helps the team split work by responsibility:

• Product managers or architects own the domain model.
• Technical developers customize UserContext and infrastructure behavior.
• Business developers use generated Q and E APIs to implement business services and controllers.

The goal is to let a small team move fast without mixing domain modeling, infrastructure customization, and business API delivery in the same role.

---

Recommended Team Structure

Role	Main Responsibility	TeaQL Focus
Product Manager	Define business concepts, workflows, and rules	Domain model
Architect	Validate model boundaries and system structure	Domain model and module boundaries
Technical Developer	Customize runtime and infrastructure	CustomUserContext, cache, ID, audit, locking, routing
Business Developer	Implement business functions and APIs	Q, E, service, controller

One person can hold more than one role in a small team, but the responsibilities should still remain clear.

---

Role 1: Product Manager or Architect Builds the Model

The product manager or architect is responsible for turning the business into a stable TeaQL model.

They should define:

• Core entities
• Entity fields
• Relationships
• Lists and references
• Status fields
• Business vocabulary
• Lifecycle rules
• Required fields
• Important query scenarios

Examples:

• Customer has many orders.
• Order has many order lines.
• Invoice belongs to one customer.
• Shipment belongs to one order.
• Order status follows a controlled lifecycle.

The model should describe the business clearly enough that generated APIs become readable.

---

Role 2: Technical Developers Customize UserContext

Technical developers own the project-specific runtime behavior.

They should customize:

• Internal ID generation
• Common ID generation
• Cache policy
• i18n and locale behavior
• Logging and trace ID
• Distributed locking
• Read/write splitting
• Audit trail
• Permission checks
• Tenant isolation
• Infrastructure adapters

Most of these decisions should be exposed through CustomUserContext.

Example:

public class CustomUserContext extends UserContext {

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

    public boolean canReadOrder(Order order) {
        return permissionService().canReadOrder(currentUser(), order);
    }

    public String nextOrderNumber() {
        return commonIdGenerator().nextCommonId("Order", this);
    }
}

This keeps infrastructure and cross-cutting policies outside business services.

---

Role 3: Business Developers Build Services and Controllers

Business developers use generated Q and E APIs to implement business behavior.

Their work should focus on:

• Reusable query functions
• Business service methods
• Controller APIs
• Request/response adaptation
• Business workflow orchestration

Recommended layering:

Controller -> Service -> Util

Example reusable query function:

public class OrderQueryUtil {

    public static OrderRequest activeOrdersForCurrentUser(CustomUserContext userContext) {
        return Q.orders()
                .whichStatusNot(OrderStatus.CANCELLED)
                .filterByUserId(userContext.currentUserId());
    }
}

Example service:

public class OrderService {

    public List<Order> listMyActiveOrders(CustomUserContext userContext) {
        return OrderQueryUtil.activeOrdersForCurrentUser(userContext)
                .orderByCreateTimeDescending()
                .executeForList(userContext);
    }
}

Example controller:

@GetMapping("/orders/my-active")
public Object myActiveOrders(@TQLContext CustomUserContext userContext) {
    return orderService.listMyActiveOrders(userContext);
}

---

Recommended Workflow

1. Product manager or architect models the domain
2. TeaQL generates Java domain APIs
3. Technical developers customize CustomUserContext
4. Business developers wrap Q/E expressions into reusable functions
5. Business developers implement services
6. Controllers expose stable APIs
7. Team reviews model and service behavior together

This workflow lets each role work at the correct abstraction level.

---

Deliverables by Role

Role	Deliverables
Product Manager	Domain terms, business rules, status lifecycle, core scenarios
Architect	Model structure, aggregate boundaries, integration boundaries
Technical Developer	CustomUserContext, infrastructure services, policies, runtime configuration
Business Developer	Query utilities, service methods, controllers, API behavior

---

Why This Works for 5-10 People

TeaQL reduces the amount of hand-written infrastructure and repository code, so a small team can specialize without becoming slow.

The model becomes the shared language:

• Product people can review the domain.
• Architects can review boundaries.
• Technical developers can control infrastructure through context.
• Business developers can write readable service code with Q and E.

---

Common Mistakes

• Letting every developer invent their own query style.
• Putting permission checks directly in controllers.
• Mixing ID generation and business service logic.
• Bypassing CustomUserContext for infrastructure decisions.
• Creating too many DTOs instead of using generated entity behavior.
• Using raw SQL before trying generated TeaQL expressions.

---

Best Practices

• Keep the model small and correct before expanding.
• Put cross-cutting behavior in CustomUserContext.
• Wrap common Q and E patterns in util functions.
• Keep controllers thin.
• Use services for transaction boundaries.
• Review generated API readability with the whole team.
• Treat domain vocabulary as a team contract.

---

Summary

Internal Team Mode works best when a 5-10 person team divides work clearly:

• Product manager or architect owns modeling.
• Technical developers own UserContext customization and infrastructure.
• Business developers use Q and E to build reusable functions, services, and controllers.

This gives small teams a clean path from domain model to production API without excessive boilerplate.