From 37ca507ae49f5562453d7592d850cdab60fa0d18 Mon Sep 17 00:00:00 2001
From: Andras Schmelczer <andras@schmelczer.dev>
Date: Wed, 27 Aug 2025 22:32:52 +0100
Subject: [PATCH] Add Claude file

---
 CLAUDE.md | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..e05e784a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+VaultLink is a self-hosted Obsidian plugin for real-time collaborative file syncing. The project consists of a Rust-based sync server and a TypeScript frontend with three main components: an Obsidian plugin, a sync client library, and a test client.
+
+## Architecture
+
+### Core Components
+
+- **sync-server/**: Rust-based WebSocket server with SQLite database for document versioning and real-time synchronization
+- **frontend/sync-client/**: TypeScript library providing core sync functionality, WebSocket management, and file operations
+- **frontend/obsidian-plugin/**: Obsidian plugin that integrates the sync client with Obsidian's API
+- **frontend/test-client/**: CLI testing tool for the sync functionality
+
+### Key Technologies
+
+- **Backend**: Rust with Axum framework, SQLite with SQLx, WebSockets for real-time sync
+- **Frontend**: TypeScript, Webpack for bundling, Jest for testing
+- **Sync Algorithm**: Uses reconcile-text library for operational transformation
+
+## Development Commands
+
+### Server Development
+```bash
+cd sync-server
+cargo run config-e2e.yml  # Start development server
+cargo test --verbose      # Run Rust tests
+cargo clippy --all-targets --all-features  # Lint Rust code
+cargo fmt --all -- --check  # Check Rust formatting
+```
+
+### Frontend Development
+```bash
+cd frontend
+npm run dev      # Start development mode (watches sync-client and obsidian-plugin)
+npm run build    # Build all workspaces
+npm run test     # Run all tests
+npm run lint     # Lint and format TypeScript code
+```
+
+### Database Setup (Development)
+```bash
+cd sync-server
+sqlx database create --database-url sqlite://db.sqlite3
+sqlx migrate run --source src/app_state/database/migrations --database-url sqlite://db.sqlite3
+cargo sqlx prepare --workspace
+```
+
+### Scripts
+- `scripts/check.sh`: Full CI check (builds, lints, tests both server and frontend)
+- `scripts/e2e.sh`: End-to-end testing
+- `scripts/clean-up.sh`: Clean logs and database files
+- `scripts/bump-version.sh patch`: Publish new version
+- `scripts/update-api-types.sh`: Update TypeScript bindings from Rust types
+
+## Code Structure
+
+### Workspace Configuration
+The frontend uses npm workspaces with three packages:
+- `sync-client`: Core synchronization logic
+- `obsidian-plugin`: Obsidian-specific integration
+- `test-client`: Testing utilities
+
+### Type Generation
+Rust structs generate TypeScript types via ts-rs crate, stored in `sync-server/bindings/` and used by frontend packages.
+
+### Key Files
+- `sync-server/src/`: Rust server implementation with WebSocket handlers
+- `frontend/sync-client/src/sync-client.ts`: Main sync client entry point
+- `frontend/obsidian-plugin/src/vault-link-plugin.ts`: Main Obsidian plugin class
+- `frontend/sync-client/src/services/sync-service.ts`: Core synchronization logic
+
+## Testing
+
+### Running Tests
+- Server: `cargo test --verbose` 
+- Frontend: `npm run test` (runs Jest across all workspaces)
+- E2E: `scripts/e2e.sh`
+
+### Test Structure
+- Rust: Unit tests alongside source files
+- TypeScript: `.test.ts` files using Jest
+- E2E: Uses test-client to simulate multiple concurrent users
+
+## Code Style
+
+### Rust
+- Uses extensive Clippy lints (see Cargo.toml)
+- Follows pedantic linting rules
+- Forbids unsafe code
+- Uses cargo fmt with default settings
+
+### TypeScript
+- Prettier configuration: 4-space tabs, trailing commas removed, LF line endings
+- ESLint with unused imports plugin
+- Consistent across all three frontend packages
\ No newline at end of file