# 🤖 JARVIS - Übergabe Dokumentation

**Projekt:** JARVIS KI-Assistent + Business Automation
**Erstes Deployment:** 12.09.2026
**Status:** ✅ Live auf VPS 72.61.186.98 (Postgres, Redis, Ollama, n8n, JARVIS-API, JARVIS-Web)
**Owner:** Jonny (MBO-Tech-IT)

---

## 📋 Übersicht

JARVIS ist ein **vollständig selbst gehosteter AI-Assistant + Business Automation Stack** auf einem VPS mit Docker-Orchestrierung. Chat-Zugriff läuft über eine eigene Web-Oberfläche (React) und spricht über Claude Tool Use direkt mit Kalender und E-Mail-Postfach.

**Kernkomponenten:**
- 🤖 **KI-Backend**: Claude API (Chat + Tool Use) + Ollama (lokale Embeddings)
- 💾 **Datenbank**: PostgreSQL mit `pgvector`-Extension (strukturierte Daten + Vector Search in einer DB, kein separates Milvus)
- ⚡ **Cache**: Redis (aktuell nur fürs Health-Check vorbereitet, noch nicht aktiv genutzt)
- 🔄 **Automation**: n8n (Workflow Engine) - Wetter- und E-Mail-Cache laufen bereits darüber
- 📡 **API**: FastAPI (Python Backend, `main.py`)
- 🌐 **Web-Frontend**: React/Vite, nginx-served
- 🔌 **Externe Integrationen**: Nextcloud-Kalender (CalDAV), E-Mail-Postfach (IMAP/SMTP)
- 🌐 **Reverse Proxy**: bereits vorhandener, JARVIS-fremder Traefik auf dem VPS (siehe unten)
- 🐳 **Container**: 6 Docker-Container (siehe "Docker Container Status")

---

## 🔑 Zugriffsdaten

```
VPS IP:        72.61.186.98
User:          jarvis-core
SSH Key:       ~/.ssh/jarvis_core_key
Domain:        jarvis.mbo-tech-it.de
Location:      /home/jarvis-core/jarvis
```

### SSH-Zugriff
```bash
ssh -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key jarvis-core@72.61.186.98
```
Die Flags `-F /dev/null -o IdentitiesOnly=yes` sind nötig, damit die globale
lokale `~/.ssh/config` nicht in die Schlüsselauswahl reinpfuscht.

**Wichtig:** `jarvis-core` muss in `/etc/ssh/sshd_config` unter `AllowUsers` stehen, sonst wird jeder Key mit "Permission denied" abgelehnt, obwohl der Key korrekt ist (passiert am 12.09.2026, gefixt durch Ergaenzen von `jarvis-core` in der `AllowUsers`-Zeile + `systemctl reload ssh`).

### n8n-Zugriff
```
URL:   https://n8n.jarvis.mbo-tech-it.de
User:  jonny@mbo-tech-it.de (Owner-Account, Passwort nicht in dieser Doku)
```
API-Keys fuer die n8n-REST-API werden unter Settings -> n8n API verwaltet
(pro Key eigenes Ablaufdatum). Aktuell existieren: "JARVIS Weather Workflow"
(Ablauf 12.10.2026) und "JARVIS Email Workflow Runtime" (Ablauf 13.10.2026,
fuer den E-Mail-Cache-Workflow angelegt). Die Key-Werte selbst sind nirgends
dauerhaft gespeichert (nur beim Erstellen einmalig sichtbar) - bei Bedarf
einfach einen neuen erstellen.

### Database Credentials
```
PostgreSQL User:     jarvis
PostgreSQL Database: jarvis (n8n hat eine eigene DB "n8n" in derselben Instanz)
PostgreSQL Port:     5432
Password:            in .env (DB_PASSWORD)
```

### Externe Dienste (Zugangsdaten in `.env` auf dem VPS)
- **Nextcloud-Kalender** (`NEXTCLOUD_CALDAV_URL`, `NEXTCLOUD_USER`, `NEXTCLOUD_APP_PASSWORD`): `https://cloud.ffw-onza.de/.../ffw-onza-alle/`, App-Passwort-Auth
- **E-Mail-Postfach** (`EMAIL_USER`, `EMAIL_PASSWORD`, `EMAIL_IMAP_HOST/PORT`, `EMAIL_SMTP_HOST/PORT`): `kontakt@mbo-tech-it.de` auf `mx2f35.netcup.net` (IMAP 143 STARTTLS, SMTP 465 implizites TLS)
- **Claude API** (`CLAUDE_API_KEY`): console.anthropic.com, separat vom Claude-Pro-Abo

