AOSSIE-Org / AOSSIE-Org/PictoPy

Docs: Interactive/clickable architecture diagram on the Architecture page

Abierto
#1,359 5 comentarios 0 reacciones 0 asignados Ver en GitHub
documentation
Lenguaje dominante
Python
Estrellas
283
Forks
679
Merge medio
7 d 2 h
PR fusionados (30 d)
3

Descripción

### 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

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.