Improve docs, update architecture diagram

README.md

@@ -7,18 +7,32 @@
 
 # Vanadium
 
-Vanadium is a Risc-V VM that runs in an embedded Secure Element.
+Vanadium is a Risc-V Virtual Machine that runs in an embedded Secure Element.
 
-By outsourcing encrypted, authenticated pages to an untrusted client, it allows to run applications (V-Apps) in the element without worrying about the limitations of the embedded platform. You can write V-Apps without worrying about binary size and memory usage: only the code actually used at runtime will be sent to the device for execution, and page swapping with the client happens transparently between the VM and the VM client.
+<img align="right" src="docs/assets/vanadium_logo.png" alt="Vanadium Logo" style="width: 50%; min-width: 200px; max-width: 280px"/>
 
+By outsourcing encrypted, authenticated pages to an untrusted client, it allows to run applications (V-Apps) in the element without worrying about the limitations of the embedded platform.
 
-# Repository
+You can write V-Apps without worrying about binary size and memory usage: only the code actually used at runtime will be sent to the device for execution, and page swapping with the client happens transparently between the VM and the VM client.
+
+During development, you will write and test code natively, without relying on an external emulator. This simplifies writing, testing and deploying your code while keeping the majority of it generic, and not tied to a specific platform.
+
+# Repository structure
 
 This repository is organized in a monorepo structure.
 
 * [docs](docs) - Architecture and technical documentation
-* [VM](vm) - The Vanadium Ledger app
-* [app-sdk](app-sdk) - Vanadium V-App SDK 
-* [client-sdk](client-sdk) - Vanadium V-App client SDK
+* [VM](vm) <small>[<tt>arm</tt>], no-std</small> - The Vanadium Ledger app. It contains the actual Virtual Machine.
+* [app-sdk](app-sdk) <small>[<tt>riscv</tt>], no_std</small> - Vanadium V-App SDK. It is used by V-Apps to access all the system services.
+* [client-sdk](client-sdk) <small>[<tt>native</tt>]</small> - Vanadium V-App client SDK. V-App Clients use it as a base for their own client crates.
+* [common](common) <small>[<tt>arm|riscv|native</tt>], no_std</small> - Any code that is shared among two or more of the above crates.
+* [apps](apps) - Complete V-Apps, and their clients
+  * [test](apps/test) - Simple V-App to test the Vanadium.
+  * [sadik](apps/sadik) - A V-App specifically designed to test the various functionality of the Vanadium V-App SDK, and particularly the ECALLs.
+  * [bitcoin](apps/bitcoin) - Grandiose things will happen here, but it's mostly empty at this stage.
+
+In VSCode, opening the [vanadium.code-workspace](vanadium.code-workspace) is the most convenient way to work with this repository.
+
+## License
 
-A [test](apps/test) V-App and client is also available.
+This project is licensed under the [Apache Licence v2.0](LICENSE).

docs/README.md

@@ -0,0 +1,31 @@
+
+
+[Vanadium architecture chart](assets/architecture.svg)
+
+# Compilation targets
+
+With the exception of the Vanadium app itself, which is an embedded Ledger app on the `ARM` target, all the other crates target either the `native` or the `riscv` targets.
+
+- The `native` target is currently `x86_64-unknown-linux-gnu`, but more native targets might be added in the future. It has `riscv` and `native` targets, in `no_std` mode.
+- The `riscv` target is currently `riscv32i-unknown-none`.
+
+> **⚠️ WARNING: The native target is insecure.**<br> While it is possible to compile and run the V-Apps on native targets, this is only intended for development and testing purposes. The cryptographic primitives are not hardened against side channels, or other kinds of attacks.
+
+# System crates
+
+In the above chart, all the crates outside *USERLAND* are developed as part of the Vanadium project.
+
+* `vanadium`: This is a Ledger application, targeting the ARM embedded platform that is used by Ledger devices. It contains the VM, code to register and run V-Apps, and provides the implementation of all the system services (via Risc-V ECALLs) to V-Apps. It interacts with the operating system ([BOLOS](https://www.ledger.com/academy/security/our-custom-operating-system-bolos)) in order to provide access to low level primitives, like communication and the cryptographic accelerator.
+* `vanadium-app-sdk`: The SDK used for developing V-Apps. It has `riscv` and `native` targets, in `no_std` mode.
+* `vanadium-client-sdk`: The SDK used for developing the client of V-Apps. It contains the client code common to all V-Apps; in particular, it manages the outsourced memory of the V-App, providing the content of memory pages (and proofs of correctness) when requested by the VM. It only has the `native` target. 
+
+# V-App structure
+
+Currently, all existing V-Apps are in this repository, with a monorepo structure.
+
+In the architecture chart above, each V-App will implement the crates in *USERLAND*: particularly, the V-App itself, the V-App client crate, and any external software using the V-App.
+
+A V-App called `foo` should contain three crates:
+* `vnd-foo`: the code of the app. It has `riscv` and `native` targets, in `no_std` mode.
+* `vnd-foo-client`: contains the client code of the V-App, built using the `vanadium-app-client-sdk` crate. It only has the `native` target. 
+* `vnd-foo-common`: any shared code between the app and client crates. It has `riscv` and `native`, in `no_std` mode.