---

## 📍 Services & Ports

| Service | URL | Port | Status | Notes |
|---------|-----|------|--------|-------|
| **Web-Frontend** | https://jarvis.mbo-tech-it.de | 80 (intern, nginx) | 🟢 Live | Chat + Dashboard, Shared-Secret-Login mit `API_KEY_ADMIN` |
| **API** | https://api.jarvis.mbo-tech-it.de | 8000 (intern) | 🟢 Live | FastAPI Swagger UI: `/docs`. Alle `/api/v1/*` Routen ausser `/health` brauchen Header `X-Admin-Key` |
| **n8n** | https://n8n.jarvis.mbo-tech-it.de | 5678 (intern) | 🟢 Live | Workflow Automation - 2 aktive Workflows (Wetter, E-Mail-Cache) |
| **Traefik** | - | 80/443 | 🟢 Genutzt (fremd) | Server hat bereits einen eigenen Traefik fuer andere Projekte. JARVIS-eigener Traefik-Service wurde entfernt (Port-Konflikt), stattdessen haengt JARVIS per Labels + externem Netzwerk `proxy-network` am bestehenden Traefik. TLS ueber Let's-Encrypt-Resolver `netcup` (DNS-01) |
| **PostgreSQL** | localhost | 5432 | 🟢 Live | Hauptdatenbank + Vector Search, Image `pgvector/pgvector:pg16` |
| **Redis** | localhost | 6379 | 🟢 Live | Läuft und wird im Health-Check geprüft, im Code aber noch nicht aktiv fürs Caching genutzt |
| **Ollama** | http://72.61.186.98:11434 | 11434 | 🟢 Live | Local LLM Runtime, genutzt für Embeddings (`nomic-embed-text` gepullt) |
| **Milvus** | - | - | ⛔ Nie deployt | Ersetzt durch `pgvector` direkt in Postgres (siehe Phase 3a). Platzhalter-Services `milvus`/`etcd` stehen noch in `docker-compose.yml`, laufen aber nicht |

**Traefik-Integration (12.09.2026):** JARVIS ist am bestehenden VPS-weiten Traefik
(`docker-compose.yml` Projekt `traefik`, `/data/docker/compose/traefik/`) angehaengt:
externes Docker-Netzwerk `proxy-network`, Labels an `jarvis-api`, `jarvis-web` und `n8n`
(`traefik.docker.network=proxy-network`, `entrypoints=websecure`,
`tls.certresolver=netcup`). DNS (`jarvis` A-Record + `*.jarvis` Wildcard) liegt
bei Netcup. Falls eine neue Subdomain (z.B. `foo.jarvis.mbo-tech-it.de`) mal
nicht auflöst, obwohl der Wildcard existiert: pruefen, ob ein expliziter
(auch leerer) Eintrag exakt fuer diesen Namen existiert - der blockiert laut
DNS-Wildcard-Regeln (RFC 1034) die Wildcard-Aufloesung nur fuer diesen einen
Namen. **Beobachtet (12.09.2026):** Auch ohne sichtbaren blockierenden
Eintrag im Netcup-Panel kann die Aufloesung eines frisch fuer eine
DNS-01-Challenge verwendeten Namens (z.B. `api.jarvis...`) deutlich laenger
brauchen als ein unberuehrter Wildcard-Name (bis zu ~20 Minuten beobachtet,
vermutlich Netcup-interner Nebeneffekt der ACME-TXT-Record-Erstellung) -
einfach abwarten, es loest sich von selbst.

---

## 🏗️ Architektur

