DOC: Visual & Structural Improvements (Multi-assignable issue)

[rohan-pandeyy]

Description

This issue acts as a parent tracker for ongoing documentation improvements across the project.

The focus is to transition from primarily text-heavy documentation to visual, structured, and intuitive documentation that helps contributors and users quickly understand the system.

Motivation

While the current documentation provides useful information, much of it is heavily text-based. This makes it harder to grasp complex concepts such as system architecture, backend workflows, and data flow.

Improving documentation with visuals and better structure will:

• Make onboarding smoother for new contributors
• Help users understand features and workflows faster
• Improve overall readability and navigation
• Make the project feel more polished and approachable

Tasks in hand

• README enhancements: (PR: Refactor README structure for improved readability and maintainability #1258)
  • Add visuals such as header/banner and feature screenshots
  • Improve structure and overall presentation
  • Add High-Level Architecture (HLA)
  
• Backend & API Documentation
  • API request/response flow diagrams
  • Service interaction maps
  • Explanation of backend logic through visuals
• Rust Layer / Processing Layer
  • Visual explanation of how the Rust layer integrates with the system
  • Processing pipelines and performance-related flows

and many more (this issue is open for suggestions in the comment section below)

Record

• I agree to follow this project's Code of Conduct
• I want to work on this issue

[github-actions]

👋 Thanks for opening this issue! The maintainers will review it shortly. Till then, do not open any PR. This is a strict rule we like to follow around here :)

[santhosh-7777]

@rohan-pandeyy i would like to work on this if this issue is open?

[MrKing2023]

Hi! I would like to work on a small part of this documentation improvement issue.

I noticed that the Architecture page is currently text-heavy and not included in the MkDocs navigation. I can submit a small docs-only PR that:

• adds a concise component overview table
• adds a high-level local processing/data flow
• clarifies the local-first privacy boundary
• adds the Architecture page to the docs navigation

I will keep the change scoped to documentation only. Please let me know if this direction is acceptable before I open a PR.

[Awaneesh03]

Hi @rohan-pandeyy, I’d like to work on a small documentation improvement for this issue.

I plan to improve the Architecture documentation by:

• improving readability and structure
• adding clearer headings/bullets
• adding a concise component overview table (if appropriate)

Please let me know if this scope is okay before I open a PR.

[rohan-pandeyy]

Thanks for the interest everyone! Since this is a parent tracking issue and also multi-assignable, We want to avoid overlap/conflicting PRs.

Please mention exactly which documentation area/subtask you want to work on before opening a PR. Try to keep the scope focused and reasonably small rather than taking the entire documentation overhaul in one go.

For example, the previously merged PR (#1258) was specifically scoped to README improvements and architecture additions.

Current proposals so far:

• @santhosh-7777 → Please specify the exact section/task you want to improve.

• @MrKing2023 → Your proposed scope looks good. Please limit the PR specifically to:

  • Architecture page improvements
  • Component overview table has already been implemented within a previous PR (refer
  • Local processing/data flow visuals
  • MkDocs navigation integration

• @Awaneesh03 → Your proposal overlaps a bit with the architecture improvements already mentioned above. Please narrow it down further and specify which exact subsection or improvement you would like to handle to avoid duplication.

In general:

• One focused docs improvement per PR is preferred
• Avoid large “complete documentation rewrite” PRs
• Please comment your intended scope first so work can be coordinated properly

Once that's done, I'll assign each one of you the issue for your respective proposed changes.

[Awaneesh03]

Hi @rohan-pandeyy, I’d like to take the MkDocs navigation integration part of this issue.

My scope will be limited to:

• checking if the Architecture page is properly included in MkDocs navigation
• adding/fixing navigation entries if missing
• improving navigation clarity without changing broader documentation content

Please let me know if this scope works, and I can proceed with a focused PR.

Thanks for the interest everyone! Since this is a parent tracking issue and also multi-assignable, We want to avoid overlap/conflicting PRs.

Please mention exactly which documentation area/subtask you want to work on before opening a PR. Try to keep the scope focused and reasonably small rather than taking the entire documentation overhaul in one go.

For example, the previously merged PR (#1258) was specifically scoped to README improvements and architecture additions.

Current proposals so far:

• @santhosh-7777 → Please specify the exact section/task you want to improve.

• @MrKing2023 → Your proposed scope looks good. Please limit the PR specifically to:

  • Architecture page improvements
  • Component overview table has already been implemented within a previous PR (refer
  • Local processing/data flow visuals
  • MkDocs navigation integration

• @Awaneesh03 → Your proposal overlaps a bit with the architecture improvements already mentioned above. Please narrow it down further and specify which exact subsection or improvement you would like to handle to avoid duplication.

In general:

• One focused docs improvement per PR is preferred
• Avoid large “complete documentation rewrite” PRs
• Please comment your intended scope first so work can be coordinated properly

Once that's done, I'll assign each one of you the issue for your respective proposed changes.

[Awaneesh03]

Hi @rohan-pandeyy, I’d like to take the MkDocs navigation integration part of this issue.

My scope will be limited to:

• checking if the Architecture page is properly included in MkDocs navigation
• adding/fixing navigation entries if missing
• improving navigation clarity without changing broader documentation content

Please let me know if this scope works, and I can proceed with a focused PR.