ERitors-Scribe-Desktop/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

ERitors Scribe is an Electron + Next.js desktop application for writers. It uses SQLite with WASM for local storage, supports offline mode with PIN authentication, and encrypts user data with AES-256-CBC.

Commands

# Development (starts Next.js on port 4000 + Electron with hot reload)
npm run dev

# Build for specific platform
npm run build:mac
npm run build:win
npm run build:linux
npm run build:all

Architecture

Process Model

Renderer (Next.js)  <--IPC-->  Main Process  <-->  SQLite DB
       via window.electron.invoke()

• Main process: electron/main.ts - Window management, IPC handlers, OS integration
• Preload script: electron/preload.ts - Secure contextBridge API
• Renderer: Next.js App Router with static export (output: 'export')

Key Directories

• electron/ - Main process code (IPC handlers, database, storage)
• electron/ipc/ - IPC handlers organized by domain (book, chapter, character, etc.)
• electron/database/ - SQLite service, models, repositories, encryption
• electron/storage/SecureStorage.ts - OS-level secure storage (macOS Keychain, Windows DPAPI)
• app/ - Next.js pages (App Router)
• context/ - React contexts for state management (13+ contexts)
• components/ - React components
• lib/locales/ - i18n translations (fr.json, en.json)

IPC Handler Pattern

All IPC handlers use createHandler<TBody, TReturn>() factory in electron/database/LocalSystem.ts:

// electron/ipc/book.ipc.ts
ipcMain.handle('db:book:books', createHandler<void, BookProps[]>(
    async (userId, _body, lang) => Book.getBooks(userId, lang)
));

// Frontend usage
const books = await window.electron.invoke('db:book:books');

The factory auto-injects userId and lang from secure storage, handles errors uniformly.

State Management

Context-based architecture with providers:

• UserContext - Authenticated user
• BookContext - Current book
• OfflineContext - Offline mode state
• SessionContext - Session data
• LangContext - i18n

Database

• One SQLite file per user: eritors-local-{userId}.db
• Uses node-sqlite3-wasm (WASM-based SQLite)
• AES-256-CBC encryption for stored data
• PBKDF2 key derivation (100K iterations)
• Schema in electron/database/schema.ts

Security

• contextIsolation: true, nodeIntegration: false, sandbox: true
• OS-level secure storage for tokens and encryption keys
• Per-user encryption keys stored in SecureStorage
• Offline PIN hashed with bcrypt

TypeScript Configuration

• tsconfig.json - Next.js/React (renderer)
• tsconfig.electron.json - Electron main process
• tsconfig.preload.json - Preload script

Build Output

• dist/ - Compiled TypeScript
• out/ - Next.js static export
• release/ - Electron builder output (DMG, NSIS, AppImage)