moneyfy

Selbst gehostete Web-Anwendung zur Planung monatlicher Kosten und Einkünfte. Single-User, deutschsprachige Oberfläche, ausgelegt für den Betrieb im Homelab hinter einem Reverse Proxy.

Status: in Entwicklung. Siehe CHANGELOG.md.

Screenshots

Platzhalter – werden ergänzt, sobald die Oberfläche steht.

Dashboard	Cashflow-Kalender	Firmen
folgt	folgt	folgt

Funktionsumfang

• Wiederkehrende Zahlungen und Einkünfte über vollständige RFC-5545-RRULEs, inklusive Werktagsverschiebung nach NRW-Feiertagen.
• Preishistorie je Vertrag, sodass vergangene Monate betragstreu bleiben.
• Verträge mit Mindestlaufzeit, Kündigungsfrist und automatischer Verlängerung.
• Ratenzahlungen mit Restschuld- und Restratenberechnung.
• Rücklagenbildung für nicht-monatliche Posten.
• Firmenlogos und Markenfarben, lokal zwischengespeichert (siehe unten).
• Auswertungen: Monatsübersicht, Cashflow-Kalender, 12-Monats-Forecast, Kategorien, Abo-Übersicht, Jahresvergleich, Budgets, Sparziele.
• Benachrichtigungen per SMTP und Apprise.

Technischer Stack

Bereich	Technologie
Backend	Python 3.12, FastAPI, SQLAlchemy 2 (async), Alembic, Pydantic v2
Datenbank	PostgreSQL 17
Scheduler	APScheduler (in-process)
Frontend	React 18, TypeScript, Vite, TailwindCSS
Charts	Recharts
Tests	pytest + httpx, vitest + testing-library

Schnellstart (Betrieb)

Voraussetzungen: Docker mit Compose-Plugin und ein externes Netz proxy.

mkdir -p /opt/moneyfy && cd /opt/moneyfy
curl -fsSLO https://git.menzel.center/menzeljonas/moneyfy/raw/branch/main/docker-compose.yml
curl -fsSLO https://git.menzel.center/menzeljonas/moneyfy/raw/branch/main/.env.example
cp .env.example .env

# Mindestens setzen: POSTGRES_PASSWORD, SECRET_KEY, MONEYFY_ADMIN_PASSWORD
$EDITOR .env

docker login git.menzel.center
docker compose up -d

Das Backend wartet auf die Datenbank, spielt die Migrationen ein und legt beim allerersten Start den Kategoriebaum an. Danach läuft die Oberfläche auf http://127.0.0.1:8087. Die vollständige Einrichtung samt Reverse Proxy und Sicherung steht in docs/deployment.md.

Schnellstart (lokale Entwicklung)

Voraussetzungen: Python 3.12, uv, Node 20+, eine erreichbare PostgreSQL-17-Instanz.

git clone https://git.menzel.center/menzeljonas/moneyfy.git
cd moneyfy
cp .env.example backend/.env      # DATABASE_URL und SECRET_KEY anpassen

make install                      # Backend-Abhängigkeiten in backend/.venv
make migrate                      # Schema anlegen
make seed                         # Kategoriebaum und Standardregeln
make dev                          # http://localhost:8000/api/docs

In einem zweiten Terminal das Frontend, es leitet /api an das Backend weiter:

make fe-install
make fe-dev                       # http://localhost:5173

Nützliche Ziele: make check (alle Prüfungen), make test, make lint, make format, make fe-lint, make fe-test, make fe-build.

Konfiguration

Alle Einstellungen kommen aus Umgebungsvariablen; .env.example enthält die vollständige, kommentierte Liste. Die wichtigsten:

Variable	Standard	Bedeutung
DATABASE_URL	–	PostgreSQL-DSN, postgresql:// wird auf asyncpg umgestellt
SECRET_KEY	–	Signaturschlüssel für JWTs, mind. 32 Zeichen (openssl rand -hex 32)
MONEYFY_ADMIN_USER / MONEYFY_ADMIN_PASSWORD	admin / –	Beim Erststart angelegter Benutzer
TIMEZONE	Europe/Berlin	Zeitzone der gesamten Anwendung
HOLIDAY_REGION	DE-NW	Feiertagsregion für Werktagsverschiebungen
LOGO_STORAGE_DIR	/data/logos	Verzeichnis des Logo-Caches
LOGODEV_API_KEY / BRANDFETCH_API_KEY	leer	Optionale Logo-Provider, ohne Schlüssel übersprungen
SMTP_*	leer	Mailversand für Benachrichtigungen
APPRISE_URLS	leer	Komma-separierte Apprise-Ziele
COOKIE_SECURE	true	Hinter HTTPS true, für lokales HTTP false
SCHEDULER_ENABLED	true	Täglicher Benachrichtigungslauf um 07:00

