enrichment schema

plan-extended-anaylis-v1/architecture.md

@@ -0,0 +1,68 @@
+# 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.