asyncapi
Codebase refactoring and cleanup + documentation update
Title: 📚 Update CLI Documentation to Reflect New Architecture, Debugging, and Testing Procedures
Description
The architecture of the AsyncAPI CLI has recently undergone major changes, including the addition and update of commands, as well as improvements in services and APIs. As a result, the existing documentation is outdated and lacks essential information around debugging, testing, and understanding the CLI’s flow.
Many contributors have faced difficulties navigating these changes and contributing effectively. Updating the documentation will help provide clarity, improve debugging workflows, and onboard new contributors more smoothly.
✅ Tasks
-
[ ] Update the AsyncAPI CLI Introduction section with diagrams Include explanations and visuals of new and updated commands.
-
[ ] Document the updated CLI architecture [ Need to write again from scratch ] Explain services, APIs, interactions, and workflows with diagrams and examples and the Server API concept : )
-
[ ] Revise the usage documentation Update CLI Usage
-
[ ] Updater Documentation with new commands, flags, and parameters.
-
[ ] Add debugging steps [ Debugging and writing test cases are very hard ] Provide step-by-step debugging and testing guidelines across all services and APIs.
-
[ ] Document best practices for contributing via PRs Provide a checklist and guidelines to help contributors submit high-quality pull requests.
-
[ ] Codebase Refraction and Cleanup
-
[ ] Outline future requirements and scope Add notes about upcoming improvements, feature requests, and areas open for contribution.
📦 Additional Context
- Updating this documentation will:
- Reduce confusion and troubleshooting time.
- Improve contributor experience.
- Help onboard new contributors faster.
- Encourage consistent and high-quality contributions.
✅ Code of Conduct
I agree to follow this project's Code of Conduct.
🚀 Are you willing to work on this issue?
Yes, I am willing to submit a PR and collaborate with the team!
Let me know if you want it formatted as a GitHub issue template (.github/ISSUE_TEMPLATE/cli-docs-update.md) so it can be reused in the repository.
@Shurtu-gal @Souvikns Putting this for bounty willing to work : ) @neoandmatrix you can also suggest as well : )
I guess it is already being worked on by @Souvikns under https://github.com/asyncapi/cli/pull/1802. We had discussed this in a meet as well.
Do we need to put this for bounty? My proposal: onboard someone with good experience with docs and slowly show them the ins and outs, paving the path for a docs maintainer here as well.
I guess it is already being worked on by @Souvikns under #1802. We had discussed this in a meet as well.
Do we need to put this for bounty? My proposal: onboard someone with good experience with docs and slowly show them the ins and outs, paving the path for a docs maintainer here as well.
@Shurtu-gal I have good experience in writing the docs, i will write it properly as also we need to cover the CLI internals as well, I have already put this in the bounty will work on this : )
@AayushSaini101, could you please compare the approximate amount of future work to this PR of Medium level? Would it still remain Advanced?
@AayushSaini101, could you please compare the approximate amount of future work to this PR of
Mediumlevel? Would it still remainAdvanced?
@aeworxet which PR is this https://github.com/asyncapi/community/pull/1894/files ?
@AayushSaini101
It was misperformed at the time, but it was still classified as Medium at the time of submission, so to keep estimates accurate I am assessing whether the amount of work on this issue exceeds that.
@AayushSaini101 It was misperformed at the time, but it was still classified as
Mediumat the time of submission, so to keep estimates accurate I am assessing whether the amount of work on this issue exceeds that.
We can consider as advanced because there are various part we need to perform in this issue
@thulieblack
Could you please assess the amount of work this issue would require? Would it fit the Advanced definition?
In fact, is it even Medium, and should it be submitted to the Bounty Program at all?
Hey, I have to agree with Ashish here https://github.com/asyncapi/cli/issues/1853#issuecomment-3278953912 this is a regular docs issue any contributor can do.
But if it really needs to be under the Bounty, then I suggest creating an outline and scope for the issue to justify why it isn't a regular docs issue but should be for Bounty.
@thulieblack @aeworxet @Shurtu-gal please review i have added some major improvements : )
This looks good to me. In addition to the documentation updates, I think the codebase could also benefit from some maintenance, developer experience (DX) improvements, and general cleanup. It might be better to frame this issue as a broader code cleanup and refactoring effort, with the documentation updates forming just one part of the overall scope.
Let me know your thoughts @AayushSaini101
This looks good to me. In addition to the documentation updates, I think the codebase could also benefit from some maintenance, developer experience (DX) improvements, and general cleanup. It might be better to frame this issue as a broader code cleanup and refactoring effort, with the documentation updates forming just one part of the overall scope.
Let me know your thoughts @AayushSaini101
yes, indeed we need benefit from some maintenance, developer experience (DX) improvements, and general cleanup and the next mentorship of the AsyncAPI, we are planning to introduce a project also in the next mentorship of the AsyncAPI, we are planning to introduce project that give us more clarity about the usage of the commands cc: @AceTheCreator @Souvikns @Amzani
Since refactors and cleanups are now expected, should the issue type be changed to Coding and the title to something like Codebase refactoring and cleanup + documentation update?
Since refactors and cleanups are now expected, should the issue type be changed to
Codingand the title to something likeCodebase refactoring and cleanup + documentation update?
updated thanks we will do some Codebase refactoring and cleanup as well, i am changing issue type to coding
@AayushSaini101, in the future, please consult and discuss the scope and implementation approaches with other maintainers prior to submitting the GitHub issue to the Bounty Program. The behavior of notifying other maintainers after the fact is beginning to show signs of being systemic.
Bounty Issue's service comment
Text labels: bounty/2025-Q4, bounty/advanced, bounty/coding
First assignment to regular contributors: 2025-09-19 00:00:00 UTC+12:00
End Of Life after: 2025-10-31 23:59:59 UTC-12:00
@asyncapi/bounty_team
The Bounty Program is not a Mentorship Program. The accepted level of Bounty Program Participants is Middle/Senior.
Regular contributors should explain in meaningful words how they are going to approach the resolution process when expressing a desire to work on this Bounty Issue.
Following the expression of desire to work on this Bounty Issue, @AayushSaini101 (githubID: 60972989) is an AsyncAPI Maintainer specified in the file https://github.com/asyncapi/community/blob/master/MAINTAINERS.yaml, so they fall under the first category in the prioritization list.
Bounty Issue's Timeline
| Complexity Level | Assignment Date (by GitHub) | Start Date (by BP Rules) | End Date (by BP Rules) | Draft PR Submission | Final PR Merge Start | Final PR Merge End |
|---|---|---|---|---|---|---|
| Advanced | 2025-09-16 | 2025-10-06 | 2025-11-30 | 2025-10-26 | 2025-11-16 | 2025-11-30 |
Please note that the dates given represent deadlines, not specific dates; so if the goal is reached sooner, it's better.
Keep in mind the responsibility for violations of the Timeline.
Assignee: @AayushSaini101 (githubID: 60972989)
Edit: rephrased to sound less confrontational, sorry
Maybe it's useful to have a list of parts I would refactor in cli/src/domain/models/{Preview,Studio}:
- Duplication between Preview and Studio:
server.listen()code,wsServercode - Large functions with deep nesting are hard to follow - can be split
-
wsServer.on('close', () => { ... })code should actually be added onsocket.on('close')- 'close' on server is triggered when the server is closed, not the client -
new WebSocketServer({ noServer: true })maybe can be replaced withnew WebSocketServer({ server, path }), saving manual HTTP handler code. Haven't looked in detail -
messageQueueseems unused: everymessageQueue.push()is followed bysendQueuedMessages(), which synchronously does.messageQueue.shift()and broadcasts the message
@AayushSaini101 (
githubID: 60972989), please provide the Draft PR of the Bounty Issue.
Done thanks : )
@aeworxet . Can we extend the bounty issue timeline for 2 weeks? I will be travelling to a conference.
Upon request of the AsyncAPI Maintainer, who is responsible for the resolution of the Bounty Issue from the AsyncAPI's side and is also the Bounty Program Participant (@AayushSaini101 (githubID: 60972989)), all remaining target dates of the Bounty Issue's Timeline are extended by two calendar weeks.
Bounty Issue's Timeline Extended
| Complexity Level | Assignment Date (by GitHub) | Start Date (by BP Rules) | End Date (by BP Rules) | Draft PR Submission | Final PR Merge Start | Final PR Merge End |
|---|---|---|---|---|---|---|
| Advanced | 2025-09-16 | 2025-10-06 | 2025-12-14 | 2025-10-26 | 2025-11-30 | 2025-12-14 |
Please note that the dates given represent deadlines, not specific dates; so if the goal is reached sooner, it's better.
Keep in mind the responsibility for violations of the Timeline.
Assignee: @AayushSaini101 (githubID: 60972989)
@aeworxet can we extend this by 2 weeks final, i am not feeling well and need to move out of the station. Thanks for the support
Upon request of the AsyncAPI Maintainer, who is responsible for the resolution of the Bounty Issue from the AsyncAPI's side and is also the Bounty Program Participant (@AayushSaini101 (githubID: 60972989)), all remaining target dates of the Bounty Issue's Timeline are extended by two calendar weeks.
Bounty Issue's Timeline Extended
| Complexity Level | Assignment Date (by GitHub) | Start Date (by BP Rules) | End Date (by BP Rules) | Draft PR Submission | Final PR Merge Start | Final PR Merge End |
|---|---|---|---|---|---|---|
| Advanced | 2025-09-16 | 2025-10-06 | 2025-12-28 | 2025-10-26 | 2025-11-30 | 2025-12-28 |
Please note that the dates given represent deadlines, not specific dates; so if the goal is reached sooner, it's better.
Keep in mind the responsibility for violations of the Timeline.
Assignee: @AayushSaini101 (githubID: 60972989)