[Update]: workflow documentation for better clarity and system understanding#95
Merged
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
WalkthroughThis pull request restructures workflow documentation by replacing an embedded diagram and overview in the README with a direct link, while expanding Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/workflow.md`:
- Line 12: The workflow images lack alt text; update each <img
src="../public/assets/workflows/connect.png" /> and the seven other workflow
<img> tags to include descriptive alt attributes as suggested (e.g.,
alt="Workflow diagram for creating DIT token using the platform UI",
alt="Workflow diagram for creating DIT token via direct smart contract
interaction", alt="Internal flow diagram showing backend token creation
process", alt="Workflow diagram for fetching token metadata using token URI",
alt="Workflow diagram showing the endorsement process", alt="Workflow diagram
showing the un-endorsement process", alt="Workflow diagram for auto-fetching
metadata via token URI") so screen readers can describe each diagram for
accessibility compliance.
- Around line 1-87: Add a "Related Resources" section to the WORKFLOWS document
that links to the contract repository's workflow docs so readers get end-to-end
coverage; specifically, append a new section with a separator and a heading like
"🔗 Related Resources" and include a bullet/link to the Contract Repository
Workflows (the Contract Repository workflows URL from Issue `#91` / PR
description) so developers can navigate from the "WORKFLOWS" doc to the contract
workflows.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: e70b4f68-aa99-4eaa-826c-203d34463b46
⛔ Files ignored due to path filters (9)
public/assets/workflows/Internal-flow-create.pngis excluded by!**/*.pngpublic/assets/workflows/connect.pngis excluded by!**/*.pngpublic/assets/workflows/create-token .pngis excluded by!**/*.pngpublic/assets/workflows/create-token-N.pngis excluded by!**/*.pngpublic/assets/workflows/create-token.pngis excluded by!**/*.pngpublic/assets/workflows/endorsement-flow.pngis excluded by!**/*.pngpublic/assets/workflows/fetch-token-metadata.pngis excluded by!**/*.pngpublic/assets/workflows/tokenUri.pngis excluded by!**/*.pngpublic/assets/workflows/unEndorsement-flow.pngis excluded by!**/*.png
📒 Files selected for processing (2)
README.mddocs/workflow.md
Comment on lines
+1
to
+87
| # 📘 WORKFLOWS | ||
|
|
||
|  | ||
| This document provides an overview of all major workflows in the system. Each section includes a brief explanation and a visual diagram to help you quickly understand how different parts of the platform interact. | ||
|
|
||
| ## Overview | ||
| --- | ||
|
|
||
| - **Self-issued identity token minting:** Users create and mint their own identity tokens, optionally attaching metadata. No central issuer is required. | ||
| ## 🔗 Connect Wallet | ||
|
|
||
| - **On-chain identity storage:** Identity tokens and their metadata are stored on-chain (e.g. as ERC-721 NFTs), providing a portable, verifiable record. | ||
| This is the entry point for users. By connecting a wallet, users can securely interact with the platform, sign transactions, and access features like token creation and endorsements. | ||
|
|
||
| - **Endorsement by other identity holders:** Holders of identity tokens can endorse other identities on-chain, building a graph of attestations and trust. | ||
| <p align="center"> | ||
| <img src="../public/assets/workflows/connect.png" width="600"/> | ||
| </p> | ||
|
|
||
| - **Optional revocation:** Endorsements or credentials can support revocation (e.g. via a registry or expiry), so trust can be updated or withdrawn when needed. | ||
| --- | ||
|
|
||
| - **Frontend reading on-chain data:** The frontend reads identity and endorsement data from the chain (e.g. via RPC and events) to display profiles, endorsements, and status. | ||
| ## 🪙 Create DIT Token (Using Platform) | ||
|
|
||
| - **External services verifying identity:** Third-party services can verify identity and endorsements by reading the same on-chain data, enabling use cases like access control or credential checks without relying on the frontend alone. | ||
| Users can create a DIT token through a simple and guided UI. The platform handles contract interaction, metadata setup, and transaction flow, making it beginner-friendly. | ||
|
|
||
| <p align="center"> | ||
| <img src="../public/assets/workflows/create-token.png" width="600"/> | ||
| </p> | ||
|
|
||
| --- | ||
|
|
||
| ## ⚙️ Create DIT Token (Without Platform) | ||
|
|
||
| This workflow is for advanced users who prefer direct interaction with smart contracts. It involves manually calling contract functions and handling parameters without the platform UI. | ||
|
|
||
| <p align="center"> | ||
| <img src="../public/assets/workflows/create-token-N.png" width="600"/> | ||
| </p> | ||
|
|
||
| --- | ||
|
|
||
| ## 🔄 Internal Flow for Token Creation | ||
|
|
||
| This flow explains what happens behind the scenes when a token is created — including contract deployment/interactions, metadata linking, and backend processes (if any). | ||
|
|
||
| <p align="center"> | ||
| <img src="../public/assets/workflows/Internal-flow-create.png" width="600"/> | ||
| </p> | ||
|
|
||
| --- | ||
|
|
||
| ## 📦 Fetch Token Metadata | ||
|
|
||
| This workflow shows how token metadata is retrieved using the token URI. It includes fetching details like title, description, and other attributes stored off-chain or on-chain. | ||
|
|
||
| <p align="center"> | ||
| <img src="../public/assets/workflows/fetch-token-metadata.png" width="600"/> | ||
| </p> | ||
|
|
||
| --- | ||
|
|
||
| ## 👍 Endorsement Flow | ||
|
|
||
| Users can endorse a token to validate or support it. This process includes wallet confirmation, on-chain verification, and updating the endorsement state. | ||
|
|
||
| <p align="center"> | ||
| <img src="../public/assets/workflows/endorsement-flow.png" width="600"/> | ||
| </p> | ||
|
|
||
| --- | ||
|
|
||
| ## 🔄 Un-Endorsement Flow | ||
|
|
||
| This flow allows users to remove their endorsement. It ensures proper validation and updates the blockchain state accordingly while maintaining data integrity. | ||
|
|
||
| <p align="center"> | ||
| <img src="../public/assets/workflows/unEndorsement-flow.png" width="600"/> | ||
| </p> | ||
|
|
||
| --- | ||
|
|
||
| ## 🔍 Auto-fetch Metadata via Token URI | ||
|
|
||
| Wallets and applications can automatically fetch token metadata using the token URI. This improves usability by displaying token details without manual input. | ||
|
|
||
| <p align="center"> | ||
| <img src="../public/assets/workflows/tokenUri.png" width="600"/> | ||
| </p> | ||
|
|
||
| --- | ||
|
|
||
| > 💡 These workflows provide a clear understanding of how users and the system interact, covering both user-facing actions and internal processes. |
Contributor
There was a problem hiding this comment.
Missing link to contract repository workflows as stated in PR objectives.
Issue #91 and the PR description specifically mention including a reference or link to the contract repository workflows to enable end-to-end understanding of the system. This deliverable appears to be missing from the updated documentation.
Consider adding a section (perhaps at the end or beginning) that links to the contract repository's workflow documentation for developers who need the complete picture.
📎 Suggested addition
Add a new section near the end of the document:
---
## 🔗 Related Resources
For a complete end-to-end understanding of the system, including smart contract workflows and backend processes, please refer to:
👉 [Contract Repository Workflows](https://github.com/StabilityNexus/IdentityTokens-EVM-Contracts/blob/main/docs/workflow.md)
---🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 12-12: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 22-22: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 32-32: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 42-42: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 52-52: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 62-62: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 72-72: Images should have alternate text (alt text)
(MD045, no-alt-text)
[warning] 82-82: Images should have alternate text (alt text)
(MD045, no-alt-text)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/workflow.md` around lines 1 - 87, Add a "Related Resources" section to
the WORKFLOWS document that links to the contract repository's workflow docs so
readers get end-to-end coverage; specifically, append a new section with a
separator and a heading like "🔗 Related Resources" and include a bullet/link to
the Contract Repository Workflows (the Contract Repository workflows URL from
Issue `#91` / PR description) so developers can navigate from the "WORKFLOWS" doc
to the contract workflows.
|
|
||
| - **Endorsement by other identity holders:** Holders of identity tokens can endorse other identities on-chain, building a graph of attestations and trust. | ||
| <p align="center"> | ||
| <img src="../public/assets/workflows/connect.png" width="600"/> |
Contributor
There was a problem hiding this comment.
Add alt text to all workflow diagrams for accessibility compliance.
All eight workflow images are missing alt text, which prevents screen readers from describing these diagrams to visually impaired users. This is a WCAG accessibility violation that blocks users with visual disabilities from understanding the documented workflows.
♿ Proposed fix to add descriptive alt text
<p align="center">
- <img src="../public/assets/workflows/connect.png" width="600"/>
+ <img src="../public/assets/workflows/connect.png" alt="Workflow diagram showing wallet connection process" width="600"/>
</p>Apply similar descriptive alt text to all other images:
- Line 22:
alt="Workflow diagram for creating DIT token using the platform UI" - Line 32:
alt="Workflow diagram for creating DIT token via direct smart contract interaction" - Line 42:
alt="Internal flow diagram showing backend token creation process" - Line 52:
alt="Workflow diagram for fetching token metadata using token URI" - Line 62:
alt="Workflow diagram showing the endorsement process" - Line 72:
alt="Workflow diagram showing the un-endorsement process" - Line 82:
alt="Workflow diagram for auto-fetching metadata via token URI"
Also applies to: 22-22, 32-32, 42-42, 52-52, 62-62, 72-72, 82-82
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)
[warning] 12-12: Images should have alternate text (alt text)
(MD045, no-alt-text)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/workflow.md` at line 12, The workflow images lack alt text; update each
<img src="../public/assets/workflows/connect.png" /> and the seven other
workflow <img> tags to include descriptive alt attributes as suggested (e.g.,
alt="Workflow diagram for creating DIT token using the platform UI",
alt="Workflow diagram for creating DIT token via direct smart contract
interaction", alt="Internal flow diagram showing backend token creation
process", alt="Workflow diagram for fetching token metadata using token URI",
alt="Workflow diagram showing the endorsement process", alt="Workflow diagram
showing the un-endorsement process", alt="Workflow diagram for auto-fetching
metadata via token URI") so screen readers can describe each diagram for
accessibility compliance.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addressed Issues:
Fixes #91
Changes Made:
Check one of the checkboxes below:
Checklist
@KanishkSogani
Summary by CodeRabbit