```
┌───────────────────────────────────────────────────────────┐
│           Bestehender, JARVIS-fremder Traefik              │
│           (VPS-weit, andere Projekte inklusive)             │
└───────────────────────────────────────────────────────────┘
                 │  proxy-network (Labels)
     ┌───────────┼──────────────┬──────────────────┐
     ▼           ▼              ▼                   
┌─────────┐ ┌──────────┐  ┌───────────┐
│jarvis-web│ │jarvis-api│  │  n8n      │
│(nginx)   │ │(FastAPI) │  │  :5678    │
└─────────┘ └────┬─────┘  └─────┬─────┘
                  │  jarvis-net (intern)   │
      ┌───────────┼───────────┐            │
      ▼           ▼           ▼            │
┌───────────┐ ┌───────┐  ┌────────┐         │
│ Postgres  │ │ Redis │  │ Ollama │         │
│ +pgvector │ │ :6379 │  │ :11434 │         │
│ :5432     │ └───────┘  └────────┘         │
└─────┬─────┘                               │
      └─── n8n schreibt Cache-Tabellen ─────┘
             (weather_cache, email_cache)

Externe Integrationen (kein eigener Container, direkter API-Zugriff aus jarvis-api):
  - Nextcloud CalDAV (Kalender lesen/schreiben)
  - IMAP/SMTP-Postfach kontakt@mbo-tech-it.de (E-Mails lesen/senden)
  - Claude API (Chat + Tool Use)
```

---

## 🐳 Docker Container Status

```bash
cd /home/jarvis-core/jarvis
docker compose ps

# Erwartete Ausgabe (6 Container):
# jarvis-postgres   Up (healthy)
# jarvis-redis      Up (healthy)
# jarvis-ollama     Up
# jarvis-n8n        Up
# jarvis-api        Up
# jarvis-web        Up
```
`milvus`/`etcd` stehen zwar noch als Service-Definitionen in
`docker-compose.yml` (Platzhalter, nie funktionsfähig konfiguriert), werden
aber mit `docker compose up -d` normalerweise nicht mit hochgezogen, wenn man
gezielt einzelne Services neu startet (`docker compose up -d jarvis-api` etc.,
so wie es in diesem Projekt durchgängig gemacht wird statt einem globalen
`up -d`).

---

## 📁 Projektstruktur

```
/home/jarvis-core/jarvis/
├── docker-compose.yml    # Container-Orchestrierung (Docker Compose v2 - "docker compose", kein Bindestrich)
├── .env                  # Umgebungsvariablen (GEHEIM!)
├── init-db.sql           # PostgreSQL Basis-Initialisierung (users/conversations/messages/tasks/documents/audit_logs)
├── migrations/           # Nachträgliche Schema-Änderungen, manuell per psql angewendet
│   ├── 002_document_chunks.sql
│   ├── 003_drop_low_data_ivfflat_index.sql
│   ├── 004_weather_cache.sql
│   └── 005_email_cache.sql
├── api/
│   ├── main.py           # FastAPI Hauptanwendung (einzige Backend-Datei)
│   └── requirements.txt  # Python Dependencies
├── web/                  # React/Vite Frontend-Quellcode + Dockerfile + nginx.conf
├── config/                # (ungenutzt)
├── data/                  # (ungenutzt - Postgres/Redis/n8n/Ollama persistieren tatsächlich über benannte Docker-Volumes, siehe docker-compose.yml `volumes:`)
└── logs/                  # (ungenutzt, kein Service schreibt aktuell hierhin)
```

Lokal (Entwicklung, dieses Repo): Backend-Code liegt unter `Claude outputs/`,
Frontend unter `web/`. Kein dediziertes Git-Repo für dieses Projekt - Dateien
werden per `scp` direkt auf den VPS deployt.

---

## 🔧 Wichtige Befehle

**Hinweis:** Die installierte Docker-Compose-Version ist v2 (Plugin-Syntax
`docker compose`, ohne Bindestrich) - das alte `docker-compose` (mit
Bindestrich) ist auf dem VPS nicht garantiert vorhanden.

### Container Management
```bash
cd /home/jarvis-core/jarvis

# Alle starten
docker compose up -d

# Alle stoppen
docker compose down

# Logs anschauen
docker compose logs -f

# Spezifischen Service neustarten (Backend-Codeänderung reicht ein restart,
# da main.py per Volume gemountet ist und uvicorn mit --reload läuft)
docker compose restart jarvis-api

# Frontend-Änderung braucht einen echten Rebuild (Multi-Stage-Dockerfile)
docker compose build jarvis-web && docker compose up -d jarvis-web

# In Container gehen
docker compose exec jarvis-api bash
docker compose exec postgres bash
```

### Database Management
```bash
# PostgreSQL CLI öffnen
docker exec -it jarvis-postgres psql -U jarvis -d jarvis

# Query ausführen
docker exec jarvis-postgres psql -U jarvis -d jarvis -c "SELECT * FROM users;"

# Migration anwenden (nach scp der .sql-Datei nach migrations/)
docker exec -i jarvis-postgres psql -U jarvis -d jarvis < migrations/00X_name.sql

# Backup erstellen
docker exec jarvis-postgres pg_dump -U jarvis jarvis > jarvis_backup.sql

# Backup wiederherstellen
docker exec -i jarvis-postgres psql -U jarvis jarvis < jarvis_backup.sql
```

