# Thanix Architecture Guide
## Introduction
This document explains the structure and architecture chosen for Thanix and gives an overview over its components.
Thanix is a code generator that takes an OpenAPI v3 YAML schema and produces a complete, idiomatic Rust API client
library crate. It follows a four-stage pipeline to convert the schema into compilable Rust code.
Ease of use is important in this regard, users should be able to generate a fully functional API client with a single
command and integrate it into their project immediately.
Thanix, very roughly, has 4 stages in its pipeline: Parse, Generate Structs, Generate Paths, and Output Assembly.
The **Parse** stage is responsible for deserializing the YAML schema and extracting metadata such as the server base
path and authentication scheme.
The **Struct Generation** stage produces Rust struct definitions from every schema component found in the API spec.
The **Path Generation** stage produces type-safe API functions for every HTTP method on every path in the spec.
The **Output Assembly** stage ties everything together using templates to produce a complete, publishable Rust crate.
## Goals
*Now, what problem does Thanix solve?*
Writing API client libraries by hand is tedious and error-prone, especially for large APIs with hundreds of endpoints
and dozens of object types. Thanix automates this process, producing idiomatic Rust code that is type-safe, documented,
and ready to use.
*What are the essential features and goals for Thanix?*
- Automate generation of Rust API client libraries from OpenAPI specs
- Produce idiomatic Rust code with proper type mappings and error handling
- Support common authentication schemes (Bearer, Basic, API Key, OAuth2)
- Allow customization for API-specific conventions (PATCH prefixes, null handling)
- Generate a complete, publishable crate with minimal manual intervention
## Non-Goals
Thanix is a code generator, it produces Rust source code from OpenAPI schemas. It is not intended to be a runtime API
client, an API gateway, or a general-purpose code generation framework. Beyond generating API client libraries from
OpenAPI v3 YAML schemas, there are currently no plans to support other input formats or code generation targets.
## Design
The Thanix codebase is organized as a pipeline where each stage has a single responsibility. The pipeline stages
communicate through well-defined data structures, ensuring that each module can be understood, tested, and modified
independently.
The following is a high-level overview of Thanix' pipeline:
```plantuml
@startuml
:YAML Schema;
:Parse\n(bindgen.rs);
fork
:Generate Structs\n(structgen.rs);
fork again
:Generate Paths\n(pathgen.rs);
end fork
:Output Crate;
note right
Templates also feed into
the final crate output
end note
@enduml
```
### Pipeline
| Parse | `bindgen.rs` | Deserialize YAML, extract server base path, detect auth scheme |
| Structs | `structgen.rs` | Generate Rust structs from `components.schemas` |
| Paths | `pathgen.rs` | Generate API functions from `paths` |
| Output | `bindgen.rs` | Assemble crate with templates |
### Data Flow
The following sequence diagram shows the interaction between the pipeline stages in more detail:
```plantuml
@startuml
actor CLI
participant "bindgen" as B
participant "structgen" as S
participant "pathgen" as P
participant "Templates" as T
CLI -> B: input path, output dir, flags
B -> B: parse YAML into OpenAPI
B -> B: extract base_path, auth_type
loop each schema component
B -> S: name, schema, patch_prefix
S --> B: Rust struct code
end
loop each path
B -> P: path, item, auth, base_path
P --> B: Rust function code
end
B -> T: output dir into crate structure
B --> CLI: generated crate
@enduml
```
### Pipeline Stages
#### 1. Schema Parsing (`bindgen.rs`)
The YAML file is parsed using `serde_yaml` into the `openapiv3::OpenAPI` struct. This stage also:
- Extracts the base path from `api.servers[0].url` for URL construction and function naming
- Detects the auth scheme from `api.components.security_schemes`
#### 2. Struct Generation (`structgen.rs`)
Iterates over `api.components.schemas` and generates `#[derive(Serialize, Deserialize, Debug, Default, Clone)]` structs for each object schema.
#### 3. Path Generation (`pathgen.rs`)
Iterates over `api.paths` and generates functions for each operation (GET, POST, PUT, PATCH, DELETE, etc.), including:
- Query parameter structs
- Response enums discriminated by HTTP status code
- Request body support
- Path parameter handling
- Auth header injection
#### 4. Output Assembly (`bindgen.rs`)
Writes the generated code into a complete Rust crate using templates for:
- `Cargo.toml`
- `src/lib.rs`
- `src/util.rs` (ThanixClient, helpers)
- `build.rs` (version embedding)
## Source Files
| `main.rs` | CLI argument parsing and entry point |
| `bindgen.rs` | Schema parsing, orchestration, type mapping |
| `structgen.rs` | Struct code generation from schema components |
| `pathgen.rs` | API path function code generation |
| `util.rs` | Utilities (dead code — kept for reference) |