Type of Change

• Bugfix
• New feature
• Enhancement
• Refactoring
• Dependency updates
• Documentation
• CI/CD

Description

Overview of the Three Crates

1. smithy crate (Procedural Macro)

This is a procedural macro crate that provides the #[derive(SmithyModel)] attribute. It's the entry point for developers who want to generate Smithy models from their Rust structs.

Key characteristics:

• Type: Procedural macro library (proc-macro = true)
• Location: crates/smithy/
• Dependencies: proc-macro2, quote, syn, smithy-core
• Main export: SmithyModel derive macro

2. smithy-core crate (Core Logic)

This contains the fundamental types and logic for Smithy model generation. It acts as the shared foundation between the macro and the generator.

Key characteristics:

• Type: Library crate

• Location: crates/smithy-core/

• Dependencies: serde, serde_json, syn, proc-macro2

• Main modules:

  • types.rs - Core data structures (SmithyModel, SmithyShape, SmithyTrait, etc.)
  • generator.rs - SmithyGenerator for converting models to IDL files

3. smithy-generator crate (Code Generation Tool)

This is an executable that scans the entire workspace for structs annotated with #[derive(SmithyModel)] and generates the corresponding Smithy IDL files.

Key characteristics:

• Type: Binary crate with build script

• Location: crates/smithy-generator/

• Dependencies: smithy-core, workspace crates (api_models, common_enums, etc.)

• Components:

  • build.rs - Workspace scanner and registry generator
  • main.rs - IDL file generator

How They Work Together

Step 1: Developer Annotation

A developer annotates their Rust struct or enum with the derive macro:

#[derive(SmithyModel)]
#[smithy(namespace = "com.hyperswitch.payments")]
pub struct PaymentRequest {
    #[smithy(value_type = "String", required)]
    pub payment_id: String,
    
    #[smithy(value_type = "Option<i64>")]
    pub amount: Option<i64>,
}

Step 2: Procedural Macro Processing (smithy crate)

When the code is compiled, the smithy crate's procedural macro:

1. Parses the struct/enum definition using syn

2. Extracts metadata from #[smithy(...)] attributes (namespace, constraints, field types)

3. Generates implementation of the SmithyModelGenerator trait for the annotated type

4. Handles complex scenarios like:

   • Flattened fields (#[serde(flatten)])
   • Optional types (Option<T>)
   • Collections (Vec<T>, HashMap<K,V>)
   • Enum variants (both string enums and unions)
   • Constraint validation (patterns, ranges, lengths)

The generated code implements SmithyModelGenerator::generate_smithy_model() which returns a SmithyModel containing the structure definition.

Step 3: Build-Time Discovery (smithy-generator build script)

The smithy-generator crate has a build script (build.rs) that:

1. Scans the entire workspace recursively through all crates/ subdirectories

2. Uses regex parsing to find structs/enums with #[derive(SmithyModel)]

3. Generates a registry file (model_registry.rs) containing:

   • Import statements for all discovered types
   • A discover_smithy_models() function that calls generate_smithy_model() on each type

Step 4: IDL Generation (smithy-generator executable)

When the smithy-generator binary runs:

1. Loads the generated registry and calls discover_smithy_models()
2. Collects all SmithyModel instances from across the workspace
3. Groups models by namespace for organized file generation
4. Uses SmithyGenerator from smithy-core to convert models to Smithy IDL syntax
5. Writes .smithy files to smithy/models/ directory

Step 5: Smithy IDL Output

The final output is proper Smithy IDL files like:

$version: "2"

namespace com.hyperswitch.payments

/// Payment request structure
structure PaymentRequest {
    @required
    payment_id: String
    
    amount: Long
}

Key Design Patterns

Type Resolution System

The smithy-core/types.rs contains sophisticated type resolution logic that:

• Maps Rust primitive types to Smithy equivalents (String → smithy.api#String)
• Handles generic types recursively (Vec<T> → List shapes, Option<T> → optional members)
• Resolves custom types and manages cross-namespace references
• Generates intermediate shapes for complex nested types

Constraint System

The framework supports rich constraint modeling:

• Validation constraints: pattern, range, length
• HTTP binding constraints: httpLabel, httpQuery
• Structural constraints: required, mixin

Workspace Integration

The build script approach allows:

• Zero-configuration discovery of models across the entire workspace
• Compile-time validation that all referenced types exist
• Automatic regeneration when models change
• Selective inclusion of only relevant crates (excludes smithy crates themselves)

This architecture provides a seamless developer experience where you simply derive SmithyModel on your types, and the toolchain automatically discovers them and generates proper Smithy IDL files during the build process.

Additional Changes

• This PR modifies the API contract
• This PR modifies the database schema
• This PR modifies application configuration/environment variables

Motivation and Context

How did you test it?

There are no test cases for this PR, since this is just addition of the Smithy Model generation framework to Hyperswitch. The only way to test this PR is to add the derive macros in structs and check the model generation, but that will be done in subsequent PRs.

Checklist

• I formatted the code cargo +nightly fmt --all
• I addressed lints thrown by cargo clippy
• I reviewed the submitted code
• I added unit tests for my changes where possible