Fable Development Guide

Fable is a creative-writing desktop app: Electron + React 19 + Vite + TanStack Query + Plate.js frontend, Node.js + SQLite + custom indexed filesystem backend, Google ADK for AI features.

Critical Invariant

Every file can have children, not just folders.

FileNode.children

category

parentId

siblingIndex

buildFileTree()

Where Does My Code Go?

digraph code_placement {
    rankdir=TB;
    node [shape=diamond];
    "Used by both\nfrontend & backend?" -> "src/shared/" [label="yes"];
    "Used by both\nfrontend & backend?" -> "Runs in\nNode.js only?" [label="no"];
    "Runs in\nNode.js only?" -> "IPC handler?" [label="yes"];
    "Runs in\nNode.js only?" -> "React component\nor hook?" [label="no"];
    "IPC handler?" -> "src/backend/handlers/" [label="yes"];
    "IPC handler?" -> "src/backend/services/" [label="no"];
    "React component\nor hook?" -> "src/frontend/components/" [label="component"];
    "React component\nor hook?" -> "src/frontend/hooks/" [label="hook"];
    "React component\nor hook?" -> "src/frontend/services/" [label="service/singleton"];

    node [shape=box];
    "src/shared/" [style=filled, fillcolor="#e8f5e9"];
    "src/backend/handlers/" [style=filled, fillcolor="#e3f2fd"];
    "src/backend/services/" [style=filled, fillcolor="#e3f2fd"];
    "src/frontend/components/" [style=filled, fillcolor="#fff3e0"];
    "src/frontend/hooks/" [style=filled, fillcolor="#fff3e0"];
    "src/frontend/services/" [style=filled, fillcolor="#fff3e0"];
}

Shared code constraint:

src/shared/

How Do I Access / Mutate Data?

digraph data_access {
    rankdir=TB;
    node [shape=diamond];
    "Inside React\ncomponent?" -> "Use query hooks" [label="yes"];
    "Inside React\ncomponent?" -> "Use queryService\nsingleton" [label="no\n(command, service)"];

    "Need to mutate\nfile tree?" -> "queryService.mutations.*\n(optimistic updates)" [label="always"];
    "Need to read\nfile content?" -> "readFileContent()\nhelper (cache-first)" [label="preferred"];

    node [shape=box];
    "Use query hooks" [style=filled, fillcolor="#e8f5e9"];
    "Use queryService\nsingleton" [style=filled, fillcolor="#e8f5e9"];
    "queryService.mutations.*\n(optimistic updates)" [style=filled, fillcolor="#fff3e0"];
    "readFileContent()\nhelper (cache-first)" [style=filled, fillcolor="#fff3e0"];
}

Never call

window.api.*

queryService.mutations.*

Key Directories

src/types.ts

src/shared/

src/backend/handlers/

src/backend/services/

src/backend/services/agent/

src/frontend/components/

src/frontend/services/commandInfra/

src/frontend/services/query/

src/frontend/hooks/

src/frontend/styles/plate/

src/locales/{en,zh-CN}/

e2e/

electron/preload.ts

window.api.*

src/global.d.ts

Window.api

Common Task Recipes

Read

references/recipes.md

• Adding a new IPC channel (5-step checklist)
• Adding a new command (5-step checklist)
• Adding a new file subType (8-step checklist)
• Adding a new agent tool (6-step checklist)
• Adding a new sidebar panel or editor handler
• Adding i18n strings

Architecture at a Glance

Read

references/architecture.md

Frontend (React) --window.api.*--> Preload --IPC--> Backend handlers --> Services --> Disk
                 <--transport push events--  <--IPC--  ProjectManager <-- IndexedFsService events

• State: TanStack Query is single source of truth.

  staleTime: Infinity

  everywhere.
• File tree: Event-driven push from backend, never polled.

  useFileTree

  sets up listener.
• Mutations:

  createTreeMutation

  factory: optimistic update -> IPC call -> rollback on error.
• Commands: VS Code-style

  CommandService

  +

  ContextService

  +

  KeybindingService

  .
• Editor routing:

  ContentViewer

  dispatches by

  subType

  first, then

  category

  .
• AI: Google ADK with multi-provider LLM registry. See

  references/agent-system.md

  .

i18n Checklist

• 8 namespaces:

  common

  ,

  fileExplorer

  ,

  chat

  ,

  project

  ,

  editor

  ,

  agentBuilder

  ,

  graph

  ,

  agentDefinition

• In components:

  const { t } = useTranslation("namespace")

• Outside React:

  import i18n from "@/src/i18n/i18n"; i18n.t("ns:key")

• Always add keys to BOTH

  en

  and

  zh-CN

Build, Lint & Test

npm run dev:electron     # Dev mode (Vite + Electron)
npm run build            # Production build
npm run check            # Lint + format + TypeScript check
npm run test:e2e         # Playwright E2E tests (headless)
npm run test:e2e:headed  # E2E with visible browser

• Path alias:

  @/*

  maps to repo root
• Formatting: Prettier (double quotes, 4-space indent, semicolons)
• Always run E2E tests you wrote before committing

Pitfalls

1. Any node can have children — not just folders
2. parentId/siblingIndex are derived — never persist
3. Tree mutations must be pure —

   treeTransformations.ts

   returns new arrays, never mutate
4. Always add i18n to BOTH locales —

   en

   and

   zh-CN

5. Toolbar renders via portal —

   #file-toolbar-portal

   in TopBar, not inside editor DOM
6. Input elements suppress keybindings —

   useKeybindings

   checks

   event.target

   tag
7. subType controls routing — checked before category in ContentViewer
8. Binary files use base64 over IPC — text uses UTF-8
9. STRUCTURAL_FILE_CHANGES control broadcasts — content "update" does NOT re-push tree
10. Add Window.api types — update

    src/global.d.ts

    when adding IPC channels
11. Shared code is process-agnostic —

    src/shared/

    cannot import browser or Node APIs
12. Tool descriptors are shared —

    toolDescriptors.ts

    serves both UI commands and LLM agents
13. Every user-facing data element needs a tooltip

References

references/architecture.md

references/command-system.md

references/workspace-structure.md

references/agent-system.md

references/recipes.md