# cypherock/cypherock-cysync architecture

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

- Interactive diagram: https://gitdiagram.com/cypherock/cypherock-cysync
- Repository: https://github.com/cypherock/cypherock-cysync

## Overview

1. This is a pnpm monorepo for Cypherock’s “cySync” product, centered on a desktop wallet app plus a CLI, with most domain logic split into shared packages. The repo is organized so UI shells are thin and most wallet/coin behavior lives in reusable packages.

2. The desktop application is an Electron app in `apps/desktop`, split into a main process and a renderer. The main process owns app lifecycle, IPC handlers, auto-update, device/system integrations, logging, and database access. The renderer is a Vite/React entry that hosts the product UI.

3. `packages/cysync-core` is the main product layer for the desktop UI. It contains pages, dialogs, components, hooks, store slices, and feature-specific services. In architecture terms, it sits between the renderer and the lower-level service packages, orchestrating screens, background tasks, and app state.

4. The desktop data flow is typically: React page/dialog in `cysync-core` -> hook/store/service -> package-level service or IPC call -> database/device/network operation -> state update back to the UI. This is where onboarding, wallet actions, send/receive, inheritance, swap, buy/sell, notifications, and wallet-connect flows are coordinated.

5. `packages/database` is the concrete persistence implementation. It defines entities for accounts, wallets, transactions, price history/info, devices, inheritance plans, notifications, and migrations, plus an encrypted database layer. `packages/db-interfaces` mirrors the database shapes and errors so higher layers can depend on stable contracts without importing the implementation directly.

6. Coin-specific behavior is isolated into many `packages/coin-support-*` packages. Each package exposes a common set of operations such as create account, receive, initialize/prepare/sign/broadcast transaction, validate address, sync account, and price sync. They differ by chain requirements and external API usage: for example Bitcoin uses Blockbook, EVM uses web3/ethers and transaction helpers, ICP uses Dfinity utilities, Solana uses SPL/token helpers, Tron uses TronWeb, Starknet has deploy-account flows, and Canton has extra transaction variants.

7. The coin support packages form the blockchain integration boundary. They translate generic wallet actions into chain-specific derivation, formatting, fee calculation, history fetching, signing, and broadcasting logic, and they reach out to chain APIs or explorers as needed. This is the main place where external blockchain infrastructure enters the system.

8. `packages/coins` is the static asset and metadata catalog for supported assets. It aggregates coin/token definitions per chain, including special token lists and JSON metadata, and is used by support packages and UI logic to identify assets consistently.

9. `packages/coin-support-utils` and `packages/coin-support-interfaces` provide shared building blocks for the chain packages. The former contains common DB/account/receive/sign/sync helpers and CoinGecko integration; the latter defines shared operation interfaces such as create account, receive, send, sign, explorer link, and sync operations. These packages are the abstraction layer that keeps all chain modules aligned.

10. `packages/cysync-core` also has substantial background processing. Its `bgTask` area handles recurring syncs for accounts, wallets, prices, notifications, network status, device handling, DB listening, and version checks. There is also a graph worker hook, which indicates some heavy UI computation is offloaded from the main thread.

11. The CLI app in `apps/cli` is a command-driven interface for wallet/device/account operations. It has command modules and matching service modules for account/device/wallet/transaction/send/receive/sign/reset flows, plus shared utilities for prompts, spinners, DB access, and device communication. Architecturally it reuses the same domain concepts as the desktop app, but without the Electron shell.

12. `packages/ui` is the shared design system and component library. It contains the low-level atoms/molecules, theming, layouts, icons, storybook, and common UI helpers used by the desktop/core product screens. `packages/desktop-ui` provides the renderer bootstrap and routing layer for the desktop app.

13. `packages/interfaces`, `packages/core-services`, and `packages/coins` are cross-cutting support libraries. `core-services` focuses on higher-level wallet/account/portfolio/transaction logic built over the database, while `interfaces` contains shared app-level types such as electron APIs and feature flags. `cysync-core-constants` centralizes error models, routes, locales, and core constants used across the UI and services.

14. The build and release system reinforces the modular architecture. The repo uses Turborepo, PNPM workspaces, changesets, GitHub Actions, and many package-level test configs. There is also a `submodules/sdk` dependency for hardware-wallet communication, which is intentionally externalized and built separately when modified.

15. Overall, the diagram should show two top-level clients — desktop and CLI — both depending on shared domain packages, coin support modules, database/interfaces, utilities, and the hardware SDK submodule. The desktop path additionally includes Electron main-process IPC and a React renderer/UI layer, while the CLI path is command/service driven and much thinner.

