# xuxian2102/cloudstack architecture

> Architecture diagram of the GitHub repository xuxian2102/cloudstack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xuxian2102/cloudstack
- Repository: https://github.com/xuxian2102/cloudstack

## Overview

CloudStack is a native GTK4 Markdown editor for local Wayland use. Its main workflow is to open a project, edit an article and its frontmatter, preview rendered Markdown, manage colocated images, then selectively commit and synchronize project content through Git. The graph separates the GTK interface, application workflow/state coordination, core project and file services, and static rendering. Several subsystem paths and capabilities come from the README and tree; unsampled wiring is omitted where it cannot be established from excerpts.

Main entry points: [`crates/cloudstack-gtk/src/window.rs`](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window.rs) (Editor window), [`crates/cloudstack-application/src/workspace.rs`](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/workspace.rs) (Workspace lifecycle), [`crates/cloudstack-core/src/services/git.rs`](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/git.rs) (Git operations), [`crates/cloudstack-core/src/services/posts.rs`](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/posts.rs) (Article operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["GTK interface"]
  node_gtk_app["GTK application<br/>[main.rs]"]
  node_window["Editor window<br/>[window.rs]"]
  node_article_ui["Article controls<br/>[articles.rs]"]
  node_frontmatter_ui["Frontmatter drawer<br/>[frontmatter.rs]"]
  node_publish_ui["Publish dialog<br/>[publish.rs]"]
  node_git_ui["Git panel<br/>[git_panel.rs]"]
  node_preview_ui["WebKit preview<br/>[preview.rs]"]
  node_search_ui["Find and replace<br/>[search.rs]"]
  node_tasks["Background tasks<br/>[tasks.rs]"]
end

subgraph group_app["Application workflows"]
  node_workspace["Workspace lifecycle<br/>[workspace.rs]"]
  node_session["Edit session state<br/>[session.rs]"]
  node_save["Save workflow<br/>[save.rs]"]
  node_drafts["Draft recovery<br/>[coordinator.rs]"]
  node_preview_coord["Preview scheduling<br/>[preview.rs]"]
  node_publish["Publish workflow<br/>[publish.rs]"]
  node_git_app["Git workflow<br/>[git.rs]"]
end

subgraph group_core["Core services"]
  node_project_service["Project configuration<br/>[project.rs]"]
  node_posts_service["Article operations<br/>[posts.rs]"]
  node_frontmatter_service["Frontmatter parsing<br/>[frontmatter.rs]"]
  node_assets_service["Local image assets<br/>[assets.rs]"]
  node_git_service["Git operations<br/>[git.rs]"]
  node_markdown_service["Markdown parsing<br/>[markdown.rs]"]
end

subgraph group_render["Preview rendering"]
  node_renderer["Markdown and KaTeX<br/>[lib.rs]"]
end

node_user(("Editor user"))
node_project_files[("Local project files")]
node_git_remote["Git remote"]
node_github_cli["GitHub CLI"]

node_user -->|"opens and edits"| node_gtk_app
node_gtk_app -->|"presents"| node_window
node_window -->|"opens workspace"| node_workspace
node_window -->|"tracks edits"| node_session
node_article_ui -->|"manages articles"| node_workspace
node_frontmatter_ui -->|"edits fields"| node_frontmatter_service
node_window -->|"saves changes"| node_save
node_save -->|"writes articles"| node_posts_service
node_workspace -->|"loads configuration"| node_project_service
node_workspace -->|"lists articles"| node_posts_service
node_drafts -->|"stores recovery drafts"| node_project_files
node_session -->|"tracks recovery state"| node_drafts
node_preview_ui -->|"schedules renders"| node_preview_coord
node_preview_ui -->|"dispatches rendering"| node_tasks
node_tasks -->|"renders Markdown"| node_renderer
node_renderer -->|"parses Markdown"| node_markdown_service
node_preview_ui -->|"loads local images"| node_assets_service
node_assets_service -->|"reads validated assets"| node_project_files
node_publish_ui -->|"selects content"| node_publish
node_publish -->|"gets article data"| node_posts_service
node_publish -->|"commits selected files"| node_git_service
node_git_ui -->|"controls Git"| node_git_app
node_git_app -->|"runs operations"| node_git_service
node_git_service -->|"reads and stages"| node_project_files
node_git_service -->|"fetches and pushes"| node_git_remote
node_git_app -.->|"creates repository"| node_github_cli
node_project_service -->|"reads and writes settings"| node_project_files
node_posts_service -->|"reads and changes articles"| node_project_files

click node_gtk_app "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/main.rs"
click node_window "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window.rs"
click node_article_ui "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/articles.rs"
click node_frontmatter_ui "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/frontmatter.rs"
click node_publish_ui "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/publish.rs"
click node_git_ui "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/git_panel.rs"
click node_preview_ui "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/preview.rs"
click node_search_ui "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/search.rs"
click node_tasks "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/tasks.rs"
click node_workspace "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/workspace.rs"
click node_session "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/session.rs"
click node_save "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/save.rs"
click node_drafts "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/drafts/coordinator.rs"
click node_preview_coord "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/preview.rs"
click node_publish "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/publish.rs"
click node_git_app "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/git.rs"
click node_project_service "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/project.rs"
click node_posts_service "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/posts.rs"
click node_frontmatter_service "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/frontmatter.rs"
click node_assets_service "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/assets.rs"
click node_git_service "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/git.rs"
click node_markdown_service "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/markdown.rs"
click node_renderer "https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-renderer/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_gtk_app,node_window,node_article_ui,node_frontmatter_ui,node_publish_ui,node_git_ui,node_preview_ui,node_search_ui,node_tasks,node_user toneBlue
class node_workspace,node_session,node_save,node_drafts,node_preview_coord,node_publish,node_git_app,node_project_files toneAmber
class node_project_service,node_posts_service,node_frontmatter_service,node_assets_service,node_git_service,node_markdown_service toneMint
class node_renderer toneRose
class node_git_remote,node_github_cli toneIndigo
```

## Components

### GTK interface

- [GTK application](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/main.rs): `crates/cloudstack-gtk/src/main.rs`
- [Editor window](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window.rs): `crates/cloudstack-gtk/src/window.rs`
- [Article controls](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/articles.rs): `crates/cloudstack-gtk/src/window/articles.rs`
- [Frontmatter drawer](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/frontmatter.rs): `crates/cloudstack-gtk/src/window/frontmatter.rs`
- [Publish dialog](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/publish.rs): `crates/cloudstack-gtk/src/window/publish.rs`
- [Git panel](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/window/git_panel.rs): `crates/cloudstack-gtk/src/window/git_panel.rs`
- [WebKit preview](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/preview.rs): `crates/cloudstack-gtk/src/preview.rs`
- [Find and replace](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/search.rs): `crates/cloudstack-gtk/src/search.rs`
- [Background tasks](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-gtk/src/tasks.rs): `crates/cloudstack-gtk/src/tasks.rs`

### Application workflows

- [Workspace lifecycle](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/workspace.rs): `crates/cloudstack-application/src/workspace.rs`
- [Edit session state](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/session.rs): `crates/cloudstack-application/src/session.rs`
- [Save workflow](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/save.rs): `crates/cloudstack-application/src/save.rs`
- [Draft recovery](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/drafts/coordinator.rs): `crates/cloudstack-application/src/drafts/coordinator.rs`
- [Preview scheduling](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/preview.rs): `crates/cloudstack-application/src/preview.rs`
- [Publish workflow](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/publish.rs): `crates/cloudstack-application/src/publish.rs`
- [Git workflow](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-application/src/git.rs): `crates/cloudstack-application/src/git.rs`

### Core services

- [Project configuration](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/project.rs): `crates/cloudstack-core/src/services/project.rs`
- [Article operations](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/posts.rs): `crates/cloudstack-core/src/services/posts.rs`
- [Frontmatter parsing](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/frontmatter.rs): `crates/cloudstack-core/src/services/frontmatter.rs`
- [Local image assets](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/assets.rs): `crates/cloudstack-core/src/services/assets.rs`
- [Git operations](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/git.rs): `crates/cloudstack-core/src/services/git.rs`
- [Markdown parsing](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-core/src/services/markdown.rs): `crates/cloudstack-core/src/services/markdown.rs`

### Preview rendering

- [Markdown and KaTeX](https://github.com/xuxian2102/cloudstack/blob/main/crates/cloudstack-renderer/src/lib.rs): `crates/cloudstack-renderer/src/lib.rs`

### Other components

- **Editor user**
- **Local project files**
- **Git remote**
- **GitHub CLI**

## Connections

- Editor user → GTK application: opens and edits
- GTK application → Editor window: presents
- Editor window → Workspace lifecycle: opens workspace
- Editor window → Edit session state: tracks edits
- Article controls → Workspace lifecycle: manages articles
- Frontmatter drawer → Frontmatter parsing: edits fields
- Editor window → Save workflow: saves changes
- Save workflow → Article operations: writes articles
- Workspace lifecycle → Project configuration: loads configuration
- Workspace lifecycle → Article operations: lists articles
- Draft recovery → Local project files: stores recovery drafts
- Edit session state → Draft recovery: tracks recovery state
- WebKit preview → Preview scheduling: schedules renders
- WebKit preview → Background tasks: dispatches rendering
- Background tasks → Markdown and KaTeX: renders Markdown
- Markdown and KaTeX → Markdown parsing: parses Markdown
- WebKit preview → Local image assets: loads local images
- Local image assets → Local project files: reads validated assets
- Publish dialog → Publish workflow: selects content
- Publish workflow → Article operations: gets article data
- Publish workflow → Git operations: commits selected files
- Git panel → Git workflow: controls Git
- Git workflow → Git operations: runs operations
- Git operations → Local project files: reads and stages
- Git operations → Git remote: fetches and pushes
- Git workflow → GitHub CLI: creates repository
- Project configuration → Local project files: reads and writes settings
- Article operations → Local project files: reads and changes articles