General design principles

Before we dive in to the design elements, it is important to state that Smithy4s is designed with the following constraints :

• optimised for number of usecases: Smithy4s is not (just) an http/json library, it can/could be used for a great many things, such as AWS SDKs, CLIs, UIs, etc. Therefore, following the protocol-agnostic nature of smithy, the code generated by Smithy4s is not biased towards any protocol or serialisation mechanism, nor any runtime or Scala version.
• optimised for correctness over compatibility: there is strictly no guarantee made regarding backward compatibility of the generated code when users evolve their smithy schemas. Therefore, users are expected to regenerate the code at use-site, instead of relying on artifacts that would contain the generated code... However, users do get idiomatic Scala code, including case classes / sealed traits (which are notoriously hard to evolve in binary compatible ways), and this generated code correctly reflects the smithy specifications.
• decoupled from third-party libraries: the generated code depends only on smithy4s-core for compilation, which does not pull third-party dependencies (not even a general purpose libraries that the maintainers love, like cats)

These constraints may sound counter-intuitive, obtuse, even alien. The internals of this library are not beginner friendly. They rely on advanced features of the Scala compiler that may unfortunately scare away newcomers interested in contributing. If you're not discouraged yet, do not hesitate to ask questions using github discussions, we will do our best to answer them!