Skip to content

README.md

Latest commit

 

History

History
375 lines (266 loc) · 9.72 KB

README.md

File metadata and controls

375 lines (266 loc) · 9.72 KB

📝 Real-Time Notes Pad (WIP)

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.

Perfect for families, small teams, and privacy-conscious users who want to keep their notes completely under their control.

Web version

🔄 Data Flow

sequenceDiagram
    participant U1 as User 1<br/>(Desktop)
    participant U2 as User 2<br/>(Mobile)
    participant WS as WebSocket<br/>Manager
    participant API as FastAPI Server
    participant DB as SQLite<br/>Database

    Note over U1,U2: Real-time Collaboration

    U1->>WS: Edit note content
    WS->>API: Process change
    API->>DB: Save to database
    API->>WS: Broadcast change
    WS-->>U2: Live update
    
    Note over U1,U2: Metadata Updates
    U2->>API: Change note title
    API->>DB: Update metadata
    API-->>U1: Title updated
    
    Note over API,DB: All data stays local
Loading

Real-Time vs REST API

  • 📡 WebSocket: Real-time content changes, cursors, typing indicators
  • 🔄 REST API: Initial load, metadata (title, tags), note management
  • 💾 Database: Single source of truth for all data

🏠 Self-Hosted Architecture

  • 🍓 Raspberry Pi friendly: Runs efficiently on ARM devices
  • 🔒 Privacy-first: Your notes never leave your network
  • 🌐 Multi-platform: Web, desktop, and mobile apps
  • 📱 Local network: Fast, low-latency collaboration
  • 💾 SQLite database: Simple, reliable, zero-config storage

🚀 Features

  • Real-time collaborative editing via WebSocket
  • Firebase Authentication (works with self-hosted setup)
  • Auto-saving with intelligent debouncing
  • Multiple notes management
  • Cross-platform clients (Web, Desktop, Mobile)
  • Simple backup (single SQLite file)
  • Docker deployment
  • Electron desktop app
  • React Native mobile app

📦 Tech Stack

Backend (Self-Hosted Server)

  • FastAPI (Python) - High-performance API
  • SQLite - Lightweight, serverless database
  • WebSocket - Real-time communication
  • Firebase Auth - User management

Frontend (Multi-Platform)

  • React + TypeScript - Web application
  • Tailwind CSS - Styling
  • Electron - Desktop wrapper
  • React Native - Mobile apps (planned)

Deployment

  • Docker - Containerized deployment
  • Docker Compose - Single-command setup

🛠 Quick Start

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/jonathas/realtime-notes-pad.git
cd realtime-notes-pad

# Start with Docker Compose
docker-compose up -d

# Access your notes at http://localhost:8000

Option 2: Manual Setup

# 1. Start the backend
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
fastapi dev app/main.py

# 2. Start the frontend
cd frontend
npm i
npm run dev

Option 3: Desktop App (Electron)

# Clone and setup
git clone https://github.com/jonathas/realtime-notes-pad.git
cd realtime-notes-pad

# Install frontend dependencies
cd frontend
npm install

# Run in development mode (starts both web server and Electron)
npm run electron-dev

# Build for production
npm run build-electron

# Create distributable packages
npm run dist

🧪 Testing

Backend API Tests

The backend includes comprehensive tests covering:

  • Unit tests - NoteService business logic
  • API tests - REST endpoints
  • WebSocket tests - Real-time functionality
# Navigate to backend directory
cd backend

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test categories
pytest -v -m "not slow"        # Skip performance tests
pytest -v -m "slow"            # Only performance tests
pytest -v -k "websocket"       # Only WebSocket tests

# Run with coverage report
pytest --cov=app --cov-report=html

Test Categories:

  • 🔧 Unit Tests: Core business logic (NoteService)
  • 🌐 API Tests: REST endpoint validation
  • 📡 WebSocket Tests: Real-time communication

All tests use isolated in-memory databases for fast, reliable testing.

📁 Project Structure

