From ff8c9f5141892864cbc2d1541e90e3e193e0a5fe Mon Sep 17 00:00:00 2001
From: Erik Thiele <erik.thiele@cancom.de>
Date: Mon, 13 Jul 2026 22:02:55 +0200
Subject: [PATCH] first commit

---
 README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1423c2b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,68 @@
+# LinkVault
+
+KI-gestützte Link-Sammlung: Links einfügen → automatisch laden, **zusammenfassen**,
+in **Kategorien / Hersteller** einsortieren und schnell **wiederfinden**.
+
+## Funktionen
+
+- 🔗 **Link hinzufügen** – Seite wird geladen und der Textinhalt extrahiert.
+- 🤖 **Automatische KI-Analyse** (OpenAI) – Titel, Zusammenfassung, Kategorie,
+  Hersteller/Quelle und Tags werden erzeugt. Bestehende Kategorien werden
+  wiederverwendet, damit die Sammlung konsistent bleibt.
+- 🗂️ **Filtern** nach Kategorie und Hersteller über die Seitenleiste.
+- 🔍 **Suche** – klassische Textsuche und optionale **semantische KI-Suche**
+  (findet auch sinnverwandte Treffer via Embeddings).
+- 👥 **Mehrbenutzer** – Registrierung/Login, jeder Nutzer sieht nur seine Links.
+
+## Technik
+
+- **Backend:** FastAPI (Python)
+- **Frontend:** HTML + HTMX (kein Node.js nötig)
+- **Datenbank:** SQLite (Standard, konfigurierbar über `DATABASE_URL`)
+- **KI:** OpenAI (`gpt-4o-mini` + `text-embedding-3-small`, konfigurierbar)
+
+## Schnellstart
+
+```bash
+./run.sh
+```
+
+Das Skript legt eine virtuelle Umgebung an, installiert die Abhängigkeiten,
+erstellt bei Bedarf eine `.env` und startet den Server auf
+http://127.0.0.1:8000.
+
+Danach in `.env` den `OPENAI_API_KEY` eintragen und den Server neu starten.
+
+> Ohne API-Key läuft die App trotzdem – Links werden dann nur ohne KI-Analyse
+> gespeichert (Kategorie „Sonstiges", keine Zusammenfassung/semantische Suche).
+
+### Manuell
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env        # OPENAI_API_KEY eintragen
+uvicorn app.main:app --reload --port 8000
+```
+
+## Projektstruktur
+
+```
+app/
+  main.py        FastAPI-App, Routen, Auth-Sessions
+  config.py      Konfiguration aus .env
+  database.py    SQLAlchemy Engine/Session
+  models.py      User- und Link-Modelle
+  security.py    Passwort-Hashing (bcrypt)
+  scraper.py     Seiteninhalt laden & extrahieren
+  ai.py          OpenAI: Kategorisierung, Zusammenfassung, Embeddings
+  search.py      Semantische Suche (Kosinus-Ähnlichkeit)
+  templates/     Jinja2 + HTMX Oberfläche
+```
+
+## Hinweise für den Produktivbetrieb
+
+- Einen zufälligen `SECRET_KEY` in `.env` setzen.
+- Hinter einem HTTPS-Reverse-Proxy betreiben (Session-Cookies).
+- Für mehr Last statt SQLite z.B. PostgreSQL via `DATABASE_URL` verwenden.