# kolah/eugene architecture

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

- Interactive diagram: https://gitdiagram.com/kolah/eugene
- Repository: https://github.com/kolah/eugene

## Overview

Eugene is a CLI that turns OpenAPI 3.0–3.2 specifications into configurable Go API artifacts. The main workflow loads and transforms a spec into an internal model, then generates selected targets and writes the formatted files. Targets cover schemas, HTTP clients, framework-specific servers, typed strict servers, and embedded specs; documented features include streaming, custom templates, and OpenAPI extensions. The sampled code confirms the CLI, transformation, generation, and template execution flow; several target details are documented but not fully sampled.

Main entry points: [`internal/codegen/generator.go`](https://github.com/kolah/eugene/blob/main/internal/codegen/generator.go) (Generation pipeline), [`internal/templates/engine.go`](https://github.com/kolah/eugene/blob/main/internal/templates/engine.go) (Template engine), [`internal/cli/go.go`](https://github.com/kolah/eugene/blob/main/internal/cli/go.go) (Generate command), [`cmd/eugene/main.go`](https://github.com/kolah/eugene/blob/main/cmd/eugene/main.go) (CLI entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_main["CLI entry<br/>[main.go]"]
  node_cli["Generate command<br/>[go.go]"]
  node_config["Configuration<br/>[config.go]"]
end

subgraph group_specflow["Spec processing"]
  node_loader["OpenAPI loader<br/>[loader.go]"]
  node_transform["Spec transformer<br/>[transform.go]"]
  node_model["API model"]
end

subgraph group_generation["Generation core"]
  node_generator["Generation pipeline<br/>[generator.go]"]
  node_golang["Go utilities"]
end

subgraph group_targets["Go output targets"]
  node_types["Type definitions<br/>[types.go]"]
  node_client["HTTP client<br/>[client.go]"]
  node_server["Server adapters"]
  node_strict["Strict server<br/>[strictserver.go]"]
  node_spectarget["Embedded spec<br/>[spec.go]"]
end

subgraph group_templates["Templates and Go logic"]
  node_engine["Template engine<br/>[engine.go]"]
  node_builtins["Built-in templates"]
end

node_user(("CLI user"))
node_openapi["OpenAPI file"]
node_output["Generated files"]
node_custom["Custom templates"]

node_user -->|"runs"| node_main
node_main -->|"executes"| node_cli
node_cli -->|"loads config"| node_config
node_user -->|"provides"| node_openapi
node_cli -->|"loads spec"| node_loader
node_loader -->|"reads"| node_openapi
node_cli -->|"transforms result"| node_transform
node_transform -->|"builds"| node_model
node_cli -->|"generates from"| node_generator
node_generator -->|"reads"| node_model
node_generator -->|"uses"| node_golang
node_generator -->|"executes templates"| node_engine
node_engine -->|"loads"| node_builtins
node_engine -.->|"loads overrides"| node_custom
node_generator -->|"dispatches"| node_types
node_generator -->|"dispatches"| node_client
node_generator -->|"dispatches"| node_server
node_generator -->|"dispatches"| node_strict
node_generator -->|"dispatches"| node_spectarget
node_types -->|"renders"| node_engine
node_client -->|"renders"| node_engine
node_server -->|"renders"| node_engine
node_strict -->|"renders"| node_engine
node_spectarget -->|"renders"| node_engine
node_cli -->|"writes"| node_output

click node_main "https://github.com/kolah/eugene/blob/main/cmd/eugene/main.go"
click node_cli "https://github.com/kolah/eugene/blob/main/internal/cli/go.go"
click node_config "https://github.com/kolah/eugene/blob/main/internal/config/config.go"
click node_loader "https://github.com/kolah/eugene/blob/main/internal/loader/loader.go"
click node_transform "https://github.com/kolah/eugene/blob/main/internal/loader/transform.go"
click node_model "https://github.com/kolah/eugene/tree/main/internal/model"
click node_generator "https://github.com/kolah/eugene/blob/main/internal/codegen/generator.go"
click node_golang "https://github.com/kolah/eugene/tree/main/internal/golang"
click node_engine "https://github.com/kolah/eugene/blob/main/internal/templates/engine.go"
click node_builtins "https://github.com/kolah/eugene/tree/main/templates/go"
click node_types "https://github.com/kolah/eugene/blob/main/internal/targets/types/types.go"
click node_client "https://github.com/kolah/eugene/blob/main/internal/targets/client/client.go"
click node_server "https://github.com/kolah/eugene/tree/main/internal/targets/server"
click node_strict "https://github.com/kolah/eugene/blob/main/internal/targets/strictserver/strictserver.go"
click node_spectarget "https://github.com/kolah/eugene/blob/main/internal/targets/spec/spec.go"

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_main,node_cli,node_config,node_user toneBlue
class node_loader,node_transform,node_model toneAmber
class node_generator,node_golang,node_openapi toneMint
class node_types,node_client,node_server,node_strict,node_spectarget toneRose
class node_engine,node_builtins,node_output,node_custom toneIndigo
```

## Components

### CLI and configuration

- [CLI entry](https://github.com/kolah/eugene/blob/main/cmd/eugene/main.go): `cmd/eugene/main.go`
- [Generate command](https://github.com/kolah/eugene/blob/main/internal/cli/go.go): `internal/cli/go.go`
- [Configuration](https://github.com/kolah/eugene/blob/main/internal/config/config.go): `internal/config/config.go`

### Spec processing

- [OpenAPI loader](https://github.com/kolah/eugene/blob/main/internal/loader/loader.go): `internal/loader/loader.go`
- [Spec transformer](https://github.com/kolah/eugene/blob/main/internal/loader/transform.go): `internal/loader/transform.go`
- [API model](https://github.com/kolah/eugene/tree/main/internal/model): `internal/model`

### Generation core

- [Generation pipeline](https://github.com/kolah/eugene/blob/main/internal/codegen/generator.go): `internal/codegen/generator.go`
- [Go utilities](https://github.com/kolah/eugene/tree/main/internal/golang): `internal/golang`

### Go output targets

- [Type definitions](https://github.com/kolah/eugene/blob/main/internal/targets/types/types.go): `internal/targets/types/types.go`
- [HTTP client](https://github.com/kolah/eugene/blob/main/internal/targets/client/client.go): `internal/targets/client/client.go`
- [Server adapters](https://github.com/kolah/eugene/tree/main/internal/targets/server): `internal/targets/server`
- [Strict server](https://github.com/kolah/eugene/blob/main/internal/targets/strictserver/strictserver.go): `internal/targets/strictserver/strictserver.go`
- [Embedded spec](https://github.com/kolah/eugene/blob/main/internal/targets/spec/spec.go): `internal/targets/spec/spec.go`

### Templates and Go logic

- [Template engine](https://github.com/kolah/eugene/blob/main/internal/templates/engine.go): `internal/templates/engine.go`
- [Built-in templates](https://github.com/kolah/eugene/tree/main/templates/go): `templates/go`

### Other components

- **CLI user**
- **OpenAPI file**
- **Generated files**
- **Custom templates**

## Connections

- CLI user → CLI entry: runs
- CLI entry → Generate command: executes
- Generate command → Configuration: loads config
- CLI user → OpenAPI file: provides
- Generate command → OpenAPI loader: loads spec
- OpenAPI loader → OpenAPI file: reads
- Generate command → Spec transformer: transforms result
- Spec transformer → API model: builds
- Generate command → Generation pipeline: generates from
- Generation pipeline → API model: reads
- Generation pipeline → Go utilities: uses
- Generation pipeline → Template engine: executes templates
- Template engine → Built-in templates: loads
- Template engine → Custom templates: loads overrides
- Generation pipeline → Type definitions: dispatches
- Generation pipeline → HTTP client: dispatches
- Generation pipeline → Server adapters: dispatches
- Generation pipeline → Strict server: dispatches
- Generation pipeline → Embedded spec: dispatches
- Type definitions → Template engine: renders
- HTTP client → Template engine: renders
- Server adapters → Template engine: renders
- Strict server → Template engine: renders
- Embedded spec → Template engine: renders
- Generate command → Generated files: writes