# arnab621/typesafe-jev-plugin architecture

> Architecture diagram of the GitHub repository arnab621/typesafe-jev-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arnab621/typesafe-jev-plugin
- Repository: https://github.com/arnab621/typesafe-jev-plugin
- Video tour (about a minute): https://gitdiagram.com/arnab621/typesafe-jev-plugin/video

## Overview

This Claude Code/Cowork plugin supports a two-stage workflow: interactively author reusable TypeSafe Jev solution signatures, then apply a signature to tabular or text inputs and export structured Excel results. The runner’s input, template, API, and output responsibilities are represented at a high level; the excerpt omits parts of its implementation, so uncertain internal call wiring is not shown.

Main entry points: [`scripts/run_dataset.py`](https://github.com/arnab621/typesafe-jev-plugin/blob/main/scripts/run_dataset.py) (Dataset runner), [`skills/create-signature/SKILL.md`](https://github.com/arnab621/typesafe-jev-plugin/blob/main/skills/create-signature/SKILL.md) (Create signature), [`examples`](https://github.com/arnab621/typesafe-jev-plugin/tree/main/examples) (Solution signature), [`skills/run-dataset/SKILL.md`](https://github.com/arnab621/typesafe-jev-plugin/blob/main/skills/run-dataset/SKILL.md) (Run dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Signature authoring"]
  node_create_skill["Create signature<br/>[SKILL.md]"]
  node_designer["Signature designer"]
  node_signature["Solution signature"]
  node_validator_agent["Signature validator"]
end

subgraph group_execution["Dataset execution"]
  node_run_skill["Run dataset<br/>[SKILL.md]"]
  node_runner["Dataset runner<br/>[run_dataset.py]"]
  node_client["HTTP API client<br/>[typesafe_client.py]"]
  node_excel["Excel results"]
end

subgraph group_integration["Plugin integration"]
  node_validator["Signature validation"]
  node_hook["Save hook"]
end

node_user(("Plugin user"))
node_input["CSV, Excel, or text"]
node_jev{{"TypeSafe Jev API"}}
node_host(("Claude plugin host"))

node_user -->|"starts authoring"| node_create_skill
node_create_skill -->|"guides design"| node_designer
node_create_skill -->|"creates"| node_signature
node_user -->|"starts run"| node_run_skill
node_run_skill -->|"invokes"| node_runner
node_input -->|"provides rows or text"| node_runner
node_signature -->|"configures run"| node_runner
node_runner -->|"submits judgments"| node_jev
node_runner -->|"writes results"| node_excel
node_validator_agent -->|"supports validation"| node_validator
node_host -->|"dispatches after save"| node_hook
node_hook -->|"runs validation"| node_validator

click node_create_skill "https://github.com/arnab621/typesafe-jev-plugin/blob/main/skills/create-signature/SKILL.md"
click node_designer "https://github.com/arnab621/typesafe-jev-plugin/blob/main/agents/signature-designer.md"
click node_signature "https://github.com/arnab621/typesafe-jev-plugin/tree/main/examples"
click node_run_skill "https://github.com/arnab621/typesafe-jev-plugin/blob/main/skills/run-dataset/SKILL.md"
click node_runner "https://github.com/arnab621/typesafe-jev-plugin/blob/main/scripts/run_dataset.py"
click node_client "https://github.com/arnab621/typesafe-jev-plugin/blob/main/scripts/typesafe_client.py"
click node_validator_agent "https://github.com/arnab621/typesafe-jev-plugin/blob/main/agents/signature-validator.md"
click node_validator "https://github.com/arnab621/typesafe-jev-plugin/blob/main/scripts/validate_signature.py"
click node_hook "https://github.com/arnab621/typesafe-jev-plugin/blob/main/hooks/scripts/validate_on_save.py"

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_create_skill,node_designer,node_signature,node_validator_agent,node_user toneBlue
class node_run_skill,node_runner,node_client,node_excel toneAmber
class node_validator,node_hook,node_jev toneMint
class node_input,node_host toneIndigo
```

## Components

### Signature authoring

- [Create signature](https://github.com/arnab621/typesafe-jev-plugin/blob/main/skills/create-signature/SKILL.md): `skills/create-signature/SKILL.md`
- [Signature designer](https://github.com/arnab621/typesafe-jev-plugin/blob/main/agents/signature-designer.md): `agents/signature-designer.md`
- [Solution signature](https://github.com/arnab621/typesafe-jev-plugin/tree/main/examples): `examples`
- [Signature validator](https://github.com/arnab621/typesafe-jev-plugin/blob/main/agents/signature-validator.md): `agents/signature-validator.md`

### Dataset execution

- [Run dataset](https://github.com/arnab621/typesafe-jev-plugin/blob/main/skills/run-dataset/SKILL.md): `skills/run-dataset/SKILL.md`
- [Dataset runner](https://github.com/arnab621/typesafe-jev-plugin/blob/main/scripts/run_dataset.py): `scripts/run_dataset.py`
- [HTTP API client](https://github.com/arnab621/typesafe-jev-plugin/blob/main/scripts/typesafe_client.py): `scripts/typesafe_client.py`
- **Excel results**

### Plugin integration

- [Signature validation](https://github.com/arnab621/typesafe-jev-plugin/blob/main/scripts/validate_signature.py): `scripts/validate_signature.py`
- [Save hook](https://github.com/arnab621/typesafe-jev-plugin/blob/main/hooks/scripts/validate_on_save.py): `hooks/scripts/validate_on_save.py`

### Other components

- **Plugin user**
- **CSV, Excel, or text**
- **TypeSafe Jev API**
- **Claude plugin host**

## Connections

- Plugin user → Create signature: starts authoring
- Create signature → Signature designer: guides design
- Create signature → Solution signature: creates
- Plugin user → Run dataset: starts run
- Run dataset → Dataset runner: invokes
- CSV, Excel, or text → Dataset runner: provides rows or text
- Solution signature → Dataset runner: configures run
- Dataset runner → TypeSafe Jev API: submits judgments
- Dataset runner → Excel results: writes results
- Signature validator → Signature validation: supports validation
- Claude plugin host → Save hook: dispatches after save
- Save hook → Signature validation: runs validation