# miguel-higorre-ch/swagger2postman-ai-cli architecture

> Architecture diagram of the GitHub repository miguel-higorre-ch/swagger2postman-ai-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/miguel-higorre-ch/swagger2postman-ai-cli
- Repository: https://github.com/miguel-higorre-ch/swagger2postman-ai-cli

## Overview

1. **Repository purpose**
   - This is a Node.js/TypeScript CLI that converts a Swagger/OpenAPI document into a Postman collection.
   - The core pipeline is: **read API spec from a URL → transform it into Postman v2.1.0 JSON → enrich some requests with Gemini AI → write the collection to disk**.

2. **Top-level structure**
   - The repo is very small and centered around three source modules in `src/`:
     - `index.ts` for CLI entrypoint and orchestration
     - `fetcher.ts` for pulling the Swagger/OpenAPI document
     - `gemini.ts` for AI-assisted transformation
   - The `.js`, `.d.ts`, and `.map` files alongside the `.ts` sources indicate the project is compiled TypeScript distributed as JavaScript plus type declarations.

3. **CLI boundary**
   - `src/index.ts` is the main external interface.
   - It likely parses command-line arguments such as `--url` and `--output`, then coordinates the rest of the flow.
   - This is the boundary between the user and the internal transformation pipeline.

4. **Spec ingestion subsystem**
   - `src/fetcher.ts` is responsible for getting the Swagger/OpenAPI JSON from a remote endpoint.
   - This subsystem is a simple network fetch layer, separate from transformation logic.
   - The README implies the tool expects a JSON API docs URL, not a local file-based parser.

5. **Transformation subsystem**
   - The main business logic is the conversion from Swagger/OpenAPI operations into Postman collection objects.
   - The README indicates the output is structured by **tags**, which means the transformation groups endpoints into collections/folders based on API metadata.
   - This is where request shape, URL templating, test scripts, and collection layout are assembled.

6. **AI enrichment boundary**
   - `src/gemini.ts` isolates the Gemini integration.
   - Its role is not to replace the converter, but to enhance generated requests with smarter validation, structure, and test script generation.
   - This keeps AI-specific behavior behind a dedicated module so the rest of the CLI can remain deterministic.

7. **Output artifact**
   - The final artifact is a **Postman Collection v2.1.0 JSON file**.
   - The tool is designed for downstream execution in Postman or Newman, so the generated JSON is the primary integration point with the rest of the ecosystem.

8. **Test script generation**
   - The generated collections include Postman test scripts using `pm.test`.
   - The README calls out checks for:
     - status codes
     - response structure
     - latency/performance
   - This means the architecture includes a testing layer embedded into the collection output, not a separate test runner.

9. **Auth/token handling**
   - There is explicit logic for token management around `/login` or `/auth` endpoints.
   - Architecturally, this suggests the transformer detects auth-related operations and propagates tokens into later requests so the collection is runnable end-to-end.
   - This is an important data flow because it links one generated request’s response to other requests’ variables.

10. **Configuration and secrets**
   - `.env.example` shows the only clearly external secret/config dependency: `GEMINI_API_KEY`.
   - This means Gemini integration is opt-in via environment configuration, while the Swagger URL and output path come from CLI arguments.
   - The configuration boundary is split between env vars and command-line inputs.

11. **Runtime and tooling**
   - The project targets **Node.js v18+** and is written in **TypeScript**.
   - The README mentions running via `ts-node`, which suggests the CLI can be executed directly from source during development.
   - `package-lock.json` indicates npm is the package manager and dependency lock is committed.

12. **Likely internal data flow**
   - The important architecture flow is:
     - CLI args parsed in `index.ts`
     - Swagger spec fetched in `fetcher.ts`
     - OpenAPI paths/operations transformed into Postman structure
     - Gemini-assisted enhancement applied where needed
     - collection JSON serialized to the requested output file
   - No database, queue, or persistent service is present; the app is a stateless single-run converter.

13. **External services**
   - The only external AI service visible from the repo is **Gemini API**.
   - Swagger/OpenAPI input is consumed over HTTP from a user-supplied URL.
   - The generated collection is intended for **Newman** execution, which is downstream tooling rather than a runtime dependency.

14. **Diagram guidance**
   - A good architecture diagram should show three main boxes:
     - **CLI Orchestrator**
     - **Swagger Fetcher**
     - **Gemini Enricher**
   - Then show outputs to:
     - **Postman Collection JSON**
     - optionally **Newman/Postman runtime**
   - The main dependency arrows should emphasize that the CLI coordinates both network fetching and AI enrichment, while the conversion remains local and file-based.

