# ogen-go/ogen architecture

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

- Interactive diagram: https://gitdiagram.com/ogen-go/ogen
- Repository: https://github.com/ogen-go/ogen

## Overview

##### Overall Project Purpose and Type
- The project is an OpenAPI v3 Code Generator written in Go. It is aimed at replacing runtime reflection and manual boilerplate code by generating efficient, statically typed code for client libraries, server interfaces, routers, and more.
- The README describes features such as “no reflection”, code-generation of json (using an optimized library), static radix routing, custom type wrappers (for optional/nullable values) and sum types. This indicates that the system is focused on parsing specs, transforming them, and templating code.

##### Core Architectural Components
a. Command-line Interface (CLI) & Entrypoints
- Located under directories like cmd/ogen and cmd/jschemagen. This is the user interface that triggers code generation.
b. OpenAPI Parsing and Schema Resolution
- Modules under openapi/parser and jsonschema are responsible for reading, expanding, and verifying OpenAPI specs and JSON schema documents.
c. Intermediate Representation (IR) Construction
- The “gen/ir” directory hosts modules that build an internal representation of the API specification (operations, schemas, security, etc.) that is later consumed by the generator.
d. Code Generation Engine and Templates
- The “gen” directory and its subdirectories (including gen/_template and gen/templates.go) include the logic to traverse the IR, apply templating, and output the generated Go code.
e. Converters and Utilities
- Modules in “conv”, “internal/*” (e.g. naming, error handling, xslices, xmaps, etc.) include supporting logic to convert data types, maintain naming consistency, log errors, and handle common utility functions.
f. Routing and HTTP Handling
- Directories such as “http” and “middleware” show that the generated code, as well as some of the supporting libraries, handle HTTP layer concerns (like static radix routers, request/response decoding).
g. Testing and Integration Components
- The “internal/integration” directory along with numerous _testdata directories indicates that there is an extensive suite of integration tests validating generated code and parser behavior.
h. CI/CD and Infrastructure
- The presence of GitHub workflows, Dockerfile, Makefile, and various configuration files in the repository indicate deployment, testing, and containerization strategies.

##### Relationships and Data Flow
- The CLI (cmd/ogen) invokes the core generator logic.
- The core generator first calls the parser modules (openapi/parser, jsonschema) to load and verify an OpenAPI spec.
- After parsing, the tools build an IR (gen/ir) that abstracts the key details of operations, schemas, paths, security, etc.
- The generation engine uses a set of predefined templates (located in gen/_template) alongside helper modules (in gen/) to translate the IR into actual Go source files.
- Utility modules (conv, internal/naming, etc.) support these transformations. They ensure correct type conversion and proper naming conventions.
- The generated code then includes client and server interfaces along with JSON encoding/decoding functions (as shown in the README examples).
- Testing components (in internal/integration and various _testdata directories) validate the output of these steps, ensuring adherence to the OpenAPI spec.
- CI/CD pipelines (GitHub workflows) automate linting, testing, coverage, and package generation.

##### Architectural Patterns and Design Principles
- Separation of concerns is evident: parsing, IR construction, templating, and testing are split into distinct modules.
- The use of a transformation pipeline – from input spec to IR to code template – is a classic compiler design pattern.
- The project emphasizes static type-safety (avoiding reflection) and code generation with heavy use of generic wrappers.
- Extensive test suites and CI/CD workflows ensure robust verification and continuous integration.

##### Technology and Framework Integration
- The core is built in Go, and it leverages optimized libraries (such as go-faster/jx for JSON) rather than the standard library.
- The repository uses Docker for containerization and GitHub Actions for automation.
- Tools and scripts (Makefile, shell scripts) assist in code formatting, linting, and testing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UserCLI["User/CLI"]:::user
        CLI_Ogen["CLI: ogen (cmd/ogen)"]:::cli
        CLI_Jschema["CLI: JS schema (cmd/jschemagen)"]:::cli
    end

    %% Parsing and Intermediate Representation
    subgraph "Parsing & IR"
        Parser_OpenAPI["OpenAPI Parser (openapi/parser)"]:::parser
        Parser_JSON["JSON Schema Parser (jsonschema)"]:::parser
        IR_Builder["IR Builder (gen/ir)"]:::parser
    end

    %% Code Generation Pipeline
    subgraph "Code Generation"
        CodeGenEngine["Code Generation Engine (gen)"]:::codegen
        CodeTemplates["Templating (gen/_template, gen/templates.go)"]:::codegen
        GeneratedCode["Generated Code (Client & Server Interfaces, JSON Codecs, etc.)"]:::codegen
    end

    %% Utilities and Converters
    subgraph "Utilities"
        Conv["Converters (conv)"]:::utilities
        Naming["Naming (internal/naming)"]:::utilities
        Xslices["XSlices (internal/xslices)"]:::utilities
        Xmaps["XMaps (internal/xmaps)"]:::utilities
    end

    %% HTTP and Routing
    subgraph "HTTP & Routing"
        HTTP["HTTP Handling (http)"]:::http
        Middleware["Middleware (middleware)"]:::http
    end

    %% Testing Components
    subgraph "Testing"
        Testing["Integration Testing (internal/integration)"]:::testing
    end

    %% CI/CD and Infrastructure
    subgraph "CI/CD & Infrastructure"
        CI_Github["GitHub Workflows (.github/workflows)"]:::cicd
        Docker["Dockerfile"]:::cicd
        Makefile["Makefile"]:::cicd
    end

    %% Flow Connections
    UserCLI --> CLI_Ogen
    UserCLI --> CLI_Jschema

    CLI_Ogen --> Parser_OpenAPI
    CLI_Jschema --> Parser_JSON

    Parser_OpenAPI --> IR_Builder
    Parser_JSON --> IR_Builder

    IR_Builder --> CodeGenEngine
    IR_Builder --> CodeTemplates

    CodeGenEngine --> CodeTemplates
    CodeGenEngine --> GeneratedCode
    CodeTemplates --> GeneratedCode

    %% Utilities supporting both IR and Code Generation
    Conv -.-> IR_Builder
    Conv -.-> CodeGenEngine
    Naming -.-> IR_Builder
    Naming -.-> CodeGenEngine
    Xslices -.-> IR_Builder
    Xslices -.-> CodeGenEngine
    Xmaps -.-> IR_Builder
    Xmaps -.-> CodeGenEngine

    %% Generated Code feeds into HTTP/Routing modules
    GeneratedCode --> HTTP
    GeneratedCode --> Middleware

    %% Testing validates Generated Code
    Testing -->|"validates"| GeneratedCode

    %% CI/CD Infrastructure triggers build and test cycles
    CI_Github --> CLI_Ogen
    CI_Github --> Testing
    Docker --> CLI_Ogen
    Makefile --> CLI_Ogen

    %% Click Events
    click CLI_Ogen "https://github.com/ogen-go/ogen/tree/main/cmd/ogen"
    click CLI_Jschema "https://github.com/ogen-go/ogen/tree/main/cmd/jschemagen"
    click Parser_OpenAPI "https://github.com/ogen-go/ogen/tree/main/openapi/parser"
    click Parser_JSON "https://github.com/ogen-go/ogen/tree/main/jsonschema"
    click IR_Builder "https://github.com/ogen-go/ogen/tree/main/gen/ir"
    click CodeGenEngine "https://github.com/ogen-go/ogen/tree/main/gen"
    click CodeTemplates "https://github.com/ogen-go/ogen/tree/main/gen/_template"
    click Conv "https://github.com/ogen-go/ogen/tree/main/conv"
    click Naming "https://github.com/ogen-go/ogen/tree/main/internal/naming"
    click Xslices "https://github.com/ogen-go/ogen/tree/main/internal/xslices"
    click Xmaps "https://github.com/ogen-go/ogen/tree/main/internal/xmaps"
    click HTTP "https://github.com/ogen-go/ogen/tree/main/http"
    click Middleware "https://github.com/ogen-go/ogen/tree/main/middleware"
    click Testing "https://github.com/ogen-go/ogen/tree/main/internal/integration"
    click CI_Github "https://github.com/ogen-go/ogen/tree/main/.github/workflows"
    click Docker "https://github.com/ogen-go/ogen/tree/main/Dockerfile"
    click Makefile "https://github.com/ogen-go/ogen/tree/main/Makefile"

    %% Styles
    classDef user fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef cli fill:#87CEFA,stroke:#333,stroke-width:2px;
    classDef parser fill:#98FB98,stroke:#333,stroke-width:2px;
    classDef codegen fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef utilities fill:#FFA07A,stroke:#333,stroke-width:2px;
    classDef http fill:#20B2AA,stroke:#333,stroke-width:2px;
    classDef testing fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef cicd fill:#F08080,stroke:#333,stroke-width:2px;
```
