# orval-labs/orval architecture

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

- Interactive diagram: https://gitdiagram.com/orval-labs/orval
- Repository: https://github.com/orval-labs/orval

## Overview

##### Project Type and Purpose
- This is a code-generation tool (a CLI/library) that parses OpenAPI v3 or Swagger v2 definitions and outputs API client code. Its purpose is to generate clients with proper TypeScript typings for different integration ecosystems.
- The README and samples indicate that the tool supports multiple frameworks (React Query, SWR, Angular, etc.), so it is effectively a generator engine with several adapters.

##### File Structure
- Top-level directories:
– “packages”: Contains sub-packages (core, angular, axios, fetch, hono, mock, orval, query, swr, zod). The “core” package likely encapsulates the common generator logic (reading specs, applying templates, outputting files) while the others are integration adapters.
– “docs”: Contains the documentation site, including components and pages that describe the tool.
– “samples”: Contains multiple example projects that show how to use the generated clients in different frameworks.
– “tests”: Contains a variety of test configurations, specifications, mutators, and regression tests.
– Additionally, many configuration files (.github, linting, prettier, etc.) indicate continuous integration, code formatting, and version management.

##### How to Represent the Architecture
a. Main Components (each should be clearly labeled):
- CLI/Configuration Interface: The entry point for reading user configuration (e.g., orval.config.ts) and invoking the generation process.
- Core Generation Engine (packages/core): This module parses OpenAPI/Swagger files, applies internal transformations, and orchestrates the generation process.
- Adapters/Integrations: Separate packages (angular, axios, fetch, hono, zod, etc.) that take the core output and generate framework-specific client code.
- File System Utilities & Writers: Located within “packages/core/src/utils” and “packages/core/src/writers” – responsible for file handling, merging, and output formatting.
- Documentation & Developer Resources: “docs” folder for the documentation website, and “samples” for usage examples.
- Testing/CI Infrastructure: “tests” with configuration files and GitHub workflows (in .github/workflows) ensuring quality through continuous testing and integration.

b. Relationships and Interactions:
- The CLI or configuration file feeds data into the Core Generation Engine.
- The Core module processes the OpenAPI/Swagger spec, generates an intermediate representation, and then hands off processing to specific adapters.
- Each adapter (e.g., for React Query, Angular, etc.) takes the processed model and generates client code tailored for its ecosystem.
- Utility modules support both the core engine and adapters by handling file I/O, templating, and logging.
- The documentation website (docs) and multiple samples demonstrate the usage of these generated clients.

c. Architectural Patterns and Design Principles:
- Modularity: The monorepo is divided into discrete packages (core, adapters, utilities) which communicate via well-defined contracts.
- Separation of Concerns: The core generation logic is separated from the framework-specific client adjustments.
- Extensibility: New adapters can be added without altering the core generation engine.
- Automation and Testing: Extensive test suites and CI/CD workflows ensure robustness.

d. Technologies and Frameworks:
- TypeScript for type safety during code generation.
- Node.js and NPM/Yarn for package management.
- GitHub Actions (workflows) for CI/CD.
- Various adapters are built for frameworks like React (React Query, SWR), Angular, Svelte, and Vue.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["CLI/Configuration Interface"]:::cli
    click A "https://github.com/orval-labs/orval/blob/master/packages/orval/src/bin/orval.ts"
    
    subgraph "Core Generation Engine"
        B["Parsing & Transformation"]:::core
        click B "https://github.com/orval-labs/orval/tree/master/packages/core/"
        C["File System Utilities"]:::core
        click C "https://github.com/orval-labs/orval/tree/master/packages/core/src/utils/"
        D["Writers"]:::core
        click D "https://github.com/orval-labs/orval/tree/master/packages/core/src/writers/"
    end
    
    A -->|"feeds"| B
    B --> C
    B --> D

    subgraph "Adapters/Integrations"
        E["Angular Adapter"]:::adapter
        click E "https://github.com/orval-labs/orval/tree/master/packages/angular/"
        F["Axios Adapter"]:::adapter
        click F "https://github.com/orval-labs/orval/tree/master/packages/axios/"
        G["Fetch Adapter"]:::adapter
        click G "https://github.com/orval-labs/orval/tree/master/packages/fetch/"
        H["Hono Adapter"]:::adapter
        click H "https://github.com/orval-labs/orval/tree/master/packages/hono/"
        I["Mock Adapter"]:::adapter
        click I "https://github.com/orval-labs/orval/tree/master/packages/mock/"
        J["Query Adapter"]:::adapter
        click J "https://github.com/orval-labs/orval/tree/master/packages/query/"
        K["SWR Adapter"]:::adapter
        click K "https://github.com/orval-labs/orval/tree/master/packages/swr/"
        L["Zod Adapter"]:::adapter
        click L "https://github.com/orval-labs/orval/tree/master/packages/zod/"
    end

    D -->|"outputs"| E
    D --> F
    D --> G
    D --> H
    D --> I
    D --> J
    D --> K
    D --> L

    subgraph "Documentation & Developer Resources"
        M["Documentation Website"]:::doc
        click M "https://github.com/orval-labs/orval/tree/master/docs/"
        N["Usage Examples"]:::doc
        click N "https://github.com/orval-labs/orval/tree/master/samples/"
    end

    L -->|"demonstrates"| M
    L --> N

    subgraph "Testing/CI Infrastructure"
        O["Test Suites"]:::test
        click O "https://github.com/orval-labs/orval/tree/master/tests/"
        P["CI/CD Workflows"]:::test
        click P "https://github.com/orval-labs/orval/tree/master/.github/workflows/"
    end

    D -->|"verified_by"| O
    O --> P

    classDef cli fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#cfc,stroke:#333,stroke-width:2px;
    classDef adapter fill:#ccf,stroke:#333,stroke-width:2px;
    classDef doc fill:#fcf,stroke:#333,stroke-width:2px;
    classDef test fill:#cff,stroke:#333,stroke-width:2px;
```
