​
The Problem We Solved

In a traditional setup, API contracts drift between backend and frontend: the Rust team writes structs, the TypeScript team writes matching types, and they diverge silently. We eliminated this entirely.

Before: 3 Sources of Truth

Hand-written Rust structs + hand-written TypeScript types + an OpenAPI doc nobody keeps in sync.

After: 1 Source of Truth

The .smithy models generate everything — Rust server traits, the TypeScript SDK, and the shared DTO + enum types.

Zero Drift

If the Smithy model doesn’t compile, nothing builds. Contract mismatch caught at compile time, not runtime.

​
Codegen Pipeline Diagram

​
Step-by-Step

1

Define the contract in Smithy IDL

API shapes, operations, and errors are described once in .smithy files under smithy/model/ (one file per domain — auth.smithy, account.smithy, insurance_policy.smithy, consultation.smithy, …). The service is in.aarokya.api#AarokyaService, assembled from per-domain namespaces in main.smithy.
2

Generate the Rust server (smithy-rs)

Produces the aarokya_server_api Rust crate with generated handler traits. Your Actix-web handlers implement these traits — the compiler enforces the contract.
3

Generate the TypeScript client

Produces @aarokya/api-client — a fully typed npm package. The Expo app consumes it directly via a file: dependency path.
4

Generate DTO types + shared enums (Rust + TypeScript)

The custom smithy-dto-gen tool reads model.json and emits:
  • backend/crates/api_models/src/*.rs — per-domain Rust DTO modules
  • backend/crates/common_enums/src/generated_enums.rs + diesel_exports.rs — shared enums
  • backend/smithy-api-model-generated/dto-ts/sdk.ts (and api.ts) — TypeScript types
In practice you run the whole thing with just gen (smithy build → smithy-dto-gen generate → rustfmt → npm install).
5

OpenAPI docs (separate, from Rust annotations)

The Rust backend uses utoipa to generate OpenAPI 3.1 from code annotations. This powers the Swagger UI at /api_docs/ui and is independent of the Smithy codegen pipeline.

​
Build Matrix

​
Why No OpenAPI in Codegen?

Smithy generates Rust server code and TypeScript clients directly, bypassing OpenAPI entirely in the codegen path. OpenAPI is only generated from Rust code annotations (via utoipa) — separately — for documentation/developer tooling purposes.This means the Smithy model is the authoritative contract, not an OpenAPI document that could drift.
See ADR-001: Smithy as IDL and ADR-002: Rust Stack for the full reasoning.