V2.0 Refactor Summary

What Was Built

1. FastAPI Backend (/backend)

A complete REST API backend that works in both desktop (SQLite) and web (PostgreSQL) modes.

Structure:

backend/
├── app/
│   ├── main.py              # FastAPI application with CORS
│   ├── config.py            # Environment-aware configuration
│   ├── database.py          # SQLAlchemy async setup
│   ├── models/
│   │   ├── base.py         # Base model with timestamps
│   │   ├── book.py         # Book model
│   │   ├── annotation.py   # Highlight, Note, ChatContext
│   │   └── settings.py     # UserSettings model
│   ├── routers/
│   │   ├── books.py        # Book CRUD + file serving
│   │   ├── annotations.py  # Annotations CRUD
│   │   └── settings.py     # Settings management
│   └── services/
│       └── epub_service.py # EPUB processing (metadata, cover)
└── requirements.txt

Key Features:

• ✅ Environment detection (VIBEREADER_DESKTOP=true/false)
• ✅ SQLite for desktop, PostgreSQL for web
• ✅ File storage in ~/VibeReader/ (desktop mode)
• ✅ EPUB metadata extraction with ebooklib
• ✅ Cover image extraction and base64 encoding
• ✅ SHA256 file hashing for duplicate detection
• ✅ Full CRUD for books, highlights, notes, chat contexts
• ✅ Reading progress tracking
• ✅ Settings persistence

API Endpoints:

POST   /api/books/import              # Import EPUB
GET    /api/books                     # List books
GET    /api/books/{id}                # Get book
GET    /api/books/{id}/file           # Download EPUB
PATCH  /api/books/{id}/progress       # Update progress
DELETE /api/books/{id}                # Delete book

POST   /api/annotations/highlights    # Create highlight
GET    /api/annotations/highlights/book/{id}
PATCH  /api/annotations/highlights/{id}
DELETE /api/annotations/highlights/{id}

POST   /api/annotations/notes         # Create note
GET    /api/annotations/notes/book/{id}
GET    /api/annotations/notes/range/{book_id}/{cfi}
PATCH  /api/annotations/notes/{id}
DELETE /api/annotations/notes/{id}

POST   /api/annotations/chat-contexts
GET    /api/annotations/chat-contexts/book/{id}
GET    /api/annotations/chat-contexts/range/{book_id}/{cfi}
PATCH  /api/annotations/chat-contexts/{id}
DELETE /api/annotations/chat-contexts/{id}

GET    /api/settings
PATCH  /api/settings/reading
PATCH  /api/settings/api

2. Electron Desktop Wrapper (/desktop)

Electron application that spawns the FastAPI backend and loads the React frontend.

Files:

• main.js - Main process (window management, backend spawning)
• preload.js - IPC bridge (exposes safe APIs to renderer)
• package.json - Electron + electron-builder config

Features:

• ✅ Spawns Python backend on startup
• ✅ Loads frontend from Vite dev server (dev) or built files (prod)
• ✅ Native file picker for EPUB import
• ✅ Platform detection
• ✅ Graceful backend shutdown
• ✅ Health check before showing window

Build Configuration:

• macOS: .dmg, .zip
• Windows: .exe (NSIS installer), portable
• Linux: .AppImage, .deb

3. Frontend API Services (/frontend/src/services)

New TypeScript services that replace IndexedDB with REST API calls.

Files Created:

• apiClient.ts - Platform-aware HTTP client
• bookApiService.ts - Book operations
• annotationApiService.ts - Annotation operations
• settingsApiService.ts - Settings operations

Key Features:

• ✅ Auto-detects Electron vs web mode
• ✅ Gets API URL from Electron IPC or environment
• ✅ Type-safe interfaces matching backend models
• ✅ Error handling with detailed messages
• ✅ File upload support

4. Documentation

