Initial commit

docs/architecture.md

@@ -0,0 +1,31 @@
+# Architecture
+
+## Components
+
+- `apps/obsidian-plugin`: Obsidian client plugin for local vault scanning, sync orchestration, merge handling, and user notifications.
+- `apps/sync-server`: Self-hosted HTTP API for device registration and encrypted revision exchange.
+- `packages/sync-protocol`: Shared schemas and request and response types.
+- `packages/sync-engine`: Shared merge, hashing, and crypto helpers.
+
+## Current Data Flow
+
+1. The plugin registers a device with the server and stores the returned device identity and token.
+2. The plugin creates or imports a local vault key.
+3. The plugin pulls encrypted remote changes and applies them locally for both text notes and binary attachments.
+4. Pull operations are paged so the client can resume from the last applied server revision after an interruption.
+5. The plugin scans syncable vault files, hashes changed content, encrypts it, and pushes encrypted revisions in batches.
+6. The server stores ciphertext, revision metadata, tombstones, device state, and active key status in a file-backed state store.
+7. Each sync run emits client-side diagnostics that can be uploaded to the server and correlated with request logs through request IDs.
+8. Recovery bundles package the vault ID, server URL, and current client-side vault key so a new device can join the same encrypted vault.
+
+## Conflict Policy
+
+- If only one side changed since the last synced base, accept the changed side.
+- If both sides changed, write conflict markers into the local file, create a separate remote conflict copy, and require user review before upload continues.
+
+## Known Gaps
+
+- The server storage backend is durable but still file-based rather than relational.
+- Key distribution between devices still depends on manually sharing a recovery bundle.
+- Full plugin integration tests across multiple Obsidian instances are not implemented yet.
+

docs/deployment.md

@@ -0,0 +1,50 @@
+# Deployment
+
+## Requirements
+
+- Node.js 22 or newer
+- npm 10 or newer
+
+## Install
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Run The Sync Server
+
+```bash
+npm run dev:server
+```
+
+The server listens on `http://localhost:8787` by default.
+
+## Environment Variables
+
+- `PORT`: overrides the default HTTP port.
+- `SYNC_DATA_DIR`: overrides the default data directory. If omitted, the server writes data under `./data` from the workspace root.
+
+## Data Written By The Server
+
+- `data/sync-state.json`: durable encrypted revision metadata, devices, tombstones, and sync history.
+- `data/logs/server.jsonl`: structured JSON-line server and client-sync diagnostics.
+
+## Management Capabilities
+
+- `POST /api/devices/list`: lists known devices for the vault plus active key status.
+- `POST /api/devices/revoke`: revokes a device so it can no longer authenticate.
+- `POST /api/keys/rotate`: stores the currently active vault key identifier.
+- `POST /api/sync/pull`: supports paged pulls through `sinceServerRevision` and `limit`.
+
+## Operational Notes
+
+- The server never needs plaintext note bodies. Clients encrypt before upload and decrypt after download.
+- Request logs include a response header named `x-request-id` for correlating client and server failures.
+- The current storage backend is file-based. It is durable for a single-node deployment but not yet designed for clustered or high-availability hosting.
+- The plugin updates local sync state after each accepted push batch and each applied pull page, which lets interrupted sync runs resume from the last durable checkpoint.