feat(#119): expose route state in catalog API and sidebar/dashboard

Add routeState field to RouteSummary DTO (null for started, 'stopped'
or 'suspended' for non-default states). Sidebar shows stop/pause icons
and state badge for affected routes in both Apps and Routes sections.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

cameleer3-server-app/src/main/java/com/cameleer3/server/app/config/AgentRegistryBeanConfig.java

@@ -3,11 +3,13 @@ package com.cameleer3.server.app.config;
 import com.cameleer3.server.core.agent.AgentEventRepository;
 import com.cameleer3.server.core.agent.AgentEventService;
 import com.cameleer3.server.core.agent.AgentRegistryService;
+import com.cameleer3.server.core.agent.RouteStateRegistry;
 import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
 
 /**
- * Creates the {@link AgentRegistryService} and {@link AgentEventService} beans.
+ * Creates the {@link AgentRegistryService}, {@link AgentEventService},
+ * and {@link RouteStateRegistry} beans.
  * <p>
  * Follows the established pattern: core module plain class, app module bean config.
  */
@@ -27,4 +29,9 @@ public class AgentRegistryBeanConfig {
     public AgentEventService agentEventService(AgentEventRepository repository) {
         return new AgentEventService(repository);
     }
+
+    @Bean
+    public RouteStateRegistry routeStateRegistry() {
+        return new RouteStateRegistry();
+    }
 }

cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/AgentCommandController.java

@@ -18,6 +18,7 @@ import com.cameleer3.server.core.agent.AgentRegistryService;
 import com.cameleer3.server.core.agent.AgentState;
 import com.cameleer3.server.core.agent.CommandReply;
 import com.cameleer3.server.core.agent.CommandType;
+import com.cameleer3.server.core.agent.RouteStateRegistry;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import jakarta.servlet.http.HttpServletRequest;
@@ -67,17 +68,20 @@ public class AgentCommandController {
     private final ObjectMapper objectMapper;
     private final AgentEventService agentEventService;
     private final AuditService auditService;
+    private final RouteStateRegistry routeStateRegistry;
 
     public AgentCommandController(AgentRegistryService registryService,
                                    SseConnectionManager connectionManager,
                                    ObjectMapper objectMapper,
                                    AgentEventService agentEventService,
-                                   AuditService auditService) {
+                                   AuditService auditService,
+                                   RouteStateRegistry routeStateRegistry) {
         this.registryService = registryService;
         this.connectionManager = connectionManager;
         this.objectMapper = objectMapper;
         this.agentEventService = agentEventService;
         this.auditService = auditService;
+        this.routeStateRegistry = routeStateRegistry;
     }
 
     @PostMapping("/{id}/commands")
@@ -157,6 +161,29 @@ public class AgentCommandController {
         boolean allSuccess = timedOut.isEmpty() &&
                 responses.stream().allMatch(r -> "SUCCESS".equals(r.status()));
 
+        // Update route state when all agents successfully ACK a route-control command
+        if (allSuccess && type == CommandType.ROUTE_CONTROL) {
+            try {
+                @SuppressWarnings("unchecked")
+                var payloadMap = objectMapper.readValue(payloadJson, java.util.Map.class);
+                String routeId = (String) payloadMap.get("routeId");
+                String action = (String) payloadMap.get("action");
+                if (routeId != null && action != null) {
+                    RouteStateRegistry.RouteState newState = switch (action) {
+                        case "start", "resume" -> RouteStateRegistry.RouteState.STARTED;
+                        case "stop" -> RouteStateRegistry.RouteState.STOPPED;
+                        case "suspend" -> RouteStateRegistry.RouteState.SUSPENDED;
+                        default -> null;
+                    };
+                    if (newState != null) {
+                        routeStateRegistry.setState(group, routeId, newState);
+                    }
+                }
+            } catch (Exception e) {
+                log.warn("Failed to parse route-control payload for state tracking", e);
+            }
+        }
+
         auditService.log("broadcast_group_command", AuditCategory.AGENT, group,
                 java.util.Map.of("type", request.type(), "agentCount", futures.size(),
                         "responded", responses.size(), "timedOut", timedOut.size()),

cameleer3-server-app/src/main/java/com/cameleer3/server/app/controller/RouteCatalogController.java

@@ -7,6 +7,7 @@ import com.cameleer3.common.graph.RouteGraph;
 import com.cameleer3.server.core.agent.AgentInfo;
 import com.cameleer3.server.core.agent.AgentRegistryService;
 import com.cameleer3.server.core.agent.AgentState;
+import com.cameleer3.server.core.agent.RouteStateRegistry;
 import com.cameleer3.server.core.storage.DiagramStore;
 import com.cameleer3.server.core.storage.StatsStore;
 import io.swagger.v3.oas.annotations.Operation;
@@ -40,13 +41,16 @@ public class RouteCatalogController {
     private final AgentRegistryService registryService;
     private final DiagramStore diagramStore;
     private final JdbcTemplate jdbc;
+    private final RouteStateRegistry routeStateRegistry;
 
     public RouteCatalogController(AgentRegistryService registryService,
                                    DiagramStore diagramStore,
-                                   @org.springframework.beans.factory.annotation.Qualifier("clickHouseJdbcTemplate") JdbcTemplate jdbc) {
+                                   @org.springframework.beans.factory.annotation.Qualifier("clickHouseJdbcTemplate") JdbcTemplate jdbc,
+                                   RouteStateRegistry routeStateRegistry) {
         this.registryService = registryService;
         this.diagramStore = diagramStore;
         this.jdbc = jdbc;
+        this.routeStateRegistry = routeStateRegistry;
     }
 
     @GetMapping("/catalog")
@@ -128,7 +132,10 @@ public class RouteCatalogController {
                         long count = routeExchangeCounts.getOrDefault(key, 0L);
                         Instant lastSeen = routeLastSeen.get(key);
                         String fromUri = resolveFromEndpointUri(routeId, agentIds);
-                        return new RouteSummary(routeId, count, lastSeen, fromUri);
+                        String state = routeStateRegistry.getState(appId, routeId).name().toLowerCase();
+                        // Only include non-default states (stopped/suspended); null means started
+                        String routeState = "started".equals(state) ? null : state;
+                        return new RouteSummary(routeId, count, lastSeen, fromUri, routeState);
                     })
                     .toList();
 

cameleer3-server-app/src/main/java/com/cameleer3/server/app/dto/RouteSummary.java

@@ -11,5 +11,8 @@ public record RouteSummary(
         @NotNull long exchangeCount,
         Instant lastSeen,
         @Schema(description = "The from() endpoint URI, e.g. 'direct:processOrder'")
-        String fromEndpointUri
+        String fromEndpointUri,
+        @Schema(description = "Operational state of the route: stopped, suspended, or null (started/default)")
+        String routeState
 ) {}
+

cameleer3-server-core/src/main/java/com/cameleer3/server/core/agent/RouteStateRegistry.java

@@ -0,0 +1,36 @@
+package com.cameleer3.server.core.agent;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * In-memory registry tracking the operational state of routes.
+ * State is inferred from successful route-control command ACKs.
+ * On server restart, all states reset to STARTED (default Camel behavior).
+ */
+public class RouteStateRegistry {
+
+    public enum RouteState { STARTED, STOPPED, SUSPENDED }
+
+    // Key: "applicationId:routeId"
+    private final ConcurrentHashMap<String, RouteState> states = new ConcurrentHashMap<>();
+
+    public void setState(String applicationId, String routeId, RouteState state) {
+        states.put(applicationId + ":" + routeId, state);
+    }
+
+    public RouteState getState(String applicationId, String routeId) {
+        return states.getOrDefault(applicationId + ":" + routeId, RouteState.STARTED);
+    }
+
+    public Map<String, RouteState> getStatesForApplication(String applicationId) {
+        Map<String, RouteState> result = new LinkedHashMap<>();
+        states.forEach((key, state) -> {
+            if (key.startsWith(applicationId + ":")) {
+                result.put(key.substring(applicationId.length() + 1), state);
+            }
+        });
+        return result;
+    }
+}

ui/src/components/LayoutShell.tsx

@@ -15,7 +15,7 @@ import {
   useStarred,
 } from '@cameleer/design-system';
 import type { SearchResult, SidebarTreeNode } from '@cameleer/design-system';
-import { Box, Cpu, GitBranch, Settings, FileText, ChevronRight } from 'lucide-react';
+import { Box, Cpu, GitBranch, Settings, FileText, ChevronRight, Square, Pause } from 'lucide-react';
 import { useRouteCatalog } from '../api/queries/catalog';
 import { useAgents } from '../api/queries/agents';
 import { useSearchExecutions, useAttributeKeys } from '../api/queries/executions';
@@ -140,6 +140,14 @@ function makeChevron() {
   return createElement(ChevronRight, { size: 14 });
 }
 
+function makeStopIcon() {
+  return createElement(Square, { size: 12, style: { color: 'var(--error)' } });
+}
+
+function makePauseIcon() {
+  return createElement(Pause, { size: 12, style: { color: 'var(--amber)' } });
+}
+
 /* ------------------------------------------------------------------ */
 /*  Section open-state keys                                           */
 /* ------------------------------------------------------------------ */
@@ -275,6 +283,7 @@ function LayoutContent() {
             id: r.routeId,
             name: r.routeId,
             exchangeCount: r.exchangeCount,
+            routeState: r.routeState ?? undefined,
           })),
         agents: [...(app.agents || [])]
           .sort((a: any, b: any) => cmp(a.name, b.name))
@@ -289,7 +298,7 @@ function LayoutContent() {
 
   // --- Tree nodes ---------------------------------------------------
   const appTreeNodes: SidebarTreeNode[] = useMemo(
-    () => buildAppTreeNodes(sidebarApps, makeStatusDot, makeChevron),
+    () => buildAppTreeNodes(sidebarApps, makeStatusDot, makeChevron, makeStopIcon, makePauseIcon),
     [sidebarApps],
   );
 
@@ -299,7 +308,7 @@ function LayoutContent() {
   );
 
   const routeTreeNodes: SidebarTreeNode[] = useMemo(
-    () => buildRouteTreeNodes(sidebarApps, makeStatusDot, makeChevron),
+    () => buildRouteTreeNodes(sidebarApps, makeStatusDot, makeChevron, makeStopIcon, makePauseIcon),
     [sidebarApps],
   );
 

ui/src/components/sidebar-utils.ts

@@ -9,6 +9,7 @@ export interface SidebarRoute {
   id: string;
   name: string;
   exchangeCount: number;
+  routeState?: 'stopped' | 'suspended';
 }
 
 export interface SidebarAgent {
@@ -71,6 +72,8 @@ export function buildAppTreeNodes(
   apps: SidebarApp[],
   statusDot: (health: string) => ReactNode,
   chevron: () => ReactNode,
+  stopIcon?: () => ReactNode,
+  pauseIcon?: () => ReactNode,
 ): SidebarTreeNode[] {
   return apps.map((app) => ({
     id: app.id,
@@ -83,8 +86,14 @@ export function buildAppTreeNodes(
     children: app.routes.map((r) => ({
       id: `${app.id}/${r.id}`,
       label: r.name,
-      icon: chevron(),
-      badge: formatCount(r.exchangeCount),
+      icon: r.routeState === 'stopped' && stopIcon
+        ? stopIcon()
+        : r.routeState === 'suspended' && pauseIcon
+          ? pauseIcon()
+          : chevron(),
+      badge: r.routeState
+        ? `${r.routeState.toUpperCase()} \u00b7 ${formatCount(r.exchangeCount)}`
+        : formatCount(r.exchangeCount),
       path: `/apps/${app.id}/${r.id}`,
       starrable: true,
       starKey: `route:${app.id}/${r.id}`,
@@ -128,6 +137,8 @@ export function buildRouteTreeNodes(
   apps: SidebarApp[],
   statusDot: (health: string) => ReactNode,
   chevron: () => ReactNode,
+  stopIcon?: () => ReactNode,
+  pauseIcon?: () => ReactNode,
 ): SidebarTreeNode[] {
   return apps.map((app) => ({
     id: `route:${app.id}`,
@@ -138,8 +149,14 @@ export function buildRouteTreeNodes(
     children: app.routes.map((r) => ({
       id: `route:${app.id}/${r.id}`,
       label: r.name,
-      icon: chevron(),
-      badge: formatCount(r.exchangeCount),
+      icon: r.routeState === 'stopped' && stopIcon
+        ? stopIcon()
+        : r.routeState === 'suspended' && pauseIcon
+          ? pauseIcon()
+          : chevron(),
+      badge: r.routeState
+        ? `${r.routeState.toUpperCase()} \u00b7 ${formatCount(r.exchangeCount)}`
+        : formatCount(r.exchangeCount),
       path: `/routes/${app.id}/${r.id}`,
     })),
   }));