### API Testing
```bash
# Health Check (kein Header noetig)
curl http://localhost:8000/health

# Admin Stats (Header noetig)
curl -H "X-Admin-Key: $API_KEY_ADMIN" http://localhost:8000/api/v1/admin/stats

# Swagger UI im Browser
https://api.jarvis.mbo-tech-it.de/docs
```

### Backend-Tests lokal ausführen (vor jedem Deploy)
Lokales Python (3.14) kann `psycopg2-binary` nicht bauen (kein Wheel) - Tests
laufen deshalb in einem `python:3.11-slim`-Container per SSH:
```bash
scp -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key \
  "Claude outputs/main.py" "Claude outputs/requirements.txt" \
  "Claude outputs/requirements-dev.txt" "Claude outputs/pytest.ini" \
  jarvis-core@72.61.186.98:/tmp/jarvis-test/
scp -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key \
  "Claude outputs/tests/"*.py jarvis-core@72.61.186.98:/tmp/jarvis-test/tests/
ssh -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key jarvis-core@72.61.186.98 \
  "docker run --rm -v /tmp/jarvis-test:/app -w /app python:3.11-slim bash -c \
   'pip install -q -r requirements-dev.txt -r requirements.txt && python -m pytest tests/ -v'"
```

---

## ⚙️ Konfiguration (.env, auf dem VPS unter `/home/jarvis-core/jarvis/.env`)

```
# Domain
DOMAIN=jarvis.mbo-tech-it.de

# Database
DB_PASSWORD=<generiert>

# Claude / Ollama
CLAUDE_API_KEY=<gesetzt>
CLAUDE_MODEL=claude-sonnet-5           # (Default in main.py, muss nicht in .env stehen)
OLLAMA_EMBED_MODEL=nomic-embed-text    # (Default in main.py)

# Admin-Zugriff (Shared Secret fürs Frontend UND alle /api/v1/* Routen)
API_KEY_ADMIN=<generiert>

# Nextcloud-Kalender
NEXTCLOUD_APP_PASSWORD=<gesetzt>

# E-Mail-Postfach kontakt@mbo-tech-it.de
EMAIL_PASSWORD=<gesetzt>

LOG_LEVEL=info
```

**⚠️ WICHTIG:** `.env` enthält Secrets - nicht in Git committen (für dieses
Projekt ohnehin kein Git-Repo im Einsatz)!

---

## 🔌 Datenbankschema

### PostgreSQL Tables (Datenbank `jarvis`)

**users** (`init-db.sql`)
- Felder: id, username, email, password_hash, api_key, role, is_active
- Es gibt kein echtes Login-System pro Nutzer (siehe "Security" unten) - die
  einzige vorhandene Zeile ist ein Seed-User `admin@jarvis.local` aus
  `init-db.sql`. `ensure_default_user()` in `main.py` nimmt schlicht den
  ersten User per ID als `DEFAULT_USER_ID` für alle Chat-Aktivität (in der
  Praxis also dieser `admin`-Seed-User, nicht ein separat angelegter
  "jarvis-service"-User, obwohl der Code-Pfad dafür existiert)

**conversations** / **messages** (`init-db.sql`)
- Chat-Verlauf, Multi-Turn über `conversation_id`
- `messages.tokens_used` trackt Claude-Token-Verbrauch pro Antwort

