Scanner Generation

Scanner & Clustering Slice

This feature manages the processing of static analysis / scanner data to group and cluster codebase artifacts into architectural modules using AI. It operates completely decoupled from the database, performing pure business logic driven by Wolverine messages.

Architectural Components

1. ScannerGenerationHandler

The entry point for the scanner feature worker.

• It consumes a ScannerGenerationRequested event.
• It retrieves the ScannerGenerationPayload from the S3 Claim-Check Store, which includes scanner output or flat lists of system contexts.
• It configures the IAIService using the project’s LLM presets.
• It delegates the core clustering workload to the ScannerClusteringCore.
• It saves the generated clustering result to the Claim-Check Store and returns a ScannerGenerationCompleted message.

2. ScannerClusteringCore

The pure logic core that drives AI-based software clustering and module definition.

• Data Transformation: Given a flat list of scanner findings or source code contexts, it uses the AI to deduce logical boundaries and group them into cohesive modules.
• Prompt Rendering: Leverages PromptLibrary to pass the necessary instructions for architecture discovery.
• State Transformation: Packages the clustered results back into DTO updates that the API can safely persist as document content.

Generation Sequence

The following diagram illustrates how the Scanner feature processes a request from the API.

sequenceDiagram
    participant API as API Apply/Prepare
    participant Broker as RabbitMQ
    participant S3 as Claim-Check Store
    participant Handler as ScannerGenerationHandler
    participant Core as ScannerClusteringCore
    participant AI as IAIService

    API->>S3: PutAsync(ScannerGenerationPayload)
    API->>Broker: Publish ScannerGenerationRequested
    Broker->>Handler: Consume Message
    Handler->>S3: GetAsync(PayloadKey)
    Handler->>Core: GenerateAsync(Payload, IAIService)
    
    Core->>AI: GenerateAsync(Architecture Prompts, FlatScannerData)
    AI-->>Core: Clustered Modules & Metadata
    Core->>Core: Format into Block Updates
    
    Core-->>Handler: ScannerGenerationResult
    Handler->>S3: PutAsync(ScannerGenerationResult)
    Handler->>Broker: Publish ScannerGenerationCompleted
    Broker->>API: Deliver Completed Event

Business Intent

The goal of the Scanner Generation feature is to automate the difficult task of architectural discovery. When static analysis tools or file crawlers output a flat, unorganized list of dependencies, the AI uses its semantic understanding of the source code to group files into logical “Modules”. This is crucial for generating high-quality Software Architecture Documents (SAD) and Software Design Descriptions (SDD) where traceability to specific architectural bounds is required.