{"id":29570226,"url":"https://github.com/jonathas/realtime-notes-pad","last_synced_at":"2025-07-19T02:36:44.006Z","repository":{"id":303252168,"uuid":"1014871156","full_name":"jonathas/realtime-notes-pad","owner":"jonathas","description":"A self-hosted real-time collaborative note-taking app built with React, FastAPI, and WebSockets. Inspired by Google Docs, but designed for privacy-first local networks.","archived":false,"fork":false,"pushed_at":"2025-07-06T15:51:41.000Z","size":571,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-06T16:30:02.998Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jonathas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-06T15:15:35.000Z","updated_at":"2025-07-06T15:51:44.000Z","dependencies_parsed_at":"2025-07-06T16:31:23.120Z","dependency_job_id":"6248dd62-e54a-4cd6-a1d4-108c158020f0","html_url":"https://github.com/jonathas/realtime-notes-pad","commit_stats":null,"previous_names":["jonathas/realtime-notes-pad"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jonathas/realtime-notes-pad","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathas%2Frealtime-notes-pad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathas%2Frealtime-notes-pad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathas%2Frealtime-notes-pad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathas%2Frealtime-notes-pad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jonathas","download_url":"https://codeload.github.com/jonathas/realtime-notes-pad/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jonathas%2Frealtime-notes-pad/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265877288,"owners_count":23842960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-19T02:36:42.126Z","updated_at":"2025-07-19T02:36:43.990Z","avatar_url":"https://github.com/jonathas.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 📝 Real-Time Notes Pad (WIP)\n\nA **self-hosted** real-time collaborative note-taking app built with **React**, **FastAPI**, and **WebSockets**. Inspired by Google Docs, but designed for privacy-first local networks.\n\nPerfect for families, small teams, and privacy-conscious users who want to keep their notes completely under their control.\n\n![Web version](/docs/images/web.png)\n\n## 🔄 Data Flow\n\n```mermaid\nsequenceDiagram\n    participant U1 as User 1\u003cbr/\u003e(Desktop)\n    participant U2 as User 2\u003cbr/\u003e(Mobile)\n    participant WS as WebSocket\u003cbr/\u003eManager\n    participant API as FastAPI Server\n    participant DB as SQLite\u003cbr/\u003eDatabase\n\n    Note over U1,U2: Real-time Collaboration\n\n    U1-\u003e\u003eWS: Edit note content\n    WS-\u003e\u003eAPI: Process change\n    API-\u003e\u003eDB: Save to database\n    API-\u003e\u003eWS: Broadcast change\n    WS--\u003e\u003eU2: Live update\n    \n    Note over U1,U2: Metadata Updates\n    U2-\u003e\u003eAPI: Change note title\n    API-\u003e\u003eDB: Update metadata\n    API--\u003e\u003eU1: Title updated\n    \n    Note over API,DB: All data stays local\n```\n\n### Real-Time vs REST API\n\n- **📡 WebSocket**: Real-time content changes, cursors, typing indicators\n- **🔄 REST API**: Initial load, metadata (title, tags), note management\n- **💾 Database**: Single source of truth for all data\n\n## 🏠 Self-Hosted Architecture\n\n- 🍓 **Raspberry Pi friendly**: Runs efficiently on ARM devices\n- 🔒 **Privacy-first**: Your notes never leave your network\n- 🌐 **Multi-platform**: Web, desktop, and mobile apps\n- 📱 **Local network**: Fast, low-latency collaboration\n- 💾 **SQLite database**: Simple, reliable, zero-config storage\n\n---\n\n## 🚀 Features\n\n- [x] Real-time collaborative editing via WebSocket\n- [x] Firebase Authentication (works with self-hosted setup)\n- [x] Auto-saving with intelligent debouncing\n- [x] Multiple notes management\n- [x] Cross-platform clients (Web, Desktop, Mobile)\n- [x] Simple backup (single SQLite file)\n- [x] Docker deployment\n- [ ] Electron desktop app\n- [ ] React Native mobile app\n\n---\n\n## 📦 Tech Stack\n\n### Backend (Self-Hosted Server)\n\n- **FastAPI** (Python) - High-performance API\n- **SQLite** - Lightweight, serverless database\n- **WebSocket** - Real-time communication\n- **Firebase Auth** - User management\n\n### Frontend (Multi-Platform)\n\n- **React + TypeScript** - Web application\n- **Tailwind CSS** - Styling\n- **Electron** - Desktop wrapper\n- **React Native** - Mobile apps (planned)\n\n### Deployment\n\n- **Docker** - Containerized deployment\n- **Docker Compose** - Single-command setup\n\n---\n\n## 🛠 Quick Start\n\n### Option 1: Docker (Recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/jonathas/realtime-notes-pad.git\ncd realtime-notes-pad\n\n# Start with Docker Compose\ndocker-compose up -d\n\n# Access your notes at http://localhost:8000\n```\n\n### Option 2: Manual Setup\n\n```bash\n# 1. Start the backend\ncd backend\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -r requirements.txt\nfastapi dev app/main.py\n\n# 2. Start the frontend\ncd frontend\nnpm i\nnpm run dev\n```\n\n### Option 3: Desktop App (Electron)\n\n```bash\n# Clone and setup\ngit clone https://github.com/jonathas/realtime-notes-pad.git\ncd realtime-notes-pad\n\n# Install frontend dependencies\ncd frontend\nnpm install\n\n# Run in development mode (starts both web server and Electron)\nnpm run electron-dev\n\n# Build for production\nnpm run build-electron\n\n# Create distributable packages\nnpm run dist\n```\n\n---\n\n## 🧪 Testing\n\n### Backend API Tests\n\nThe backend includes comprehensive tests covering:\n\n- **Unit tests** - NoteService business logic\n- **API tests** - REST endpoints\n- **WebSocket tests** - Real-time functionality\n\n```bash\n# Navigate to backend directory\ncd backend\n\n# Run all tests\npytest\n\n# Run with verbose output\npytest -v\n\n# Run specific test categories\npytest -v -m \"not slow\"        # Skip performance tests\npytest -v -m \"slow\"            # Only performance tests\npytest -v -k \"websocket\"       # Only WebSocket tests\n\n# Run with coverage report\npytest --cov=app --cov-report=html\n```\n\n**Test Categories:**\n\n- 🔧 **Unit Tests**: Core business logic (NoteService)\n- 🌐 **API Tests**: REST endpoint validation\n- 📡 **WebSocket Tests**: Real-time communication\n\nAll tests use isolated in-memory databases for fast, reliable testing.\n\n---\n\n## 📁 Project Structure\n\n```bash\nrealtime-notes-pad/\n├── frontend/                 # React web application\n│   ├── src/\n│   │   ├── components/\n│   │   │   ├── Editor/       # Real-time text editor\n│   │   │   ├── Toolbar/      # Navigation and controls\n│   │   │   └── Modals/       # Settings and note selection\n│   │   ├── services/\n│   │   │   ├── storage.ts    # API client\n│   │   │   ├── firebase.ts   # Authentication\n│   │   │   └── websocket.ts  # Real-time communication\n│   │   └── hooks/            # React hooks\n│   ├── electron/             # Desktop app wrapper\n│   │   └── main.js           # Electron main process\n│   ├── public/\n│   └── package.json\n├── backend/                  # FastAPI server\n│   ├── app/\n│   │   ├── routers/          # API endpoints\n│   │   ├── services/         # Business logic\n│   │   ├── models/           # Database models\n│   │   └── auth/             # Authentication\n│   ├── tests/                # Comprehensive test suite\n│   │   ├── test_note_service.py    # Unit tests\n│   │   ├── test_notes_api.py       # API tests\n│   │   ├── test_websockets.py      # WebSocket tests\n│   ├── data/                 # SQLite database\n│   └── requirements.txt\n├── docker-compose.yml        # Development setup\n└── README.md\n```\n\n---\n\n## 🌐 Client Applications\n\n### Web App\n\n- Access via any modern browser\n- Works on desktop and mobile\n- Real-time collaboration\n\n### 🖥️ Desktop App (Electron) - ⚠️ Work in Progress\n\nA native desktop wrapper for the web app with enhanced features.\n\n![Desktop version](/docs/images/electron.png)\n\n#### ⚠️ Current Status: Not Ready for Production\n\nThe Electron app is currently **under development** and missing critical authentication features:\n\n- ❌ **Firebase Authentication**: Google sign-in doesn't work properly in Electron\n- ❌ **OAuth Flow**: Browser-based auth redirects don't return to the app\n- ❌ **Custom Protocol Handler**: Not yet implemented for auth callbacks\n\n**Built Apps Location:**\n\n- **Development**: Runs from `http://localhost:5173`\n- **Production**: Packaged in `dist-electron/` folder\n\n**Planned Features:**\n\n- 🖥️ **Native window**: Proper desktop integration\n- 📱 **Cross-platform**: Windows, macOS, and Linux\n- 🔐 **Embedded auth**: In-app Google authentication\n- 🔄 **Auto-updater ready**: Built-in update mechanism\n\n**For now, please use the web app** at `http://localhost:8000` which has full authentication support.\n\n### 🌐 PWA Features (Connection-Required)\n\nThis app is designed as a **connected-only** PWA that requires real-time WebSocket connection:\n\n- 📱 **App-like experience**: Installs like a native app\n- 🚀 **Fast loading**: Static assets cached locally\n- 🔄 **Smart reconnection**: Automatically reconnects when server available\n- 📡 **Connection awareness**: Shows connection status and graceful degradation\n- 💾 **No offline storage**: Notes require server connection (by design)\n\n#### Why No Offline Mode?\n\n- Real-time collaboration requires active connections\n- Notes are stored securely on your self-hosted server\n- Prevents sync conflicts and data loss\n- Simpler architecture and better security\n\n### Mobile Apps (Planned)\n\n- React Native for iOS/Android\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\n```bash\n# Frontend (.env)\n# Firebase Configuration\nVITE_FIREBASE_API_KEY=your_api_key_here\nVITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com\nVITE_FIREBASE_PROJECT_ID=your-project-id\nVITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com\nVITE_FIREBASE_MESSAGING_SENDER_ID=123456789\nVITE_FIREBASE_APP_ID=1:123456789:web:abcdef123456\n\n# API Configuration\nVITE_API_URL=http://localhost:8000\n```\n\n---\n\n## 🔒 Privacy \u0026 Security\n\n### Data Privacy\n\n- ✅ **Local storage**: Notes never leave your network\n- ✅ **No cloud dependencies**: Works completely offline\n- ✅ **Your data, your control**: Easy backups and migrations\n- ✅ **Firebase auth only**: User accounts, not note data\n\n### Security Features\n\n- 🔐 **JWT authentication**: Secure user sessions\n- 🛡️ **CORS protection**: Configurable origins\n- 🔄 **Automatic backups**: SQLite file copying\n- 🚫 **No telemetry**: No tracking or analytics\n\n---\n\n## 🔄 Backup \u0026 Restore\n\n### Backup Your Notes\n\n```bash\n# Simple file copy\ncp data/notes.db backups/notes-$(date +%Y%m%d).db\n```\n\n### Restore from Backup\n\n```bash\n# Stop the service\ndocker-compose down\n\n# Restore database\ncp backups/notes-20240105.db data/notes.db\n\n# Restart\ndocker-compose up -d\n```\n\n---\n\n## 🤝 Use Cases\n\n### Perfect For\n\n- 👨‍👩‍👧‍👦 **Families**: Shared grocery lists, vacation planning\n- 🏢 **Small teams**: Meeting notes, project planning\n- 🔒 **Privacy-conscious users**: Keep sensitive notes local\n- 🏠 **Home labs**: Self-hosted enthusiasts\n- 📚 **Students**: Collaborative study notes\n- ✍️ **Writers**: Draft sharing and feedback\n\n### Why Self-Hosted?\n\n- **No subscription fees** - One-time setup\n- **Complete privacy** - Your data stays home\n- **Fast performance** - Local network speed\n- **Works offline** - No internet required\n- **Customizable** - Modify to fit your needs\n\n---\n\n### Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. **Run tests**: `cd backend \u0026\u0026 pytest`\n5. Test on Raspberry Pi if possible\n6. Submit a pull request\n\n---\n\n## 📜 License\n\nMIT © Jonathas Ribeiro\n\n**Built for self-hosters, by self-hosters** 🏠\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathas%2Frealtime-notes-pad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjonathas%2Frealtime-notes-pad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjonathas%2Frealtime-notes-pad/lists"}