From f91e3fcb6660a17ab0261ed2ce905d44244120b0 Mon Sep 17 00:00:00 2001
From: sergeych <real.sergeych@gmail.com>
Date: Tue, 16 Sep 2025 15:49:07 +0400
Subject: [PATCH] multiporject structure more comments and docs

---
 README.md                           |  7 +++++++
 jvm_console/README.md               |  5 +++++
 jvm_console/build.gradle.kts        | 10 +++++++++-
 jvm_console/settings.gradle.kts     |  1 -
 jvm_console/src/main/kotlin/Main.kt | 17 ++++++++++++++---
 settings.gradle.kts                 |  1 +
 6 files changed, 36 insertions(+), 5 deletions(-)
 create mode 100644 README.md
 create mode 100644 jvm_console/README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..16eb8cb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,7 @@
+# unitedgold.io samples directory
+
+This project will contain samples of API usage for the [UnitedGold](https://dev.unitedgold.io) project.
+
+
+- [jvm_console](jvm_console) simple JVM console application
+
diff --git a/jvm_console/README.md b/jvm_console/README.md
new file mode 100644
index 0000000..70ac940
--- /dev/null
+++ b/jvm_console/README.md
@@ -0,0 +1,5 @@
+# unitedgold.io JVM console sample
+
+This project will contain samples of API usage for the [UnitedGold](https://dev.unitedgold.io) project.
+
+This sample shows how to configure and connect APU library, create connection to the server and perform most basic operations.
diff --git a/jvm_console/build.gradle.kts b/jvm_console/build.gradle.kts
index d87bd78..2819ff0 100644
--- a/jvm_console/build.gradle.kts
+++ b/jvm_console/build.gradle.kts
@@ -7,23 +7,31 @@ version = "1.0-SNAPSHOT"
 
 repositories {
     mavenCentral()
+
+    // 3 custom repositories for unitedgold.io components:
     maven("https://gitea.sergeych.net/api/packages/SergeychWorks/maven")
     maven("https://maven.universablockchain.com")
     maven("https://gitea.sergeych.net/api/packages/YoungBlood/maven")
-    mavenLocal()
+    // end of unitedgold.io required repositories
 }
 
 val apiVersion = "0.0.1-SNAPSHOT"
 
 dependencies {
+    // The API library
     implementation("io.unitedgold.api:shared:$apiVersion")
+
+    // To silence logback error messages of "not being configured",
+    // this is Ktor client issue (we use ktor client in API)
     implementation("ch.qos.logback:logback-classic:1.5.18")
+
     testImplementation(kotlin("test"))
 }
 
 tasks.test {
     useJUnitPlatform()
 }
+
 kotlin {
     jvmToolchain(17)
 }
\ No newline at end of file
diff --git a/jvm_console/settings.gradle.kts b/jvm_console/settings.gradle.kts
index 0f72f14..2d254d2 100644
--- a/jvm_console/settings.gradle.kts
+++ b/jvm_console/settings.gradle.kts
@@ -1,5 +1,4 @@
 plugins {
     id("org.gradle.toolchains.foojay-resolver-convention") version "0.8.0"
 }
-rootProject.name = "unitedgold_sample_console_jvm"
 
diff --git a/jvm_console/src/main/kotlin/Main.kt b/jvm_console/src/main/kotlin/Main.kt
index bd70748..59b34a5 100644
--- a/jvm_console/src/main/kotlin/Main.kt
+++ b/jvm_console/src/main/kotlin/Main.kt
@@ -4,14 +4,25 @@ import kotlinx.coroutines.runBlocking
 import net.sergeych.crypto2.initCrypto
 import net.sergeych.ugdx.UGClient
 
-//TIP To <b>Run</b> code, press <shortcut actionId="Run"/> or
-// click the <icon src="AllIcons.Actions.Execute"/> icon in the gutter.
 fun main() {
+
+    // united gold API is coroutine-based; this way it can effectively
+    // run ell on single-thread platforms like JS aor WasmJS, but it comes
+    // with the cost of running it in a coroutine:
     runBlocking {
+        // API uses heavy cryptography, see https://gitea.sergeych.net/sergeych/crypto2
+        // it needs early asynchronous initialization (again to work well with JS and WasmJS):
         initCrypto()
+
+        // now the crypto is ready and we can start using API
+        // create a client connection using WebSocket to the dev server
         val client = UGClient("wss://dev.unitedgold.io/kp")
+
+        // enumerate all currencies
         for( cp in client.currencyPairs() ) {
-            println(cp)
+            // label is short text like "UBIT/USDX"
+            // them we output longer token names:
+            println("${cp.label}: ${cp.base.name} / ${cp.quote.name}")
 
         }
     }
diff --git a/settings.gradle.kts b/settings.gradle.kts
index c35990b..670a2f5 100644
--- a/settings.gradle.kts
+++ b/settings.gradle.kts
@@ -1,2 +1,3 @@
 rootProject.name = "unitedgold_samples"
+
 include(":jvm_console")