# chuspeeism/dashi-taskboard architecture

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

- Interactive diagram: https://gitdiagram.com/chuspeeism/dashi-taskboard
- Repository: https://github.com/chuspeeism/dashi-taskboard

## Overview

#### Purpose and entry points
Codex Taskboard is a local-first task/project board usable in a browser, through a macOS launcher that embeds it into Codex/ChatGPT, and through automation clients. Primary entry points are the Node HTTP service (`server/index.mjs`), React client (`web/src/main.tsx`), CLI (`cli/taskctl.mjs`), and Tauri launcher (`src-tauri/src/main.rs`).

#### Local service and persistence
The Node service owns the HTTP API, SQLite-backed task data, attachments, and real-time synchronization. It serves the built web client, writes local data under the configured data directory, and uses server-sent events to notify connected boards; reconnecting clients perform a full refresh.
- `server/app.mjs`
- `server/database.mjs`
- `server/index.mjs`

#### Domain and workflow model
Shared modules define taskboard domain concepts plus workflow sequencing/control-flow semantics used across service, UI, CLI, and automation. Project automation policies bridge task state changes to Codex-oriented execution behavior.
- `shared/domain.mjs`
- `shared/workflow-control-flow.mjs`
- `shared/taskboard-automation.mjs`

#### React taskboard client
The Vite/React application consumes the local API and presents dashboard, board, Gantt/list, issue detail/editor, relations, comments, attachments, and project automation configuration. Client state includes storage-backed preferences, API access, revision polling, and AI-chat state.
- `web/src/App.tsx`
- `web/src/api.ts`
- `web/src/components/TaskDetail.tsx`

#### AI chat subsystem
The server exposes AI-chat endpoints and coordinates process execution, turn ownership, cataloging, and persisted chat/task state. The web UI renders the corresponding conversation experience, keeping this integration behind the HTTP API rather than directly invoking local Codex capabilities.
- `server/ai-chat.mjs`
- `server/ai-chat-process.mjs`
- `web/src/components/AiChat.tsx`

#### Codex/ChatGPT embedding and automation
Injection tooling launches or attaches to a Chromium DevTools Protocol-enabled official client, bypasses renderer CSP as needed, and inserts the taskboard entry/iframe without modifying the vendor application. Shared executable/environment discovery and the supervisor support long-running injected sessions and recovery.
- `scripts/codex-injector.mjs`
- `scripts/taskboard-supervisor.mjs`
- `inject/codex-taskboard.user.js`

#### macOS distribution runtime
A Tauri Rust launcher packages Node, server, web assets, CLI, injector, and skill into a universal macOS app. It starts a loopback service on a random port, starts a separate official-client window with a random CDP port, injects the board, supervises failures, and uses Tauri’s signed updater. GitHub Actions builds, signs, notarizes, verifies, and promotes immutable releases.
- `src-tauri/src/main.rs`
- `src-tauri/tauri.conf.json`
- `.github/workflows/release-macos.yml`

#### Optional cloud collaboration
Cloud deployment is a Cloudflare Worker-based shared backend using D1 migrations, static assets, and private R2 attachments. Local devices retain project checkout mappings and companion capabilities; cloud proxy/config code separates this optional synchronized mode from the local database runtime.
- `cloud/src/index.mjs`
- `cloud/migrations/0001_initial.sql`
- `server/cloud-proxy.mjs`

