AOSSIE-Org / AOSSIE-Org/PictoPy

Docs: Interactive/clickable architecture diagram on the Architecture page

未关闭
#1,359 5 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
documentation
主要语言
Python
星标
283
派生
679
平均合并
7 天 2 小时
30 天内合并 PR
3

描述

### Describe the feature

### Is this related to a problem?
Not a bug — this is a documentation/UX enhancement request.

### Describe the feature
PictoPy has a genuinely non-trivial multi-service architecture: a Tauri/React frontend, a Rust backend layer, a Python (FastAPI) backend for AI/image processing, and a separate sync-microservice. Currently, the Architecture page on the docs site (https://aossie-org.github.io/PictoPy/overview/architecture/) explains this as static text/description.

I'd like to propose replacing (or supplementing) this with an **interactive, clickable architecture diagram** where each major component is a clickable node:

- Frontend (Tauri/React)
- Rust Backend
- Python Backend (FastAPI)
- Sync-Microservice

Clicking a node would either:
- Expand an inline summary of that component's responsibilities directly on the diagram, or
- Jump/link to that component's dedicated docs section (e.g. clicking "Python Backend" navigates to the Python Backend API page)

### Why this is useful
- New contributors (like myself) currently have to read through several separate doc pages to piece together how the services communicate. A single interactive diagram gives an at-a-glance mental model before diving into details.
- Material for MkDocs supports Mermaid diagrams natively, so this can likely be done with minimal tooling overhead — no need for custom JS frameworks.
- Makes the docs site feel more like an onboarding tool and less like a flat reference.

### Proposed implementation approach
1. Enable Mermaid diagram support in `mkdocs.yml` (via `pymdownx.superfences` custom fence for Mermaid), if not already enabled.
2. Build a flowchart/graph diagram representing the 4 components and their communication paths (e.g. Frontend ↔ Rust Backend ↔ Python Backend ↔ Sync-Microservice).
3. Use Mermaid's clickable node syntax (`click NodeName "url" "tooltip"`) to link each node to its corresponding docs page.
4. Fallback: if click-to-expand inline is preferred over navigation, this could instead be built as a small custom HTML/JS component embedded in the page.

### Scope
This is a documentation-site-only change — no impact on the actual application code, frontend, or backend.

### Additional context
I'm happy to work on this if the general direction (Mermaid diagram with clickable nodes linking to existing doc pages) sounds good to maintainers. Open to adjusting the approach based on feedback — e.g., if a more custom interactive component is preferred over Mermaid.

### Add ScreenShots

@rohan-pandeyy i would like to woork on this feture please confirm it so that i can raise PR

### Record

- [x] I agree to follow this project's Code of Conduct
- [x] I want to work on this issue

贡献指南

打开贡献指南

评估

这个 Issue 还没有评估数据。

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。