Begleitdienst zur Verwaltung von Vertragsmetadaten (Laufzeiten, Kündigungsfristen, Kosten) mit moderner Weboberfläche, Terminüberwachung und Benachrichtigungen. Der Service ist in TypeScript geschrieben (Express + React) und kann eigenständig oder als Ergänzung zu paperless-ngx betrieben werden.

Highlights

✅ Eigenständige Vertragsdatenbank auf SQLite (better-sqlite3) mit REST-API (Express).
✅ Paperless-Integration (optional): Verknüpft Verträge mit Dokumenten, zieht Metadaten per Token, durchsucht paperless direkt aus der UI.
✅ Modernes React-Frontend (Vite + MUI) mit Dashboard, Vertragsliste, Kalender, Detailansicht und umfangreichen Einstellungen.
✅ Benachrichtigungen & Automatisierung: Scheduler prüft Deadlines, optionaler Mailversand, ntfy-Push, iCal-Feed zum Abonnieren.
✅ Konfigurierbare Authentifizierung: Optionales Login mit JWT, Benutzername/Passwort verwaltbar in den Settings.
✅ Mehrsprachigkeit: UI derzeit auf Deutsch und Englisch lokalisiert.
✅ Docker-ready: Backend und Frontend als Container, Konfiguration via docker-compose.yml.

Projektüberblick

backend/ (TypeScript)
  src/
    index.ts              # Express-Server, Routing, Auth, Settings, Calendar, Paperless-Suche
    contractsStore.ts     # CRUD auf SQLite
    scheduler.ts          # Deadline-Monitor
    paperlessClient.ts    # Paperless-Proxy mit Korrespondenten/Tag-Anreicherung
    notifications.ts      # SMTP & ntfy-Tests, Benachrichtigungen
    runtimeSettings.ts    # Persistente Einstellungen (z.B. Mail, ntfy, Paperless)
    validators.ts         # Zod-Schemas

frontend/ (React + Vite)
  src/
    routes/               # Dashboard, Contracts, Calendar, Settings, Login
    components/           # Listen, Dialoge, Layout, Snackbar etc.
    api/                  # REST-Client (fetch)
    locales/              # de/en Übersetzungen

Getting Started

Voraussetzungen

Node.js ≥ 20.x (Backend & Frontend)
npm oder pnpm
optional Docker / Docker Compose

Lokale Entwicklung

# Backend
npm install
npm run dev            # startet Express per tsx (Hot-Reload)

# Frontend
cd frontend
npm install
npm run dev            # http://localhost:5173 (Proxy auf http://localhost:8000/api)

Hinweis: Die node_modules Verzeichnisse sind aus dem Repository ausgenommen. Vor jedem Build/Start zunächst npm install im jeweiligen Ordner ausführen, damit TypeScript (tsc) verfügbar ist.

Docker Compose

docker compose up --build

API: http://localhost:8112 (siehe Compose)
Frontend: http://localhost:8113
SQLite-Datenbank: Volume contracts-data → /app/data/contracts.db

Konfiguration

Variable	Standard	Beschreibung
`PORT`	`8000`	Port des Express-Servers.
`LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`.
`DATABASE_PATH`	`/app/data/contracts.db`	Pfad zur SQLite-Datei (Volume mounten).
`SCHEDULER_INTERVAL_MINUTES`	`60`	Intervall für Deadline-Checks (5–1440).
`ALERT_DAYS_BEFORE`	`30`	Vorlauf in Tagen für Warnungen.
`AUTH_USERNAME` / `AUTH_PASSWORD`	(leer)	Aktiviert JWT-Login, wenn beide gesetzt sind.
`AUTH_JWT_SECRET`	(leer)	Signatur-Secret (Pflicht bei aktivem Login).
`AUTH_TOKEN_EXPIRES_IN_HOURS`	`12`	Lebensdauer der Tokens.
`PAPERLESS_BASE_URL`	(leer)	API-URL deiner paperless-ngx Instanz.
`PAPERLESS_EXTERNAL_URL`	(leer)	Optionale externe URL für Direktlinks im Browser.
`PAPERLESS_TOKEN`	(leer)	API-Token aus paperless-ngx.
`NTFY_SERVER_URL` / `NTFY_TOPIC`	(leer)	Aktiviert ntfy-Push-Benachrichtigungen.
`NTFY_TOKEN` / `NTFY_PRIORITY`	(leer)	Optionaler Bearer-Token & Priorität.
`MAIL_SERVER` / `MAIL_PORT` / `MAIL_USERNAME` / `MAIL_PASSWORD`	(leer)	SMTP-Settings (TLS optional über `MAIL_USE_TLS`).
`MAIL_FROM` / `MAIL_TO`	(leer)	Absender/Empfänger für Mail-Benachrichtigungen.
`ICAL_SECRET`	(leer)	Optional vorgegebenes Token für den iCal-Feed.

