# mizcausevic-dev/wellknown-index-aggregator architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/wellknown-index-aggregator, 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/wellknown-index-aggregator
- Repository: https://github.com/mizcausevic-dev/wellknown-index-aggregator

## Overview

#### Purpose and principal workflow

This Node.js library and CLI turns Kinetic Gain disclosure JSON files into a `/.well-known/index.json` index, while reporting integrity issues such as missing IDs, duplicate IDs, and broken references. The workflow starts when a **CLI user or automation** invokes `wk-index` with a disclosure directory; alternatively, a library consumer calls the exported API with loaded documents. The tool scans local files, identifies and indexes documents, then prints or writes the index or a full report. It does not use a network, LLM, or external schema validator.

#### Components

##### Entry points and input
- **CLI** — `src/cli.ts`: Parses options, loads the requested directory, runs index construction, emits findings, and writes output to stdout or a file; `--strict` returns an error status when integrity errors exist.
- **Public library API** — `src/index.ts`: Re-exports index construction, rendering, document loading, detection helpers, and public types for library consumers.
- **CLI user or automation** — `null` repository path: Invokes the CLI with arguments, including the input directory and optional output/report settings.
- **Disclosure directory** — `null` repository path: Supplies local JSON disclosure files to the loader.
- **Index consumer or output destination** — `null` repository path: Receives the generated index through stdout or the CLI-selected output file.
- **Directory loader** — `src/load.ts`: Recursively reads `.json` files, requires each top-level value to be an object, and returns filename/body pairs sorted by filename.

##### Document interpretation and index construction
- **Disclosure detection and routing** — `src/detect.ts`: Identifies kinds from version keys and extracts IDs, versions, references, and canonical well-known paths.
- **Index builder and integrity checks** — `src/build.ts`: Builds entries; reports unknown kinds, missing IDs or versions, duplicate IDs, and references to IDs not present in the indexed set; sorts entries and calculates counts and `ok`.
- **Index renderer** — `src/build.ts`: Converts report entries to formatted JSON with a generated timestamp; the CLI uses this for index-only output, while report mode serializes the full report directly.
- **Public data contracts** — `src/types.ts`: Defines input documents, kinds, entries, findings, reports, and build options shared by the library and CLI.

#### Relationships

- **CLI user or automation -> CLI**: Invokes `wk-index` with arguments; the package declares the executable entry point and the CLI parses its arguments.
- **Disclosure directory -> Directory loader**: Supplies the directory scanned recursively for JSON files.
- **CLI -> Directory loader**: Calls `loadDir` with the requested directory.
- **Directory loader -> Disclosure detection and routing**: Passes parsed document bodies and source filenames to the builder, which uses detection helpers.
- **CLI -> Index builder and integrity checks**: Calls `buildIndex` with loaded documents and optional base URL.
- **Index builder and integrity checks -> Disclosure detection and routing**: Calls helpers to determine kind, ID, version, references, and output path.
- **CLI -> Index renderer**: Calls `toIndexJson` when producing index-only output; report mode instead serializes the report in the CLI.
- **CLI -> Index consumer or output destination**: Writes output to stdout by default or to the `--out` file; the CLI also prints findings to stderr.
- **Public library API -> Index builder and integrity checks**: Re-exports `buildIndex` for library consumers.
- **Public library API -> Directory loader**: Re-exports `loadDir` for library consumers.
- **Public library API -> Index renderer**: Re-exports `toIndexJson` for library consumers.

#### Coverage limits

Source excerpts establish the CLI, library exports, file loading, detection, index construction, and output behavior. The downstream publication or serving of the generated index is not shown; the README describes composing with a separate disclosure-rendering operator, but that operator is external to this repository.

Main entry points: [`src/cli.ts`](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/cli.ts) (CLI), [`src/load.ts`](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/load.ts) (Directory loader), [`src/index.ts`](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/index.ts) (Public library API), [`src/build.ts`](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/build.ts) (Index builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and input"]
  node_cli_user["CLI user<br/>actor"]
  node_disclosure_dir["Disclosure directory<br/>input"]
  node_cli["CLI<br/>command"]
end

subgraph group_pipeline["Index pipeline"]
  node_loader["Directory loader<br/>[load.ts]"]
  node_detection["Disclosure detection<br/>detector"]
  node_builder["Index builder<br/>[build.ts]"]
  node_renderer["Index renderer<br/>[build.ts]"]
end

subgraph group_interfaces["Library and output"]
  node_library_api["Public library API<br/>[index.ts]"]
  node_index_consumer["Index consumer"]
end

node_cli_user -->|"invokes"| node_cli
node_disclosure_dir -->|"supplies files"| node_loader
node_cli -->|"loads directory"| node_loader
node_loader -->|"passes documents"| node_detection
node_cli -->|"builds index"| node_builder
node_builder -->|"uses helpers"| node_detection
node_cli -->|"renders index"| node_renderer
node_cli -->|"writes output"| node_index_consumer
node_library_api -->|"re-exports"| node_builder
node_library_api -->|"re-exports"| node_loader
node_library_api -->|"re-exports"| node_renderer

click node_cli "https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/cli.ts"
click node_loader "https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/load.ts"
click node_detection "https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/detect.ts"
click node_builder "https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/build.ts"
click node_renderer "https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/build.ts"
click node_library_api "https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/index.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_user,node_disclosure_dir,node_cli toneBlue
class node_loader,node_detection,node_builder,node_renderer toneAmber
class node_library_api,node_index_consumer toneMint
```

## Components

### Entry and input

- **CLI user**: actor
- **Disclosure directory**: input
- [CLI](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/cli.ts): command · `src/cli.ts`

### Index pipeline

- [Directory loader](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/load.ts): loader · `src/load.ts`
- [Disclosure detection](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/detect.ts): detector · `src/detect.ts`
- [Index builder](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/build.ts): builder · `src/build.ts`
- [Index renderer](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/build.ts): renderer · `src/build.ts`

### Library and output

- [Public library API](https://github.com/mizcausevic-dev/wellknown-index-aggregator/blob/main/src/index.ts): library · `src/index.ts`
- **Index consumer**: consumer

## Connections

- CLI user → CLI: invokes
- Disclosure directory → Directory loader: supplies files
- CLI → Directory loader: loads directory
- Directory loader → Disclosure detection: passes documents
- CLI → Index builder: builds index
- Index builder → Disclosure detection: uses helpers
- CLI → Index renderer: renders index
- CLI → Index consumer: writes output
- Public library API → Index builder: re-exports
- Public library API → Directory loader: re-exports
- Public library API → Index renderer: re-exports