From 6e02e1a2766e04f2dd88f6ed52cb8682a79909ae Mon Sep 17 00:00:00 2001
From: Stefan Hacker <duffy@debian-linux-terminal.local>
Date: Sat, 11 Apr 2026 15:10:42 +0200
Subject: [PATCH] docs: add project README with installation and usage guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 161 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 161 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fc24f6c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,161 @@
+# Mini-Cloud
+
+Selbstgehostete Web-Cloud-Plattform mit Dateiverwaltung, Kalender, Kontakte, E-Mail-Webclient, Office-Viewer und Passwort-Manager.
+
+## Features
+
+- **Dateiverwaltung** - Upload/Download, Ordner, Berechtigungen, Share-Links (Passwort + Ablaufdatum)
+- **Kalender** - CalDAV-kompatibel (iOS, DAVx5, Thunderbird, Outlook), iCal-Export, Teilen mit Benutzern
+- **Kontakte** - CardDAV-kompatibel, vCard-Export, Adressbuecher teilen
+- **E-Mail-Webclient** - IMAP/SMTP-Proxy (kein eigener Mailserver), Multi-Account, Absender-Logik
+- **Office-Viewer** - DOCX, XLSX, PPTX, PDF direkt im Browser anzeigen
+- **Passwort-Manager** - AES-256-GCM clientseitig verschluesselt, TOTP, KeePass-Import, Ordner teilen
+- **Benutzerverwaltung** - Rollen (Admin/User), Speicher-Quotas
+- **Sync-API** - Delta-Sync fuer Desktop/Mobile-Clients
+
+## Tech-Stack
+
+| Bereich | Technologie |
+|---------|------------|
+| Backend | Python / Flask |
+| Frontend | Vue 3 / Vite / PrimeVue |
+| Datenbank | SQLite (WAL-Modus) |
+| Auth | JWT (Web-UI) + HTTP Basic Auth (CalDAV/CardDAV) |
+
+## Installation
+
+### Voraussetzungen
+
+- Python 3.11+
+- Node.js 18+
+- npm
+
+### Entwicklungsumgebung
+
+```bash
+# Repository klonen
+git clone <repo-url>
+cd mini-cloud-datei-email-kalender-kontakte
+
+# .env anlegen
+cp .env.example .env
+# SECRET_KEY und JWT_SECRET_KEY generieren:
+python3 -c "import secrets; print(secrets.token_urlsafe(64))"
+# Generierte Werte in .env eintragen
+
+# Backend einrichten
+cd backend
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+
+# Backend starten
+python wsgi.py
+# -> laeuft auf http://localhost:5000
+
+# Frontend einrichten (neues Terminal)
+cd frontend
+npm install
+
+# Frontend starten
+npm run dev
+# -> laeuft auf http://localhost:3100
+```
+
+Beim ersten Registrieren wird der Benutzer automatisch zum Admin.
+
+### Docker (Produktion)
+
+```bash
+# .env anlegen und Secrets eintragen
+cp .env.example .env
+
+# Starten
+docker-compose up --build -d
+# -> laeuft auf http://localhost:5000
+```
+
+Die Datenbank und hochgeladene Dateien liegen unter `./data/` (Bind Mount, keine Docker Volumes).
+
+## Verwendung
+
+### Dateien
+
+- Dateien per Drag-and-Drop oder Upload-Button hochladen
+- Ordner erstellen, Dateien verschieben/umbenennen/loeschen
+- Share-Links erstellen: optional mit Passwort und Ablaufdatum
+- Share-Links funktionieren ohne Login fuer externe Empfaenger
+
+### Kalender
+
+- Kalender erstellen, Events anlegen (Monats-/Tagesansicht)
+- Kalender mit anderen Benutzern teilen (Lesen oder Lesen+Schreiben)
+- iCal-Link generieren fuer Read-Only-Import in Google Calendar, Apple Kalender etc.
+- CalDAV-Zugriff fuer native Sync:
+  - **iOS**: Einstellungen > Kalender > Accounts > Anderer > CalDAV
+  - **Android (DAVx5)**: Server-URL: `https://<deine-domain>/dav/`
+  - **Thunderbird**: Neuer Kalender > Im Netzwerk > CalDAV
+  - **Outlook (CalDAV-Synchronizer)**: Server-URL: `https://<deine-domain>/dav/`
+
+### Kontakte
+
+- Adressbuecher anlegen, Kontakte erstellen/bearbeiten
+- Adressbuecher mit anderen Benutzern teilen
+- vCard-Export fuer Backup
+- CardDAV-Zugriff analog zum Kalender
+
+### E-Mail
+
+- E-Mail-Konten unter Einstellungen hinzufuegen (IMAP/SMTP-Zugangsdaten)
+- Kein eigener Mailserver noetig - verbindet sich mit externen Mailservern
+- Bei keinem konfigurierten Konto wird der E-Mail-Bereich ausgeblendet
+- Mehrere Konten: Ordner nach Konten gruppiert, Standard-Absender = aktives Konto
+- Absender-Dropdown nur sichtbar bei mehr als einem Konto
+
+### Office-Viewer
+
+- DOCX, XLSX, PPTX und PDF direkt im Browser anzeigen (nur Lesen)
+- Bilder und Textdateien werden ebenfalls inline dargestellt
+
+### Passwort-Manager
+
+- Alle Daten clientseitig mit AES-256-GCM verschluesselt (Zero Knowledge)
+- TOTP-Codes direkt generieren
+- Passwort-Generator integriert
+- KeePass-Import (.kdbx) mit Ordnerstruktur
+- Einzelne Passwoerter oder ganze Ordner mit anderen Benutzern teilen
+
+## Projektstruktur
+
+```
+backend/
+  app/
+    api/          # REST-Endpunkte
+    models/       # SQLAlchemy-Models
+    services/     # Business-Logik (Crypto, etc.)
+    dav/          # CalDAV/CardDAV (Radicale-Vorbereitung)
+  wsgi.py         # Einstiegspunkt
+
+frontend/
+  src/
+    views/        # Vue-Seiten
+    components/   # Wiederverwendbare Komponenten
+    stores/       # Pinia State Management
+    api/          # Axios API-Client
+    router/       # Vue Router
+
+data/             # Laufzeitdaten (gitignored)
+  minicloud.db    # SQLite-Datenbank
+  files/          # Hochgeladene Dateien
+```
+
+## Roadmap
+
+- Desktop Sync-Client (Windows, Linux, macOS) mit Full Sync + Virtual Files
+- Mobile Sync-Client (iOS, Android) mit On-Demand-Download
+- Native Passwort-Manager Clients mit Autofill und Biometrie
+- Radicale-Integration fuer vollstaendiges CalDAV/CardDAV-Protokoll
+
+## Lizenz
+
+Privates Projekt.