**tasks** (`init-db.sql`)
- Tabelle existiert, wird aber von den `/api/v1/tasks`-Endpoints noch NICHT
  genutzt (die sind aktuell Stubs mit hartcodierten Werten, siehe "API
  Endpoints" unten) - offener Punkt für Phase 4b

**documents** + **document_chunks** (`init-db.sql` + `migrations/002_document_chunks.sql`)
- Knowledge Base fürs RAG: `documents` hält Titel/Volltext,
  `document_chunks` die 768-dim `pgvector`-Embeddings (Ollama
  `nomic-embed-text`) pro Chunk
- `ivfflat`-Index wurde wieder entfernt (`003_drop_low_data_ivfflat_index.sql`),
  da er bei wenig Daten 0 Treffer lieferte - aktuell Sequential Scan

**weather_cache** (`migrations/004_weather_cache.sql`)
- Wird ausschließlich vom n8n-Workflow "Wetter Crailsheim" befüllt (Cache,
  kein Live-API-Call aus `main.py`)

**email_cache** (`migrations/005_email_cache.sql`)
- Wird ausschließlich vom n8n-Workflow "Neue E-Mails Cache" befüllt
  (Absender/Betreff/Empfangsdatum, keine Volltexte). Der Chat greift für
  Live-Anfragen separat direkt per IMAP zu, nicht über diesen Cache

**audit_logs** (`init-db.sql`)
- Tabelle existiert, wird aber aktuell von keinem Code-Pfad beschrieben
  (vorbereitet für spätere Compliance-Anforderungen)

### Redis
- Läuft und wird im Health-Check geprüft (`check_redis()`), im Code aber
  noch nirgends für Sessions/Caching/Queues genutzt - reiner Platzhalter für
  spätere Erweiterung

---

## 🚀 API Endpoints

Alle `/api/v1/*`-Routen (ausser keine - `/health` ist die einzige offene
Route) verlangen den Header `X-Admin-Key: <API_KEY_ADMIN>`.

### Health
```
GET  /health                          # Oeffentlich, kein Header noetig
GET  /api/v1/admin/stats              # Conversations/Tasks/Documents-Zaehler
GET  /api/v1/admin/health/detailed    # Postgres/Redis/Milvus(TCP-Check)/Ollama/n8n
```

### Chat (Claude, mit Tool Use für Kalender + E-Mail)
```
POST /api/v1/chat
  Body: {"conversation_id": 1, "message": "...", "context": {}}
  -> {"conversation_id", "response", "tokens_used", "timestamp"}

GET  /api/v1/conversations/{id}       # Voller Nachrichtenverlauf
```
Claude kann in `run_chat_completion()` bis zu `MAX_TOOL_ROUNDS = 5` Tool-Runden
hintereinander ausführen: `list_calendar_events`, `create_calendar_event`,
`update_calendar_event`, `delete_calendar_event` (Löschen nur nach expliziter
Chat-Bestätigung), `list_recent_emails`, `send_email` (Senden nur nach
expliziter Chat-Bestätigung).

### Kalender
```
GET  /api/v1/calendar/events?days=14  # Naechste Termine (Nextcloud CalDAV)
```

### Wetter
```
GET  /api/v1/weather                  # Neuester Cache-Eintrag (503 wenn leer)
```

### E-Mail
```
GET  /api/v1/emails?limit=10          # Neueste gecachte Mails ([] wenn leer, kein 503)
```

### Tasks (⚠️ noch nicht mit Postgres verbunden - TODO)
```
POST /api/v1/tasks                    # Stub: gibt immer id=1 zurueck, speichert nichts
GET  /api/v1/tasks?status=pending     # Stub: gibt immer leere Liste zurueck
```

### Documents (Knowledge Base)
```
POST /api/v1/documents?title=...&content=...&document_type=...
  # Chunking + Ollama-Embedding + Insert

GET  /api/v1/documents?query=...&limit=10
  # Vector-Similarity-Suche ueber document_chunks
```

### Workflows (⚠️ noch nicht mit n8n verbunden - TODO)
```
POST /api/v1/workflows/trigger        # Stub: ruft n8n nicht wirklich auf
```

---

## 🔐 Security

Es gibt **kein** vollwertiges Auth-System mit Login pro Nutzer. Stattdessen:
- Frontend-Login = ein geteiltes Secret (`API_KEY_ADMIN`), das im Browser in
  `localStorage` liegt und bei jedem Request als `X-Admin-Key`-Header
  mitgeschickt wird (`require_admin_key`-Dependency in `main.py`)
- Der `admin`-User in der `users`-Tabelle (aus `init-db.sql`) ist nur ein
  DB-Seed für die `user_id`-Fremdschluessel, kein aktives Login - das Feld
  `password_hash` wird von keinem Code-Pfad geprüft
- Für ein echtes Multi-User-System (eigene Logins, Rollen) wäre eine
  separate Architektur-Runde nötig - bewusst "Out of Scope" laut Frontend-Spec

### Secrets (alle in `.env` auf dem VPS, nicht im Repo)
- **API_KEY_ADMIN**: Shared Secret fürs Frontend-Login + alle geschützten API-Routen
- **DB_PASSWORD**: Postgres-Passwort
- **CLAUDE_API_KEY**: Anthropic API Key
- **NEXTCLOUD_APP_PASSWORD**: Nextcloud CalDAV App-Passwort
- **EMAIL_PASSWORD**: IMAP/SMTP-Passwort für kontakt@mbo-tech-it.de

---

## 📊 Monitoring & Logs

```bash
# Real-time Logs
docker compose logs -f

# Logs für spezifischen Service
docker compose logs -f jarvis-api

# Alte Logs anschauen
docker logs --tail 100 jarvis-api

# System Resources
docker stats
```

---

## 🛠️ Troubleshooting

### Container startet nicht
```bash
docker compose logs jarvis-api
docker compose restart jarvis-api
docker compose down && docker compose up -d
```

### Database Connection Error
```bash
docker exec jarvis-postgres pg_isready -U jarvis
docker exec jarvis-postgres psql -U jarvis -d jarvis -c "SELECT 1"
```

### API antwortet nicht
```bash
docker compose ps
curl -v http://localhost:8000/health
docker compose logs jarvis-api
```

### Frontend zeigt eine neue Aenderung nicht an, obwohl deployt
`web/nginx.conf` setzt `index.html` auf `no-cache` und `/assets/*` auf
`immutable` - trotzdem: harter Reload (Strg+Shift+R) probieren, bevor man
tiefer sucht. Ursache war einmal ein fehlender Cache-Header (siehe Phase 4d).

### n8n-Workflow läuft nicht wie erwartet
Executions-Tab des jeweiligen Workflows in der n8n-UI ansehen (zeigt Input/
Output pro Node) - schneller als Logs raten.

---

## 📈 Entwicklungsverlauf (chronologisch)

### Phase 1: Grundsetup ✅
- [x] Docker Stack deployed, alle Kern-Services laufen, Datenbank initialisiert, API verfügbar

### Phase 2: KI-Integration ✅
- [x] Claude API Key eingetragen (console.anthropic.com, separat vom Claude Pro Abo)
- [x] Claude Integration in API (Multi-Turn ueber `conversation_id`)
- [x] Token-Tracking implementiert (`tokens_used` pro Message + Response)
- [x] Postgres-Persistenz fuer Conversations/Messages
- [x] Echte Health-Checks (Postgres, Redis, Ollama, n8n; Milvus als TCP-Check vorbereitet)

### Phase 3a: Knowledge Base ✅
- [x] pgvector-Extension in Postgres (Image gewechselt auf `pgvector/pgvector:pg16`)
- [x] `document_chunks`-Tabelle (768-dim Embeddings, Chunking 1000/100 Zeichen Overlap)
- [x] Embeddings via Ollama `nomic-embed-text` (lokal, keine externen Kosten)
- [x] `POST/GET /api/v1/documents` funktionsfaehig
- [x] Bug gefunden+gefixt: `ivfflat`-Index lieferte bei wenig Daten 0 Treffer - Index vorerst entfernt, Sequential Scan aktiv
- [ ] Follow-up: `ivfflat`/`hnsw`-Index neu anlegen, sobald genug Dokumente vorhanden sind

### Phase 3b: Frontend ✅
- [x] React/Vite Web UI (`jarvis-web` Container, nginx-served) unter https://jarvis.mbo-tech-it.de
- [x] Shared-Secret-Login (wiederverwendet `API_KEY_ADMIN`, Header `X-Admin-Key`)
- [x] Chat Interface (Multi-Turn) + Dashboard (Stats + Health-Tabelle)
- [x] API auf eigene Subdomain umgezogen: https://api.jarvis.mbo-tech-it.de
- [x] Bug gefixt (13.09.2026): Chat verlor Verlauf bei Tab-Wechsel/Reload, da
      `conversationId` nur im React-State lag. Fix: `conversationId` in
      `localStorage`, Verlauf wird beim Mounten via `GET /api/v1/conversations/{id}`
      wiederhergestellt (`web/src/components/Chat.tsx`)
- [ ] Vollwertiges User-/Auth-System (Login pro Nutzer, Rollen) - weiterhin offen

### Phase 4a: Wetter-Widget ✅ (erster echter n8n-Workflow)
- [x] n8n Owner-Account eingerichtet (`jonny@mbo-tech-it.de`)
- [x] n8n-Workflow "Wetter Crailsheim" (id `BwNCJ2TkuZfqUzst`): Schedule-Trigger
      (alle 30 Min) -> Open-Meteo API (kein Key noetig) -> Code-Node (WMO-Code
      -> deutscher Text) -> Postgres-Insert in `weather_cache`
- [x] n8n-Credential "JARVIS Postgres" (zeigt auf dieselbe `jarvis`-DB wie die API)
- [x] `GET /api/v1/weather` liest die neueste Zeile
- [x] `WeatherWidget` oben rechts in der Frontend-Nav-Leiste

### Phase 4d: Nextcloud-Kalender-Integration ✅
- [x] CalDAV-Zugriff auf `https://cloud.ffw-onza.de/.../ffw-onza-alle/` via
      App-Passwort, Python-Library `caldav`
- [x] `GET /api/v1/calendar/events` + "Naechste Termine"-Widget im Dashboard
- [x] Chat kann Kalender abfragen, Termine anlegen und verschieben (direkt,
      ohne Rueckfrage) sowie loeschen (nur nach Bestaetigung im Chat) -
      Claude Tool Use mit `list_calendar_events` / `create_calendar_event` /
      `update_calendar_event` / `delete_calendar_event`
- [x] Bug gefixt (13.09.2026): `run_chat_completion` unterstuetzte nur eine
      Tool-Runde - "Termin verschieben" braucht aber zwei (erst uid per
      `list_calendar_events` finden, dann `update_calendar_event`), die
      zweite Runde wurde still verworfen (leere Antwort). Jetzt eine echte
      Schleife (`MAX_TOOL_ROUNDS = 5`)
- [x] Bug gefixt: neu angelegte Termine landeten als UTC statt Europe/Berlin
      (2h Verschiebung) - naive Datumswerte werden jetzt explizit lokalisiert
      (`_as_calendar_local`)
- [x] Bug gefixt: `web/nginx.conf` hatte keine Cache-Header - `index.html`
      wurde vom Browser gecacht, wodurch ein Deploy im Browser nicht ankam,
      obwohl der Server bereits den neuen Build auslieferte. Jetzt:
      `index.html` = `no-cache`, `/assets/*` = `immutable`

### Phase 4e: Sprach-Ein-/Ausgabe im Chat ✅
- [x] Mikrofon-Button (🎤) nutzt die Browser-eigene Web Speech API
      (`SpeechRecognition`, `de-DE`) - reine Frontend-Loesung, blendet sich
      selbst aus, wenn der Browser das nicht unterstuetzt (v.a. Firefox)
- [x] Assistant-Antworten werden automatisch per `SpeechSynthesis`
      vorgelesen, Standard "an"; Mute-Button (🔊/🔇) merkt sich Zustand in
      `localStorage` (`jarvis_speech_muted`)
- [x] Neues Modul `web/src/speech.ts` buendelt beide APIs (nach Vorbild von `api.ts`)
- [x] Bug gefixt (13.09.2026): `continuous=false` beendete die Erkennung bei
      jeder Sprechpause. Jetzt `continuous=true` mit automatischem Neustart
      bei Chrome's internem Session-Timeout (akkumuliert Text ueber
      Neustarts hinweg, damit nichts verloren geht)
