Sealearn Architecture: Backend, Frontend, and Real-Time

const app    = express();
const httpServer = http.createServer(app);

// Global middleware
app.use(cors({ origin: [process.env.CLIENT_URL, /https:\/\/sea-frontend.*\.vercel\.app$/], credentials: true }));
app.use(express.json());
app.use(morgan("dev"));
app.use(passport.initialize());

// REST route groups
app.use("/api/users",    userRoutes);
app.use("/api/profile",  profileRoutes);
app.use("/api/subjects", subjectRoutes);
app.use("/api/lessons",  lessonRoutes);
app.use("/api/questions",questionRoutes);
app.use("/api/progress", progressRoutes);
app.use("/api/auth",     authRoutes);
app.use("/api/password", passwordRoutes);
app.use("/api/friends",  friendsRoutes);
app.use("/api/upload",   uploadRoutes);
app.use("/api/leagues",  leagueRoutes);
app.use("/api/admin",    adminRoutes);
app.use("/api/chat",     chatRoutes);
app.use("/api/shop",     shopRoutes);

// Cron jobs (registered before DB connects)
setupCronJobs();

// Socket.IO (duel default namespace + /chat namespace)
const io = setupDuelSocket(httpServer);
setupChatSocket(io);

connectDB().then(() => httpServer.listen(PORT));

routes/lesson.js
  └─ controllers/lesson.controller.js
       └─ services/adaptive.service.js
       └─ models/lesson.js, models/question.js

cron.schedule("0 0 * * 1", async () => {
  const count = await processWeeklyLeagues();
  console.log(`[Cron] Ligas procesadas: ${count} salas`);
}, { timezone: "America/Bogota" });

const connectDB = async () => {
  await mongoose.connect(process.env.MONGODB_URI);
};

type: {
  type: String,
  enum: [
    "multiple_choice", "true_false", "fill_blank",
    "order_items",     "match_pairs", "sentence_builder",
    "free_text",       "typing",      "code_python",
  ],
},
// Multiple choice: options[] with isCorrect flag
// True/false:      correctBoolean
// Fill blank:      correctAnswers[]
// Order items:     items[] (correct order)
// Match pairs:     pairs[] with { left, right }
// Code:            evaluationCriteria, maxScore, isCodeExercise

// duel.socket.js — creates the Server instance
const io = new Server(httpServer, {
  cors: { origin: process.env.FRONTEND_URL, credentials: true },
  path: "/socket.io",
});

// chat.socket.js — attaches to the existing io
const chat = io.of("/chat");

io.use((socket, next) => {
  const token = socket.handshake.auth.token;
  const decoded = jwt.verify(token, process.env.JWT_SECRET);
  socket.userId = decoded._id;
  next();
});

Client A                    Server                    Client B
   │                           │                           │
   ├─ duel:invite ────────────►│                           │
   │  { friendId, lessonId }   ├─ duel:invited ───────────►│
   │◄─ duel:invite_sent ───────┤                           │
   │                           │◄──────── duel:accept ─────┤
   │                           │  build duelState in Redis  │
   │◄─ duel:start ─────────────┼──────── duel:start ───────►│
   │                           │                           │
   ├─ duel:answer ────────────►│◄──────── duel:answer ─────┤
   │◄─ duel:answer_result ─────┤                           │
   │                           ├─ duel:opponent_progress ──►│
   │                           │                           │
   │◄─ duel:finished ──────────┼──────── duel:finished ────►│

const redis = new Redis(process.env.REDIS_URL);
const DUEL_TTL = 60 * 30; // 30 minutes

createDuel(duelId, data)   // setex duel:<id> DUEL_TTL
getDuel(duelId)            // get  duel:<id>
updateDuel(duelId, data)   // setex duel:<id> DUEL_TTL  (resets TTL)
deleteDuel(duelId)         // del  duel:<id>

class CircuitBreaker {
  constructor(name, { failureThreshold = 3, resetTimeMs = 60_000 } = {}) { ... }

  get isOpen() {
    // Auto-resets after resetTimeMs (half-open probe)
    if (this.openedAt && Date.now() - this.openedAt > this.resetTimeMs) {
      this.failures = 0;
      this.openedAt = null;
    }
    return this.openedAt !== null;
  }

  recordSuccess() { this.failures = 0; this.openedAt = null; }
  recordFailure()  { if (++this.failures >= this.failureThreshold) this.openedAt = Date.now(); }
}

const groqPool = GROQ_KEYS.map(apiKey => ({
  client:  new Groq({ apiKey }),
  breaker: new CircuitBreaker(`Groq-${apiKey.slice(-6)}`),
}));

function getNextGroqClient() {
  for (let i = 0; i < groqPool.length; i++) {
    const entry = groqPool[groqPoolIndex];
    groqPoolIndex = (groqPoolIndex + 1) % groqPool.length;
    if (!entry.breaker.isOpen) return entry;
  }
  throw new Error("Todas las keys de Groq están saturadas");
}

const cache = new Map();
const CACHE_TTL_MS = 30 * 60 * 1000;

// Duel namespace (default)
const socket = io("http://localhost:3000", {
  auth: { token: authStore.getState().token },
  path: "/socket.io",
});

// Chat namespace
const chatSocket = io("http://localhost:3000/chat", {
  auth: { token: authStore.getState().token },
  path: "/socket.io",
});