SimpleCRM

SimpleCRM is a desktop-based Customer Relationship Management (CRM) application built with Electron, React, and TypeScript. It bundles essential CRM features on your local machine, helping you manage customers, products, deals, tasks, and your schedule. It also offers optional one-way data synchronization from your JTL MSSQL database. A self-hostable server edition (Fastify API + PostgreSQL, deployed with Docker) is also available — see Server edition (Docker) below. Updating: see Aktualisieren (Update / Upgrade).

Features

• Customer Management: Create, Read, Update, and Delete customer records.
• Product Management: Keep track of your local product inventory and details.
• Deal Tracking: Create, manage, and visualize your sales deals. Link products and monitor stages from lead to win.
• Task Management: Create and manage tasks linked directly to customers.
• Calendar Integration: Schedule appointments, meetings, and reminders within the app.
• JTL Synchronization (Optional): Sync Customer and Product data from an external JTL MSSQL database into your local CRM (one-way sync).
• E-Mail (IMAP + POP3 + SMTP, Desktop): Accounts support IMAP or POP3 (node-pop3); passwords in keychain. E-Mail → SMTP & KI configures outgoing mail (nodemailer), optional separate SMTP password, Sent-Ordner for IMAP-Append, Google and Microsoft OAuth (refresh tokens in keychain; IMAP XOAUTH2), and an OpenAI-compatible API for composer transforms. IMAP: first sync loads the newest messages only (capped); incremental UID search; optional server thread id when supported; background IDLE + periodic sync. POP3: UIDL-based incremental fetch.
• CRM-style mail: JWZ-style threading from Message-ID / References, ticket codes [SCR-…], customer link, internal notes, categories, assignment to team members, attachments stored under userData (≤25 MB/file) with open / save as, soft delete / restore, archive, views Inbox / Sent / Drafts / Archive, search.
• Workflows: E-Mail → Workflows — React Flow visual editor (compiles to JSON), triggers inbound, outbound, draft_created, schedule (cron + optional account sync per workflow); actions include forward_copy, tag_attachment_meta, category, tags, etc. Cron jobs reload when workflows are saved. The server edition runs schedule workflows too (minute tick per workspace, workspace time zone, each slot fires once, no catch-up older than 15 minutes; a schedule fires only after it was saved once in the server).
• Templates & KI: Canned responses and custom AI prompts under SMTP & KI; HTML composer (React Quill) with plain-text fallback for SMTP.
• Reporting & DSGVO: Mail-Report (/email/reporting) with volume/unread/archived/workflow-run stats; ZIP data export (metadata + attachment files, no passwords) under SMTP & KI.
• Plan vs. Stand: siehe docs/EMAIL_PHASES.md.
• Dokumentation E-Mail: Entwickler/LLM · Anwender · Learnings · Deep Review · Changelog
• Not implemented (optional / later): Omni-channel, SLA automation/escalation, full React Flow branching per edge, raw-mail full archive in export.
• Local Database: All your CRM data is stored securely and locally using SQLite (better-sqlite3).
• Secure Configuration: MSSQL connection details are stored securely using your OS keychain via Keytar (keytar).

How it Works

SimpleCRM leverages the Electron framework to deliver a web-powered experience on your desktop:

1. Main Process (electron/main.ts): Handles window management, background logic, database interactions (SQLite & MSSQL), and inter-process communication (IPC). Manages essential services including sqlite-service, mssql-keytar-service, and sync-service.
2. Renderer Process (src/): The user interface built with React and Vite. Communicates with the Main process using secure IPC calls (defined in electron/preload.ts) to fetch and update data.
3. Database (electron/sqlite-service.ts, electron/database-schema.ts): Manages the SQLite database (database.sqlite in your app data folder), defining the schema and handling all data operations (Create, Read, Update, Delete).
4. MSSQL & Sync (electron/mssql-keytar-service.ts, electron/sync-service.ts): Connects securely to your JTL MSSQL database, fetches customer and product data, and updates your local SQLite database.
5. UI Components (src/components/): Built with Shadcn/ui library for a consistent and customizable user interface.

Tech Stack

• Framework: Electron, React
• Language: TypeScript
• UI: Shadcn/ui, Tailwind CSS
• Routing: TanStack Router
• Local Database: SQLite (via better-sqlite3)
• External DB Connection: mssql package
• Secure Storage: keytar
• Build Tool: Vite
• Bundler/Packager: Electron Builder

Setup & Installation

