LearnING10 – Lokales Setup & Troubleshooting (MVP)

1Projektstruktur anlegen

Lege zuerst den Code in einen eigenen Projektordner:

1. Erstelle einen Ordner, z. B. learning10-monorepo.
2. Lege alle Dateien hinein, z. B.:
   • package.json, pnpm-workspace.yaml, README.md
   • apps/web/... (Next.js Frontend)
   • apps/api/... (FastAPI Backend)
3. Öffne ein Terminal und wechsle in diesen Ordner:

   cd learning10-monorepo

2pnpm-workspace.yaml korrigieren

Damit pnpm korrekt arbeitet, muss die Workspace-Datei gültiges YAML sein und nur existierende Pfade enthalten.

Deine Datei sollte so aussehen:

packages:
  - "apps/*"

• Keine //-Kommentare – in YAML sind Kommentare nur mit # erlaubt.
• Der Eintrag "packages/*" ist entfernt, weil es aktuell keinen packages-Ordner im MVP gibt.

3Voraussetzungen prüfen

node -v
pnpm -v

python --version
# oder manchmal:
python3 --version

4Dependencies installieren

Im Projekt-Root:

pnpm setup

Das führt zwei Dinge aus:

• pnpm install für alle Node/Next.js-Abhängigkeiten
• pip install -r apps/api/requirements.txt für FastAPI

Falls es Fehler gibt (z. B. bei Python), kannst du die Befehle auch manuell ausführen:

# Node-Dependencies
pnpm install

# Python-Dependencies
cd apps/api
pip install --upgrade pip
pip install -r requirements.txt
cd ../../

5Ports freimachen (falls blockiert)

Standardports des Projekts:

• Frontend (Next.js): http://localhost:3000
• Backend (FastAPI): http://localhost:8000

Wenn schon andere Prozesse darauf laufen, kannst du sie beenden.

5.1 macOS / Linux

# Port 3000 räumen
lsof -ti:3000 | xargs kill -9

# Port 8000 räumen
lsof -ti:8000 | xargs kill -9

5.2 Windows (PowerShell)

# Prozess auf Port 3000 finden
netstat -ano | findstr :3000
# PID ausgeben, dann:
taskkill /PID  /F

# dasselbe für Port 8000
netstat -ano | findstr :8000
taskkill /PID  /F

6Backend (FastAPI) starten

Variante A – über das Root-Script:

pnpm dev:api

Das entspricht intern in apps/api ungefähr:

uvicorn main:app --reload --port 8000

Im Terminal solltest du etwas sehen wie:

INFO:     Uvicorn running on http://127.0.0.1:8000

API testen:

• Basis-Route: http://localhost:8000
• Health Check: http://localhost:8000/health
• API-Doku (Swagger): http://localhost:8000/docs

Typischer Fehler: ModuleNotFoundError: No module named 'fastapi'

Lösung:

cd apps/api
pip install --upgrade pip
pip install -r requirements.txt
uvicorn main:app --reload --port 8000

7Frontend (Next.js) starten

Öffne ein zweites Terminal im Projekt-Root:

pnpm dev:web

Dann sollte im Terminal stehen, dass Next.js auf Port 3000 läuft, z. B.:

ready - started server on 0.0.0.0:3000

Frontend testen:

• Im Browser: http://localhost:3000

8Frontend & Backend gemeinsam starten (optional)

Wenn beide Einzelschritte funktionieren, kannst du alles in einem Rutsch starten:

pnpm dev

Dann laufen gleichzeitig:

• pnpm dev:web (Next.js)
• pnpm dev:api (FastAPI)

9Typische Fehler & Troubleshooting

9.1 pnpm: command not found

Lösung:

npm install -g pnpm
pnpm setup

9.2 API-Calls schlagen im Frontend fehl (CORS/Network Error)

1. Prüfen, ob die API läuft: http://localhost:8000/health
2. Prüfen, ob das Frontend auf http://localhost:3000 läuft.
3. In apps/api/main.py ist CORS bereits so gesetzt:

   allow_origins=["http://localhost:3000"]

   Wenn du einen anderen Host/Port nutzt, musst du den hier anpassen.
4. Falls deine API z.B. unter einer anderen URL läuft, kannst du im Frontend eine .env.local anlegen (im Ordner apps/web):

   NEXT_PUBLIC_API_URL=http://deine-api-url:port

   Danach pnpm dev:web neu starten.

9.3 EADDRINUSE: address already in use :::3000 oder :::8000

Der Port ist schon belegt. Siehe oben Schritt 5 (Ports freimachen), dann den jeweiligen Server neu starten.

9.4 Frontend findet Pfade wie @/lib/... nicht

• Stelle sicher, dass du im Projekt-Root pnpm dev:web startest.
• In apps/web/tsconfig.json sollten diese Pfade existieren:

  "paths": {
    "@/*": ["./src/*"]
  }

• Wenn du Dateien verschoben hast, ggf. noch einmal pnpm install im Root ausführen.

10Kurzer Funktionstest des MVP

Wenn beide Server laufen:

1. Öffne http://localhost:3000.
2. Klicke auf „🎉 Start Learning!“ → du landest auf /onboarding/parent.
3. Fülle Parent-Daten aus → Weiter.
4. Fülle Kind-Daten aus → Weiter.
5. Beantworte die Sorting-Hat-Fragen → Weiter.
6. Wähle einen Avatar → „Let’s Go!“.
7. Du landest auf der Map → Wähle eine Insel (z.B. „Tutorial Island“ oder „Loops Canyon“).
8. Klicke auf einen freigeschalteten Node → Node-Player öffnet sich (Video, Quiz, Puzzle, Code etc.).
9. Löse die Aufgabe → Submit → XP/Coins sollten im HUD ansteigen.