# ctrf-io/ai-test-reporter architecture

> Architecture diagram of the GitHub repository ctrf-io/ai-test-reporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ctrf-io/ai-test-reporter
- Repository: https://github.com/ctrf-io/ai-test-reporter

## Overview

##### Project type and purpose
- This is a Node.js + TypeScript command-line tool (CLI) named “AI Test Reporter” (package name: ai-ctrf).
- Its purpose is to read a CTRF JSON test report, analyze every failing test via one of many AI model providers, optionally consolidate those AI summaries, and write back an augmented CTRF report.

##### File structure
- Top-level files: ESLint/Prettier configs, GitHub workflows, CONTRIBUTING, LICENSE, README.
- package.json / tsconfig.json define a Node CLI written in TS.
- /src holds the entire application source:
- index.ts – CLI entry point and command dispatcher
- common.ts, constants.ts – shared utilities/config
- consolidated-summary.ts – logic to merge multiple AI responses into a high-level overview
- models/ – one adapter per AI provider (azure-openai.ts, claude.ts, deepseek.ts, gemini.ts, grok.ts, mistral.ts, openai.ts, openrouter.ts, perplexity.ts)

##### README for additional insights
- The README confirms single-process CLI usage via `npx ai-ctrf <provider> <path>`.
- Each provider module wraps HTTP calls to an external AI API.
- It supports options like model, systemPrompt, temperature, maxTokens, consolidate, etc.
- Input: CTRF JSON test report; Output: the same CTRF JSON augmented with an “ai” field per failing test (and optionally a consolidated summary).

##### Main components
a. CLI Entry Point (index.ts)
b. Core Orchestrator
- File Reader / JSON Parser
- Test Filter (extract failed tests)
- Request Batcher (respects --maxMessages)
- Consolidated Summary Module
c. Provider Adapters (Strategy modules under src/models)
- One adapter per AI service: OpenAI, Azure, Claude, Gemini, Mistral, Grok, DeepSeek, Perplexity, OpenRouter
- Each adapter implements a common interface (prompt construction, HTTP request, parse response)
d. External AI Services
- REST/HTTP endpoints for each provider
e. File Writer
- Merge AI responses into original CTRF object
- Serialize & overwrite or output to new file
f. Configuration / Environment
- ENV vars (API keys, endpoints, deployment names)
- CLI flags

##### Relationships and interactions (data flow)
1. User invokes CLI (`npx ai-ctrf <provider> report.json`)
2. Index.ts parses CLI arguments → selects provider adapter → loads config
3. File Reader loads `report.json` → JSON parser produces Report object
4. Core Orchestrator filters failed tests → for each chunk (maxMessages) → calls Adapter.sendRequests()
5. Adapter builds prompt + sends HTTP request to External AI Service → receives AI summary(s)
6. Core Orchestrator attaches AI summaries to each test object
7. If `--consolidate` enabled: consolidated-summary.ts processes all summaries → produces high-level overview
8. File Writer serializes augmented Report → writes back to disk
9. CLI logs output (optional)

##### Architectural patterns and design principles
- Strategy Pattern: each AI provider implements a common interface (sendRequests, buildPrompt).
- Single responsibility: parsing, provider communication, response consolidation, file I/O are separate modules.
- Plugin-style extensibility: adding a new provider only requires a new module in src/models.
- Config-driven: environment variables + CLI flags drive behavior.

##### Key labels and elements
- “--maxMessages,” “--consolidate” flags influencing batching & consolidation
- Illustration of Strategy interface used by all provider modules

