docs: add starting guide

.github/workflows/satp-hermes-release.yaml

@@ -102,7 +102,6 @@ jobs:
             - Custom Version: ${{ inputs.custom_version || 'None (using package.json)' }}
             - Source Branch: ${{ inputs.release_branch || github.ref }}
             - Workflow Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
-
-            Released on: $(date -u '+%Y-%m-%d %H:%M:%S UTC')
+            - Release Time (github): ${{ github.run_started_at }}
           draft: false
           prerelease: ${{ contains(inputs.tag_version, 'alpha') || contains(inputs.tag_version, 'beta') || contains(inputs.tag_version, 'rc') }}

CONTRIBUTING.md

@@ -196,65 +196,82 @@ NOTE: You can refer original tutorial ['GitHub Standard Fork & Pull Request Work
 Whenever you begin to use your codes on Hyperledger Cacti, you should follow the directory structure on Hyperledger Cacti.
 The current directory structure is described as the following:
 
-> - contrib/ : Contributions from each participants, which are not directly dependent on Cacti code.
->   - Fujitsu-ConnectionChain/
->   - Accenture-BIF/
->   - IBM-Weaver/
-> - docs/
->   - API/
->     - business-logic-plugin.md
->     - ledger-plugin.md
->     - routing-interface.md
-> - examples/
->   - example01-car-trade/
->     - src/
-> - plugins/
->     - business-logic-plugin/
->       - lib/ : libraries for building Business Logic Plugin
->     - ledger-plugin/ : Codes of Ledger Plugin
->       - (ledger-name)/ : Including the ledger name (e.g. Ethereum, Fabric, ...)
->         - verifier/
->           - src/ : Source codes of Verifier on Ledger Plugin
->           - unit-test/ : Unit test codes of Verifier on Ledger Plugin (single driver / driver and docker env / ...)
->         - validator/
->           - src/ : Source codes of Validator on Ledger Plugin
->           - unit-test/ : Unit test codes of Validator on Ledger Plugin (single driver / driver and docker env / ...)
->     - routing-interface/
-> - whitepaper/
-> - test/
->   - docker-env/
->   - kubernetes-env/
+> - docs/ : Project documentation (MkDocs-based)
+>   - docs/ : Documentation source files
+>   - assets/ : Static assets for documentation
+> - examples/ : Example applications and demos
+>   - cactus-example-carbon-accounting-backend/
+>   - cactus-example-cbdc-bridging/
+>   - cactus-example-supply-chain-backend/
+>   - cactus-example-discounted-asset-trade/
+>   - ... (additional examples)
+> - extensions/ : Optional extensions and plugins
+> - packages/ : Core packages (monorepo structure)
+>   - cactus-api-client/ : API client utilities
+>   - cactus-cmd-api-server/ : API server command
+>   - cactus-common/ : Common utilities and shared code
+>   - cactus-core/ : Core framework functionality
+>   - cactus-core-api/ : Core API definitions
+>   - cacti-plugin-ledger-connector-*/ : Ledger connector plugins
+>     - cacti-plugin-ledger-connector-besu/
+>     - cacti-plugin-ledger-connector-fabric/
+>     - cacti-plugin-ledger-connector-ethereum/
+>     - cacti-plugin-ledger-connector-corda/
+>     - ... (additional connectors)
+>   - cacti-plugin-keychain-*/ : Keychain plugins
+>   - cacti-plugin-satp-hermes/ : SATP (Secure Asset Transfer Protocol) implementation
+>   - cacti-test-*/ : Test packages for integration testing
+>   - cacti-copm-*/ : COPM (Cross-chain Operation Protocol) packages
+>   - cacti-plugin-weaver-*/ : Weaver integration plugins
+> - tools/ : Build and CI/CD tooling
+>   - docker/ : Docker images (all-in-one ledger images)
+>   - ci.sh : Main CI script
+> - weaver/ : Weaver interoperability framework
+>   - common/ : Shared Weaver components
+>   - core/ : Core Weaver implementation
+>   - rfcs/ : Weaver RFCs and specifications
+>   - samples/ : Weaver sample applications
+>   - sdks/ : Weaver SDKs
+> - whitepaper/ : Project whitepaper
 
 ## Create a new package
 
 To create a new package in Hyperledger Cacti:
 1. Create a new subfolder under the `/packages` folder;
 2. Name the folder according to the convention: `cacti-$PLUGIN_TYPE-$PLUGIN_FLAVOR`. Example: `cacti-plugin-satp-hermes`;
+   > **Note**: Legacy packages may use the `cactus-` prefix, but all new packages should use `cacti-`.
 3. Inside the new package folder, follow the base directory structure of the current packages (NOTE: the `dist` and `node_modules` are generated folders. As such, there is no need to create them previously):
 > - CHANGELOG.md
-> -  README.md
-> -  package.json
-> -  src
->     - main
->        - $language
->        - $language
->     - test
->        - $language
->        - $language
+> - CONTRIBUTING.md (optional, for package-specific guidelines)
+> - README.md
+> - package.json
+> - src/
+>   - main/
+>     - typescript/
+>   - test/
+>     - typescript/
+>       - unit/
+>       - integration/
 > - tsconfig.json
 
-Example:
+Example (cacti-plugin-satp-hermes):
 > - CHANGELOG.md
-> -  README.md
-> -  package.json
-> -  src
->     - main
->        - typescript
->        - yml
->     - test
->        - typescript
->        - solidity
+> - README.md
+> - package.json
+> - src/
+>   - main/
+>     - typescript/
+>     - solidity/ (for smart contracts)
+>     - yml/ (for OpenAPI specs)
+>   - test/
+>     - typescript/
+>       - unit/
+>       - integration/
+>     - solidity/ (for contract tests)
+>     - cucumber/ (for BDD tests)
 > - tsconfig.json
+> - jest.config-unit.ts
+> - jest.config-integration.ts
 
 4. In the `package.json` file, change the name to `@hyperledger/<your-package-name>`. Example: `@hyperledger/cacti-plugin-satp-hermes`;
 5. In the `tsconfig.json` file, ensure it extends the Hyperledger Cacti base `tsconfig.ts` file. You can do it by following this example:
@@ -292,7 +309,7 @@ Example:
 NOTE: Sequence order matters. The packages are built sequentially which can raise some issues if there are dependencies between packages. More specialized packages (i.e. with more dependencies) should be inserted down the list.
 
 7. At base Hyperledger Cacti scope, run `yarn configure`. If it runs successfully, the new package was added!
-8. When testing, make sure to have a separate test package which is able to depend on the api-server package without causing circular dependencies. The name `cacti-test-$PLUGIN_TYPE-$PLUGIN_FLAVOR`, is recommended. Example: `cacti-test-plugin-satp-hermes`.
+8. When testing, make sure to have a separate test package which is able to depend on the api-server package without causing circular dependencies. The name `cacti-test-$PLUGIN_TYPE-$PLUGIN_FLAVOR` is recommended. Example: `cacti-test-plugin-satp-hermes`.
 
 
 ## Test Automation

docs/docs/guides/developers.md

@@ -1,3 +1,21 @@
 # Developer's Guide
 
-We will provide more instructions and guidelines soon. For now, please refer to the [Cacti Contributions guide](../contributing/how-to-contribute.md) and the [project best practices](../references/best-practices.md).
+## Getting Started
+
+If you're new to Cacti, start with our comprehensive **[Getting Started Guide](./getting-started.md)** which covers:
+
+- Understanding Cacti's architecture and what components are part of the framework
+- Choosing the right level of integration for your project:
+  - **Level 1**: Using connectors as npm dependencies (lowest barrier to entry)
+  - **Level 2**: Running the API server with plugins (for non-Node.js projects)
+  - **Level 3**: Full framework integration with business logic plugins
+- Step-by-step tutorials for each level of immersion
+
+## Additional Resources
+
+For more detailed information, please refer to:
+
+- [Cacti Contributions guide](../contributing/how-to-contribute.md) - How to contribute to the project
+- [Project best practices](../references/best-practices.md) - Coding standards and conventions
+- [Architecture overview](../architecture.md) - Understanding the integrated architecture
+- [Cactus packages](../cactus/packages.md) - Documentation for individual components

docs/docs/guides/diagrams/cacti-architecture-stack.mmd

@@ -0,0 +1,42 @@
+---
+title: Cacti Technology Stack
+---
+flowchart TB
+    subgraph YOUR_APP["YOUR APPLICATION"]
+        direction TB
+        FE["Frontend - React, Vue, Angular<br/>───────────<br/>NOT CACTI"]
+        BL["Business Logic / REST API<br/>───────────<br/>YOUR code OR Cacti Plugin"]
+        FE --> BL
+    end
+
+    subgraph LEVELS["CACTI INTEGRATION LEVELS"]
+        direction LR
+        L1["LEVEL 1<br/>─────────<br/>Connector<br/>Library Only"]
+        L2["LEVEL 2<br/>─────────<br/>API Server<br/>+ Plugins"]
+        L3["LEVEL 3<br/>─────────<br/>Full Framework<br/>+ BL Plugin"]
+    end
+
+    subgraph CORE["CACTI CORE COMPONENTS"]
+        direction LR
+        LC["Ledger<br/>Connectors"]
+        KC["Keychain<br/>Plugins"]
+        CP["Consortium<br/>Plugins"]
+        CC["Cross-Chain<br/>SATP, Weaver"]
+    end
+
+    subgraph LEDGERS["BLOCKCHAIN NETWORKS - NOT CACTI"]
+        direction LR
+        Fabric["Fabric"]
+        Besu["Besu"]
+        ETH["Ethereum"]
+        Corda["Corda"]
+    end
+
+    YOUR_APP --> LEVELS
+    LEVELS --> CORE
+    CORE --> LEDGERS
+
+    style YOUR_APP fill:#e1f5fe,stroke:#0277bd
+    style LEVELS fill:#fff3e0,stroke:#ef6c00
+    style CORE fill:#e8f5e9,stroke:#2e7d32
+    style LEDGERS fill:#fce4ec,stroke:#c2185b

docs/docs/guides/diagrams/level1-connector-flow.mmd

@@ -0,0 +1,23 @@
+---
+title: Level 1 - Connector as Library
+---
+sequenceDiagram
+    participant App as Your Node.js App
+    participant Svc as Your Service Layer
+    participant Conn as Cacti Connector<br/>(npm dependency)
+    participant BC as Blockchain Network
+
+    App->>Svc: Business Operation Request
+    activate Svc
+    Svc->>Conn: connector.invokeContract()
+    activate Conn
+    Conn->>BC: JSON-RPC / gRPC Call
+    activate BC
+    BC-->>Conn: Transaction Result
+    deactivate BC
+    Conn-->>Svc: InvokeContractResponse
+    deactivate Conn
+    Svc-->>App: Business Response
+    deactivate Svc
+
+    Note over App,BC: Your code owns the entire stack.<br/>Cacti is just an npm dependency.

docs/docs/guides/diagrams/level2-api-server-flow.mmd

@@ -0,0 +1,28 @@
+---
+title: Level 2 - API Server with Plugins
+---
+sequenceDiagram
+    participant App as Your App<br/>(Python/Java/Go)
+    participant API as Cacti API Server<br/>(Docker Container)
+    participant Conn as Connector Plugin
+    participant KC as Keychain Plugin
+    participant BC as Blockchain Network
+
+    App->>API: REST POST /invoke-contract
+    activate API
+    API->>KC: Get signing credentials
+    activate KC
+    KC-->>API: Credentials
+    deactivate KC
+    API->>Conn: invokeContract(request)
+    activate Conn
+    Conn->>BC: JSON-RPC Call
+    activate BC
+    BC-->>Conn: Transaction Result
+    deactivate BC
+    Conn-->>API: Response
+    deactivate Conn
+    API-->>App: HTTP 200 + JSON
+    deactivate API
+
+    Note over App,BC: Your app uses REST API.<br/>Cacti runs as a containerized service.

docs/docs/guides/diagrams/level3-full-framework.mmd

@@ -0,0 +1,41 @@
+---
+title: Level 3 - Full Framework Integration
+---
+flowchart TB
+    subgraph CLIENT["Client Layer"]
+        FE["Your Frontend<br/>(React/Angular/Vue)"]
+    end
+
+    subgraph APISERVER["Cacti API Server"]
+        direction TB
+
+        subgraph YOURPLUGIN["Your Business Logic Plugin"]
+            EP["Your REST Endpoints"]
+            SVC["Your Services"]
+            EP --> SVC
+        end
+
+        subgraph CACTIPLUGINS["Cacti Plugins"]
+            direction LR
+            CONN["Ledger Connectors"]
+            KC["Keychain"]
+            CONS["Consortium"]
+        end
+
+        YOURPLUGIN --> CACTIPLUGINS
+    end
+
+    subgraph LEDGERS["Blockchain Networks"]
+        direction LR
+        L1["Fabric"]
+        L2["Besu"]
+        L3["Ethereum"]
+    end
+
+    CLIENT --> APISERVER
+    CACTIPLUGINS --> LEDGERS
+
+    style CLIENT fill:#e3f2fd,stroke:#1565c0
+    style YOURPLUGIN fill:#fff8e1,stroke:#ff8f00
+    style CACTIPLUGINS fill:#e8f5e9,stroke:#2e7d32
+    style LEDGERS fill:#fce4ec,stroke:#c2185b