GTC Sync

GTC-Sync

An Obsidian plugin that synchronizes Obsidian notes with GTC (An ERP by Etudes Informatiques et Services) through a WebSocket.

Overview

The plugin maintains a persistent WebSocket connection with a GTC-Sync server. Synchronization is bidirectional: local changes are pushed to the server, and the server can remotely control the Obsidian vault.

Only notes that have an IdNote field in their YAML frontmatter participate in synchronization.

---
IdNote: <identifier assigned by the server>
---

---

Data flow

Plugin → Server

When a note with IdNote is modified or renamed, the plugin automatically sends its content to the server (note.saved) after a 1-second debounce. The payload includes the content line by line and file metadata (creation and modification dates).

Only the active file triggers an outgoing sync. Changes applied by Obsidian Sync from other devices are not propagated.

On rename, the plugin also synchronizes every note that references the renamed file (Obsidian resolved links are re-evaluated).

Server → Plugin

The server can send JSON commands that the plugin executes directly on the vault:

---

WebSocket protocol

Messages are JSON objects. Each exchange uses an id field (unique identifier generated by the plugin) to match responses to requests.

Authentication: on connection open, if a token is configured, the plugin sends { type: "auth", token } before any other exchange. The server replies with auth.ok or auth.error.

Outgoing requests (plugin → server): the plugin waits for the response with a 10-second timeout. Past that delay, the request is rejected.

Incoming commands (server → plugin): the plugin executes the command and replies with { id, ok: true, result } or { id, ok: false, error }.

Session replacement: if another plugin instance connects with the same token, the server sends session.replaced. The plugin stops auto-reconnecting and shows an alert.

---

Loop prevention

Any remote write (note.create, note.replace, note.move) temporarily marks the file in updatingFiles. The vault modify event ignores those files to prevent a remote change from immediately triggering an outgoing sync back to the server.

---

Quick notes

A quick note is a blank note created with a server-assigned IdNote. It lets you link a new Obsidian note to an existing entry on the server side.

Several ways to create one:

• Left ribbon icon (pen)
• File/folder context menu → Create quick note
• Command palette → GTC-Sync: Create quick note

The note is created in the folder of the target file, or the active file's folder if no target is selected. Its name follows the format Quick Note YYYY-MM-DD HH-MM-SS.md.

You can also link an existing note to a server identifier via the context menu → Send to quick note: this injects an IdNote into the selected note's frontmatter.

---

Connection indicators

The connection status is shown in two places:

• Status bar (bottom of the window): GTC-Sync : ● with a tooltip
• Left ribbon (icon): changes based on current state

When a synced note is opened or modified while the plugin is disconnected, an alert modal appears with a Reconnect button.

---

Error handling

Server errors on save are surfaced via modals:

• Code 74: the note is reserved by another user — local changes may be lost.
• Code 78: the note does not exist anymore.
• Other codes: generic error modal showing the code and message returned by the server.

---

Settings

Accessible via Obsidian Settings → GTC-Sync.

Settings are stored locally via localStorage (key gtc-sync-plugin-local-settings) and are not synchronized by Obsidian Sync across devices.

Changing the URL or token automatically restarts the connection.

---

Available commands

---

Language support

The plugin adapts to the Obsidian interface language automatically. All user-facing text — menus, commands, notices, modals, settings, error messages, and debug logs — is available in:

• English (default)
• French (fr)

Language detection uses Obsidian's internal locale (window.moment.locale()). No configuration is needed: switching Obsidian's language in its settings is enough.

To add a new language, open src/i18n.ts, duplicate the en block, fill in the translations, and register the new locale in the detectLang function.

---

Development

# Development (watch + inline sourcemaps)
npm run dev

# Production build (TypeScript check + optimized bundle)
npm run build

Validation is done manually inside Obsidian. There is no automated test suite.

Source structure