##### Final recommendation
- With key technology: Node.js, TypeScript, HTTP/REST.
- Keep it concise but complete—each internal module and external dependency should be represented.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Config and Types
    Config["Configuration / Env Vars"]:::config
    click Config "https://github.com/ctrf-io/ai-test-reporter/blob/main/package.json"
    click Config "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/constants.ts"
    CTRFTypes["CTRF Types"]:::types
    click CTRFTypes "https://github.com/ctrf-io/ai-test-reporter/blob/main/types/ctrf.d.ts"

    %% Main CLI Process
    subgraph "CLI Tool (Node.js + TS)" 
        direction TB
        CLIEntry["CLI Entry Point\n(index.ts)"]:::internal
        click CLIEntry "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/index.ts"

        subgraph "Internal Modules" 
            direction TB
            FileReader["File Reader / JSON Parser"]:::internal
            TestFilter["Test Filter"]:::internal
            RequestBatcher["Request Batcher"]:::internal
            Orchestrator["Core Orchestrator\n(arg parsing, dispatch)"]:::internal
            FileWriter["File Writer"]:::internal
            click FileReader "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/common.ts"
            click TestFilter "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/common.ts"
            click RequestBatcher "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/common.ts"
            click Orchestrator "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/common.ts"
            click FileWriter "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/common.ts"
        end

        Consolidator["Consolidated Summary Module"]:::internal
        click Consolidator "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/consolidated-summary.ts"
    end

    %% Provider Adapters
    subgraph "AI Provider Adapters" 
        direction TB
        AZURE["Azure OpenAI Adapter"]:::adapter
        CLAUDE["Claude Adapter"]:::adapter
        DEEPSEEK["DeepSeek Adapter"]:::adapter
        GEMINI["Gemini Adapter"]:::adapter
        GROK["Grok Adapter"]:::adapter
        MISTRAL["Mistral Adapter"]:::adapter
        OPENAI["OpenAI Adapter"]:::adapter
        OPENROUTER["OpenRouter Adapter"]:::adapter
        PERPLEXITY["Perplexity Adapter"]:::adapter

        click AZURE "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/azure-openai.ts"
        click CLAUDE "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/claude.ts"
        click DEEPSEEK "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/deepseek.ts"
        click GEMINI "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/gemini.ts"
        click GROK "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/grok.ts"
        click MISTRAL "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/mistral.ts"
        click OPENAI "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/openai.ts"
        click OPENROUTER "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/openrouter.ts"
        click PERPLEXITY "https://github.com/ctrf-io/ai-test-reporter/blob/main/src/models/perplexity.ts"
    end

    %% External AI Services
    subgraph "External AI Services" 
        direction TB
        CloudAI["AI Service Endpoints"]:::external
    end

    %% Data File
    ReportFile["CTRF JSON File"]:::data

    %% Flows
    ReportFile -->|read report.json| FileReader
    CLIEntry -->|CLI args| Orchestrator
    Config --> Orchestrator
    FileReader --> TestFilter
    TestFilter --> RequestBatcher
    RequestBatcher -->|batch tests| AZURE
    RequestBatcher --> CLAUDE
    RequestBatcher --> DEEPSEEK
    RequestBatcher --> GEMINI
    RequestBatcher --> GROK
    RequestBatcher --> MISTRAL
    RequestBatcher --> OPENAI
    RequestBatcher --> OPENROUTER
    RequestBatcher --> PERPLEXITY

    AZURE -->|HTTP request / prompt| CloudAI
    CLAUDE -->|HTTP request / prompt| CloudAI
    DEEPSEEK -->|HTTP request / prompt| CloudAI
    GEMINI -->|HTTP request / prompt| CloudAI
    GROK -->|HTTP request / prompt| CloudAI
    MISTRAL -->|HTTP request / prompt| CloudAI
    OPENAI -->|HTTP request / prompt| CloudAI
    OPENROUTER -->|HTTP request / prompt| CloudAI
    PERPLEXITY -->|HTTP request / prompt| CloudAI

    CloudAI -->|AI summary response| AZURE
    CloudAI --> CLAUDE
    CloudAI --> DEEPSEEK
    CloudAI --> GEMINI
    CloudAI --> GROK
    CloudAI --> MISTRAL
    CloudAI --> OPENAI
    CloudAI --> OPENROUTER
    CloudAI --> PERPLEXITY

    AZURE --> Orchestrator
    CLAUDE --> Orchestrator
    DEEPSEEK --> Orchestrator
    GEMINI --> Orchestrator
    GROK --> Orchestrator
    MISTRAL --> Orchestrator
    OPENAI --> Orchestrator
    OPENROUTER --> Orchestrator
    PERPLEXITY --> Orchestrator

    Orchestrator -->|attach summaries| Consolidator
    Consolidator -->|consolidation step| Orchestrator
    Orchestrator -->|augmented report.json| FileWriter
    FileWriter -->|write report.json| ReportFile
    FileWriter -->|log output| CLIEntry

    %% Styles
    classDef internal fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef adapter fill:#FFF5BA,stroke:#D6A700,color:#D6A700;
    classDef external fill:#FFE0CC,stroke:#D94300,color:#D94300;
    classDef data fill:#E2F0D9,stroke:#1F7A1F,color:#1F7A1F;
    classDef config fill:#E8F3D0,stroke:#6B8E23,color:#6B8E23;
    classDef types fill:#F0F0F0,stroke:#636363,color:#636363;
```