Main entry points: [`src/index.ts`](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts) (Converter), [`src/gemini.ts`](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/gemini.ts) (Gemini enricher), [`src/fetcher.ts`](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/fetcher.ts) (Spec fetch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI flow"]
  node_n1["CLI entry<br/>ts command<br/>[index.ts]"]
  node_n2["Orchestrator<br/>pipeline coordinator<br/>[index.ts]"]
  node_n3["Arg parsing<br/>cli input<br/>[index.ts]"]
end

subgraph group_core["Conversion core"]
  node_n4["Spec fetch<br/>http fetcher<br/>[fetcher.ts]"]
  node_n5["OpenAPI spec<br/>input document"]
  node_n6["Converter<br/>postman builder<br/>[index.ts]"]
  node_n7["Tag grouping<br/>layout rule"]
  node_n8["Auth handling<br/>token flow"]
  node_n9["Test scripts<br/>pm.test generator"]
  node_n10["Gemini enricher<br/>ai integration<br/>[gemini.ts]"]
  node_n11(("Gemini API<br/>external ai"))
end

subgraph group_output["Outputs"]
  node_n12["Collection JSON<br/>postman v2.1.0"]
  node_n13["Output file<br/>filesystem artifact"]
  node_n14(("Postman/Newman<br/>downstream runtime"))
  node_n15["Node.js 18+<br/>runtime"]
  node_n16["TypeScript build<br/>compiled sources"]
end

node_n1 -->|"reads"| node_n3
node_n1 -->|"starts"| node_n2
node_n2 -->|"fetches"| node_n4
node_n4 -->|"returns"| node_n5
node_n2 -->|"converts"| node_n6
node_n5 -->|"source"| node_n6
node_n6 -->|"organizes"| node_n7
node_n6 -->|"applies"| node_n8
node_n6 -->|"embeds"| node_n9
node_n2 -->|"enriches"| node_n10
node_n10 -->|"requests"| node_n11
node_n10 -->|"refines"| node_n6
node_n6 -->|"serializes"| node_n12
node_n12 -->|"writes"| node_n13
node_n13 -->|"consumed by"| node_n14
node_n1 -->|"runs on"| node_n15
node_n1 -->|"built from"| node_n16

click node_n1 "https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts"
click node_n2 "https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts"
click node_n3 "https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts"
click node_n4 "https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/fetcher.ts"
click node_n6 "https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts"
click node_n10 "https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/gemini.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_n1,node_n2,node_n3 toneBlue
class node_n4,node_n5,node_n6,node_n7,node_n8,node_n9,node_n10,node_n11 toneAmber
class node_n12,node_n13,node_n14,node_n15,node_n16 toneMint
```

## Components

### CLI flow

User-facing command entrypoint and orchestration

- [CLI entry](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts): ts command · Parses args and starts the conversion run · `src/index.ts`
- [Orchestrator](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts): pipeline coordinator · Coordinates fetch, conversion, enrichment, and write steps · `src/index.ts`
- [Arg parsing](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts): cli input · Accepts Swagger URL, output path, and runtime options · `src/index.ts`

### Conversion core

Spec ingestion, transformation, and AI enrichment

- [Spec fetch](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/fetcher.ts): http fetcher · Retrieves Swagger/OpenAPI JSON from a remote URL · `src/fetcher.ts`
- **OpenAPI spec**: input document · Fetched API description used as conversion source
- [Converter](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/index.ts): postman builder · Transforms operations into Postman v2.1.0 collection structure · `src/index.ts`
- **Tag grouping**: layout rule · Organizes requests and folders by API tags
- **Auth handling**: token flow · Detects login or auth endpoints and propagates tokens
- **Test scripts**: pm.test generator · Embeds checks for status, structure, and latency
- [Gemini enricher](https://github.com/miguel-higorre-ch/swagger2postman-ai-cli/blob/main/src/gemini.ts): ai integration · Optional AI-assisted request refinement and script generation · `src/gemini.ts`
- **Gemini API**: external ai · LLM service used through environment configuration

### Outputs

Generated artifacts and downstream consumers

- **Collection JSON**: postman v2.1.0 · Serialized Postman collection written to disk
- **Output file**: filesystem artifact · User-specified destination for the generated collection
- **Postman/Newman**: downstream runtime · Consumes the generated collection for execution
- **Node.js 18+**: runtime · Execution environment for the CLI
- **TypeScript build**: compiled sources · Distributed as JS, declarations, and sourcemaps

## Connections

- CLI entry → Arg parsing: reads · CLI entry parses command-line inputs
- CLI entry → Orchestrator: starts · Entrypoint hands control to the orchestrator
- Orchestrator → Spec fetch: fetches · Coordinator loads the remote API spec
- Spec fetch → OpenAPI spec: returns · Fetcher yields the OpenAPI document
- Orchestrator → Converter: converts · Orchestrator invokes the collection builder
- OpenAPI spec → Converter: source · Spec data becomes Postman output
- Converter → Tag grouping: organizes · Requests are grouped by tags
- Converter → Auth handling: applies · Auth-aware logic wires token flow between requests
- Converter → Test scripts: embeds · Generated requests include Postman test scripts
- Orchestrator → Gemini enricher: enriches · Coordinator optionally calls Gemini for smarter output
- Gemini enricher → Gemini API: requests · Gemini module communicates with the external AI service
- Gemini enricher → Converter: refines · AI output feeds back into request shaping and scripts
- Converter → Collection JSON: serializes · Collection is emitted as Postman v2.1.0 JSON
- Collection JSON → Output file: writes · Generated JSON is persisted to the requested file
- Output file → Postman/Newman: consumed by · Artifact is used in Postman or Newman
- CLI entry → Node.js 18+: runs on · CLI executes in a Node.js 18+ environment
- CLI entry → TypeScript build: built from · Source is compiled and distributed as JS plus typings