1. Clone the Repository:

   git clone <your-repository-url>
   cd simplecrmelectron

2. Install Dependencies:

   corepack enable
   corepack prepare pnpm@11.13.1 --activate
   pnpm install

   The root workspace is pinned to Node.js 24 LTS, pnpm 11.13.1, and TypeScript 7.0.2+. pnpm resolves the root peer-dependency tree without --legacy-peer-deps.
3. Prepare Native Modules: Node 24 and Electron 43 use different native ABIs. The postinstall script caches both better-sqlite3 builds and leaves the workspace ready for Node-based tests. Electron commands select their cached ABI automatically and restore Node afterwards. If you encounter an ABI error, run:

   pnpm run native:initialize
   pnpm run native:status

   Do not run electron-rebuild directly; that replaces the single active binary without preserving the other runtime.

Windows users: For a detailed step-by-step guide using PowerShell (including prerequisites like Visual Studio Build Tools, troubleshooting native module errors, and more), see docs/SETUP_WINDOWS.md.

Running the Application

• Development Mode: Starts the Vite dev server for instant UI updates and the Electron app. The electron:dev script compiles main-process TypeScript in watch mode so IPC handlers (including E-Mail) stay in sync with dist-electron.

  pnpm run electron:dev

  While this command is running, you should not need to manually rebuild after code changes.
• Production Mode: Runs the app as it would be packaged. Build the renderer with pnpm run build:web, compile the Electron main-process TypeScript with pnpm run build:electron:main, or run pnpm run build to do both.

  pnpm run electron:start

Building the Application

To create an installer (.exe, .dmg, etc.):

1. Build the Frontend & Electron Code:

   pnpm run build

   This runs build:web (renderer) and build:electron:main (compiled IPC/services under dist-electron/electron/). The Vite Electron bundle step is included in pnpm run build via vite build.
2. Package with Electron Builder:

   pnpm run electron:build

   The installer will be created in the dist-build directory.

Server edition (Docker)

Beyond the desktop app, SimpleCRM has a self-hostable server edition: a Fastify HTTP API (packages/server) backed by PostgreSQL, fronted by Caddy for TLS, and deployed with Docker Compose from the docker/ directory. It enables multi-user, browser-based access to the same CRM data model.

• Setup: docs/SETUP_SERVER.md — Docker Compose stack (Caddy + PostgreSQL + API), environment/secrets, and first-run owner setup.
• Migrate from the desktop/standalone app: docs/MIGRATION_STANDALONE_TO_SERVER.md.
• Implementation status: docs/SERVER_EDITION_IMPLEMENTATION.md.

CI validates the stack end-to-end in the server-compose-smoke job (.github/workflows/ci.yml): it builds the images, boots PostgreSQL + migrations + API + Caddy, then runs the backup, doctor, and restore-drill profiles.

Aktualisieren (Update / Upgrade)

Diese Anleitung gilt für alle, die SimpleCRM nutzen. Ihre Daten bleiben bei jedem Update erhalten. Bevor sich die Datenbank ändert, legen die installierte Desktop-App und das Server-Update automatisch eine Sicherung an. Welcher Weg für Sie gilt:

Sie nutzen …	So aktualisieren Sie
die Desktop-App unter Windows	A — automatisch
die Desktop-App unter macOS	B — neue .dmg installieren
die Server-Edition (Docker)	C — ein Befehl auf dem Server
SimpleCRM aus dem Quellcode (Entwickler, Linux)	D — Git und Build
die Desktop-App mit einem SimpleCRM-Server verbunden	erst den Server (C), dann die App (A oder B) auf dieselbe Version

Vor jedem Update

1. Release-Hinweise lesen: auf der Release-Seite oder im CHANGELOG.md. Für Server-Betreiber steht dort unter „Upgrade (Server)“, ob etwas zu beachten ist.
2. Zusätzliche Sicherung (empfohlen, dauert eine Minute):
   • Desktop: E-Mail → Einstellungen → Diagnose & Backup → „Vollbackup (ZIP)…“ (Owner oder Admin). Das ZIP enthält Datenbank und Anhänge. Zurückspielen kann es der Owner an derselben Stelle.
   • Server: sh docker/simplecrm backup. Das Update sichert zusätzlich selbst.

A) Desktop-App unter Windows

Die App sucht beim Start nach Updates und lädt neue Versionen im Hintergrund. Installiert wird beim Beenden der App. Beim nächsten Start läuft die neue Version.