Main entry points: [`server/app.mjs`](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/app.mjs) (Local API & sync), [`web/src/App.tsx`](https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/App.tsx) (Taskboard UI), [`src-tauri/src/main.rs`](https://github.com/chuspeeism/dashi-taskboard/blob/main/src-tauri/src/main.rs) (Tauri launcher), [`server/ai-chat.mjs`](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/ai-chat.mjs) (AI chat coordinator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_local["Local Runtime"]
  node_server_entry["HTTP service entry<br/>Node entry point<br/>[index.mjs]"]
  node_server_app["Local API &amp; sync<br/>Node HTTP app<br/>[app.mjs]"]
  node_database[("Local task store<br/>SQLite persistence<br/>[database.mjs]")]
  node_ai_chat["AI chat coordinator<br/>chat API<br/>[ai-chat.mjs]"]
  node_ai_process{{"Codex process runner<br/>process execution"}}
  node_cloud_proxy["Cloud mode proxy<br/>sync adapter<br/>[cloud-proxy.mjs]"]
end

subgraph group_web["Board UI"]
  node_web_entry["React client entry<br/>Vite entry point<br/>[main.tsx]"]
  node_board_ui["Taskboard UI<br/>React application<br/>[App.tsx]"]
  node_api_client["Local API client<br/>HTTP/SSE client<br/>[api.ts]"]
  node_task_detail["Task editor<br/>React component<br/>[TaskDetail.tsx]"]
  node_chat_ui["Chat UI<br/>React component<br/>[AiChat.tsx]"]
end

subgraph group_automation["Embedding &amp; Automation"]
  node_cli{{"taskctl<br/>automation CLI<br/>[taskctl.mjs]"}}
  node_injector{{"Codex injector<br/>CDP integration<br/>[codex-injector.mjs]"}}
  node_supervisor{{"Session supervisor<br/>recovery supervisor"}}
  node_injected_board["Injected board bridge<br/>user script"]
end

subgraph group_desktop["macOS Distribution"]
  node_tauri["Tauri launcher<br/>macOS runtime<br/>[main.rs]"]
  node_tauri_config["Signed updater config<br/>Tauri configuration<br/>[tauri.conf.json]"]
  node_release["macOS release pipeline<br/>GitHub Actions<br/>[release-macos.yml]"]
end

subgraph group_cloud["Optional Cloud Mode"]
  node_cloud_worker["Shared cloud backend<br/>Cloudflare Worker<br/>[index.mjs]"]
  node_cloud_schema[("D1 schema<br/>database migration<br/>[0001_initial.sql]")]
end

node_domain["Shared domain<br/>domain model<br/>[domain.mjs]"]
node_workflow["Workflow control<br/>workflow rules"]
node_automation_policy["Automation policies<br/>automation rules"]

node_server_entry -->|"starts"| node_server_app
node_server_app -->|"persists tasks"| node_database
node_server_app -->|"uses"| node_domain
node_server_app -->|"applies"| node_workflow
node_server_app -->|"applies"| node_automation_policy
node_server_app -->|"routes chat API"| node_ai_chat
node_ai_chat -->|"runs turns"| node_ai_process
node_web_entry -->|"mounts"| node_board_ui
node_board_ui -->|"uses"| node_api_client
node_board_ui -->|"renders"| node_task_detail
node_board_ui -->|"renders"| node_chat_ui
node_api_client -->|"HTTP and SSE"| node_server_app
node_chat_ui -->|"HTTP API"| node_ai_chat
node_cli -->|"automates via API"| node_server_app
node_injector -->|"installs"| node_injected_board
node_injected_board -->|"embeds"| node_board_ui
node_supervisor -->|"restarts"| node_injector
node_tauri -->|"launches loopback service"| node_server_entry
node_tauri -->|"starts"| node_supervisor
node_tauri -->|"opens CDP session"| node_injector
node_release -->|"builds and signs"| node_tauri
node_tauri_config -->|"configures updater"| node_tauri
node_server_app -.->|"optional cloud mode"| node_cloud_proxy
node_cloud_proxy -.->|"syncs"| node_cloud_worker
node_cloud_worker -->|"uses D1"| node_cloud_schema

click node_domain "https://github.com/chuspeeism/dashi-taskboard/blob/main/shared/domain.mjs"
click node_workflow "https://github.com/chuspeeism/dashi-taskboard/blob/main/shared/workflow-control-flow.mjs"
click node_automation_policy "https://github.com/chuspeeism/dashi-taskboard/blob/main/shared/taskboard-automation.mjs"
click node_server_entry "https://github.com/chuspeeism/dashi-taskboard/blob/main/server/index.mjs"
click node_server_app "https://github.com/chuspeeism/dashi-taskboard/blob/main/server/app.mjs"
click node_database "https://github.com/chuspeeism/dashi-taskboard/blob/main/server/database.mjs"
click node_ai_chat "https://github.com/chuspeeism/dashi-taskboard/blob/main/server/ai-chat.mjs"
click node_ai_process "https://github.com/chuspeeism/dashi-taskboard/blob/main/server/ai-chat-process.mjs"
click node_cloud_proxy "https://github.com/chuspeeism/dashi-taskboard/blob/main/server/cloud-proxy.mjs"
click node_web_entry "https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/main.tsx"
click node_board_ui "https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/App.tsx"
click node_api_client "https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/api.ts"
click node_task_detail "https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/components/TaskDetail.tsx"
click node_chat_ui "https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/components/AiChat.tsx"
click node_cli "https://github.com/chuspeeism/dashi-taskboard/blob/main/cli/taskctl.mjs"
click node_injector "https://github.com/chuspeeism/dashi-taskboard/blob/main/scripts/codex-injector.mjs"
click node_supervisor "https://github.com/chuspeeism/dashi-taskboard/blob/main/scripts/taskboard-supervisor.mjs"
click node_injected_board "https://github.com/chuspeeism/dashi-taskboard/blob/main/inject/codex-taskboard.user.js"
click node_tauri "https://github.com/chuspeeism/dashi-taskboard/blob/main/src-tauri/src/main.rs"
click node_tauri_config "https://github.com/chuspeeism/dashi-taskboard/blob/main/src-tauri/tauri.conf.json"
click node_release "https://github.com/chuspeeism/dashi-taskboard/blob/main/.github/workflows/release-macos.yml"
click node_cloud_worker "https://github.com/chuspeeism/dashi-taskboard/blob/main/cloud/src/index.mjs"
click node_cloud_schema "https://github.com/chuspeeism/dashi-taskboard/blob/main/cloud/migrations/0001_initial.sql"

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_server_entry,node_server_app,node_database,node_ai_chat,node_ai_process,node_cloud_proxy toneBlue
class node_web_entry,node_board_ui,node_api_client,node_task_detail,node_chat_ui toneAmber
class node_cli,node_injector,node_supervisor,node_injected_board toneMint
class node_tauri,node_tauri_config,node_release toneRose
class node_cloud_worker,node_cloud_schema toneIndigo
class node_domain,node_workflow,node_automation_policy toneNeutral
```

## Components

### Local Runtime

- [HTTP service entry](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/index.mjs): Node entry point · `server/index.mjs`
- [Local API & sync](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/app.mjs): Node HTTP app · Serves board assets, APIs, attachments, and SSE updates. · `server/app.mjs`
- [Local task store](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/database.mjs): SQLite persistence · Taskboard data is stored under the configured local data directory. · `server/database.mjs`
- [AI chat coordinator](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/ai-chat.mjs): chat API · Coordinates chat state, turn ownership, and execution. · `server/ai-chat.mjs`
- [Codex process runner](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/ai-chat-process.mjs): process execution · `server/ai-chat-process.mjs`
- [Cloud mode proxy](https://github.com/chuspeeism/dashi-taskboard/blob/main/server/cloud-proxy.mjs): sync adapter · Separates optional cloud synchronization from local persistence. · `server/cloud-proxy.mjs`

### Board UI

- [React client entry](https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/main.tsx): Vite entry point · `web/src/main.tsx`
- [Taskboard UI](https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/App.tsx): React application · Dashboard, board, Gantt/list, and project configuration. · `web/src/App.tsx`
- [Local API client](https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/api.ts): HTTP/SSE client · Maintains API access, revision refresh, and realtime board updates. · `web/src/api.ts`
- [Task editor](https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/components/TaskDetail.tsx): React component · Edits issues, relations, comments, and attachments. · `web/src/components/TaskDetail.tsx`
- [Chat UI](https://github.com/chuspeeism/dashi-taskboard/blob/main/web/src/components/AiChat.tsx): React component · `web/src/components/AiChat.tsx`

### Embedding & Automation

- [taskctl](https://github.com/chuspeeism/dashi-taskboard/blob/main/cli/taskctl.mjs): automation CLI · `cli/taskctl.mjs`
- [Codex injector](https://github.com/chuspeeism/dashi-taskboard/blob/main/scripts/codex-injector.mjs): CDP integration · Attaches to the official client and inserts the board iframe. · `scripts/codex-injector.mjs`
- [Session supervisor](https://github.com/chuspeeism/dashi-taskboard/blob/main/scripts/taskboard-supervisor.mjs): recovery supervisor · Maintains long-running injected sessions and recovery. · `scripts/taskboard-supervisor.mjs`
- [Injected board bridge](https://github.com/chuspeeism/dashi-taskboard/blob/main/inject/codex-taskboard.user.js): user script · `inject/codex-taskboard.user.js`

### macOS Distribution

- [Tauri launcher](https://github.com/chuspeeism/dashi-taskboard/blob/main/src-tauri/src/main.rs): macOS runtime · Starts loopback service and official-client window on random ports. · `src-tauri/src/main.rs`
- [Signed updater config](https://github.com/chuspeeism/dashi-taskboard/blob/main/src-tauri/tauri.conf.json): Tauri configuration · `src-tauri/tauri.conf.json`
- [macOS release pipeline](https://github.com/chuspeeism/dashi-taskboard/blob/main/.github/workflows/release-macos.yml): GitHub Actions · Builds, signs, notarizes, verifies, and promotes releases. · `.github/workflows/release-macos.yml`

### Optional Cloud Mode

- [Shared cloud backend](https://github.com/chuspeeism/dashi-taskboard/blob/main/cloud/src/index.mjs): Cloudflare Worker · Optional shared backend for synchronized projects. · `cloud/src/index.mjs`
- [D1 schema](https://github.com/chuspeeism/dashi-taskboard/blob/main/cloud/migrations/0001_initial.sql): database migration · Cloud task data schema; attachments are private R2 objects. · `cloud/migrations/0001_initial.sql`

### Other components

- [Shared domain](https://github.com/chuspeeism/dashi-taskboard/blob/main/shared/domain.mjs): domain model · Task, project, and workflow semantics shared across runtimes. · `shared/domain.mjs`
- [Workflow control](https://github.com/chuspeeism/dashi-taskboard/blob/main/shared/workflow-control-flow.mjs): workflow rules · `shared/workflow-control-flow.mjs`
- [Automation policies](https://github.com/chuspeeism/dashi-taskboard/blob/main/shared/taskboard-automation.mjs): automation rules · `shared/taskboard-automation.mjs`

## Connections

- HTTP service entry → Local API & sync: starts
- Local API & sync → Local task store: persists tasks
- Local API & sync → Shared domain: uses
- Local API & sync → Workflow control: applies
- Local API & sync → Automation policies: applies
- Local API & sync → AI chat coordinator: routes chat API
- AI chat coordinator → Codex process runner: runs turns
- React client entry → Taskboard UI: mounts
- Taskboard UI → Local API client: uses
- Taskboard UI → Task editor: renders
- Taskboard UI → Chat UI: renders
- Local API client → Local API & sync: HTTP and SSE
- Chat UI → AI chat coordinator: HTTP API
- taskctl → Local API & sync: automates via API
- Codex injector → Injected board bridge: installs
- Injected board bridge → Taskboard UI: embeds
- Session supervisor → Codex injector: restarts
- Tauri launcher → HTTP service entry: launches loopback service
- Tauri launcher → Session supervisor: starts
- Tauri launcher → Codex injector: opens CDP session
- macOS release pipeline → Tauri launcher: builds and signs
- Signed updater config → Tauri launcher: configures updater
- Local API & sync → Cloud mode proxy: optional cloud mode
- Cloud mode proxy → Shared cloud backend: syncs
- Shared cloud backend → D1 schema: uses D1