# arnab621/typesafe-jev-plugin-copy architecture

> Architecture diagram of the GitHub repository arnab621/typesafe-jev-plugin-copy, 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-copy
- Repository: https://github.com/arnab621/typesafe-jev-plugin-copy
- Video tour (about a minute): https://gitdiagram.com/arnab621/typesafe-jev-plugin-copy/video

## Overview

TypeSafe Jev Plugin is a Claude Code/Cowork plugin for designing reusable classification or scoring signatures and running them against tabular or text datasets. The main workflow is signature creation, dataset ingestion and state mapping, Jev evaluation, then structured Excel export. The README documents the skills and capabilities; sampled runner and validator code provide implementation details. Runner-to-client wiring is not established by the excerpts, so those components are shown separately.

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

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Signature authoring"]
  node_create_skill["Create signature skill<br/>[SKILL.md]"]
  node_designer["Signature designer"]
  node_signature["Solution signature"]
  node_examples["Example signatures"]
end

subgraph group_execution["Dataset execution"]
  node_run_skill["Run dataset skill<br/>[SKILL.md]"]
  node_dataset["CSV, Excel, or text input"]
  node_runner["Dataset runner<br/>[run_dataset.py]"]
  node_state_mapping["State mapping<br/>[run_dataset.py]"]
  node_answer_extraction["Answer extraction<br/>[run_dataset.py]"]
  node_excel_export["Excel results<br/>[run_dataset.py]"]
end

subgraph group_integration["API integration"]
  node_api_client["TypeSafe API client<br/>[typesafe_client.py]"]
  node_jev{{"TypeSafe Jev API"}}
end

subgraph group_validation["Signature validation"]
  node_validator["Signature validator"]
  node_save_hook["Save validation hook"]
  node_validator_agent["Signature validator agent"]
end

node_user(("Plugin user"))

node_user -->|"starts authoring"| node_create_skill
node_create_skill -->|"guides design"| node_designer
node_create_skill -->|"produces"| node_signature
node_examples -->|"provides examples"| node_user
node_user -->|"starts run"| node_run_skill
node_run_skill -->|"invokes"| node_runner
node_dataset -->|"supplies input"| node_runner
node_signature -->|"configures"| node_runner
node_runner -->|"resolves templates"| node_state_mapping
node_state_mapping -->|"submits state and questions"| node_jev
node_jev -->|"returns answers"| node_answer_extraction
node_answer_extraction -->|"writes results"| node_excel_export
node_api_client -->|"posts requests"| node_jev
node_save_hook -->|"runs validation"| node_validator
node_signature -->|"validates"| node_validator

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

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_examples,node_user toneBlue
class node_run_skill,node_dataset,node_runner,node_state_mapping,node_answer_extraction,node_excel_export toneAmber
class node_api_client,node_jev toneMint
class node_validator,node_save_hook,node_validator_agent toneRose
```

## Components

### Signature authoring

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

### Dataset execution

- [Run dataset skill](https://github.com/arnab621/typesafe-jev-plugin-copy/blob/main/skills/run-dataset/SKILL.md): `skills/run-dataset/SKILL.md`
- **CSV, Excel, or text input**
- [Dataset runner](https://github.com/arnab621/typesafe-jev-plugin-copy/blob/main/scripts/run_dataset.py): `scripts/run_dataset.py`
- [State mapping](https://github.com/arnab621/typesafe-jev-plugin-copy/blob/main/scripts/run_dataset.py): `scripts/run_dataset.py`
- [Answer extraction](https://github.com/arnab621/typesafe-jev-plugin-copy/blob/main/scripts/run_dataset.py): `scripts/run_dataset.py`
- [Excel results](https://github.com/arnab621/typesafe-jev-plugin-copy/blob/main/scripts/run_dataset.py): `scripts/run_dataset.py`

### API integration

- [TypeSafe API client](https://github.com/arnab621/typesafe-jev-plugin-copy/blob/main/scripts/typesafe_client.py): `scripts/typesafe_client.py`
- **TypeSafe Jev API**

### Signature validation

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

### Other components

- **Plugin user**

## Connections

- Plugin user → Create signature skill: starts authoring
- Create signature skill → Signature designer: guides design
- Create signature skill → Solution signature: produces
- Example signatures → Plugin user: provides examples
- Plugin user → Run dataset skill: starts run
- Run dataset skill → Dataset runner: invokes
- CSV, Excel, or text input → Dataset runner: supplies input
- Solution signature → Dataset runner: configures
- Dataset runner → State mapping: resolves templates
- State mapping → TypeSafe Jev API: submits state and questions
- TypeSafe Jev API → Answer extraction: returns answers
- Answer extraction → Excel results: writes results
- TypeSafe API client → TypeSafe Jev API: posts requests
- Save validation hook → Signature validator: runs validation
- Solution signature → Signature validator: validates