Main entry points: [`packages/coin-support-btc/src/index.ts`](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-btc/src/index.ts) (Chain packages), [`packages/cysync-core/src/index.ts`](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/index.ts) (cysync-core), [`apps/desktop/src/main/index.ts`](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/src/main/index.ts) (Main process), [`packages/core-services/src/index.ts`](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/core-services/src/index.ts) (Core services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop app"]
  node_desktop_main["Main process<br/>electron host<br/>[index.ts]"]
  node_desktop_renderer["Renderer<br/>react shell<br/>[index.tsx]"]
  node_desktop_ipc["IPC layer<br/>electron IPC<br/>[index.ts]"]
  node_desktop_preload["Preload<br/>bridge<br/>[index.ts]"]
end

subgraph group_cli["CLI app"]
  node_cli_app["CLI app<br/>command shell<br/>[index.ts]"]
  node_cli_commands["Commands<br/>cli entrypoints<br/>[index.ts]"]
  node_cli_services["CLI services<br/>domain flows<br/>[index.ts]"]
end

subgraph group_shared["Shared packages"]
  node_cysync_core["cysync-core<br/>product orchestration<br/>[index.ts]"]
  node_core_bg["Background tasks<br/>sync workers<br/>[index.tsx]"]
  node_core_ui["Core UI<br/>screens and dialogs<br/>[index.ts]"]
  node_core_store["Store<br/>ui state<br/>[store.ts]"]
  node_core_services["Core services<br/>wallet logic<br/>[index.ts]"]
  node_coin_utils["Coin utils<br/>shared helpers<br/>[index.ts]"]
  node_coin_ifaces["Coin interfaces<br/>contracts<br/>[index.ts]"]
  node_coins_catalog["Coins catalog<br/>asset metadata<br/>[index.ts]"]
  node_db_impl[("Database<br/>encrypted persistence<br/>[index.ts]")]
  node_db_contracts["DB contracts<br/>stable schemas<br/>[index.ts]"]
  node_coin_supports["Chain packages<br/>blockchain integrations<br/>[index.ts]"]
  node_coin_btc["BTC support<br/>utxo chain<br/>[index.ts]"]
  node_coin_evm["EVM support<br/>account chain<br/>[index.ts]"]
  node_coin_icp["ICP support<br/>canister chain<br/>[index.ts]"]
  node_coin_solana["Solana support<br/>token chain<br/>[index.ts]"]
  node_coin_tron["Tron support<br/>account chain<br/>[index.ts]"]
  node_coin_starknet["Starknet support<br/>deploy chain<br/>[index.ts]"]
  node_coin_canton["Canton support<br/>specialized chain<br/>[index.ts]"]
end

subgraph group_build["Tooling"]
  node_sdk_submodule["Hardware SDK<br/>submodule"]
  node_workspace_tooling["Workspace tooling<br/>repo infra<br/>[turbo.json]"]
end

node_desktop_renderer -->|"hosts UI"| node_cysync_core
node_desktop_preload -->|"bridges"| node_desktop_ipc
node_desktop_ipc -->|"routes to main"| node_desktop_main
node_desktop_main -->|"persists"| node_db_impl
node_desktop_main -->|"uses SDK"| node_sdk_submodule
node_cysync_core -->|"schedules tasks"| node_core_bg
node_cysync_core -->|"updates state"| node_core_store
node_cysync_core -->|"orchestrates flows"| node_core_services
node_core_bg -->|"runs sync"| node_core_services
node_core_services -->|"reads/writes"| node_db_impl
node_core_services -->|"delegates chain ops"| node_coin_supports
node_coin_supports -->|"shares helpers"| node_coin_utils
node_coin_supports -->|"implements contracts"| node_coin_ifaces
node_coin_supports -->|"resolves assets"| node_coins_catalog
node_coin_supports -->|"targets contracts"| node_db_contracts
node_cli_app -->|"dispatches"| node_cli_commands
node_cli_commands -->|"invokes"| node_cli_services
node_cli_services -->|"reuses chain ops"| node_coin_supports
node_cli_services -->|"persists"| node_db_impl
node_workspace_tooling -->|"builds"| node_desktop_main
node_workspace_tooling -->|"builds"| node_cli_app

click node_desktop_main "https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/src/main/index.ts"
click node_desktop_renderer "https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/renderer/index.tsx"
click node_desktop_ipc "https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/src/main/ipc/index.ts"
click node_desktop_preload "https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/src/preload/index.ts"
click node_cysync_core "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/index.ts"
click node_core_bg "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/bgTask/index.tsx"
click node_core_ui "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/pages/index.ts"
click node_core_store "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/store/store.ts"
click node_core_services "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/core-services/src/index.ts"
click node_coin_utils "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-utils/src/index.ts"
click node_coin_ifaces "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-interfaces/src/index.ts"
click node_coins_catalog "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coins/src/index.ts"
click node_db_impl "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/database/src/index.ts"
click node_db_contracts "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/db-interfaces/src/index.ts"
click node_cli_app "https://github.com/cypherock/cypherock-cysync/blob/develop/apps/cli/src/index.ts"
click node_cli_commands "https://github.com/cypherock/cypherock-cysync/blob/develop/apps/cli/src/commands/onboarding/index.ts"
click node_cli_services "https://github.com/cypherock/cypherock-cysync/blob/develop/apps/cli/src/services/index.ts"
click node_coin_supports "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-btc/src/index.ts"
click node_coin_btc "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-btc/src/index.ts"
click node_coin_evm "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-evm/src/index.ts"
click node_coin_icp "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-icp/src/index.ts"
click node_coin_solana "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-solana/src/index.ts"
click node_coin_tron "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-tron/src/index.ts"
click node_coin_starknet "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-starknet/src/index.ts"
click node_coin_canton "https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-canton/src/index.ts"
click node_sdk_submodule "https://github.com/cypherock/cypherock-cysync/tree/develop/submodules/sdk"
click node_workspace_tooling "https://github.com/cypherock/cypherock-cysync/blob/develop/turbo.json"

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_desktop_main,node_desktop_renderer,node_desktop_ipc,node_desktop_preload toneBlue
class node_cli_app,node_cli_commands,node_cli_services toneAmber
class node_cysync_core,node_core_bg,node_core_ui,node_core_store,node_core_services,node_coin_utils,node_coin_ifaces,node_coins_catalog,node_db_impl,node_db_contracts,node_coin_supports,node_coin_btc,node_coin_evm,node_coin_icp,node_coin_solana,node_coin_tron,node_coin_starknet,node_coin_canton toneMint
class node_sdk_submodule,node_workspace_tooling toneRose
```

## Components

### Desktop app

Electron wallet shell with main-process services and React renderer.

- [Main process](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/src/main/index.ts): electron host · Owns lifecycle, IPC, updates, device/system integration, logging, and database access. · `apps/desktop/src/main/index.ts`
- [Renderer](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/renderer/index.tsx): react shell · Vite/React entry that bootstraps the product UI. · `apps/desktop/renderer/index.tsx`
- [IPC layer](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/src/main/ipc/index.ts): electron IPC · Handlers that bridge renderer requests to app, device, DB, logs, reset, wallet-connect, and updater flows. · `apps/desktop/src/main/ipc/index.ts`
- [Preload](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/desktop/src/preload/index.ts): bridge · Exposes a controlled renderer-to-main API surface. · `apps/desktop/src/preload/index.ts`

### CLI app

Command-driven wallet interface built on shared domain services.

- [CLI app](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/cli/src/index.ts): command shell · Command-driven wallet and device interface with thin orchestration over shared services. · `apps/cli/src/index.ts`
- [Commands](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/cli/src/commands/onboarding/index.ts): cli entrypoints · Account, device, onboarding, portfolio, receive, reset, send, sign, transaction, and wallet commands. · `apps/cli/src/commands/onboarding/index.ts`
- [CLI services](https://github.com/cypherock/cypherock-cysync/blob/develop/apps/cli/src/services/index.ts): domain flows · Service modules that implement account, device, wallet, send/receive, sign, transaction, portfolio, and reset flows. · `apps/cli/src/services/index.ts`

### Shared packages

Reusable domain, blockchain, persistence, and UI libraries.

- [cysync-core](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/index.ts): product orchestration · Desktop product layer coordinating pages, dialogs, hooks, store, and feature services. · `packages/cysync-core/src/index.ts`
- [Background tasks](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/bgTask/index.tsx): sync workers · Recurring account, wallet, price, notification, device, network, DB, and version jobs. · `packages/cysync-core/src/bgTask/index.tsx`
- [Core UI](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/pages/index.ts): screens and dialogs · Pages, dialogs, and components for onboarding, wallet actions, inheritance, swap, buy/sell, and wallet-connect. · `packages/cysync-core/src/pages/index.ts`
- [Store](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/cysync-core/src/store/store.ts): ui state · Central application state slices for wallet, account, device, dialog, notification, network, and transaction data. · `packages/cysync-core/src/store/store.ts`
- [Core services](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/core-services/src/index.ts): wallet logic · Higher-level wallet, portfolio, transaction, swap, buy/sell, and inheritance services built over persistence. · `packages/core-services/src/index.ts`
- [Coin utils](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-utils/src/index.ts): shared helpers · Common create-account, receive, sign, sync, DB, and CoinGecko helpers used by chain packages. · `packages/coin-support-utils/src/index.ts`
- [Coin interfaces](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-interfaces/src/index.ts): contracts · Shared chain operation interfaces and explorer/address/sign/sync contracts. · `packages/coin-support-interfaces/src/index.ts`
- [Coins catalog](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coins/src/index.ts): asset metadata · Static coin/token definitions and chain-specific metadata used for consistent asset identification. · `packages/coins/src/index.ts`
- [Database](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/database/src/index.ts): encrypted persistence · Concrete encrypted database, entities, repositories, migrations, and key-value storage implementation. · `packages/database/src/index.ts`
- [DB contracts](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/db-interfaces/src/index.ts): stable schemas · Interface layer mirroring entity shapes and database errors for higher-level consumers. · `packages/db-interfaces/src/index.ts`
- [Chain packages](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-btc/src/index.ts): blockchain integrations · Coin-specific operation modules that adapt generic wallet actions to each chain and its APIs. · `packages/coin-support-btc/src/index.ts`
- [BTC support](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-btc/src/index.ts): utxo chain · Bitcoin integration with Blockbook, fee helpers, UTXO history, signing, broadcasting, and sync. · `packages/coin-support-btc/src/index.ts`
- [EVM support](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-evm/src/index.ts): account chain · Ethereum-compatible integration with web3/ethers helpers, address formatting, transaction helpers, and sync. · `packages/coin-support-evm/src/index.ts`
- [ICP support](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-icp/src/index.ts): canister chain · Internet Computer integration with Dfinity utilities, address derivation, and transaction flows. · `packages/coin-support-icp/src/index.ts`
- [Solana support](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-solana/src/index.ts): token chain · Solana and SPL token integration with web3, SPL helpers, and transaction helpers. · `packages/coin-support-solana/src/index.ts`
- [Tron support](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-tron/src/index.ts): account chain · Tron integration with TronWeb, trigger-constant-contract support, and transaction helpers. · `packages/coin-support-tron/src/index.ts`
- [Starknet support](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-starknet/src/index.ts): deploy chain · Starknet integration with deploy-account flows and chain-specific transaction preparation/signing. · `packages/coin-support-starknet/src/index.ts`
- [Canton support](https://github.com/cypherock/cypherock-cysync/blob/develop/packages/coin-support-canton/src/index.ts): specialized chain · Canton integration with extra broadcast variants and transaction preparation paths. · `packages/coin-support-canton/src/index.ts`

### Tooling

Repo-wide build, release, and workspace infrastructure.

- [Hardware SDK](https://github.com/cypherock/cypherock-cysync/tree/develop/submodules/sdk): submodule · External SDK submodule for hardware-wallet communication, built separately when changed. · `submodules/sdk`
- [Workspace tooling](https://github.com/cypherock/cypherock-cysync/blob/develop/turbo.json): repo infra · Turborepo, pnpm workspace, changesets, CI workflows, and release/build scripts. · `turbo.json`

## Connections

- Renderer → cysync-core: hosts UI · Renderer mounts the product layer and its screens.
- Preload → IPC layer: bridges · Preload exposes a safe API surface to the renderer.
- IPC layer → Main process: routes to main · IPC handlers execute lifecycle, update, DB, device, and system work in the main process.
- Main process → Database: persists · Desktop main process reads and writes encrypted app data.
- Main process → Hardware SDK: uses SDK · Main process integrates with the hardware-wallet communication submodule.
- cysync-core → Background tasks: schedules tasks · Core UI coordinates recurring background jobs and listeners.
- cysync-core → Store: updates state · Hooks, dialogs, and services drive application state transitions.
- cysync-core → Core services: orchestrates flows · Product actions delegate wallet, portfolio, swap, and inheritance work.
- Background tasks → Core services: runs sync · Background tasks invoke higher-level sync and maintenance services.
- Core services → Database: reads/writes · Service logic persists and queries wallet and portfolio data.
- Core services → Chain packages: delegates chain ops · Higher-level services use chain modules for blockchain-specific work.
- Chain packages → Coin utils: shares helpers · Chain packages reuse common account, receive, sign, sync, and price helpers.
- Chain packages → Coin interfaces: implements contracts · Each chain module conforms to common operation interfaces.
- Chain packages → Coins catalog: resolves assets · Chain logic uses the metadata catalog to identify coins and tokens.
- Chain packages → DB contracts: targets contracts · Chain support modules depend on stable DB shapes and error contracts.
- CLI app → Commands: dispatches · CLI entrypoint maps commands to feature modules.
- Commands → CLI services: invokes · Commands call service modules for the actual wallet operations.
- CLI services → Chain packages: reuses chain ops · CLI service flows reuse the same blockchain integration boundary.
- CLI services → Database: persists · CLI flows use the shared database for account and wallet state.
- Workspace tooling → Main process: builds · Repo tooling drives packaging, test, and release pipelines for the desktop app.
- Workspace tooling → CLI app: builds · Repo tooling also packages and tests the CLI application.
