breakpilot-pwa/CONTENT_SERVICE_SETUP.md

BreakPilot Content Service - Setup & Deployment Guide

🎯 Übersicht

Der BreakPilot Content Service ist eine vollständige Educational Content Management Plattform mit:

• ✅ Content Service API (FastAPI) - Educational Content Management
• ✅ MinIO S3 Storage - File Storage für Videos, PDFs, Bilder
• ✅ H5P Service - Interactive Educational Content (Quizzes, etc.)
• ✅ Matrix Feed Integration - Content Publishing zu Matrix Spaces
• ✅ PostgreSQL - Content Metadata Storage
• ✅ Creative Commons Licensing - CC-BY, CC-BY-SA, etc.
• ✅ Rating & Download Tracking - Analytics & Impact Scoring

🚀 Quick Start

1. Alle Services starten

# Haupt-Services + Content Services starten
docker-compose \
  -f docker-compose.yml \
  -f docker-compose.content.yml \
  up -d

# Logs verfolgen
docker-compose -f docker-compose.yml -f docker-compose.content.yml logs -f

2. Verfügbare Services

Service	URL	Beschreibung
Content Service API	http://localhost:8002	REST API für Content Management
MinIO Console	http://localhost:9001	Storage Dashboard (User: minioadmin, Pass: minioadmin123)
H5P Service	http://localhost:8003	Interactive Content Editor
Content DB	localhost:5433	PostgreSQL Database

3. API Dokumentation

Content Service API Docs:

http://localhost:8002/docs

📦 Installation (Development)

Content Service (Backend)

cd backend/content_service

# Virtual Environment erstellen
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Dependencies installieren
pip install -r requirements.txt

# Environment Variables
cp .env.example .env

# Database Migrations
alembic upgrade head

# Service starten
uvicorn main:app --reload --port 8002

H5P Service

cd h5p-service

# Dependencies installieren
npm install

# Service starten
npm start

Creator Dashboard (Frontend)

cd frontend/creator-studio

# Dependencies installieren
npm install

# Development Server
npm run dev

🔧 Konfiguration

Environment Variables

Erstelle .env im Projekt-Root:

# Content Service
CONTENT_DB_URL=postgresql://breakpilot:breakpilot123@localhost:5433/breakpilot_content
MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin123
MINIO_BUCKET=breakpilot-content

# Matrix Integration
MATRIX_HOMESERVER=http://localhost:8008
MATRIX_ACCESS_TOKEN=your-matrix-token-here
MATRIX_BOT_USER=@breakpilot-bot:localhost
MATRIX_FEED_ROOM=!breakpilot-feed:localhost

# OAuth2 (consent-service)
CONSENT_SERVICE_URL=http://localhost:8081
JWT_SECRET=your-jwt-secret-here

# H5P Service
H5P_BASE_URL=http://localhost:8003
H5P_STORAGE_PATH=/app/h5p-content

📝 Content Service API Endpoints

Content Management

# Create Content
POST /api/v1/content
{
  "title": "5-Minuten Yoga für Grundschule",
  "description": "Bewegungspause mit einfachen Yoga-Übungen",
  "content_type": "video",
  "category": "movement",
  "license": "CC-BY-SA-4.0",
  "age_min": 6,
  "age_max": 10,
  "tags": ["yoga", "bewegung", "pause"]
}

# Upload File
POST /api/v1/upload
Content-Type: multipart/form-data
file: <video-file>

# Add Files to Content
POST /api/v1/content/{content_id}/files
{
  "file_urls": ["http://minio:9000/breakpilot-content/..."]
}

# Publish Content (→ Matrix Feed)
POST /api/v1/content/{content_id}/publish

# List Content (with filters)
GET /api/v1/content?category=movement&age_min=6&age_max=10

# Get Content Details
GET /api/v1/content/{content_id}

# Rate Content
POST /api/v1/content/{content_id}/rate
{
  "stars": 5,
  "comment": "Sehr hilfreich für meine Klasse!"
}

H5P Interactive Content

# Get H5P Editor
GET http://localhost:8003/h5p/editor/new

# Save H5P Content
POST http://localhost:8003/h5p/editor
{
  "library": "H5P.InteractiveVideo 1.22",
  "params": { ... }
}

# Play H5P Content
GET http://localhost:8003/h5p/play/{contentId}

# Export as .h5p File
GET http://localhost:8003/h5p/export/{contentId}

🎨 Creator Workflow

1. Content erstellen

// Creator Dashboard
const content = await createContent({
  title: "Mathe-Quiz: Einmaleins",
  description: "Interaktives Quiz zum Üben des Einmaleins",
  content_type: "h5p",
  category: "math",
  license: "CC-BY-SA-4.0",
  age_min: 7,
  age_max: 9
});

2. Files hochladen

// Upload Video/PDF/Images
const file = document.querySelector('#fileInput').files[0];
const formData = new FormData();
formData.append('file', file);

const response = await fetch('/api/v1/upload', {
  method: 'POST',
  body: formData
});

const { file_url } = await response.json();

3. Publish to Matrix Feed

// Publish → Matrix Spaces
await publishContent(content.id);
// → Content erscheint in #movement, #math, etc.

