# 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.
```java
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
```java
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 `TriggerDetector`s 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.