Request Lifecycle

This page is the quick lifecycle view. For the full interactive debug tree, open /docs/v2/deep-dive/request-lifecycle.

1. API Entry Point

The journey begins when a client sends a POST request to /api/v1/conversation/message.

ConversationController.message

package: com.github.salilvnair.convengine.api.controllerfile: src/main/java/com/github/salilvnair/convengine/api/controller/ConversationController.java

JAVA

@PostMapping("/message")
public ConversationResponse message(@RequestBody ConversationRequest request) {
  EngineContext engineContext = EngineContext.builder()
  .conversationId(request.getConversationId())
  .userText(request.getMessage())
  .inputParams(request.getInputParams())
  .build();

  EngineResult result = engine.process(engineContext);

  return mapToResponse(result);
}

2. Engine Processing

DefaultConversationalEngine.process

package: com.github.salilvnair.convengine.engine.providerfile: src/main/java/com/github/salilvnair/convengine/engine/provider/DefaultConversationalEngine.java

JAVA

@Override
public EngineResult process(EngineContext engineContext) {
  EngineSession session = sessionFactory.open(engineContext);
  session.setConversationHistory(historyProvider.lastTurns(session.getConversationId(), 10));
  EnginePipeline pipeline = pipelineFactory.create();
  return pipeline.execute(session);
}

3. The Pipeline (Step-by-Step)

1LoadOrCreateConversationStep

2CacheInspectAuditStep

3ResetConversationStep

4PersistConversationBootstrapStep

5AuditUserInputStep

6PolicyEnforcementStep

7DialogueActStep

8InteractionPolicyStep

9CorrectionStep

10ActionLifecycleStep

11DisambiguationStep

12GuardrailStep

13IntentResolutionStep

14ResetResolvedIntentStep

15FallbackIntentStateStep

16AddContainerDataStep

17PendingActionStep

18ToolOrchestrationStep

19McpToolStep

20SchemaExtractionStep

21AutoAdvanceStep

22RulesStep

23StateGraphStep

24ResponseResolutionStep

25MemoryStep

26PersistConversationStep

27PipelineEndGuardStep

Core path vs conditional steps

DialogueActStep, InteractionPolicyStep, CorrectionStep, ActionLifecycleStep, DisambiguationStep, PendingActionStep, ToolOrchestrationStep, McpToolStep, StateGraphStep, and MemoryStep are route-conditional and execute only when their prerequisites are met.

Audit Trail + Real-world trace

Every step emits audit events. Use /audit/{id}/trace, then open /docs/v2/deep-dive/request-lifecycle and /docs/v2/deep-dive/examples to compare turn-by-turn real-world traces.