- [x] Sprachausgabe filtert vor dem Vorlesen: Emojis (inkl. Zahlen-Emoji wie
      1⃣2⃣3⃣), Markdown-Formatierung (`**fett**`, `#Ueberschriften`) und
      dekorative Trennlinien/Tabellenzeichen (`---`, `═══`, `|`) - siehe
      `cleanForSpeech()` in `web/src/speech.ts`

### Phase 4f: E-Mail-Integration ✅
- [x] Postfach `kontakt@mbo-tech-it.de` (IMAP `mx2f35.netcup.net:143` STARTTLS,
      SMTP `mx2f35.netcup.net:465` implizites TLS) via Python-Standardbibliothek
      (`imaplib`, `smtplib`, `email`) angebunden - keine neue Dependency
- [x] Chat-Tools `list_recent_emails` (liest live per IMAP, `BODY.PEEK` damit
      der Lese-Status nicht veraendert wird, RFC-2047-Betreffs dekodiert) und
      `send_email` (SMTP_SSL) in `run_chat_completion()`, analog zum Kalender.
      `send_email` verlangt wie `delete_calendar_event` immer erst eine
      Bestaetigung im Chat, bevor tatsaechlich versendet wird
- [x] n8n-Workflow "Neue E-Mails Cache" (id `VaAQdw18ElYWkEfr`, aktiv):
      eingebauter `Email Trigger (IMAP)`-Node (`postProcessAction: "nothing"`,
      damit das Cachen den echten Lese-Status im Postfach nicht veraendert)
      -> Postgres-Insert in `email_cache` (nur Metadaten, keine Volltexte)