• README.md - Updated with v2.0 architecture
• docs/getting-started/development.md - Complete dev setup guide
• docs/development/migration-guide.md - Step-by-step migration from v1
• docs/fixes/refactor-summary.md - This file
• backend/README.md - Backend-specific docs

What Still Needs to Be Done

Priority 1: Frontend Migration

• Update Library.tsx to use bookApiService
• Update Reader.tsx to load EPUB from API URL
• Update ReaderSettings.tsx to use settingsApiService
• Update AnnotationPanel.tsx to use annotationApiService
• Update UnifiedContextMenu.tsx for highlight creation
• Update NoteDialog.tsx for note management
• Update ChatPanel.tsx for chat context storage

Priority 2: Desktop Build

• Set up PyInstaller to bundle Python runtime
• Create build scripts for all platforms
• Test desktop builds on macOS, Windows, Linux
• Set up code signing certificates
• Configure auto-updater

Priority 3: Testing

• Backend unit tests (pytest)
• Frontend component tests
• E2E tests (Playwright)
• Desktop app smoke tests

Priority 4: Features

• Nostr integration (NIP-84 highlights)
• AI chat with LangGraph
• Cloud storage adapter for web mode
• Data export/import
• Search functionality

Migration Strategy

Phase 1: Parallel Implementation (Current)

• ✅ New API services exist alongside old IndexedDB code
• ✅ No breaking changes to existing functionality
• ✅ Can test backend independently

Phase 2: Component-by-Component Migration (Next)

1. Start with Library.tsx (simplest)
2. Move to Reader.tsx (core functionality)
3. Migrate annotation components
4. Update settings management
5. Remove old IndexedDB code

Phase 3: Desktop Build (After Migration)

1. Bundle Python with PyInstaller
2. Test desktop builds
3. Set up CI/CD for releases

Phase 4: Production (Final)

1. Deploy web version
2. Publish desktop apps
3. Set up auto-updates

Testing the Backend

1. Install Dependencies

cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Run Backend

export VIBEREADER_DESKTOP=true
uvicorn app.main:app --reload --port 8000

3. Test API

Visit http://localhost:8000/docs for interactive API testing

4. Test with curl

# Health check
curl http://localhost:8000/health

# Import book
curl -X POST http://localhost:8000/api/books/import \
  -F "file=@/path/to/book.epub"

# Get books
curl http://localhost:8000/api/books

Testing the Desktop App

1. Install Dependencies

cd desktop
npm install

2. Run in Dev Mode

npm run dev

This will: 1. Start backend from ../backend/venv/bin/python 2. Load frontend from http://localhost:5173 (Vite dev server) 3. Open Electron window

3. Check Logs

• Backend logs appear in terminal
• Frontend logs in Electron DevTools (Cmd+Option+I)

Database Locations

Desktop Mode

~/VibeReader/
├── vibereader.db      # SQLite database
├── books/             # EPUB files
│   └── {hash}.epub
└── covers/            # Cover images (future)

Inspecting Database

sqlite3 ~/VibeReader/vibereader.db

.tables
SELECT * FROM books;
SELECT * FROM highlights;

Architecture Benefits

Code Reuse

• Frontend: 100% shared between desktop and web
• Backend: ~95% shared (only storage layer differs)

Flexibility

• Desktop: Local-first, privacy-focused
• Web: Cloud-hosted, auto-sync
• Both: Same features, same codebase

Future-Proof

• Easy to add features to both versions
• Can switch between SQLite and PostgreSQL
• Can add cloud storage adapters
• Can integrate external services (Nostr, AI)

Next Steps

1. Test the backend - Make sure it works standalone
2. Start migration - Begin with Library.tsx
3. Iterate - Migrate one component at a time
4. Test thoroughly - Ensure no regressions
5. Remove old code - Clean up IndexedDB services
6. Build desktop - Set up PyInstaller bundling
7. Deploy - Web version and desktop releases

Questions?

See the documentation: - Development Setup - Setup and workflow - Migration Guide - Migration details - Electron Architecture - Desktop architecture