feat: better documentation clarity across cadence-samples to reduce onboarding friction for new developers (#126)

* Configured dev env to run in 'cadence-samples

Signed-off-by: Diana Zawadzki <[email protected]>

* Fixed --workflow flag, param isn't passed with dashes

Signed-off-by: Diana Zawadzki <[email protected]>

* Add Docker troubleshooting section to README

Signed-off-by: Diana Zawadzki <[email protected]>

* Add visual walkthrough screenshots to hello_world README

Signed-off-by: Diana Zawadzki <[email protected]>

* Clean up hello_world README: remove redundant screenshots

Signed-off-by: Diana Zawadzki <[email protected]>

* Move workflow files to activities/ and operations/ folders

Signed-off-by: Diana Zawadzki <[email protected]>

---------

Signed-off-by: Diana Zawadzki <[email protected]>

Author: zawadzkidiana

README.md

@@ -38,6 +38,46 @@ This downloads and starts all required dependencies including Cadence server, da
 make
 ```
 
+### Docker Troubleshooting
+
+The `docker-compose` command requires Docker daemon to be running. On macOS/Windows, open Docker Desktop. On Linux, run `sudo systemctl start docker`.
+
+<details>
+<summary>Port conflicts</summary>
+
+If you see `Bind for 0.0.0.0:<port> failed: port is already allocated`, find the process using that port:
+
+```bash
+lsof -i tcp:<port>
+```
+
+To find which container is using it:
+```bash
+docker ps --format '{{.ID}}\t{{.Ports}}\t{{.Names}}' | grep <port>
+```
+
+Stop and remove the conflicting container:
+```bash
+docker stop <container_id> && docker rm <container_id>
+```
+
+Cadence uses these ports: `7833`, `7933`, `7939`, `8000-8003`, `8088` (Web UI), `9042` (Cassandra), `9090` (Prometheus), `3000` (Grafana).
+
+</details>
+
+<details>
+<summary>Reset everything</summary>
+
+```bash
+docker-compose down
+docker ps -a  # check for leftover containers
+docker rm <container_id>  # remove if needed
+```
+
+Verify with `docker ps` and visit [http://localhost:8088](http://localhost:8088).
+
+</details>
+
 ## 📚 Sample Categories
 
 ### Table of Contents

config/development.yaml

@@ -1,5 +1,5 @@
 # config for sample
-domain: "default"
+domain: "cadence-samples"
 service: "cadence-frontend"
 host: "localhost:7833"
 # config for emitting metrics

new_samples/README.md

@@ -33,43 +33,41 @@ cadence --env development \
 Try to inspect the log message for the output.
 
 ### Signal Workflow
-This workflow demonstrate a basic signal workflow. It takes your name as input parameter
-and greet you based on languages you pick. To start the workflow, try the following CLI.
+This workflow demonstrates a basic signal workflow. It waits for a signal to complete.
+To start the workflow, try the following CLI.
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
   workflow start \
-  --workflow_type cadence_samples.SignalGreeterMultiLanguageWorkflow \
+  --workflow_type cadence_samples.SimpleSignalWorkflow \
   --tl cadence-samples-worker \
-  --et 6000 \
-  --input '{"name":"Uber"}'
+  --et 600
 ```
 
-A workflow ID and run ID will be return in your terminal. Copy the workflow ID and replace
-to the CLI below to trigger the signal. Try to change the input language value and inspect what
-happens in the log. Also, try to inspect what happened after you interact with the signal multiple times.
+A workflow ID and run ID will be returned in your terminal. Copy the workflow ID and use
+the CLI below to send a signal. The workflow will continue running until it receives a
+`complete` signal with the value `true`.
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
   workflow signal \
-  --workflow_id <Your workflow ID> \
-  --name "language" \
-  --input '"english"'
+  --wid <Your workflow ID> \
+  --name "complete" \
+  --input 'false'
 ```
 
-To cancel the workflow, try the following CLI.
+To complete the workflow, send the signal with `true`:
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
   workflow signal \
-  --workflow_id <Your workflow ID> \
-  --name "cancel" \
+  --wid <Your workflow ID> \
+  --name "complete" \
   --input 'true'
 ```
-The workflow should have a status of fail.
 
 ### Dynamic workflow
 This dynamic workflow is very similar to the Hello World workflow above, but instead of passing the

new_samples/workflows/dynamic_workflow.go renamed to new_samples/activities/dynamic_workflow.go

@@ -43,6 +43,14 @@ cadence --env development \
   --input '{"message":"Cadence"}'
 ```
 
+You should see output like this:
+
+![Trigger command output](images/02-trigger-command-started-workflow.png)
+
+And the worker will log the completed workflow:
+
+![Worker output showing workflow completed](images/01-worker-output-workflow-completed.png)
+
 Here are the details to this command:
 
 * `--domain` option describes under which domain to run this workflow
@@ -60,24 +68,33 @@ To see more options run `cadence --help`
 
 Click on `cadence-samples` domain in cadence-web to view your workflow.
 
+![Workflow list showing completed workflow](images/03-web-ui-workflow-list-completed.png)
+
+Click on the workflow to see details:
+
 * In Summary tab, you will see the input and output to your workflow
-* Click on History tab to see individual steps.
+
+![Summary tab](images/04-web-ui-summary-tab.png)
+
+* Click on History tab to see individual steps. Expand an activity to see its result:
+
+![History tab with activity result](images/05-web-ui-history-activity-result.png)
 
 #### CLI
 
 List workflows using the following command:
 
 ```bash
- cadence --env development --domain cadence-samples --workflow list
+cadence --env development --domain cadence-samples workflow list
 ```
 
 You can view an individual workflow by using the following command:
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow describe \
- --wid <workflow_id>
+  workflow describe \
+  --wid <workflow_id>
 ```
 
 * `workflow` is the noun to run commands within workflow scope
@@ -90,10 +107,18 @@ To view the entire history of the workflow, use the following command:
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow show \
- --wid <workflow_id>
+  workflow show \
+  --wid <workflow_id>
 ```
 
+## Troubleshooting
+
+If you see port conflicts when starting Docker, use `lsof` to find what's using the port:
+
+![Docker port conflict troubleshooting](images/06-docker-port-conflict-troubleshooting.png)
+
+See the main [README](../../README.md#docker-troubleshooting) for detailed Docker troubleshooting steps.
+
 ## References
 
 * The website: https://cadenceworkflow.io

new_samples/workflows/parallel_pick_first_workflow.go renamed to new_samples/activities/parallel_pick_first_workflow.go

@@ -37,16 +37,16 @@ Click on `cadence-samples` domain in cadence-web to view your workflow.
 List workflows using the following command:
 
 ```bash
- cadence --env development --domain cadence-samples --workflow list
+cadence --env development --domain cadence-samples workflow list
 ```
 
 You can view an individual workflow by using the following command:
 
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow describe \
- --wid <workflow_id>
+  workflow describe \
+  --wid <workflow_id>
 ```
 
 * `workflow` is the noun to run commands within workflow scope
@@ -59,6 +59,6 @@ To view the entire history of the workflow, use the following command:
 ```bash
 cadence --env development \
   --domain cadence-samples \
-  --workflow show \
- --wid <workflow_id>
+  workflow show \
+  --wid <workflow_id>
 ```