Benachrichtigungen

Ein Job läuft täglich um 07:00 Uhr (Europe/Berlin) im Anwendungsprozess – ohne Redis, ohne Celery. Er prüft vier Anlässe: bald fällige Posten, Kündigungsfristen 30, 14 und 7 Tage vor dem Termin, überschrittene Budgets und Vertragsverlängerungen im kommenden Monat.

Der Duplikatsschutz hängt am Zieltag des Ereignisses, nicht am Versandtag: Eine Fälligkeit am 15.03. wird genau einmal gemeldet, unabhängig davon, an welchem Tag des Vorlaufs der Job läuft. Ein fehlgeschlagener Versand gilt als offen und wird beim nächsten Lauf erneut versucht.

Als Kanäle stehen SMTP (HTML-Mail mit eingebetteten Firmenlogos) und Apprise zur Verfügung. Über Einstellungen → Benachrichtigungen lassen sich Regeln pflegen, eine Testnachricht verschicken und das Versandprotokoll einsehen.

Diagramme

Die Serienfarben stammen aus einer Palette, die gegen die hellen und dunklen Flächen der Anwendung auf Kontrast und Farbfehlsichtigkeit geprüft wurde; ihre Reihenfolge ist Teil dieser Absicherung. Grün und Rot bleiben den Vorzeichen im Text vorbehalten – als Serienpaar wären sie bei Deuteranopie nicht zu unterscheiden. Jedes Diagramm mit mehr als einer Serie führt eine Legende, und zu den Balkendiagrammen lässt sich die Wertetabelle aufklappen.

Einnahmen, Ausgaben und der kumulierte Kontostand stehen bewusst in zwei getrennten Diagrammen untereinander: eine gemeinsame Größenachse würde bei so verschiedenen Größenordnungen einen Zusammenhang vortäuschen.

Logos und Markenfarben

Jede Firma bekommt ein Bild. Die Provider-Kette arbeitet der Reihe nach:

1. simple-icons – rund 3.500 Marken, im Repository unter backend/app/assets/simple_icons.json.gz mitgeliefert. Kein Schlüssel, kein Netzzugriff. Neu erzeugen mit make vendor-icons.
2. logo.dev – nur mit LOGODEV_API_KEY.
3. Brandfetch – nur mit BRANDFETCH_API_KEY und hinterlegter Domain.
4. Favicon – über den Google-Dienst, wenn eine Domain bekannt oder aus dem Namen ableitbar ist.
5. Generierter Avatar – Buchstaben-Monogramm mit fester Farbe aus dem Namens-Hash. Schlägt nie fehl.

Findet die Kette einen eindeutigen Treffer im lokalen Katalog, unterbleiben die Anfragen nach außen vollständig – die Firmenliste verlässt den Server nicht. Im Auswahldialog (POST /api/merchants/{id}/logo/search) läuft dagegen bewusst die ganze Kette, damit Alternativen zur Wahl stehen.

Ausgewählte Logos landen unter LOGO_STORAGE_DIR, benannt nach ihrem SHA-256-Hash, und werden nur über GET /api/logos/{id} ausgeliefert. Beim Seitenaufruf entsteht dadurch kein Zugriff auf fremde Dienste. Ein Upload oder eine bewusste Auswahl setzt den Status auf manual und wird von der Automatik nie überschrieben.

Projektstruktur

backend/     FastAPI-Anwendung, Modelle, Services, Alembic-Migrationen, Tests
frontend/    React-Oberfläche (Vite)
docs/        Betriebs- und Runner-Dokumentation
.gitea/      Gitea-Actions-Workflows

Alternativ lässt sich alles aus dem Quellcode bauen:

cp docker-compose.override.yml.example docker-compose.override.yml
docker compose up -d --build

Die Override-Datei baut beide Images lokal, bindet den Quellcode ein und öffnet die Ports für Backend (8000) und Vite (5173).

Bauen und Ausrollen

Zwei Gitea-Workflows unter .gitea/workflows/:

• ci.yml läuft bei jedem Push und Pull Request: ruff, pytest, tsc --noEmit, eslint, vitest und der Bundle-Bau.
• build.yml läuft auf main und bei Tags v* und lädt beide Images für linux/amd64 in die Gitea-Registry. Push auf main erzeugt :main und :sha-<kurz>, ein Tag v1.2.3 zusätzlich :1.2.3, :1.2 und :latest.

Ausgerollt wird nicht automatisch. Die Einrichtung des Runners beschreibt docs/runner.md, das Ausrollen docs/deployment.md.

Lizenz

MIT