Merge pull request #35 from testcontainers/architecture

Add initial project architecture overview

Author: oleg-nenashev

README.md

@@ -66,9 +66,24 @@ See [the examples and demos](./demo/README.md) for more examples.
 ### Using in other languages
 
 TL;DR: You get the C header file, a shared library object or a DLL file from the
-[Testcontainers for C](./docs/c/README.md) module,
-Then, you know the drill.
+[Testcontainers for C](./docs/c/README.md) module.
+Then, you can bind this native library in your project type.
+It allows supporting many other languages that support using
+native tooling via dynamically or statically linked libraries:
+
+![Languages that can leverage Testcontainers for C](docs/images/supported-languages.png)
+
+Disclaimer:
+The schema above shows the most popular languages for Embedded systems,
+based on the
+[IEEE Spectrum 2021 Report](https://spectrum.ieee.org/top-programming-languages-2021)
+and the [JetBrains 2021 Developer Ecosystem Survey for Embedded Software](https://www.jetbrains.com/lp/devecosystem-2021/embedded/).
+More native languages exist and can be supported by Testcontainers Native.
+
 Feel free to contribute examples or SDKs for the languages!
+See the [Swift Solution Page](./docs/swift/README.md) for examples.
+[Testcontainers Native Architecture](./docs/architecture/README.md)
+describes how it can be done in principle.
 
 ## Credits
 

docs/architecture/README.md

@@ -3,3 +3,29 @@
 !!! note
     This section is coming soon.
     All contributions are welcome, just submit a pull request!
+
+## Build Process
+
+![Testcontainers Native Build Process](./images/build-process.png)
+
+### Stage 1. Testcontainers for C shared library
+
+The core `testcontainers-c` shared library is built with [Cgo](https://pkg.go.dev/cmd/cgo).
+For that the `-buildmode=c-shared` is used in the Golang builder,
+and it also receives a customized header so that the types can be mapped between C and Golang.
+For that, we also have to flatten the structure and to switch the reference-based build process to fixed Objects stored in the Golang namespace, and C API
+using unique object IDs.
+
+### Stage 2. Language Bindings
+
+Then, we build custom binding libraries, by using Testcontainers for C
+as a static library that is bundled into the language specific libs.
+This stage depends on the language and common practices there.
+
+### Stage 3. Executable Code
+
+Well, you build it.
+From the previous stages,
+you get a header file, binding libraries,
+a shared library object or a DLL file from the [Testcontainers for C](./docs/c/README.md) module.
+Then, you know the drill.