# w3dev33/beads-task-issue-tracker architecture

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

- Interactive diagram: https://gitdiagram.com/w3dev33/beads-task-issue-tracker
- Repository: https://github.com/w3dev33/beads-task-issue-tracker

## Overview

Beads Task-Issue Tracker is a desktop human control panel for issues managed by the `br` or `bd` CLI. Users select a project, inspect dashboard and filtered issue lists, then view or edit issues, comments, and relationships; changes made externally are reflected in the app. The README also describes attachments, project favorites, themes, repair, and live updates. The graph combines documented capabilities with sampled entry-point and storage code; several feature-to-API details are unsampled, so uncertain wiring is omitted.

Main entry points: [`app/pages/index.vue`](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/pages/index.vue) (App workspace), [`app/components/details/IssuePreview.vue`](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/details/IssuePreview.vue) (Issue preview), [`app/utils/bd-api.ts`](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/utils/bd-api.ts) (CLI API client), [`server/api/bd/list.get.ts`](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/server/api/bd/list.get.ts) (Issue API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["App experience"]
  node_index["App workspace<br/>[index.vue]"]
  node_app_shell["App shell<br/>[app.vue]"]
  node_dashboard["Dashboard"]
end

subgraph group_issue_workflow["Issue workflow"]
  node_issue_list["Issue list<br/>[IssueListPanel.vue]"]
  node_issue_preview["Issue preview<br/>[IssuePreview.vue]"]
  node_issue_form["Issue editing<br/>[IssueForm.vue]"]
  node_comments["Comments<br/>[CommentSection.vue]"]
  node_attachments["Attachments<br/>[useAttachments.ts]"]
  node_markdown["Markdown viewer"]
  node_issue_state["Issue data<br/>[issue.ts]"]
  node_issue_logic["Issue operations<br/>[useIssues.ts]"]
  node_markdown_io["Markdown preview UI"]
end

subgraph group_integration["CLI integration"]
  node_api_client["CLI API client<br/>[bd-api.ts]"]
  node_api_routes["Issue API routes<br/>[list.get.ts]"]
  node_executor["CLI executor<br/>[bd-executor.ts]"]
  node_transformers["Issue transformers<br/>[bd-transformers.ts]"]
end

subgraph group_project_state["Project state"]
  node_project_path["Project selection<br/>[useBeadsPath.ts]"]
  node_project_storage[("Project settings")]
end

subgraph group_desktop["Desktop services"]
  node_change_detection["Change detection"]
  node_native_runtime["Tauri runtime<br/>[lib.rs]"]
end

node_user(("Human user"))
node_beads_cli{{"br / bd CLI"}}
node_project_files[("Beads project files")]

node_user -->|"uses workspace"| node_index
node_index -->|"shows dashboard"| node_dashboard
node_index -->|"shows issues"| node_issue_list
node_index -->|"previews selection"| node_issue_preview
node_issue_list -->|"requests issue data"| node_issue_logic
node_issue_preview -->|"opens editing"| node_issue_form
node_issue_preview -->|"manages comments"| node_comments
node_issue_preview -->|"manages attachments"| node_attachments
node_attachments -->|"opens markdown"| node_markdown
node_markdown -->|"renders and edits"| node_markdown_io
node_issue_logic -->|"calls issue operations"| node_api_client
node_api_client -->|"requests API"| node_api_routes
node_api_routes -->|"executes CLI"| node_executor
node_executor -->|"invokes"| node_beads_cli
node_beads_cli -->|"reads and writes"| node_project_files
node_transformers -->|"transforms issue data"| node_api_routes
node_project_path -->|"supplies project path"| node_api_client
node_project_path -->|"namespaces settings"| node_project_storage
node_project_storage -->|"persists preferences"| node_user
node_project_files -->|"watches changes"| node_native_runtime
node_native_runtime -->|"emits change events"| node_change_detection
node_change_detection -->|"refreshes issue data"| node_index
node_app_shell -->|"hosts page"| node_index
node_index -->|"holds issue state"| node_issue_state

click node_index "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/pages/index.vue"
click node_app_shell "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/app.vue"
click node_dashboard "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/dashboard/DashboardContent.vue"
click node_issue_list "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/issues/IssueListPanel.vue"
click node_issue_preview "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/details/IssuePreview.vue"
click node_issue_form "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/details/IssueForm.vue"
click node_comments "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/details/CommentSection.vue"
click node_attachments "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useAttachments.ts"
click node_markdown "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useMarkdownPreview.ts"
click node_issue_state "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/types/issue.ts"
click node_issue_logic "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useIssues.ts"
click node_api_client "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/utils/bd-api.ts"
click node_api_routes "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/server/api/bd/list.get.ts"
click node_executor "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/server/utils/bd-executor.ts"
click node_transformers "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/server/utils/bd-transformers.ts"
click node_project_path "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useBeadsPath.ts"
click node_project_storage "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useProjectStorage.ts"
click node_change_detection "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useChangeDetection.ts"
click node_native_runtime "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/src-tauri/src/lib.rs"
click node_markdown_io "https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/ui/markdown-preview/MarkdownPreviewDialog.vue"

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_index,node_app_shell,node_dashboard,node_user toneBlue
class node_issue_list,node_issue_preview,node_issue_form,node_comments,node_attachments,node_markdown,node_issue_state,node_issue_logic,node_markdown_io,node_project_files toneAmber
class node_api_client,node_api_routes,node_executor,node_transformers toneMint
class node_project_path,node_project_storage toneRose
class node_change_detection,node_native_runtime,node_beads_cli toneIndigo
```

## Components

### App experience

- [App workspace](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/pages/index.vue): `app/pages/index.vue`
- [App shell](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/app.vue): `app/app.vue`
- [Dashboard](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/dashboard/DashboardContent.vue): `app/components/dashboard/DashboardContent.vue`

### Issue workflow

- [Issue list](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/issues/IssueListPanel.vue): `app/components/issues/IssueListPanel.vue`
- [Issue preview](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/details/IssuePreview.vue): `app/components/details/IssuePreview.vue`
- [Issue editing](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/details/IssueForm.vue): `app/components/details/IssueForm.vue`
- [Comments](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/details/CommentSection.vue): `app/components/details/CommentSection.vue`
- [Attachments](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useAttachments.ts): `app/composables/useAttachments.ts`
- [Markdown viewer](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useMarkdownPreview.ts): `app/composables/useMarkdownPreview.ts`
- [Issue data](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/types/issue.ts): `app/types/issue.ts`
- [Issue operations](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useIssues.ts): `app/composables/useIssues.ts`
- [Markdown preview UI](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/components/ui/markdown-preview/MarkdownPreviewDialog.vue): `app/components/ui/markdown-preview/MarkdownPreviewDialog.vue`

### CLI integration

- [CLI API client](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/utils/bd-api.ts): `app/utils/bd-api.ts`
- [Issue API routes](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/server/api/bd/list.get.ts): `server/api/bd/list.get.ts`
- [CLI executor](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/server/utils/bd-executor.ts): `server/utils/bd-executor.ts`
- [Issue transformers](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/server/utils/bd-transformers.ts): `server/utils/bd-transformers.ts`

### Project state

- [Project selection](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useBeadsPath.ts): `app/composables/useBeadsPath.ts`
- [Project settings](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useProjectStorage.ts): `app/composables/useProjectStorage.ts`

### Desktop services

- [Change detection](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/app/composables/useChangeDetection.ts): `app/composables/useChangeDetection.ts`
- [Tauri runtime](https://github.com/w3dev33/beads-task-issue-tracker/blob/master/src-tauri/src/lib.rs): `src-tauri/src/lib.rs`

### Other components

- **Human user**
- **br / bd CLI**
- **Beads project files**

## Connections

- Human user → App workspace: uses workspace
- App workspace → Dashboard: shows dashboard
- App workspace → Issue list: shows issues
- App workspace → Issue preview: previews selection
- Issue list → Issue operations: requests issue data
- Issue preview → Issue editing: opens editing
- Issue preview → Comments: manages comments
- Issue preview → Attachments: manages attachments
- Attachments → Markdown viewer: opens markdown
- Markdown viewer → Markdown preview UI: renders and edits
- Issue operations → CLI API client: calls issue operations
- CLI API client → Issue API routes: requests API
- Issue API routes → CLI executor: executes CLI
- CLI executor → br / bd CLI: invokes
- br / bd CLI → Beads project files: reads and writes
- Issue transformers → Issue API routes: transforms issue data
- Project selection → CLI API client: supplies project path
- Project selection → Project settings: namespaces settings
- Project settings → Human user: persists preferences
- Beads project files → Tauri runtime: watches changes
- Tauri runtime → Change detection: emits change events
- Change detection → App workspace: refreshes issue data
- App shell → App workspace: hosts page
- App workspace → Issue data: holds issue state