# Crumbforest 🦉

## Vision

Crumbforest ist ein KI-gestütztes Wissensmanagement- und Tagebuch-System für Kinder und Familien.

## Wuuuuhuuu! - Die Eule als Symbol

Die Eule steht für:
- 🦉 **Weisheit** - Wissen sammeln und bewahren
- 🌙 **Nachtaktiv** - Immer da, wenn man sie braucht
- 👁️ **Scharfer Blick** - Details erkennen und verstehen
- 🌲 **Waldtier** - Naturverbundenheit

## Kernfunktionen

### 1. Tagebuch-System (Diary)
Jedes Kind hat sein eigenes, sicheres Tagebuch:
- Markdown-basierte Einträge
- Bilder und Zeichnungen einbinden
- Privatsphäre durch Verschlüsselung
- Token-basierter Zugang via QR-Code

### 2. RAG-System (AI-Suche)
Intelligente Suche über alle Einträge:
- **Semantic Search** - Suche nach Bedeutung, nicht nur Wörtern
- **Q&A** - Fragen in natürlicher Sprache stellen
- **Context-Aware** - Versteht Zusammenhänge
- **Multi-Provider** - OpenAI, Claude, OpenRouter

### 3. Wissenssammlung
Dokumentation und Kontext:
- RZ Nullfeld Dokumentation
- Crumbforest Dokumentation
- Automatisches Indexing
- Versionierung via Git

## Technische Architektur

### Stack
```
Frontend:  Server-Rendered HTML (Jinja2) + Pico CSS
Backend:   FastAPI (Python 3.12)
Database:  MariaDB (MySQL)
Vector DB: Qdrant
AI:        OpenAI, Anthropic Claude, OpenRouter
```

### Datenfluss

```
Kind schreibt Tagebuch
       ↓
PHP Backend speichert in MySQL
       ↓
FastAPI wird getriggert
       ↓
Markdown → Chunks → Embeddings
       ↓
Qdrant Vector DB (Collection: diary_child_{id})
       ↓
Suche & RAG Queries möglich
```

## Sicherheit & DSGVO

### Datenschutz-Prinzipien
1. **Data Minimization** - Nur notwendige Daten sammeln
2. **Purpose Limitation** - Daten nur für definierten Zweck
3. **Storage Limitation** - Daten nicht ewig speichern
4. **Integrity & Confidentiality** - Verschlüsselt & sicher

### Technische Maßnahmen
- **Verschlüsselung**: AES-256 für sensible Daten
- **Access Control**: Role-Based (admin/user)
- **Audit Logging**: Jede Aktion wird protokolliert (immutable)
- **Data Isolation**: Jedes Kind hat eigene Qdrant Collection

### DSGVO-konforme Features
- ✅ **Recht auf Auskunft** - Export aller Daten
- ✅ **Recht auf Löschung** - Kaskadierte Löschung
- ✅ **Recht auf Datenübertragbarkeit** - JSON/Markdown Export
- ✅ **Recht auf Widerspruch** - Opt-out jederzeit möglich

## Architektur-Entscheidungen

### Warum Hybrid (PHP + FastAPI)?
- **PHP**: Bewährt, stabil, einfach zu hosten
- **FastAPI**: Modern, async, perfekt für AI/ML
- **Best of Both Worlds**: Legacy-Kompatibilität + Zukunftssicherheit

### Warum Qdrant?
- **Open Source** - Keine Vendor-Lock-in
- **Self-Hosted** - Daten bleiben in Deutschland
- **Performance** - Sehr schnell bei Vektor-Suche
- **Docker-Ready** - Einfache Deployment

### Warum Multi-Provider AI?
- **Flexibilität** - Provider wechseln ohne Code-Änderung
- **Ausfallsicherheit** - Fallback auf anderen Provider
- **Cost Optimization** - Günstigsten Provider wählen
- **Feature-Diversity** - Beste Features von jedem Provider

## Komponenten-Übersicht

