# agrostar/zzapi architecture

> Architecture diagram of the GitHub repository agrostar/zzapi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agrostar/zzapi
- Repository: https://github.com/agrostar/zzapi

## Overview

##### Main Components
- Core Library Modules (located in the “src” directory):
- Request Execution: Modules such as executeRequest.ts and constructCurl.ts handle turning YAML definitions into actual API calls.
- Parsing & Data Merging: Files like parseBundle.ts, convertPostman.ts, mergeData.ts, and replaceVars.ts indicate that the library parses API bundle files and merges in environment variables.
- Variable Management: captureVars.ts, variables.ts, and variableParser.ts represent modules dedicated to managing and capturing dynamic variables.
- Type Checking and Validation: checkTypes.ts and associated utility functions (in src/utils/typeUtils.ts) lend structure to how data is validated.
- Models: models.ts likely contains core definitions of the data structures used across the library.
- Test Runner: runTests.ts exists for executing tests, further supported by test utilities and integration tests in the “tests” directory.
- Schemas: The “schemas” directory contains JSON schemas (zzapi-bundle.schema.json and zzapi-varset.schema.json) to validate the YAML bundle and variable set files.
- External Tools: Although not part of the repository, the README mentions a VS Code extension and a CLI tool that use this library, making them external clients of the library.
- Documentation & Examples: The “docs” and “examples” directories provide specification details and sample configurations of how the API bundles and variable sets are formatted.

##### Relationships and Interactions
- Data Flow from Input to Execution:
- The system starts with API configuration files (YAML bundles and variable sets) defined by the user.
- These files are parsed by the library (using parseBundle.ts and convertPostman.ts) and validated against provided JSON schemas.
- The parsed data is then processed by merging variables (mergeData.ts) and replacing placeholders (replaceVars.ts).
- Once the API requests are fully prepared, they flow into the Request Execution module (via executeRequest.ts and constructCurl.ts), which handles sending requests and optionally capturing responses (captureVars.ts).
- Testing Workflow:
- The runTests.ts module – along with supporting modules in the tests directory – manages automated API tests, checking responses against expected outputs without requiring additional code from the end user.
- External Integration:

