character-arc: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Package manager: pnpm (pinned to 10.33.2 in package.json). Scripts shell out via Windows set syntax — on macOS/Linux replace set ELECTRON_RUN_AS_NODE=&& with cross-env ELECTRON_RUN_AS_NODE= or strip the prefix.

pnpm install          # install deps (uses npmmirror via .npmrc)
pnpm run dev          # electron-vite dev: starts main + preload + renderer (Vite on 127.0.0.1, port auto-selected)
pnpm run build        # vue-tsc --noEmit (full type check) then electron-vite build
pnpm run preview      # run the production build locally
pnpm run dist         # type check + build + electron-builder (Windows NSIS installer)

There is no test runner, linter, or formatter configured. "Build = type check" — vue-tsc --noEmit is the only static gate, and pnpm run build will fail loudly on TS errors. Run it before declaring work done.

Architecture

CharacterArc is an Electron 37 + Vue 3.5 + TypeScript desktop app for novel writing. Three processes, three roots:

• electron/main/ — Node main process: SQLite, AI pipeline, IPC handlers, file I/O
• electron/preload/ — context-bridge surface exposed as window.characterArc
• electron/shared/ — types shared across process boundaries (@shared/* alias)
• renderer/src/ — Vue 3 + Pinia + Naive UI + TipTap (@/* alias → renderer/src/*)

Build outputs land in dist-electron/{main,preload} and out/renderer. Entry is dist-electron/main/index.js (see package.json#main).

Data flow

The renderer never touches the filesystem or AI providers directly. Everything goes through IPC:

1. App boot (renderer/src/main.ts) creates Pinia, calls useAppStore().initialize(), which IPC-loads the workspace snapshot from SQLite, then app.mount('#app').
2. Edits mutate the Pinia store (renderer/src/stores/app.ts); a debounced persistence layer (renderer/src/features/workspace/persistence.ts) writes back via window.characterArc.saveWorkspace / saveAppSettings.
3. Main holds latestWorkspaceSnapshot in memory for AI tasks to read; on before-quit it flushes one last time.
4. The renderer-side characterArc API and the main-side IPC channels share names like characterarc:*. IPC_CHANNELS in electron/shared/ipc-types.ts is partial — most channel names are still string literals on both sides.