# swytchcodehq/wrekenfile-converter architecture

> Architecture diagram of the GitHub repository swytchcodehq/wrekenfile-converter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/swytchcodehq/wrekenfile-converter
- Repository: https://github.com/swytchcodehq/wrekenfile-converter

## Overview

Wrekenfile Converter is a TypeScript library and CLI that turns OpenAPI v3, OpenAPI v2/Swagger, and Postman inputs into execution-oriented Wrekenfile YAML. Consumers select a spec-version API or CLI; converters build method, input, response, authentication, schema, and signing metadata, then serialize YAML. The library also validates v1 files and splits generated files into standalone per-method mini-wrekenfiles. The v2 conversion utilities are grouped as an internal layer. Edges reflect README descriptions and indexed imports; unsampled implementation details are not inferred.

Main entry points: [`src/v2/openapi-to-wreken.ts`](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/openapi-to-wreken.ts) (OpenAPI v3 v2), [`src/v2/openapi-v2-to-wrekenfile.ts`](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/openapi-v2-to-wrekenfile.ts) (Swagger v2), [`src/v2/postman-to-wrekenfile.ts`](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/postman-to-wrekenfile.ts) (Postman v2), [`src/v2/index.ts`](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/index.ts) (v2 API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Consumer entry points"]
  node_v1api["v1 API<br/>[index.ts]"]
  node_v2api["v2 API<br/>[index.ts]"]
  node_v1cli["v1 CLI"]
  node_v2cli["v2 CLI"]
end

subgraph group_conversion["Spec conversion"]
  node_v1openapi3["OpenAPI v3 v1"]
  node_v1openapi2["Swagger v1"]
  node_v1postman["Postman v1"]
  node_v2openapi3["OpenAPI v3 v2"]
  node_v2openapi2["Swagger v2"]
  node_v2postman["Postman v2"]
end

subgraph group_shared["Shared conversion utilities"]
  node_utils["Conversion utilities"]
  node_canonical["Canonical IDs<br/>[canonical-id.ts]"]
  node_auth["Authentication mapping<br/>[auth-utils.ts]"]
  node_signing["Request signing<br/>[signing-utils.ts]"]
  node_stats["Conversion statistics"]
  node_yaml["YAML serialization<br/>[yaml-utils.ts]"]
  node_versions["Version constants<br/>[versions.ts]"]
end

subgraph group_outputs["Wrekenfile outputs"]
  node_validate["Wrekenfile validation"]
  node_mini1["Mini files v1"]
  node_mini2["Mini files v2"]
end

node_consumer(("Library consumer"))
node_cliuser(("CLI user"))

node_consumer -->|"selects v1"| node_v1api
node_consumer -->|"selects v2"| node_v2api
node_cliuser -->|"runs commands"| node_v1cli
node_cliuser -->|"runs commands"| node_v2cli
node_v1api -->|"exports converter"| node_v1openapi3
node_v1api -->|"exports converter"| node_v1openapi2
node_v1api -->|"exports converter"| node_v1postman
node_v2api -->|"exports converter"| node_v2openapi3
node_v2api -->|"exports converter"| node_v2openapi2
node_v2api -->|"exports converter"| node_v2postman
node_v1cli -->|"invokes"| node_v1openapi3
node_v1cli -->|"invokes"| node_v1postman
node_v1cli -->|"invokes"| node_mini1
node_v2cli -->|"invokes"| node_v2openapi3
node_v2cli -->|"invokes"| node_v2openapi2
node_v2cli -->|"invokes"| node_v2postman
node_v2cli -->|"invokes"| node_mini2
node_v2openapi3 -->|"uses helpers"| node_utils
node_v2openapi2 -->|"uses helpers"| node_utils
node_v2postman -->|"uses helpers"| node_utils
node_v2openapi3 -->|"resolves IDs"| node_canonical
node_v2openapi2 -->|"resolves IDs"| node_canonical
node_v2postman -->|"resolves IDs"| node_canonical
node_v2openapi3 -->|"maps auth"| node_auth
node_v2openapi2 -->|"maps auth"| node_auth
node_v2postman -->|"maps auth"| node_auth
node_v2openapi3 -->|"handles recipes"| node_signing
node_v2openapi2 -->|"handles recipes"| node_signing
node_v2postman -->|"handles recipes"| node_signing
node_v2openapi3 -.->|"reports stats"| node_stats
node_v2api -->|"exports versioning"| node_versions
node_consumer -->|"validates file"| node_validate
node_consumer -->|"generates minis"| node_mini1
node_consumer -->|"generates minis"| node_mini2
node_v1openapi3 -.->|"produces YAML for"| node_mini1
node_v2openapi3 -->|"serializes output"| node_yaml
node_v2openapi2 -->|"serializes output"| node_yaml
node_v2postman -->|"serializes output"| node_yaml
node_v2api -->|"exports generator"| node_mini2
node_v1api -.->|"exposes generator"| node_mini1

click node_v1api "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/index.ts"
click node_v2api "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/index.ts"
click node_v1cli "https://github.com/swytchcodehq/wrekenfile-converter/tree/main/src/v1/cli"
click node_v2cli "https://github.com/swytchcodehq/wrekenfile-converter/tree/main/src/v2/cli"
click node_v1openapi3 "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/openapi-to-wreken.ts"
click node_v1openapi2 "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/openapi-v2-to-wrekenfile.ts"
click node_v1postman "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/postman-to-wrekenfile.ts"
click node_v2openapi3 "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/openapi-to-wreken.ts"
click node_v2openapi2 "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/openapi-v2-to-wrekenfile.ts"
click node_v2postman "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/postman-to-wrekenfile.ts"
click node_utils "https://github.com/swytchcodehq/wrekenfile-converter/tree/main/src/v2/utils"
click node_canonical "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/canonical-id.ts"
click node_auth "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/auth-utils.ts"
click node_signing "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/signing-utils.ts"
click node_stats "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/conversion-stats.ts"
click node_yaml "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/yaml-utils.ts"
click node_validate "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/wrekenfile-validator.ts"
click node_mini1 "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/mini-wrekenfile-generator.ts"
click node_mini2 "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/mini-wrekenfile-generator.ts"
click node_versions "https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/versions.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_v1api,node_v2api,node_v1cli,node_v2cli,node_cliuser toneBlue
class node_v1openapi3,node_v1openapi2,node_v1postman,node_v2openapi3,node_v2openapi2,node_v2postman toneAmber
class node_utils,node_canonical,node_auth,node_signing,node_stats,node_yaml,node_versions toneMint
class node_validate,node_mini1,node_mini2 toneRose
class node_consumer toneIndigo
```

## Components

### Consumer entry points

- [v1 API](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/index.ts): `src/v1/index.ts`
- [v2 API](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/index.ts): `src/v2/index.ts`
- [v1 CLI](https://github.com/swytchcodehq/wrekenfile-converter/tree/main/src/v1/cli): `src/v1/cli`
- [v2 CLI](https://github.com/swytchcodehq/wrekenfile-converter/tree/main/src/v2/cli): `src/v2/cli`

### Spec conversion

- [OpenAPI v3 v1](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/openapi-to-wreken.ts): `src/v1/openapi-to-wreken.ts`
- [Swagger v1](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/openapi-v2-to-wrekenfile.ts): `src/v1/openapi-v2-to-wrekenfile.ts`
- [Postman v1](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/postman-to-wrekenfile.ts): `src/v1/postman-to-wrekenfile.ts`
- [OpenAPI v3 v2](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/openapi-to-wreken.ts): `src/v2/openapi-to-wreken.ts`
- [Swagger v2](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/openapi-v2-to-wrekenfile.ts): `src/v2/openapi-v2-to-wrekenfile.ts`
- [Postman v2](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/postman-to-wrekenfile.ts): `src/v2/postman-to-wrekenfile.ts`

### Shared conversion utilities

- [Conversion utilities](https://github.com/swytchcodehq/wrekenfile-converter/tree/main/src/v2/utils): `src/v2/utils`
- [Canonical IDs](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/canonical-id.ts): `src/v2/utils/canonical-id.ts`
- [Authentication mapping](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/auth-utils.ts): `src/v2/utils/auth-utils.ts`
- [Request signing](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/signing-utils.ts): `src/v2/utils/signing-utils.ts`
- [Conversion statistics](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/conversion-stats.ts): `src/v2/utils/conversion-stats.ts`
- [YAML serialization](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/utils/yaml-utils.ts): `src/v2/utils/yaml-utils.ts`
- [Version constants](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/versions.ts): `src/versions.ts`

### Wrekenfile outputs

- [Wrekenfile validation](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/wrekenfile-validator.ts): `src/v1/wrekenfile-validator.ts`
- [Mini files v1](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v1/mini-wrekenfile-generator.ts): `src/v1/mini-wrekenfile-generator.ts`
- [Mini files v2](https://github.com/swytchcodehq/wrekenfile-converter/blob/main/src/v2/mini-wrekenfile-generator.ts): `src/v2/mini-wrekenfile-generator.ts`

### Other components

- **Library consumer**
- **CLI user**

## Connections

- Library consumer → v1 API: selects v1 (evidence: `README.md`)
- Library consumer → v2 API: selects v2 (evidence: `README.md`)
- CLI user → v1 CLI: runs commands (evidence: `src/v1/cli/cli-openapi-to-wrekenfile.ts`)
- CLI user → v2 CLI: runs commands (evidence: `src/v2/cli/cli-openapi-to-wrekenfile.ts`)
- v1 API → OpenAPI v3 v1: exports converter (evidence: `src/v1/index.ts`)
- v1 API → Swagger v1: exports converter (evidence: `src/v1/index.ts`)
- v1 API → Postman v1: exports converter (evidence: `src/v1/index.ts`)
- v2 API → OpenAPI v3 v2: exports converter (evidence: `src/v2/index.ts`)
- v2 API → Swagger v2: exports converter (evidence: `src/v2/index.ts`)
- v2 API → Postman v2: exports converter (evidence: `src/v2/index.ts`)
- v1 CLI → OpenAPI v3 v1: invokes (evidence: `src/v1/cli/cli-openapi-to-wrekenfile.ts`)
- v1 CLI → Postman v1: invokes (evidence: `src/v1/cli/cli-postman-to-wrekenfile.ts`)
- v1 CLI → Mini files v1: invokes (evidence: `src/v1/cli/cli-mini-wrekenfile-generator.ts`)
- v2 CLI → OpenAPI v3 v2: invokes (evidence: `src/v2/cli/cli-openapi-to-wrekenfile.ts`)
- v2 CLI → Swagger v2: invokes (evidence: `src/v2/cli/cli-openapi-v2-to-wrekenfile.ts`)
- v2 CLI → Postman v2: invokes (evidence: `src/v2/cli/cli-postman-to-wrekenfile.ts`)
- v2 CLI → Mini files v2: invokes (evidence: `src/v2/cli/cli-mini-wrekenfile-generator.ts`)
- OpenAPI v3 v2 → Conversion utilities: uses helpers (evidence: `src/v2/openapi-to-wreken.ts`)
- Swagger v2 → Conversion utilities: uses helpers (evidence: `src/v2/openapi-v2-to-wrekenfile.ts`)
- Postman v2 → Conversion utilities: uses helpers (evidence: `src/v2/postman-to-wrekenfile.ts`)
- OpenAPI v3 v2 → Canonical IDs: resolves IDs (evidence: `src/v2/openapi-to-wreken.ts`)
- Swagger v2 → Canonical IDs: resolves IDs (evidence: `src/v2/openapi-v2-to-wrekenfile.ts`)
- Postman v2 → Canonical IDs: resolves IDs (evidence: `src/v2/postman-to-wrekenfile.ts`)
- OpenAPI v3 v2 → Authentication mapping: maps auth (evidence: `src/v2/openapi-to-wreken.ts`)
- Swagger v2 → Authentication mapping: maps auth (evidence: `src/v2/openapi-v2-to-wrekenfile.ts`)
- Postman v2 → Authentication mapping: maps auth (evidence: `src/v2/postman-to-wrekenfile.ts`)
- OpenAPI v3 v2 → Request signing: handles recipes (evidence: `src/v2/openapi-to-wreken.ts`)
- Swagger v2 → Request signing: handles recipes (evidence: `src/v2/openapi-v2-to-wrekenfile.ts`)
- Postman v2 → Request signing: handles recipes (evidence: `src/v2/postman-to-wrekenfile.ts`)
- OpenAPI v3 v2 → Conversion statistics: reports stats (evidence: `src/v2/index.ts`)
- v2 API → Version constants: exports versioning (evidence: `src/v2/index.ts`)
- Library consumer → Wrekenfile validation: validates file (evidence: `README.md`)
- Library consumer → Mini files v1: generates minis (evidence: `README.md`)
- Library consumer → Mini files v2: generates minis (evidence: `README.md`)
- OpenAPI v3 v1 → Mini files v1: produces YAML for
- OpenAPI v3 v2 → YAML serialization: serializes output (evidence: `src/v2/openapi-to-wreken.ts`)
- Swagger v2 → YAML serialization: serializes output (evidence: `src/v2/openapi-v2-to-wrekenfile.ts`)
- Postman v2 → YAML serialization: serializes output (evidence: `src/v2/postman-to-wrekenfile.ts`)
- v2 API → Mini files v2: exports generator (evidence: `src/v2/index.ts`)
- v1 API → Mini files v1: exposes generator (evidence: `README.md`)