- [x] `GET /api/v1/emails` liest die neuesten Zeilen; leerer Cache liefert
      `[]` statt 503 (anders als beim Wetter kein Fehlerzustand)
- [x] `EmailWidget` ("Neue E-Mails") im Dashboard, nach demselben Muster wie
      `CalendarWidget`/`WeatherWidget`
- [x] Live end-to-end getestet: Chat hat echte Inbox-Mails aufgelistet,
      Testmail per Chat mit Bestaetigungsdialog versendet und im Postfach
      verifiziert, n8n-Workflow hat dieselbe Mail in `email_cache` erfasst,
      Dashboard-Widget zeigt sie an
- [x] Kleiner Fix waehrend der Verifikation: von JARVIS selbst versendete
      Mails hatten keinen `Date`-Header (smtplib/EmailMessage setzt den nicht
      automatisch) - `_send_email_sync` setzt jetzt `Date` und `Message-ID`
- Out of Scope (siehe Spec): Anhaenge, Antworten/Weiterleiten, Loeschen/
  Verschieben von Mails, mehrere Postfaecher/Ordner

### Phase 4b: Weitere Automation ⏳ (offen)
- [ ] `POST/GET /api/v1/tasks` an die vorhandene `tasks`-Tabelle anbinden (aktuell Stub)
- [ ] `POST /api/v1/workflows/trigger` tatsaechlich an die n8n-API anbinden (aktuell Stub)
- [ ] Weitere n8n Business-Workflows definieren (Kundenbericht-Automation o.ä.)

