# mizcausevic-dev/agent-card-fleet-summary architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/agent-card-fleet-summary, 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/agent-card-fleet-summary
- Repository: https://github.com/mizcausevic-dev/agent-card-fleet-summary

## Overview

Purpose and principal workflow: This Node.js library and CLI analyze a fleet of A2A AgentCard JSON documents, count autonomy and memory categories, and report governance findings. The main workflow starts when a command-line user runs `agent-card-fleet-summary` with a cards directory; the CLI reads the cards, invokes the analyzer, formats a report, and writes it to stdout or a file. The package also exposes the analyzer and formatters to library consumers.

Components

**CLI and file workflow**
- **CLI runner** — `src/cli.ts`: Parses options, reads `*.json` AgentCards from a directory, calls the summarizer and formatter, and writes output; optionally exits with failure when high-severity findings exist.

**Analysis and output**
- **Fleet analyzer** — `src/summarize.ts`: Builds per-agent rows and fleet counts, evaluates the documented governance rules, and returns a report with `ok` false when any finding is high severity.
- **Report formatters** — `src/format.ts`: Renders a report as Markdown or a concise summary; the CLI also supports JSON serialization directly.
- **Library entry point** — `src/index.ts`: Exports the summarizer, formatters, and public types for package consumers.

**Domain contract**
- **AgentCard and report types** — `src/types.ts`: Defines the AgentCard subset analyzed by the library, finding codes and severities, summary rows, and the fleet report shape.

**External actors**
- **Command-line user** — path: null. Supplies the cards directory and optional formatting, timestamp, output, and failure-threshold options.
- **Library consumer** — path: null. May provide AgentCard objects to the exported summarizer and use the exported formatters.

Relationships

- **Command-line user -> CLI runner**: invokes the installed command with a cards directory and options; documented usage and argument handling establish this entry point.
- **CLI runner -> Fleet analyzer**: calls `summarize(cards, args.now)` after loading the input files.
- **Fleet analyzer -> AgentCard and report types**: consumes AgentCard-shaped inputs and returns a FleetReport containing rows, counts, findings, and status.
- **CLI runner -> Report formatters**: calls a formatter for Markdown or summary output; for JSON, serializes the report directly.
- **Report formatters -> AgentCard and report types**: reads the report structure and finding severities to render output.
- **CLI runner -> Command-line user**: writes the report to stdout unless an output file was specified; returns documented status codes, including failure for high findings when requested.
- **CLI runner -> Output file**: writes formatted report text when `--out` is supplied; the file is a runtime destination, not a repository component.
- **Library consumer -> Library entry point**: imports the package’s public exports.
- **Library entry point -> Fleet analyzer**: re-exports `summarize` for library use.
- **Library entry point -> Report formatters**: re-exports `toMarkdown` and `toSummary`.
- **Library entry point -> AgentCard and report types**: re-exports the public types.

Coverage limits: The sampled source establishes the CLI, analysis rules, report formatting, and public exports. No persistent state, network calls, or external provider integrations are shown; the analyzer operates on the supplied in-memory cards.

Main entry points: [`src/cli.ts`](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/cli.ts) (CLI Runner), [`src/index.ts`](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/index.ts) (Library Entry Point), [`src/summarize.ts`](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/summarize.ts) (Fleet Analyzer), [`src/format.ts`](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/format.ts) (Report Formatters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and File Workflow"]
  node_cli_runner["CLI Runner<br/>[cli.ts]"]
end

subgraph group_analysis["Analysis and Output"]
  node_fleet_analyzer["Fleet Analyzer<br/>[summarize.ts]"]
  node_report_formatters["Report Formatters<br/>[format.ts]"]
  node_library_entry_point["Library Entry Point<br/>Package exports"]
end

subgraph group_contract["Domain Contract"]
  node_agentcard_report_types["AgentCard and Report Types<br/>Domain contract"]
end

node_command_line_user(("Command-line User<br/>External actor"))
node_output_file["Output File<br/>Runtime destination"]
node_library_consumer(("Library Consumer<br/>External actor"))

node_command_line_user -->|"invokes"| node_cli_runner
node_cli_runner -->|"calls"| node_fleet_analyzer
node_fleet_analyzer -->|"uses"| node_agentcard_report_types
node_cli_runner -->|"formats report"| node_report_formatters
node_report_formatters -->|"reads"| node_agentcard_report_types
node_cli_runner -->|"writes report"| node_command_line_user
node_cli_runner -->|"writes report"| node_output_file
node_library_consumer -->|"imports"| node_library_entry_point
node_library_entry_point -->|"re-exports"| node_fleet_analyzer
node_library_entry_point -->|"re-exports"| node_report_formatters
node_library_entry_point -->|"re-exports"| node_agentcard_report_types

click node_cli_runner "https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/cli.ts"
click node_fleet_analyzer "https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/summarize.ts"
click node_report_formatters "https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/format.ts"
click node_library_entry_point "https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/index.ts"
click node_agentcard_report_types "https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/types.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_cli_runner,node_command_line_user toneBlue
class node_fleet_analyzer,node_report_formatters,node_library_entry_point toneAmber
class node_agentcard_report_types toneMint
class node_output_file,node_library_consumer toneIndigo
```

## Components

### CLI and File Workflow

- [CLI Runner](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/cli.ts): CLI · `src/cli.ts`

### Analysis and Output

- [Fleet Analyzer](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/summarize.ts): Analyzer · `src/summarize.ts`
- [Report Formatters](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/format.ts): Formatter · `src/format.ts`
- [Library Entry Point](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/index.ts): Package exports · `src/index.ts`

### Domain Contract

- [AgentCard and Report Types](https://github.com/mizcausevic-dev/agent-card-fleet-summary/blob/main/src/types.ts): Domain contract · `src/types.ts`

### Other components

- **Command-line User**: External actor
- **Output File**: Runtime destination
- **Library Consumer**: External actor

## Connections

- Command-line User → CLI Runner: invokes
- CLI Runner → Fleet Analyzer: calls
- Fleet Analyzer → AgentCard and Report Types: uses
- CLI Runner → Report Formatters: formats report
- Report Formatters → AgentCard and Report Types: reads
- CLI Runner → Command-line User: writes report
- CLI Runner → Output File: writes report
- Library Consumer → Library Entry Point: imports
- Library Entry Point → Fleet Analyzer: re-exports
- Library Entry Point → Report Formatters: re-exports
- Library Entry Point → AgentCard and Report Types: re-exports