##### Architectural Patterns and Technologies
- Modularity: The project is divided into well-separated modules responsible for parsing, execution, variable management, and testing.
- Schema-Based Validation: Using JSON schemas for validating configuration files is an important design principle.
- CLI/Extension Integration: The library’s API is designed for easy integration with other tools, emphasizing a clear separation between core functionality and presentation/UI layers.
- Utilization of TypeScript: The use of TypeScript (as evidenced by the .ts files, tsconfig.json, and tsup.config.ts) ensures type safety and better modularity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        VSCode["VS Code Extension"]:::external
        CLI["CLI Tool"]:::external
    end

    %% API Input Layer
    subgraph "API Input"
        API_Input["API Configuration (YAML & Var Files)"]:::input
    end

    %% Parsing and Validation Layer
    subgraph "Parsing and Validation"
        ParseBundle["Parse Bundle"]:::processing
        ConvertPostman["Convert Postman"]:::processing
        BundleSchema["Bundle Schema"]:::schema
        VarsetSchema["Varset Schema"]:::schema
    end

    %% Data Merging & Variable Replacement Layer
    subgraph "Data Merging & Variable Replacement"
        MergeData["Merge Data"]:::processing
        ReplaceVars["Replace Variables"]:::processing
        VariableParser["Variable Parser"]:::processing
    end

    %% Request Execution Layer
    subgraph "Request Execution"
        ExecuteRequest["Execute Request"]:::execution
        ConstructCurl["Construct cURL"]:::execution
    end

    %% Variable Management Layer
    subgraph "Variable Management"
        CaptureVars["Capture Variables"]:::processing
        VariablesModule["Manage Variables"]:::processing
    end

    %% Test Runner Layer
    subgraph "Test Runner"
        RunTests["Run Tests"]:::testing
        CheckTypes["Check Types"]:::testing
        TypeUtils["Type Utils"]:::testing
    end

    %% Core Models
    subgraph "Core Models"
        Models["Models"]:::models
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        Documentation["Documentation"]:::docs
        Examples["Examples"]:::docs
    end

    %% Relationships
    VSCode -->|"calls"| API_Input
    CLI -->|"calls"| API_Input

    API_Input -->|"feeds"| ParseBundle
    API_Input -->|"feeds"| ConvertPostman

    ParseBundle -->|"validates"| BundleSchema
    ParseBundle -->|"validates"| VarsetSchema
    ConvertPostman -->|"validates"| BundleSchema
    ConvertPostman -->|"validates"| VarsetSchema

    BundleSchema -->|"triggers merge"| MergeData
    VarsetSchema -->|"triggers merge"| MergeData

    MergeData -->|"updates"| ReplaceVars
    ReplaceVars -->|"processes"| VariableParser

    VariableParser -->|"initiates"| ExecuteRequest

    ExecuteRequest -->|"builds"| ConstructCurl
    ConstructCurl -->|"captures"| CaptureVars

    CaptureVars -->|"updates"| VariablesModule

    ExecuteRequest -->|"triggers"| RunTests

    RunTests -->|"verifies"| CheckTypes
    RunTests -->|"verifies"| TypeUtils

    %% Connections to Models for shared references
    BundleSchema -->|"defines"| Models
    VarsetSchema -->|"defines"| Models
    VariableParser -->|"models data"| Models
    CheckTypes -->|"uses"| Models
    TypeUtils -->|"uses"| Models

    %% Styling
    classDef input fill:#FFF2CC,stroke:#D79B00,stroke-width:2px;
    classDef processing fill:#CFE2F3,stroke:#6D9EEB,stroke-width:2px;
    classDef execution fill:#D9EAD3,stroke:#6AA84F,stroke-width:2px;
    classDef testing fill:#F4CCCC,stroke:#E06666,stroke-width:2px;
    classDef external fill:#FCE5CD,stroke:#E69138,stroke-width:2px;
    classDef schema fill:#EAD1DC,stroke:#BF8CBF,stroke-width:2px;
    classDef models fill:#D9D2E9,stroke:#8E7CC3,stroke-width:2px;
    classDef docs fill:#D0E0E3,stroke:#76A5AF,stroke-width:2px;

    %% Click Events for Core Components
    click ParseBundle "https://github.com/agrostar/zzapi/blob/main/src/parseBundle.ts"
    click ConvertPostman "https://github.com/agrostar/zzapi/blob/main/src/convertPostman.ts"
    click MergeData "https://github.com/agrostar/zzapi/blob/main/src/mergeData.ts"
    click ReplaceVars "https://github.com/agrostar/zzapi/blob/main/src/replaceVars.ts"
    click VariableParser "https://github.com/agrostar/zzapi/blob/main/src/variableParser.ts"
    click ExecuteRequest "https://github.com/agrostar/zzapi/blob/main/src/executeRequest.ts"
    click ConstructCurl "https://github.com/agrostar/zzapi/blob/main/src/constructCurl.ts"
    click CaptureVars "https://github.com/agrostar/zzapi/blob/main/src/captureVars.ts"
    click VariablesModule "https://github.com/agrostar/zzapi/blob/main/src/variables.ts"
    click CheckTypes "https://github.com/agrostar/zzapi/blob/main/src/checkTypes.ts"
    click TypeUtils "https://github.com/agrostar/zzapi/blob/main/src/utils/typeUtils.ts"
    click RunTests "https://github.com/agrostar/zzapi/blob/main/src/runTests.ts"
    click Models "https://github.com/agrostar/zzapi/blob/main/src/models.ts"
    click BundleSchema "https://github.com/agrostar/zzapi/blob/main/schemas/zzapi-bundle.schema.json"
    click VarsetSchema "https://github.com/agrostar/zzapi/blob/main/schemas/zzapi-varset.schema.json"
    click Documentation "https://github.com/agrostar/zzapi/tree/main/docs"
    click Examples "https://github.com/agrostar/zzapi/tree/main/examples"
```