### Backend Services
```
app/
├── routers/
│   ├── admin_rag.py       - RAG Management
│   ├── diary_rag.py       - Diary Indexing & Search
│   └── document_rag.py    - Markdown Docs Indexing
├── services/
│   ├── rag_service.py     - Core RAG Logic
│   ├── embedding_service.py - Embedding Generation
│   └── provider_factory.py - AI Provider Management
└── lib/
    ├── embedding_providers/ - OpenAI, Claude, etc.
    └── markdown_chunker.py  - Smart Markdown Chunking
```

### Datenbank-Schema
```sql
-- Kinder mit Token-Zugang
children (id, name, age, token)

-- Tagebuch-Einträge
diary_entries (id, child_id, entry_text, created_at)

-- Vektor-Tracking
post_vectors (post_id, post_type, child_id, collection_name, vector_ids)

-- DSGVO Audit Log
audit_log (action, entity_type, entity_id, user_id, metadata, created_at)
```

### Collections in Qdrant
```
posts_de          - Deutsche Blog-Posts
posts_en          - Englische Blog-Posts
diary_child_1     - Tagebuch von Kind 1
diary_child_2     - Tagebuch von Kind 2
docs_rz_nullfeld  - RZ Nullfeld Dokumentation
docs_crumbforest  - Crumbforest Dokumentation
```

## Workflow-Beispiele

### Tagebuch-Eintrag erstellen
```bash
# 1. Kind scannt QR-Code → Erhält Token
# 2. Kind schreibt Tagebuch auf Handy/Tablet
# 3. PHP speichert in MySQL

# 4. PHP triggert FastAPI Indexing
curl -X POST http://fastapi:8000/api/diary/index \
  -H "Content-Type: application/json" \
  -d '{
    "entry_id": 123,
    "child_id": 1,
    "content": "# Heute im Wald\n\nIch habe einen Igel gesehen!",
    "provider": "openai"
  }'

# 5. Kind kann später suchen
curl -X POST http://fastapi:8000/api/diary/search \
  -d '{"child_id": 1, "query": "Igel"}'
```

### Frage ans Tagebuch stellen
```bash
curl -X POST http://fastapi:8000/api/diary/ask \
  -H "Content-Type: application/json" \
  -d '{
    "child_id": 1,
    "question": "Was habe ich im Wald gesehen?",
    "provider": "claude"
  }'

# Response:
{
  "answer": "Du hast einen Igel im Wald gesehen. Du warst mit deinem Papa dort...",
  "sources": [
    {"entry_id": 123, "score": 0.95}
  ],
  "provider": "claude",
  "model": "claude-3-5-sonnet-20241022"
}
```

## Deployment

### Production-Ready Setup
```bash
# 1. Environment Setup
cp compose/.env.example compose/.env
nano compose/.env  # API Keys eintragen

# 2. Build & Start
./setup.sh

# 3. Verify
./test.sh
```

### Monitoring
- **Health**: http://localhost:8000/health
- **API Docs**: http://localhost:8000/docs
- **Qdrant**: http://localhost:6333/dashboard
- **Logs**: `./logs.sh app -f`

## Roadmap

### Phase 1: MVP ✅
- [x] FastAPI Backend
- [x] RAG System (OpenAI, Claude, OpenRouter)
- [x] Diary Indexing & Search
- [x] DSGVO Audit Logging
- [x] Modern UI (Pico CSS)

### Phase 2: Auto-Indexing 🚧
- [ ] Markdown Docs Auto-Indexing
- [ ] Change Detection (File Hashes)
- [ ] Startup Hooks
- [ ] Re-Indexing on File Change

### Phase 3: Enhanced Features
- [ ] Voice Input für Tagebuch
- [ ] Bilder-Upload & OCR
- [ ] Multi-Child Sharing (mit Permissions)
- [ ] PDF Export von Tagebüchern
- [ ] Emotion Detection in Entries

### Phase 4: AI-Features
- [ ] Auto-Tagging von Einträgen
- [ ] Sentiment Analysis
- [ ] Zusammenfassungen (Weekly/Monthly)
- [ ] Inspiration & Writing Prompts

## Team & Kontakt

**Entwickelt mit 💚 von der Eule**

- Repository: https://github.com/crumbforest/core
- Docs: https://docs.crumbforest.local
- Issues: https://github.com/crumbforest/core/issues

**Wuuuuhuuu!** 🦉