Note Sync Now / Brave Sync Notes

End-to-End Encrypted Note Synchronization

📚 Documentation • 🏠 Project Home • 📦 Releases • 🤝 Contributing

English | 简体中文

---

✨ Features

🔐 End-to-End Encryption Client-side AES-256-GCM encryption Server only relays ciphertext 12-word mnemonic recovery ⚡ Real-time Sync WebSocket + Socket.IO Automatic chunked transfer (>50KB) Smart reconnection

🔄 Conflict Resolution Three-way merge algorithm Manual resolution UI Version tracking 💾 Multi-Layer Storage Server: Redis / SQLite / Memory Client: IndexedDB / LocalStorage Automatic fallback

---

🚀 Quick Start

Prerequisites

• Node.js 18+ (20 LTS recommended)
• npm 9+
• Redis (optional, for persistent storage)

Installation

# 1. Clone the repository
git clone https://github.com/LessUp/brave-sync-notes.git
cd brave-sync-notes

# 2. Start the server
cd apps/api && npm ci && cp .env.example .env && node index.js

# 3. Start the client (new terminal)
cd apps/web && npm ci && cp .env.example .env && npm run dev

Access the application:

• Client: http://localhost:5173
• Server: http://localhost:3002

Docker Deployment

cd brave-sync-notes
docker-compose up -d

For detailed setup instructions, see our Getting Started Guide.

---

⌨️ Keyboard Shortcuts

Shortcut	Action
Ctrl/⌘ + S	Save
Ctrl/⌘ + B	Toggle sidebar
Ctrl/⌘ + P	Toggle preview
Ctrl/⌘ + H	Toggle history
Ctrl/⌘ + N	New note
Ctrl/⌘ + /	Toggle dark mode
Esc	Close modal

---

📖 Documentation

We provide comprehensive documentation in both English and 简体中文.

Specifications (Single Source of Truth)

Spec	Description
Product Requirements	Feature definitions & acceptance criteria
Core Architecture	System design & technical decisions
API Specification	WebSocket & REST API definitions
Database Schema	Data models & storage structure
Testing Strategy	Test frameworks & correctness properties

User & Developer Guides

English Documentation

Document	Description
Getting Started	Complete installation and setup guide
Architecture	System design and data flow
Deployment	Production deployment guide
Security	Encryption and synchronization
Contributing	Development guidelines
API Reference	WebSocket and REST API docs

中文文档

文档	说明
快速入门	完整安装和设置指南
架构说明	系统设计与数据流
部署指南	生产环境部署指南
安全机制	加密与同步机制
贡献指南	开发规范
API 参考	WebSocket 和 REST API 文档

Full Documentation Site: https://lessup.github.io/brave-sync-notes/

---

🏗️ Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                        Clients                              │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐     │
│  │  Browser A  │◄──►│  Browser B  │◄──►│  Mobile App │     │
│  └──────┬──────┘    └──────┬──────┘    └──────┬──────┘     │
│         │                  │                  │             │
│  [React + Vite]      [Zustand State]   [AES-256 Crypto]    │
└─────────┬──────────────────┬──────────────────┬─────────────┘
          │                  │                  │
          └──────────────────┼──────────────────┘
                             │ WebSocket
                             ▼
┌─────────────────────────────────────────────────────────────┐
│                       Server                                │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  Express + Socket.IO                                   │  │
│  │  • Room Management                                     │  │
│  │  • Event Distribution                                  │  │
│  │  • Rate Limiting                                       │  │
│  └──────────────────┬────────────────────────────────────┘  │
│                     │                                       │
│  ┌──────────────────▼──────────────────┐                   │
│  │      Persistence Layer              │                   │
│  │  ┌──────────┐ ┌──────────┐         │                   │
│  │  │  Redis   │ │  SQLite  │ (Fallback)                  │
│  │  └──────────┘ └──────────┘         │                   │
│  └─────────────────────────────────────┘                   │
└─────────────────────────────────────────────────────────────┘

For detailed architecture, see Architecture Documentation.

---

🛠️ Development

Testing

# Client tests
cd apps/web && npm test -- --run

# Server tests
cd apps/api && npm test

# Property-based tests
cd apps/api && npm run test:property

Project Structure

brave-sync-notes/
├── apps/
│   ├── web/             # React + Vite frontend
│   │   ├── src/         # Source code
│   │   └── tests/       # Test files
│   └── api/             # Express + Socket.IO backend
│       ├── src/         # Source code
│       └── tests/       # Test files
├── docs/                # Documentation (EN/ZH)
├── changelog/           # Version history
└── .github/workflows/   # CI/CD configuration

---

📊 Project Status

Metric	Status
Latest Version	v2.2.0
Build Status
Documentation
License	MIT

---

🔄 OpenSpec Integration

This project uses OpenSpec for spec-driven development with AI assistance. All changes are managed through structured proposals.

Quick Commands

Command	Description
/opsx:propose	Create a new change proposal
/opsx:explore	Explore ideas before committing
/opsx:apply	Implement tasks from a change
/opsx:archive	Archive a completed change

Workflow

/opsx:propose "feature-name"  →  /opsx:apply  →  /opsx:archive

Two-Tier Specification System

Directory	Purpose
specs/	Stable, approved specifications (Single Source of Truth)
openspec/	Change management and delta specs

See AGENTS.md for detailed workflow instructions.

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick links:

• Report a Bug
• Request a Feature
• View Issues

---

📜 License

This project is licensed under the MIT License.

---

❓ FAQ

Is Redis required?

No, the system automatically falls back to SQLite or in-memory storage if Redis is unavailable.

What's the maximum note size?

Notes up to 5MB are supported through automatic chunked transfer.

How does the 12-word recovery work?

The mnemonic follows the BIP39 standard. Your encryption key is derived from these 12 words, enabling secure recovery on any device.

---

🔧 Troubleshooting

Connection Failed

• Ensure the backend server is running on port 3002
• Check if the port is occupied: lsof -i :3002
• Verify firewall settings allow WebSocket connections

Sync Not Working

• Confirm both devices use the same mnemonic
• Check browser console for errors
• Ensure WebSocket connection is established (green indicator)

Redis Connection Error

• Verify Redis is running: redis-cli ping
• Or let the system fall back to SQLite automatically

---

🙏 Acknowledgments

• React - Frontend framework
• Vite - Build tool
• Socket.IO - Real-time communication
• Zustand - State management
• Express - Web framework

---

Made with ❤️ by LessUp

🌐 Website • 👥 GitHub