kruemel/Crumb-Core-v.1
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2fd60fdfd5b2afc62a6085dcd6a2c41ac778ffbb
Crumb-Core-v.1/docs/crumbforest/README.md

6.5 KiB
Raw Blame History

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

-- 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

# 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

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

# 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

Roadmap

Phase 1: MVP ✅

  • FastAPI Backend
  • RAG System (OpenAI, Claude, OpenRouter)
  • Diary Indexing & Search
  • DSGVO Audit Logging
  • 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

Wuuuuhuuu! 🦉