Developer Guide

Developer Guide

This page introduces the repository, its main development paths, and the rules to understand before making a change.

ChemDraft is a local-file-first chemical drawing application for macOS and Windows. The desktop shell uses Tauri, React, TypeScript and Vite; Rust handles operating-system integration. Shared packages provide the native document model, chemistry adapters, drawing geometry, exports and plugin contracts. The command-line interface (CLI) and Model Context Protocol (MCP) server expose shared functionality to scripts and assistants.

The current public app version is 1.0.0. The checkout can contain work newer than that release, so use the build stamp and release records when investigating a reported problem. A workspace package version is not necessarily the app version.

Read the right sources first

Start with these files in the repository:

1. AGENTS.md: contributor rules, package boundaries, platform requirements and verification.
2. PLANS.md: the slice currently in flight and explicitly parked work.
3. README.md, package.json and pnpm-workspace.yaml: repository orientation, scripts and workspace membership.
4. The README of the package you will change.
5. The relevant subsystem notes in docs/architecture/ and recent records in docs/shipped/.

Read PLAN.md for product scope, a new dependency, licensing decisions or a user-facing feature proposal. It is a charter, not a reliable inventory of implemented features. Some foundation-era README paragraphs are also historical. Current code and the newest shipped record resolve implementation questions; do not copy old “not implemented” statements into a bug report without checking.

Choose an entry point

Your goal	Start here
Run the desktop app	Building from Source
Understand dependencies	Architecture Overview, then Package Map
Change document behavior	Document Model
Fix a drawing or export discrepancy	Rendering and Layout Engine
Add a tool, menu action or shortcut	Commands and Registry
Extend the app from a plugin	Writing a Plugin
Automate headless work	Agent Tools Overview
Prepare a contribution	Contributing, then Testing and CI

For an implementation search, begin with the behavior's command ID or native object type. Follow the command through the desktop workflow and into its shared package. This is usually more productive than starting in the largest React component.

Three boundaries to keep in mind

The native document is authoritative. An embedded molecule editor, imported CDXML and a plugin report are views or boundary representations. None replaces ChemDraftDocument. Mutations go through validated patches, with undo and selection behavior owned by the host workflow.

Chemical meaning is preserved or explicitly declined. Moving a label, applying a style or exporting a file must not silently change atoms, bond orders, charge, isotopes, radicals or stereochemistry. A chemistry result needs its method, interpretation and status. An unavailable method is different from one the user did not request.

Extensions use declared capabilities. A plugin imports @chemdraft/plugin-api, requests permissions and invokes typed host capabilities. It does not reach into React state or private app functions. Agent-facing document logic belongs in shared packages, so a headless caller and the desktop do not maintain competing implementations.

Work on both platforms

macOS and Windows ship from the same commit under one version. Common TypeScript logic should accept the platform where behavior differs, allowing tests to exercise both branches on one host. Native changes need matching Rust platform branches and actual verification on both operating systems.

macOS has an application-wide menu; Windows attaches its menu only to the document window. Floating utilities belong to that window and must preserve drawing focus. Keyboard conventions use Command on macOS and Control on Windows where appropriate. Read macOS and Windows Differences before changing native integration.

Finish a complete contribution

Keep the change within the active plan, add meaningful tests and authoring documentation where relevant, and report exactly what ran. Runtime changes require a new CURRENT_BUILD_STAMP in apps/desktop/src/MainWindow.tsx. Launch from your own worktree and record its label; never replace the stable installed app with a branch build.

Changes land through a pull request with green CI. A useful handoff includes the summary, explicit changed files, test commands and results, macOS and Windows verification status, known limitations, and one recommended next task.

Next

• Building from Source
• Architecture Overview
• Project Rules
• Licensing and Notices