realtime-notes-pad/
├── frontend/                 # React web application
│   ├── src/
│   │   ├── components/
│   │   │   ├── Editor/       # Real-time text editor
│   │   │   ├── Toolbar/      # Navigation and controls
│   │   │   └── Modals/       # Settings and note selection
│   │   ├── services/
│   │   │   ├── storage.ts    # API client
│   │   │   ├── firebase.ts   # Authentication
│   │   │   └── websocket.ts  # Real-time communication
│   │   └── hooks/            # React hooks
│   ├── electron/             # Desktop app wrapper
│   │   └── main.js           # Electron main process
│   ├── public/
│   └── package.json
├── backend/                  # FastAPI server
│   ├── app/
│   │   ├── routers/          # API endpoints
│   │   ├── services/         # Business logic
│   │   ├── models/           # Database models
│   │   └── auth/             # Authentication
│   ├── tests/                # Comprehensive test suite
│   │   ├── test_note_service.py    # Unit tests
│   │   ├── test_notes_api.py       # API tests
│   │   ├── test_websockets.py      # WebSocket tests
│   ├── data/                 # SQLite database
│   └── requirements.txt
├── docker-compose.yml        # Development setup
└── README.md

🌐 Client Applications

Web App

  • Access via any modern browser
  • Works on desktop and mobile
  • Real-time collaboration

🖥️ Desktop App (Electron) - ⚠️ Work in Progress

A native desktop wrapper for the web app with enhanced features.

Desktop version

⚠️ Current Status: Not Ready for Production

The Electron app is currently under development and missing critical authentication features:

  • ❌ Firebase Authentication: Google sign-in doesn't work properly in Electron
  • ❌ OAuth Flow: Browser-based auth redirects don't return to the app
  • ❌ Custom Protocol Handler: Not yet implemented for auth callbacks

Built Apps Location:

  • Development: Runs from http://localhost:5173
  • Production: Packaged in dist-electron/ folder

Planned Features:

  • 🖥️ Native window: Proper desktop integration
  • 📱 Cross-platform: Windows, macOS, and Linux
  • 🔐 Embedded auth: In-app Google authentication
  • 🔄 Auto-updater ready: Built-in update mechanism

For now, please use the web app at http://localhost:8000 which has full authentication support.

🌐 PWA Features (Connection-Required)

This app is designed as a connected-only PWA that requires real-time WebSocket connection:

  • 📱 App-like experience: Installs like a native app
  • 🚀 Fast loading: Static assets cached locally
  • 🔄 Smart reconnection: Automatically reconnects when server available
  • 📡 Connection awareness: Shows connection status and graceful degradation
  • 💾 No offline storage: Notes require server connection (by design)

Why No Offline Mode?

  • Real-time collaboration requires active connections
  • Notes are stored securely on your self-hosted server
  • Prevents sync conflicts and data loss
  • Simpler architecture and better security

Mobile Apps (Planned)

  • React Native for iOS/Android

🔧 Configuration

Environment Variables

# Frontend (.env)
# Firebase Configuration
VITE_FIREBASE_API_KEY=your_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
VITE_FIREBASE_APP_ID=1:123456789:web:abcdef123456

# API Configuration
VITE_API_URL=http://localhost:8000

🔒 Privacy & Security

Data Privacy

  • ✅ Local storage: Notes never leave your network
  • ✅ No cloud dependencies: Works completely offline
  • ✅ Your data, your control: Easy backups and migrations
  • ✅ Firebase auth only: User accounts, not note data

Security Features

  • 🔐 JWT authentication: Secure user sessions
  • 🛡️ CORS protection: Configurable origins
  • 🔄 Automatic backups: SQLite file copying
  • 🚫 No telemetry: No tracking or analytics

🔄 Backup & Restore

Backup Your Notes

# Simple file copy
cp data/notes.db backups/notes-$(date +%Y%m%d).db

Restore from Backup

# Stop the service
docker-compose down

# Restore database
cp backups/notes-20240105.db data/notes.db

# Restart
docker-compose up -d

🤝 Use Cases

Perfect For

  • 👨‍👩‍👧‍👦 Families: Shared grocery lists, vacation planning
  • 🏢 Small teams: Meeting notes, project planning
  • 🔒 Privacy-conscious users: Keep sensitive notes local
  • 🏠 Home labs: Self-hosted enthusiasts
  • 📚 Students: Collaborative study notes
  • ✍️ Writers: Draft sharing and feedback

Why Self-Hosted?

  • No subscription fees - One-time setup
  • Complete privacy - Your data stays home
  • Fast performance - Local network speed
  • Works offline - No internet required
  • Customizable - Modify to fit your needs

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Run tests: cd backend && pytest
  5. Test on Raspberry Pi if possible
  6. Submit a pull request

📜 License

MIT © Jonathas Ribeiro

Built for self-hosters, by self-hosters 🏠