# mizcausevic-dev/kg-suite-fleet-overview-action architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/kg-suite-fleet-overview-action, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/kg-suite-fleet-overview-action
- Repository: https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action

## Overview

Purpose and principal workflow: This GitHub Action scans the JSON files in the configured `dir`, routes documents from a mixed Kinetic Gain Suite fleet, and produces a composition report for terminal output and optionally a pull-request comment. The initiating actor is the GitHub Actions runner executing the Action in response to a workflow event—typically `pull_request`; optional gates can fail the run for missing core protocols or too many unrouted documents.

Components

**Action entry and orchestration**
- **GitHub Actions runner** — *null repository path.* Supplies the Action’s inputs and GitHub event environment, and invokes the configured JavaScript entry point.
- **Action metadata** — `action.yml`. Declares the reusable GitHub Action interface and execution configuration; its exact input and runtime declarations were not included in the sampled source.
- **Action entry point** — `src/index.ts`. Reads `INPUT_*` variables and GitHub environment values, calls the runner, and exits using its result or reports an error.
- **Workflow runner** — `src/runner.ts`. Validates inputs, loads JSON files, orchestrates report generation and publication, writes Action outputs, and applies configured failure gates.
- **JSON fleet directory** — *null repository path.* The caller-provided directory of JSON documents that the runner scans.

**Protocol routing and composition**
- **Protocol detector** — `src/detect.ts`. Implements the vendored routing logic, identifying supported protocols by version discriminator or document shape and returning confidence.
- **Fleet overview builder** — `src/overview.ts`. Routes each loaded document, extracts protocol-specific IDs and names, and groups and summarizes results, including missing core protocols, low-confidence detections, and unrouted files.
- **Overview data types** — `src/types.ts`. Defines protocol identifiers and the detection, document-summary, bucket, and fleet-report structures used across the workflow.

**Report and publication**
- **Markdown formatter** — `src/format.ts`. Converts the fleet report into the composition overview, including per-protocol tables, missing-protocol callouts, low-confidence results, and unrouted documents.
- **GitHub Issues API** — *null repository path.* Receives a PR comment when publication is enabled and the runner has a token and PR number.

Relationships

- **GitHub Actions runner -> Action entry point:** invokes the configured Action; the entry point reads runner-provided environment variables.
- **Action entry point -> Workflow runner:** calls `run` with parsed inputs and GitHub environment values.
- **Workflow runner -> JSON fleet directory:** reads the configured directory’s `.json` files and parses them.
- **Workflow runner -> Fleet overview builder:** passes loaded documents for report generation.
- **Fleet overview builder -> Protocol detector:** detects a protocol and confidence for each document before the builder classifies it.
- **Fleet overview builder -> Overview data types:** constructs the report using the shared protocol and summary structures.
- **Workflow runner -> Markdown formatter:** formats the completed report for output and, when appropriate, comment publication.
- **Workflow runner -> GitHub Actions runner:** appends report counts to `GITHUB_OUTPUT`, writes the report, and returns a failure result when configured gates are exceeded.
- **Workflow runner -> GitHub Issues API:** sends a POST request with the formatted comment body when comment publication is requested and the required token, repository, and PR number are available.

Coverage limits: The Action metadata and README document the intended interface, but `action.yml` content was not sampled, so its exact runtime wiring could not be verified. The sampled implementation shows comment creation but not comment updates or deduplication. The detector is vendored in this repository; the README’s references to external protocol-detection and overview packages do not establish runtime calls to those packages.

Main entry points: [`src/runner.ts`](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/runner.ts) (Workflow runner), [`src/overview.ts`](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/overview.ts) (Fleet overview builder), [`src/index.ts`](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/index.ts) (Action entry point), [`src/detect.ts`](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/detect.ts) (Protocol detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Action orchestration"]
  node_github_runner["GitHub Actions runner<br/>External actor"]
  node_action_entry["Action entry point<br/>[index.ts]"]
  node_workflow_runner["Workflow runner<br/>Orchestrator"]
  node_fleet_directory["JSON fleet directory<br/>Input"]
end

subgraph group_routing["Protocol routing"]
  node_overview_builder["Fleet overview builder<br/>Report builder"]
  node_protocol_detector["Protocol detector<br/>[detect.ts]"]
  node_overview_types["Overview data types<br/>Shared types"]
end

subgraph group_reporting["Report and publication"]
  node_markdown_formatter["Markdown formatter<br/>[format.ts]"]
  node_github_issues_api["GitHub Issues API<br/>External API"]
end

node_github_runner -->|"invokes"| node_action_entry
node_action_entry -->|"calls run"| node_workflow_runner
node_workflow_runner -->|"reads JSON files"| node_fleet_directory
node_workflow_runner -->|"passes documents"| node_overview_builder
node_overview_builder -->|"detects protocols"| node_protocol_detector
node_overview_builder -->|"constructs report"| node_overview_types
node_workflow_runner -->|"formats report"| node_markdown_formatter
node_workflow_runner -->|"writes outputs"| node_github_runner
node_workflow_runner -.->|"posts comment"| node_github_issues_api

click node_action_entry "https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/index.ts"
click node_workflow_runner "https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/runner.ts"
click node_overview_builder "https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/overview.ts"
click node_protocol_detector "https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/detect.ts"
click node_overview_types "https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/types.ts"
click node_markdown_formatter "https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/format.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_github_runner,node_action_entry,node_workflow_runner,node_fleet_directory toneBlue
class node_overview_builder,node_protocol_detector,node_overview_types toneAmber
class node_markdown_formatter,node_github_issues_api toneMint
```

## Components

### Action orchestration

- **GitHub Actions runner**: External actor
- [Action entry point](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/index.ts): Entry point · `src/index.ts`
- [Workflow runner](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/runner.ts): Orchestrator · `src/runner.ts`
- **JSON fleet directory**: Input

### Protocol routing

- [Fleet overview builder](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/overview.ts): Report builder · `src/overview.ts`
- [Protocol detector](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/detect.ts): Detector · `src/detect.ts`
- [Overview data types](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/types.ts): Shared types · `src/types.ts`

### Report and publication

- [Markdown formatter](https://github.com/mizcausevic-dev/kg-suite-fleet-overview-action/blob/main/src/format.ts): Formatter · `src/format.ts`
- **GitHub Issues API**: External API

## Connections

- GitHub Actions runner → Action entry point: invokes
- Action entry point → Workflow runner: calls run
- Workflow runner → JSON fleet directory: reads JSON files
- Workflow runner → Fleet overview builder: passes documents
- Fleet overview builder → Protocol detector: detects protocols
- Fleet overview builder → Overview data types: constructs report
- Workflow runner → Markdown formatter: formats report
- Workflow runner → GitHub Actions runner: writes outputs
- Workflow runner → GitHub Issues API: posts comment · Only when comment publication is requested and required credentials and PR details are available.