spring-state-machine-renderer/plan-extended-anaylis-v1/architecture.md

Extended State Machine Analysis: Trigger Point Mapping

Overview

The goal of this extension is to bridge the gap between state machine definitions and their real-world usage in application code. By identifying where events are triggered (e.g., REST endpoints, message listeners), we can provide a more holistic view of the system's behavior.

Key Concepts

• Trigger Point: A location in the source code where an event is sent to a state machine (e.g., stateMachine.sendEvent(E)).
• Entry Point: A high-level application component (e.g., a REST Controller or Message Listener) that ultimately leads to a Trigger Point.
• Event Linkage: The process of connecting an Entry Point to one or more state machine transitions via the event that triggers them.

Proposed Architecture

1. TriggerDetector

A generic interface for identifying trigger points and extracting context.

public interface TriggerDetector {
    List<TriggerPoint> detect(CompilationUnit cu, CodebaseContext context);
}

2. Predefined Detectors

• SpringMvcDetector: Looks for @RestController / @Controller and mappings like @PostMapping.
• SpringWebFluxDetector:
  • Annotation-based: Similar to MVC but handles Mono/Flux return types.
  • Functional-based: Scans for RouterFunction beans and extracts routes/handlers.
• MessageListenerDetector:
  • Kafka: @KafkaListener.
  • RabbitMQ: @RabbitListener.
  • JMS: @JmsListener.
• GenericEventDetector: Looks for any sendEvent call and tries to find its context.

3. TriggerPoint Model

public record TriggerPoint(
    String className,
    String methodName,
    String event,
    TriggerContext context
) {}

public record TriggerContext(
    String type, // "REST", "KAFKA", "JMS", "GENERIC"
    Map<String, String> metadata // path="/api/submit", topic="orders", etc.
) {}

4. Analysis Flow

1. Scan Phase: Existing CodebaseContext.scan(root).
2. Configuration Phase: Existing StateMachineAggregator finds states and transitions.
3. Trigger Discovery Phase: New TriggerAggregator runs various TriggerDetectors over the scanned codebase.
4. Correlation Phase: Match TriggerPoint.event with Transition.event.
5. Export Phase: Enhance DOT/SCXML or generate a new "System Flow Map".

Challenges

• Multiple State Machines: How to know which StateMachine instance is being used?
  • Initial heuristic: If there's only one, assume it's that one.
  • If multiple, check generic types StateMachine<S, E> or variable names.
• Indirect Calls: Method A (Controller) calls B (Service), and B calls sendEvent.
  • Static analysis might need to follow call graphs.
  • Use JDT's cross-reference capabilities if possible, or build a simple call graph.
• Inheritance:
  • Controllers might extend base classes with common mappings.
  • State machine configurations already handle inheritance; Trigger detection should too.

Next Steps

1. Create a PoC TriggerDetector for Spring MVC.
2. Integrate TriggerAggregator into the main analysis pipeline.
3. Update the Exporter to visualize these links.