Paperless optional nutzen

Paperless ist nicht verpflichtend. Lässt du PAPERLESS_* leer, bleibt die Vertragsverwaltung voll funktionsfähig (Deadlines, Benachrichtigungen, iCal, ntfy, etc.). Die UI blendet paperless-spezifische Funktionen aus bzw. deaktiviert Buttons und zeigt Hinweise an. Sobald du später eine URL/Token hinterlegst, werden Suche und Direktlinks automatisch freigeschaltet.

Integrationen

Bereits vorhanden

paperless-ngx (optional): Sucht Dokumente, verknüpft sie mit Verträgen, zeigt Metadaten und öffnet Direktlinks zur paperless-Oberfläche.
SMTP-Mail: Verschickt Erinnerungen sowie Testmails aus den Einstellungen.
ntfy: Sendet Push-Alerts (Test-Button in den Settings).
iCal-Feed: Kündigungsfristen abonnierbar in gängigen Kalendern.

Perspektivische Erweiterungen

Einige sinnvolle Ergänzungen, falls du die Plattform weiter denkst:

Nextcloud / ownCloud – Dokumentenverknüpfung oder Dateiimporte via WebDAV/REST.
Seafile / S3 (MinIO, Wasabi) – Ablage von Vertrags-PDFs in einem Objektspeicher.
Slack / Microsoft Teams / Mattermost – Deadlines als Channel-Notifications.
Jira / Asana / Trello – Automatische Tasks zur Kündigung bzw. Verlängerung.
Banking / Finance APIs – Abgleich von Zahlungen oder Lastschriften mit Vertragskosten.
CRM-Integration (HubSpot, Salesforce, Pipedrive) – Verträge direkt im Kundenkontext.

Diese Ideen sind in diesem Repository noch nicht umgesetzt, aber durch die REST-Architektur vergleichsweise leicht nachrüstbar.

Status & Roadmap

Erledigt

Backend-API mit Contracts CRUD, Settings-Storage und optionaler Authentifizierung.
Scheduler + Notification-Pipeline (Mail, ntfy).
Paperless-Integration inkl. Suchdialog, Dokumentdetail, Metadaten-Anreicherung.
React-UI mit Dashboard, Kalender, Vertragsliste/-details, Settings.
Mehrsprachigkeit (Deutsch/Englisch) inkl. Language Switch.
iCal-Feed mit granularen Einträgen und Direktlinks zu Verträgen.
Docker-Setup für Backend und Frontend.

In Arbeit / Offene Punkte

Opt-in/Opt-out-Schalter für Paperless in der Oberfläche (UI zeigt bereits Hinweise).
Additional Integrations (z. B. Nextcloud, Slack) – Konzept klar, Implementation offen.
Weitere Automatisierungen (z. B. automatische Erstellung von Tasks/Kalendereinträgen).
Testsuite / CI-Pipeline (derzeit keine automatisierten Tests).
Mehrbenutzer-Unterstützung & Rechteverwaltung (derzeit Single-User + optionaler Login).

Fühle dich frei, Pull Requests oder Issues mit neuen Ideen zu eröffnen.

Entwicklung & Beiträge

Repository klonen, npm install im Root und in frontend/.
Backend mit npm run dev, Frontend mit npm run dev starten.
Die jeweiligen .env Dateien (oder Docker-Compose Variablen) für deine Umgebung setzen.
Änderungen strukturieren, npm run build im Root und im Frontend ausführen, um Typfehler zu erkennen (TypeScript läuft nur mit installierten Modulen).
Pull Request eröffnen.

Coding Guidelines

TypeScript überall (Backend & Frontend).
Zod-Schemas für Request-Validierung.
Lass paperlessClient die einzige Stelle sein, an der Paperless-HTTP-Aufrufe passieren.
UI nutzt React Query + React Hook Form, MUI-Komponenten (Varianten/Theme konsistent halten).
Lokalisierte Strings über react-i18next.

Lizenz

Noch keine Lizenz festgelegt – bei Bedarf ergänzen (z. B. MIT). Bis dahin gelten die Standardrechte des Autoren.

Viel Spaß mit dem Paperless Contract Companion! Wenn du Feedback oder Integrationsideen hast, gerne melden.

README.md Unescape Escape

Paperless Contract Companion