ArchitectureSummaryApiController.java

package com.taxonomy.architecture.controller;

import com.taxonomy.dto.ArchitectureSummary;
import com.taxonomy.dto.NodeGraphMetadata;
import com.taxonomy.catalog.model.TaxonomyNode;
import com.taxonomy.catalog.service.TaxonomyService;
import com.taxonomy.architecture.service.ArchitectureSummaryService;
import com.taxonomy.architecture.service.DerivedMetadataService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.LinkedHashMap;
import java.util.Map;

/**
 * REST API for Architecture Summary and Derived Metadata.
 *
 * <p>Provides:
 * <ul>
 *     <li>Architecture summary with next-step guidance</li>
 *     <li>Node-level graph metadata (relation counts, roles)</li>
 *     <li>Trigger for metadata recomputation</li>
 * </ul>
 */
@RestController
@RequestMapping("/api/architecture")
@Tag(name = "Architecture Intelligence")
public class ArchitectureSummaryApiController {

    private final ArchitectureSummaryService summaryService;
    private final DerivedMetadataService metadataService;
    private final TaxonomyService taxonomyService;

    public ArchitectureSummaryApiController(ArchitectureSummaryService summaryService,
                                            DerivedMetadataService metadataService,
                                            TaxonomyService taxonomyService) {
        this.summaryService = summaryService;
        this.metadataService = metadataService;
        this.taxonomyService = taxonomyService;
    }

    @GetMapping("/summary")
    @Operation(summary = "Get architecture summary with next steps",
            description = "Returns key findings (top capabilities, processes, services, hubs, gaps) " +
                    "and recommended next actions based on the current architecture state.")
    public ResponseEntity<ArchitectureSummary> getSummary() {
        return ResponseEntity.ok(summaryService.buildSummary());
    }

    @PostMapping("/metadata/recompute")
    @Operation(summary = "Recompute derived graph metadata",
            description = "Recalculates relation counts, requirement coverage, and graph roles " +
                    "for all taxonomy nodes. This should be called after bulk data changes.")
    public ResponseEntity<Map<String, Object>> recomputeMetadata() {
        int updated = metadataService.recomputeAll();
        Map<String, Object> result = new LinkedHashMap<>();
        result.put("updatedNodes", updated);
        return ResponseEntity.ok(result);
    }

    @GetMapping("/metadata/{nodeCode}")
    @Operation(summary = "Get derived metadata for a specific node",
            description = "Returns relation counts, requirement coverage count, and graph role " +
                    "for the given node code.")
    public ResponseEntity<?> getNodeMetadata(@PathVariable String nodeCode) {
        TaxonomyNode node = taxonomyService.getNodeByCode(nodeCode);
        if (node != null) {
            NodeGraphMetadata metadata = new NodeGraphMetadata(
                    node.getCode(),
                    node.getIncomingRelationCount(),
                    node.getOutgoingRelationCount(),
                    node.getTotalRelationCount(),
                    node.getRequirementCoverageCount(),
                    node.getGraphRole()
            );
            return ResponseEntity.ok(metadata);
        } else {
            return ResponseEntity.notFound().build();
        }
    }
}