### Phase 5: Production ⏳ (offen)
- [ ] Backup-Strategie (Postgres-Dumps automatisieren, aktuell nur manuell per `pg_dump`)
- [ ] Monitoring & Alerts (aktuell nur manuelles Ansehen von `/api/v1/admin/health/detailed`)
- [ ] Sicherheits-Hardening / echtes Multi-User-Auth-System

---

## 📞 Kontakt & Support

**Owner:** Jonny (Markus)
**Email:** jonny@mbo-tech-it.de
**Company:** MBO-Tech-IT
**Location:** Crailsheim, Baden-Württemberg

---

## 📚 Dokumentation & Links

- [FastAPI Docs](https://api.jarvis.mbo-tech-it.de/docs)
- [n8n Docs](https://docs.n8n.io)
- [PostgreSQL Docs](https://www.postgresql.org/docs/)
- [pgvector Docs](https://github.com/pgvector/pgvector)
- [Claude API Docs](https://docs.anthropic.com)
- [Docker Docs](https://docs.docker.com)
- [Traefik Docs](https://doc.traefik.io)

Spezifikationen und Implementierungspläne aller Phasen liegen lokal unter
`docs/superpowers/specs/` und `docs/superpowers/plans/`.

---

## 🎯 Quick Reference

### Start JARVIS
```bash
cd /home/jarvis-core/jarvis
docker compose up -d
```

### Check Status
```bash
docker compose ps
curl http://localhost:8000/health
```

### View Logs
```bash
docker compose logs -f
```

### Backend-Code aktualisieren
```bash
scp -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key \
  "Claude outputs/main.py" jarvis-core@72.61.186.98:/home/jarvis-core/jarvis/api/main.py
ssh -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key jarvis-core@72.61.186.98 \
  "cd /home/jarvis-core/jarvis && docker compose restart jarvis-api"
```

### Frontend-Code aktualisieren
```bash
scp -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key -r \
  web/src jarvis-core@72.61.186.98:/home/jarvis-core/jarvis/web/
ssh -F /dev/null -o IdentitiesOnly=yes -i ~/.ssh/jarvis_core_key jarvis-core@72.61.186.98 \
  "cd /home/jarvis-core/jarvis && docker compose build jarvis-web && docker compose up -d jarvis-web"
```

### Backup Database
```bash
docker exec jarvis-postgres pg_dump -U jarvis jarvis > backup.sql
```

---

**🎉 JARVIS ist bereit!**

*Letzte Aktualisierung: 13.09.2026*
*Deployment Status: ✅ LIVE*