Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/DerBasilisk/SEA-ServicioEvaluaconAsistida/llms.txt

Use this file to discover all available pages before exploring further.

This guide gets a fully functional local instance of Sealearn running on your machine — backend API, React frontend, MongoDB, and Redis — in under ten minutes. By the end you will have a running app pre-loaded with sample subjects and shop items that you can log into and explore immediately.
1

Install Prerequisites

Sealearn requires three services to be available before you install any dependencies.
RequirementMinimum versionNotes
Node.js18.x LTSThe frontend uses Vite 7 which requires Node 18+
MongoDB6.xCan be a local mongod process or a free MongoDB Atlas cluster
Redis6.xRequired for real-time duel state and invite management
Verify your environment before continuing:
node --version   # should print v18.x.x or higher
mongod --version # should print v6.x or higher
redis-cli ping   # should print PONG
Redis is not optional. The duel system stores all in-progress game state, invite tokens, and pending-duel queues in Redis via ioredis. If REDIS_URL is missing or Redis is unreachable, the backend process will fail to connect and real-time duels will be completely unavailable. Always ensure Redis is running before starting the backend.
2

Clone the Repository

Clone the Sealearn monorepo from GitHub. The repository contains both the backend and frontend/sea directories at the top level.
git clone https://github.com/DerBasilisk/SEA-ServicioEvaluaconAsistida.git
cd SEA-ServicioEvaluaconAsistida
3

Install Backend Dependencies

Navigate into the backend directory and install all Node.js packages. The backend uses CommonJS modules with Express 5, Mongoose, Socket.IO, ioredis, Passport, and the Groq and Google GenAI SDKs.
cd backend
npm install
Key packages installed include express ^5.2.1, mongoose ^9.2.4, socket.io ^4.8.1, ioredis ^5.10.0, groq-sdk ^1.1.1, @google/genai ^1.46.0, and nodemon ^3.1.14 for development hot-reloading.
4

Install Frontend Dependencies

Open a new terminal tab, then navigate to frontend/sea from the repo root and install the React project’s dependencies.
cd frontend/sea
npm install
The frontend uses React 19, Vite 7, Tailwind CSS 3, Zustand 5, React Router v7, and the socket.io-client ^4.8.3 package that connects to both the default duel namespace and the /chat namespace.
5

Configure Backend Environment Variables

Inside the backend directory, create a .env file. Below is a complete template with descriptions for every variable the application reads.
# backend/.env

# ── Server ────────────────────────────────────────────────────
PORT=3000

# ── Database ──────────────────────────────────────────────────
MONGODB_URI=mongodb://localhost:27017/sealearn

# ── Auth ──────────────────────────────────────────────────────
JWT_SECRET=your_super_secret_jwt_key_change_in_production

# ── CORS / Client origins ─────────────────────────────────────
# Must match the URL your React dev server runs on
CLIENT_URL=http://localhost:5173
FRONTEND_URL=http://localhost:5173
# Optional: www-prefixed production domain
CLIENT_URL_WWW=http://localhost:5173

# ── Cloudinary (avatar & banner uploads) ─────────────────────
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# ── AI — Groq (primary, Llama 3.3-70B) ───────────────────────
# Supply up to 3 keys; the service rotates between them and
# applies a per-key circuit breaker on repeated 429 errors.
GROQ_API_KEY_1=gsk_...
GROQ_API_KEY_2=gsk_...   # optional second key
GROQ_API_KEY_3=gsk_...   # optional third key

# ── AI — Gemini (fallback, Gemini 2.0 Flash) ─────────────────
GEMINI_API_KEY=AIza...

# ── Email (Resend) ────────────────────────────────────────────
RESEND_API_KEY=re_...

# ── OAuth — Google ────────────────────────────────────────────
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback

# ── OAuth — Discord ───────────────────────────────────────────
DISCORD_CLIENT_ID=your_discord_client_id
DISCORD_CLIENT_SECRET=your_discord_client_secret
DISCORD_CALLBACK_URL=http://localhost:3000/api/auth/discord/callback

# ── Redis ─────────────────────────────────────────────────────
REDIS_URL=redis://localhost:6379
You only need one GROQ_API_KEY_* for local development. The AI service (services/ai.service.js) filters out blank entries and builds a pool from whichever keys are present. Gemini is only called when all Groq circuit breakers are open.
6

Start the Backend

From the backend directory, start the development server. nodemon watches for file changes and restarts automatically.
# from backend/
npm run dev
You should see output similar to:
[Cron] Jobs registrados
✅┬─┬ノ(ಠ_ಠノ) Conectado a la base de datos
Servidor corriendo en http://localhost:3000
Confirm the API is healthy:
curl http://localhost:3000/api/health
# → {"ok":true,"message":"SEA API corriendo","timestamp":"..."}
The backend mounts these route groups: /api/users, /api/profile, /api/subjects, /api/lessons, /api/questions, /api/progress, /api/auth, /api/password, /api/friends, /api/upload, /api/leagues, /api/admin, /api/chat, and /api/shop. Socket.IO listens on the same HTTP server at path /socket.io.
7

Start the Frontend

In your second terminal (inside frontend/sea), start the Vite dev server:
# from frontend/sea/
npm run dev
Vite will start on http://localhost:5173 by default and print a local URL you can open directly. The frontend connects to the backend at http://localhost:3000 (configured via the Axios base URL and the Socket.IO client connection string).
8

Seed the Database

With both the backend and MongoDB running, open a third terminal and run the seed scripts from the backend directory to populate subjects, units, lessons, and shop items.
# from backend/
node seeds/seedSubject.js
node seeds/seedShop.js
seedSubject.js creates a sample subject hierarchy (subject → units → lessons) so that adaptive lessons and duels have real content to work with. seedShop.js populates ShopItem documents with the default cosmetic catalogue that learners can browse and purchase.
A third script — node seeds/seedQuestions.js — is also available if you want a full set of pre-built questions attached to the seeded lessons. This is recommended if you want to test the duel system locally without first authoring questions manually.
9

Register and Explore

Open http://localhost:5173 in your browser. You will land on the Sealearn welcome screen.
  1. Click Register and create an account with your email and a password.
  2. Verify your email if Resend is configured, or skip verification for local testing by setting emailVerified: true directly on your user document in MongoDB.
  3. Browse the seeded subjects and start a lesson to see the adaptive question flow in action.
  4. Add a friend, then challenge them to a Duel from the chat window to test the real-time Socket.IO layer.
To grant yourself admin privileges, open a MongoDB shell or a GUI such as MongoDB Compass and update your user document: set role to "admin". This unlocks the admin dashboard at /admin in the frontend and the /api/admin routes on the backend, giving you full control over users, content, and league management.

​
Common Issues

# Make sure mongod is running
mongod --dbpath /usr/local/var/mongodb

# Or start it as a service (macOS with Homebrew)
brew services start mongodb-community

Build docs developers (and LLMs) love

Get started for freeTalk to us