# EnglishWorldCenter Chatbot

Plataforma de aprendizaje de inglés con bots conversacionales (voz y texto).
Integra ElevenLabs (voz) y OpenAI (feedback, opcional). Tres roles: ADMIN,
TEACHER, STUDENT. Producción: https://chat.englishworldcenter.com

## Stack

- **Frontend** (`frontend/`): Vue 3 (Composition API + `<script setup>`),
  Vite, Pinia, Vue Router 4, Bootstrap 5, Lucide icons, Axios, TypeScript.
- **Backend** (`backend/`): Node.js ≥ 22, Express 4, TypeScript, JWT en
  cookies httpOnly, Winston, Zod, WebSocket (`ws`) en `/ws`.
- **BD**: PostgreSQL 15 + Prisma. Esquema único en `prisma/schema.prisma`
  (raíz del repo, NO dentro de `backend/`); los scripts de backend usan
  `--schema=../prisma/schema.prisma`.
- **Infra**: Docker Compose con perfiles `dev` y `prod`; contenedor Temporal;
  Apache como reverse proxy en producción (no Nginx).
- Package manager: **npm** en los tres niveles (raíz, backend, frontend).
  El `package.json` de la raíz no tiene scripts pero NO es residual: sus
  dependencias las usan `create-admin-user.js` y los scripts de `test/*.js`.
  El código de la app vive en `backend/` y `frontend/`.

## Comandos

```bash
# Entorno completo en local (frontend 5173, API 3000, health /health)
docker compose --profile dev up -d --build
docker compose --profile dev logs -f backend
docker compose --profile dev down            # -v borra la BD, no usarlo a la ligera

# Backend sin Docker (backend/)
npm run dev              # tsx watch
npm run build && npm run start
npm run lint / lint:fix / format
npm run prisma:generate / prisma:migrate / prisma:deploy / prisma:studio / prisma:seed

# Frontend sin Docker (frontend/)
npm run dev
npm run build            # incluye type-check (vue-tsc)
npm run lint / format
```

Sin perfil (`docker compose up`) no arranca ningún frontend: `frontend-dev`
y `frontend-prod` están detrás de los perfiles `dev`/`prod`.

## Arquitectura

- `backend/src/index.ts` — entrada Express; exporta `prisma` (PrismaClient).
- `backend/src/routes/` → `controllers/` → `services/` (ElevenLabs, OpenAI,
  conversaciones); `middlewares/` (auth JWT, roles, errores); `utils/`.
- `backend/src/prisma/seed.ts` — seed (usuarios demo `@example.com`).
- `backend/docker-entrypoint.sh` — en Docker: migra (`PRISMA_MIGRATE`) o
  `db push`, seed opcional (`RUN_SEED`), build y arranque.
- `frontend/src/views/` — vistas por rol (`admin/`, `teacher/`, `student/`);
  `stores/` (Pinia, auth), `services/` (capa API Axios), `router/` (guards
  por rol con meta `requiresAuth`/`roles`), `components/`, `composables/`.
- Rutas API bajo `/api/*`: auth, users, bots, bot-assignments, conversations,
  elevenlabs, feedback, statistics, openai, systemConfig.

## Convenciones

- TypeScript estricto en ambos lados; ESLint + Prettier (`npm run lint`,
  `npm run format` en cada paquete).
- Prisma: modelos PascalCase, campos camelCase, enums para valores fijos
  (UserRole, Level). Cambios de esquema siempre vía migraciones en desarrollo
  (`npm run prisma:migrate`), nunca editando la BD a mano.
- Controllers con `try/catch` + `next(error)`; logging con Winston, no
  `console.log` en backend.
- La API key de ElevenLabs se configura desde el panel admin del frontend
  (tabla de configuración en BD), no solo por `.env`.

## Testing

No hay framework de tests configurado. `test/` contiene scripts Node ad-hoc
(`node test/simple-test.js`, etc.) que se ejecutan desde la raíz del repo
contra la API levantada y usan las dependencias del `package.json` raíz, más
guías de pruebas manuales (`test/MANUAL-BOT-TESTS.md`). No asumir jest/vitest.

## Deploy y producción

- Deploy inicial: `./deploy-to-server.sh <dominio> <email>` (Apache + Certbot,
  systemd, cron de backup). Actualizaciones: `./upgrade-production.sh`
  (interactivo, hace backup y `git pull`; pedir snapshot del VPS antes).
- Producción: `docker compose --profile prod up -d --build`. Frontend estático
  en host 8080, backend 3000, contenedores `ai-learning-platform-ewc-*`.
- La BD real se llama **`ai_learning_platform`** (lo que dicen
  `docker-compose.yml` y los scripts); ignorar `englishworldcenter` si aparece
  en `env.production`/`.env.prod`.
- `VITE_API_URL` se embebe en **build time**: tras cambiarla hay que
  reconstruir `frontend-prod` (`build --no-cache`).
- Nunca `docker compose down -v` en producción (borra la BD).
- Los `.env` contienen secretos y no se commitean. No mostrarlos ni copiarlos.
- Referencia operativa completa: `../DOCUMENTACION-TRASPASO.md` (fuera del
  repo) y `README.md`.

## Notas para Claude

- Entorno de trabajo: macOS. Todos los scripts de operación son `.sh`
  (los `.ps1` de Windows se eliminaron del repo en julio 2026).