📊 Matrix Feed Integration

Matrix Spaces Struktur

#breakpilot (Root Space)
├── #feed (Chronologischer Content Feed)
├── #bewegung (Kategorie: Movement)
├── #mathe (Kategorie: Math)
├── #steam (Kategorie: STEAM)
└── #sprache (Kategorie: Language)

Content Message Format

Wenn Content published wird, erscheint in Matrix:

📹 5-Minuten Yoga für Grundschule

Bewegungspause mit einfachen Yoga-Übungen für den Unterricht

📝 Von: Max Mustermann
🏃 Kategorie: movement
👥 Alter: 6-10 Jahre
⚖️ Lizenz: CC-BY-SA-4.0
🏷️ Tags: yoga, bewegung, pause

[📥 Inhalt ansehen/herunterladen]

🔐 Creative Commons Lizenzen

Verfügbare Lizenzen:

• CC-BY-4.0 - Attribution (Namensnennung)
• CC-BY-SA-4.0 - Attribution + ShareAlike (empfohlen)
• CC-BY-NC-4.0 - Attribution + NonCommercial
• CC-BY-NC-SA-4.0 - Attribution + NonCommercial + ShareAlike
• CC0-1.0 - Public Domain

Lizenz-Workflow

# Bei Content-Erstellung: Creator wählt Lizenz
content.license = "CC-BY-SA-4.0"

# System validiert:
✅ Nur erlaubte Lizenzen
✅ Lizenz-Badge wird angezeigt
✅ Lizenz-Link zu Creative Commons

📈 Analytics & Impact Scoring

Download Tracking

# Automatisch getrackt bei Download
POST /api/v1/content/{content_id}/download

# → Zähler erhöht
# → Download-Event gespeichert
# → Für Impact-Score verwendet

Creator Statistics

# Get Creator Stats
GET /api/v1/stats/creator/{creator_id}

{
  "total_contents": 12,
  "total_downloads": 347,
  "total_views": 1203,
  "avg_rating": 4.7,
  "impact_score": 892.5,
  "content_breakdown": {
    "movement": 5,
    "math": 4,
    "steam": 3
  }
}

🧪 Testing

API Tests

# Pytest
cd backend/content_service
pytest tests/

# Mit Coverage
pytest --cov=. --cov-report=html

Integration Tests

# Test Content Upload Flow
curl -X POST http://localhost:8002/api/v1/content \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Test Content",
    "content_type": "pdf",
    "category": "math",
    "license": "CC-BY-SA-4.0"
  }'

🐳 Docker Commands

# Build einzelnen Service
docker-compose -f docker-compose.content.yml build content-service

# Nur Content Services starten
docker-compose -f docker-compose.content.yml up -d

# Logs einzelner Service
docker-compose logs -f content-service

# Service neu starten
docker-compose restart content-service

# Alle stoppen
docker-compose -f docker-compose.yml -f docker-compose.content.yml down

# Mit Volumes löschen (Achtung: Datenverlust!)
docker-compose -f docker-compose.yml -f docker-compose.content.yml down -v

🗄️ Database Migrations

cd backend/content_service

# Neue Migration erstellen
alembic revision --autogenerate -m "Add new field"

# Migration anwenden
alembic upgrade head

# Zurückrollen
alembic downgrade -1

📱 Frontend Development

Creator Studio

cd frontend/creator-studio

# Install dependencies
npm install

# Development
npm run dev  # → http://localhost:3000

# Build
npm run build

# Preview Production Build
npm run preview

🔒 DSGVO Compliance

Datenminimierung

• ✅ Nur notwendige Metadaten gespeichert
• ✅ Keine Schülerdaten
• ✅ IP-Adressen anonymisiert nach 7 Tagen
• ✅ User kann Content/Account löschen

Datenexport

# User Data Export
GET /api/v1/user/export
→ JSON mit allen Daten des Users

🚨 Troubleshooting

MinIO Connection Failed

# Check MinIO status
docker-compose logs minio

# Test connection
curl http://localhost:9000/minio/health/live

Content Service Database Connection

# Check PostgreSQL
docker-compose logs content-db

# Connect manually
docker exec -it breakpilot-pwa-content-db psql -U breakpilot -d breakpilot_content

H5P Service Not Starting

# Check logs
docker-compose logs h5p-service

# Rebuild
docker-compose build h5p-service
docker-compose up -d h5p-service

📚 Weitere Dokumentation

• Architekturempfehlung
• Content Service API
• H5P Integration
• Matrix Feed Setup

🎉 Next Steps

1. ✅ Services starten (siehe Quick Start)
2. ✅ Creator Account erstellen
3. ✅ Ersten Content hochladen
4. ✅ H5P Interactive Content erstellen
5. ✅ Content publishen → Matrix Feed
6. ✅ Teacher Discovery UI testen
7. 🔜 OAuth2 SSO mit consent-service integrieren
8. 🔜 Production Deployment vorbereiten

💡 Support

Bei Fragen oder Problemen:

• GitHub Issues: https://github.com/breakpilot/breakpilot-pwa/issues
• Matrix Chat: #breakpilot-dev:matrix.org
• Email: dev@breakpilot.app