• Sofort aktualisieren: Einstellungen → Wartung → „Nach Updates suchen“, danach „Neustart & Aktualisieren“ (Owner oder Admin).
• Oder von Hand: den Windows-Installer (.exe) der neuen Version von der Release-Seite laden und über die bestehende Installation installieren. Deinstallieren ist nicht nötig.

B) Desktop-App unter macOS

Die Mac-Version zeigt eine neue Version an und verlinkt die Release-Seite. Selbst installiert sie sich nicht, weil sie noch nicht von Apple signiert ist.

1. SimpleCRM beenden.
2. Die .dmg der neuen Version von der Release-Seite laden, öffnen und SimpleCRM in „Programme“ ziehen. Die alte App ersetzen.
3. Starten. Blockiert macOS die App („nicht verifizierter Entwickler“): Systemeinstellungen → Datenschutz & Sicherheit → „Dennoch öffnen“. Auf älteren macOS-Versionen genügt im Finder Rechtsklick auf SimpleCRM → Öffnen.

Die Mac-Version gibt es für Apple-Silicon-Macs (M1 und neuer).

Was die Desktop-App beim ersten Start der neuen Version tut

Bevor die neue Version die Datenbank erweitert, legt sie eine vollständige Kopie an: im Datenordner von SimpleCRM (der Ordner, in dem database.sqlite liegt) unter backups/pre-update/, mit alter und neuer Version im Dateinamen. Die letzten drei Kopien bleiben erhalten.

Den Datenordner finden Sie unter Windows in %APPDATA%, unter macOS in ~/Library/Application Support, jeweils im Unterordner SimpleCRM bzw. simplecrm.

Zurück zur vorherigen Version, falls nach einem Update etwas nicht stimmt:

1. SimpleCRM beenden.
2. Im Datenordner database.sqlite umbenennen (z. B. in database.sqlite.neu). Falls vorhanden, auch database.sqlite-wal und database.sqlite-shm wegräumen.
3. Die passende Kopie aus backups/pre-update/ nach database.sqlite kopieren.
4. Die vorherige Version von der Release-Seite installieren und starten.

C) Server-Edition (Docker)

Auf dem Server, im Verzeichnis des geklonten Repositorys:

sh docker/simplecrm update --version latest

--version latest nimmt die neueste veröffentlichte Version (Git-Tag vX.Y.Z). Mit --version v1.1.0 wählen Sie genau eine Version. Ohne --version wird auf den aktuellen Entwicklungsstand von main aktualisiert; für Produktivserver ist das nicht empfohlen.

Der Befehl erledigt alles in sicherer Reihenfolge und bricht beim ersten Fehler ab:

1. gewählte Version auschecken (lokale Änderungen an Dateien des Repositorys stoppen das Update, statt überschrieben zu werden),
2. Datenbank und Anhänge sichern,
3. Images bauen,
4. Datenbank-Migrationen einspielen,
5. alte API stoppen, neue starten,
6. warten, bis die neue API gesund meldet, und die Migrationen prüfen.

Die Anwendung ist nur kurz zwischen Schritt 5 und 6 nicht erreichbar.

Zurück zur vorherigen Version: Das Update behält die Images der vorherigen Version und die Sicherung von direkt davor (die normale Backup-Aufbewahrung löscht sie nicht). Ein Befehl bringt beides zurück, ohne etwas neu zu bauen:

sh docker/simplecrm rollback

Der Befehl zeigt vorher, was passiert, und fragt nach. Nach einem abgebrochenen Update kehrt er zur Version davor zurück, auch wenn danach weitere Versuche gescheitert sind; die Daten spielt er nur zurück, wenn Migrationen schon gelaufen waren. Nach einem erfolgreichen Update macht er dieses Update rückgängig. Dann gehen Änderungen seit dem Update verloren, und der Befehl sagt das vorher. Einzelne Sicherungen spielen Sie mit sh docker/simplecrm restore /backups/db-<Zeitstempel>.dump zurück.

Speicherplatz: Das Update prüft vorher, ob genug Platz frei ist (UPDATE_MIN_FREE_GB, Standard 6 GB). Wird es knapp, leert es zuerst den Docker-Build-Cache; reicht es dann immer noch nicht, bricht es ab, bevor sich etwas ändert. Nach einem erfolgreichen Update bleiben nur die aktuelle und die vorherige Version der SimpleCRM-Images, und der Build-Cache wird auf 2 GB begrenzt (DOCKER_BUILD_CACHE_KEEP_GB). Volumes und Daten löscht das Update nie. Container-Logs sind auf 3 × 10 MB begrenzt, das Zugriffslog von Caddy auf 4 × 25 MB bzw. 14 Tage.

