QUICKSTART_MICROSERVICES

PersonalLearningPro Microservices — Quick Start

⚠️ Historical (W30, 2026-07). This document describes the vendored features/ai-classroom/studyArena microservice, which was removed. The live implementation is native under server/services/study-arena/ (see study-arena-inspired-by-openmaic.md) and attribution is at OpenMAIC-ATTRIBUTION.md. Kept for historical reference only.

🚀 5-Minute Setup

1. Initialize Services

# Run setup script
bash scripts/setup-services.sh

# This creates:
# - services/iniclaw/
# - Dockerfiles and package.json files

2. Copy Your Code (optional companion services)

# IniClaw is already in this repo — no copy needed
# features/ai-classroom/ini_claw/ is the built-in LLM gateway

3. Configure Environment

# Copy and edit .env
cp .env.example .env

# Generate BRIDGE_SECRET
openssl rand -hex 32  # Copy this value to BRIDGE_SECRET in .env

# Fill in Firebase credentials
# Fill in OpenAI API key
# Fill in MongoDB password

4. Start Services

# With Docker (recommended)
docker compose up

# Without Docker (2 terminals)
# Terminal 1: EduAI app (includes native Study Arena — no extra process needed)
npm run dev

# Terminal 2 (optional): IniClaw LLM gateway
cd features/ai-classroom/ini_claw && BRIDGE_SECRET=<secret> INICLAW_PORT=7070 node gateway.js

5. Verify

# EduAI (always required)
curl http://localhost:5001/api/health
curl http://localhost:5001/api/ai-classroom/health  # native Study Arena

# Optional services
curl http://localhost:4000/api/health  # IniClaw (services/iniclaw, Docker)
curl http://localhost:7070/health      # IniClaw (local dev gateway)

# Access the apps
# - EduAI + AI Classroom: http://localhost:5001
# - EduAI + AI Classroom: http://localhost:5001/ai-classroom
# - IniClaw gateway:      http://localhost:5001/gateway (via Nginx)

📋 What Was Set Up

Docker Compose

• EduAI (React + Express + native Study Arena) on port 5001
• IniClaw (services/iniclaw — production gateway) on port 4000
• IniClaw (features/ai-classroom/ini_claw — local dev gateway) on port 7070
• MongoDB on port 27017
• Cassandra on port 9042
• Redis on port 6379
• Nginx reverse proxy on port 80

Authentication Bridge

• Firebase JWT tokens validated by EduAI
• Automatic user sync between Firebase and MongoDB

Webhook Integration

• Gateway events stored in MongoDB
• Analytics tracked for study plan generation

Reverse Proxy Routing

• / → EduAI main app
• /api/* → EduAI backend
• /gateway/* → IniClaw agent gateway

🔗 API Examples

Create AI Classroom (native Study Arena)

curl -X POST http://localhost:5001/api/ai-classroom/create \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Calculus",
    "sceneTypes": ["slides", "quiz"]
  }'
# Returns: { "jobId": "abc123", "status": "generating" }

Poll Job Status

curl http://localhost:5001/api/ai-classroom/status/abc123 \
  -H "Authorization: Bearer <jwt>"

List My Classrooms

curl http://localhost:5001/api/ai-classroom/my-classrooms \
  -H "Authorization: Bearer <jwt>"

🐛 Troubleshooting

Services won't start

# Check Docker is running
docker ps

# Check logs
docker compose logs -f

# Rebuild images
docker compose build --no-cache

Authentication fails

# Verify Firebase credentials in .env
echo $VITE_FIREBASE_PROJECT_ID

# Check token verification
curl -H "Authorization: Bearer <token>" http://localhost:5001/api/auth/me

Webhook signature fails

# Verify BRIDGE_SECRET is set
echo $BRIDGE_SECRET

# Check webhook logs
docker compose logs iniclaw-gateway | grep webhook

Port already in use

# Find process using port
lsof -i :5001

# Kill process
kill -9 <PID>

# Or change port in .env
PORT=5002 docker compose up

📚 Full Documentation

See docs/MICROSERVICES_INTEGRATION.md for:

• Complete architecture overview
• Phase-by-phase implementation guide
• API endpoint documentation
• Webhook event specifications
• Security best practices
• Production deployment guide

🎯 Next Steps

1. ✅ Services initialized
2. ✅ Docker Compose configured
3. ✅ Native Study Arena replaces external dependency for core classroom generation
4. ✅ IniClaw rewritten as lightweight LLM proxy (zero npm dependencies)
5. ✅ 25/25 API integration tests passing
6. ⏳ Deploy to production

💡 Tips

• Use docker compose logs -f <service> to debug specific services
• Services communicate via internal Docker network (no localhost needed)
• Nginx handles routing and SSL termination in production
• All services share Firebase authentication
• MongoDB stores all application data
• Cassandra stores high-volume message data

🆘 Need Help?

1. Check logs: docker compose logs -f
2. Verify environment: cat .env | grep -E "FIREBASE|BRIDGE|MONGO"
3. Test health endpoints: curl http://localhost:5001/api/health
4. Review integration guide: docs/MICROSERVICES_INTEGRATION.md

---

Ready to go! 🎉 Your microservices are now orchestrated and ready for development.