docs: improve architecture diagram readability

[zywind]

Summary

• reorganize the high-level Mermaid overview into vertically separated architectural stages
• connect stages at their boundaries with labeled handoffs and place reporting after evaluation results

Test plan

• mise run format-check
• verify through the local MkDocs live-reload server

Summary by CodeRabbit

• Documentation
  • Updated the architecture diagram to present the pipeline flow more clearly.
  • Added labeled connections showing how configuration, data processing, training, generation, evaluation, and reporting relate to one another.
  • Improved diagram rendering and display settings.

[coderabbitai]

Walkthrough

The architecture documentation now configures Mermaid rendering through an HTML wrapper and explicit initialization settings. Its diagram wiring was revised across configuration, training, generation, evaluation, reporting, and the end-to-end pipeline.

Changes

Architecture Diagram Documentation

Layer / File(s)	Summary
Explicit diagram rendering docs/developer-guide/architecture.md	The architecture diagram is wrapped in an architecture-diagram HTML container and given explicit Mermaid initialization settings.
Architecture flow wiring docs/developer-guide/architecture.md	Entry-point, backend, generation, evaluation, reporting, and labeled end-to-end pipeline connections are revised.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Suggested labels: docs

Suggested reviewers: binaryaaron

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the docs architecture diagram readability improvements in this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yz/docs-readable-architecture

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

This PR updates the high-level architecture Mermaid diagram in docs/developer-guide/architecture.md to replace fine-grained cross-subgraph node edges with subgraph-level stage boundary connections, reducing visual clutter and making the pipeline flow easier to follow.

• Five node-level inter-stage edges (CLI → ConfigBuilder, SDK → ConfigBuilder, Assembler → TrainingBackendBase, HFBackend → GenBackend, VLLMBackend → EvaluatorComp, EvaluatorComp → ReportGen) are removed and replaced with six labelled subgraph-to-subgraph arrows that trace the end-to-end pipeline at a higher level of abstraction.
• The evaluationComponents → reporting edge correctly positions the reporting sub-stage after evaluation results flow through the system, consistent with the execution sequence diagram already in the file.

Confidence Score: 5/5

Documentation-only change to a single Mermaid diagram; no executable code is touched.

The change only modifies diagram edge definitions in a Markdown file. It trades individual cross-subgraph node edges for cleaner subgraph-to-subgraph stage arrows, which is consistent with the execution sequence diagram already in the file. No logic, configuration, or runtime behaviour is affected.

No files require special attention.

Important Files Changed

Filename	Overview
docs/developer-guide/architecture.md	High-level Mermaid diagram refactored to use subgraph-level stage edges instead of individual cross-subgraph node edges, improving readability; no logic or code changes.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant EP as Entry Points (CLI/SDK)
    participant CL as Config Layer
    participant DP as Data Processing
    participant TB as Training Backend
    participant GB as Generation Backend
    participant ES as Evaluation System
    participant RP as Reporting

    EP->>CL: invocation
    CL->>DP: configuration
    DP->>TB: training examples
    TB->>GB: adapter
    GB->>ES: synthetic records
    ES->>RP: results

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant EP as Entry Points (CLI/SDK)
    participant CL as Config Layer
    participant DP as Data Processing
    participant TB as Training Backend
    participant GB as Generation Backend
    participant ES as Evaluation System
    participant RP as Reporting

    EP->>CL: invocation
    CL->>DP: configuration
    DP->>TB: training examples
    TB->>GB: adapter
    GB->>ES: synthetic records
    ES->>RP: results

Loading

_{Reviews (2): Last reviewed commit: "docs: use responsive architecture overvi..." | Re-trigger Greptile}