sh docker/simplecrm disk

zeigt, wo der Platz hingeht: Platte, Docker-Images und Build-Cache, Volumes (auch alte Volumes ohne Container), Datenbank, Anhänge, Logs und das Systemjournal. Der Befehl löscht nichts, er gibt nur Hinweise. Das Systemjournal von Ubuntu gehört nicht zu SimpleCRM; begrenzen lässt es sich mit SystemMaxUse=500M in /etc/systemd/journald.conf.d/.

Mails und Anhänge platzsparend, ohne Verlust:

• Mail-Original: Es wird komprimiert gespeichert. Anhänge, die als Datei vorliegen, stehen nicht noch einmal im Original; beim Anzeigen oder Herunterladen wird es byte-genau wieder zusammengesetzt. Jedes Speichern beweist vorher, dass das gelingt, und jedes Lesen prüft die Prüfsumme.
• Suche: Sie nutzt eigene Indizes (Betreff, Text, Adressen, Anhang-Text) und ist davon nicht betroffen.
• Durchsuchbare Anhänge (beide Editionen): PDF, Word (docx, doc), Excel (xlsx, xlsm, xlsb, xls), OpenDocument (odt, ods, odp), PowerPoint (pptx), RTF, HTML und Textdateien (txt, csv, tsv, md, json, xml, log, ics, vcf). Zahlen in Tabellen stehen im Index so, wie sie in der Zelle gespeichert sind: Eine EAN wie 4006381333931 ist mit allen Ziffern auffindbar, auch wenn Excel sie als 4,00638E+12 anzeigt. CSV aus Excel (Windows-1252 oder UTF-16) wird mit Umlauten gelesen. Office-Dateien (auf dem Server auch PDF) werden in einem abgeschotteten Worker gelesen (eigene Speichergrenze, Abbruch nach 30 s), nie ausgeführt. Bereits vorhandene Anhänge, die eine frühere Version nicht lesen konnte, werden nach dem Update einmal im Hintergrund nachgelesen.
• Gleiche Anhänge: Sie belegen nur einmal Platz. Jede Mail behält ihre eigene Datei, per Hardlink auf denselben Inhalt.
• Anhangssicherung: Sie ist inkrementell: Jede Sicherung kopiert nur neue Inhalte, lässt sich aber trotzdem allein vollständig wiederherstellen.
• Umstellung: Bestehende Mails werden nach dem Update im Hintergrund umgestellt. Anhänge werden nie automatisch gelöscht.
• Gelöschte Mails: Die Anhangkopie aus dem Original einer gelöschten Mail wird erst beiseitegelegt (weiter lesbar) und 7 Tage später entfernt, wenn keine Mail sie mehr braucht. So belegen gelöschte Anhänge nicht dauerhaft Platz auf dem Server und in den Sicherungen.
• Beschädigtes Original: Kann ein gespeichertes Original nicht mehr gelesen werden, laufen SPF/DKIM/DMARC- und Rspamd-Prüfung für diese Mail nicht (statt eine nachgebaute Nachricht zu bewerten), und Rspamd lernt sie nicht.

sh docker/simplecrm maintenance

prüft Anhang-Dateien und Mail-Originale gegen die Datenbank und erledigt die Umstellung sofort. Es meldet fehlende oder veränderte Dateien und Dateien ohne Eintrag. Anhänge und Originale löscht es nie; nur Anhangkopien gelöschter Mails werden wie oben beiseitegelegt und nach 7 Tagen entfernt. --check-only prüft nur, --deep liest jede Datei vollständig. Das Update führt am Ende eine kurze Prüfung aus.

Einmalig bei älteren Servern: Kennt Ihr Server --version noch nicht (Stand 1.1.0 oder älter, Meldung unknown update flag), aktualisieren Sie einmal mit sh docker/update.sh. Danach steht --version zur Verfügung.

Details, Sonderfälle und alle Optionen: docs/SETUP_SERVER.md.

D) Aus dem Quellcode

git pull
corepack enable
pnpm install
pnpm run build
pnpm run electron:start

Bei selbst gebauten Ständen legt die App keine automatische Sicherung an. Exportieren Sie vorher ein Backup (siehe „Vor jedem Update“).

Configuration

• MSSQL Connection: Configure the connection to your JTL MSSQL database in the Settings page within the app. Your password is stored securely in your operating system's keychain.