Los cursos técnicos suelen fallar por lo mismo: cada lección enseña una API aislada con un ejemplo de juguete, y al terminar sabes escribir veinte fragmentos que nunca has visto encajar. Este curso funciona al revés. Todo lo que aprendas a partir de aquí construirá una única aplicación real, módulo a módulo, hasta llegar a una API en producción.

Esa aplicación es Escena Viva. Ya has visto sus datos en las lecciones anteriores; ahora vamos a formalizarla: quién es, a quién sirve, cuál es su modelo de dominio, qué convenciones adopta y —lo más importante— qué parte de ella construirás en cada uno de los doce módulos. Al terminar esta lección tendrás el esqueleto del proyecto creado, el fichero semilla datos/eventos.json escrito y un mapa claro del destino.

1. El contexto de negocio
2. Los actores y lo que necesita cada uno
3. El modelo de dominio
4. El fichero semilla datos/eventos.json
5. La estructura de carpetas del repositorio
6. Hoja de ruta: qué construye cada módulo
7. Convenciones del proyecto
8. Nota sobre datos ficticios

Escena Viva es una pequeña empresa que gestiona la venta de entradas de tres espacios culturales de una ciudad de tamaño medio:

Hasta ahora, cada sala vendía sus entradas por su cuenta: una con una hoja de cálculo, otra por teléfono y la tercera con un sistema heredado que nadie sabe mantener. Escena Viva nace para unificarlo todo en una sola plataforma.

Los tres eventos con los que arrancamos —y que ya conoces— son:

• Concierto de Otoño (Teatro Almendra), 2 sesiones en octubre de 2026.
• Noche de Monólogos (Sala Bóveda), 3 sesiones en octubre de 2026.
• Festival de Jazz de Primavera (Auditorio Ribera), 2 sesiones en abril de 2027.

Los requisitos que marcan las decisiones técnicas del proyecto son estos:

1. Picos de concurrencia brutales y muy cortos. Cuando se abre la venta de un festival, miles de personas entran a la vez durante diez minutos. El resto del mes el tráfico es modesto.
2. El aforo no puede sobrevenderse. Es el requisito duro: dos personas no pueden comprar la misma butaca.
3. Los precios son dinero real. No admiten errores de redondeo.
4. Hay que integrarse con terceros: pasarela de pago, envío de correo, y en el futuro un lector de códigos en la puerta.
5. El equipo es pequeño. Dos personas desarrollan y mantienen todo, así que la simplicidad y la reutilización de conocimiento entre cliente y servidor tienen valor real.

Los puntos 1, 4 y 5 son exactamente las razones por las que, en la primera lección, concluimos que Node.js encaja con este negocio.

Esta separación no es decorativa: es la que justificará el control de acceso basado en roles del Módulo 8. Un organizador del Teatro Almendra no debe poder ver la recaudación de la Sala Bóveda.

Estas son las entidades del sistema. Los nombres de la columna "identificador" son los que usaremos literalmente en el código, en español y sin tildes ni ñ.

Y así se relacionan:

Tres decisiones de modelado que conviene entender desde ya:

• El aforo vive en la sesión, no en el evento. El Teatro Almendra tiene 420 localidades, pero una sesión concreta puede sacar a la venta solo 380 si hay una zona reservada para prensa. La sala aporta el máximo; la sesión, la realidad.
• La entrada es individual y tiene código propio. Un pedido de 4 entradas genera 4 registros entrada, cada uno con su código único, porque cada uno se valida por separado en la puerta.
• vendidas es un contador desnormalizado en la sesión. En rigor podría calcularse contando entradas, pero mostrar la disponibilidad en el catálogo debe ser instantáneo. En el Módulo 7 veremos cómo mantener ese contador coherente con transacciones.

Hasta el Módulo 7, cuando aparezca la base de datos escena_viva, este fichero es la fuente de datos de toda la aplicación. Crea datos/eventos.json con exactamente este contenido:

JSON no admite comentarios, así que los ponemos aquí:

Comprueba que el fichero es JSON válido antes de seguir:

Si el comando falla con SyntaxError, hay una coma de más, una comilla sin cerrar o has usado comillas simples. En JSON todas las claves y todas las cadenas van entre comillas dobles, y no se admite coma tras el último elemento.

Todavía no sabemos leer este fichero desde el código con fs —eso es el Módulo 3—, pero ya está en su sitio y ya es la referencia. A partir de ahí, src/catalogo-datos.js dejará de tener los datos incrustados.

Esta es la estructura objetivo, la que tendrá el proyecto al final del curso. No la crees entera ahora: crecerá con cada módulo.

Principios de organización que seguiremos:

• Una responsabilidad por carpeta. Si un fichero no sabes dónde ponerlo, probablemente hace dos cosas.
• src/ contiene solo código; datos/ solo datos; informes/ solo resultados generados. Los resultados generados nunca se versionan.
• Nombres de fichero en minúsculas y con guiones (catalogo-datos.js), nunca con espacios ni mayúsculas. Linux distingue mayúsculas y minúsculas aunque tu portátil no lo haga, y eso ha roto más despliegues de los que se pueden contar.

Esta tabla es el mapa del curso. Guárdala: cada vez que empieces un módulo sabrás qué pieza de Escena Viva estás añadiendo.

Estas reglas se aplican a todo el código del curso. Escritas una vez aquí, no volveremos a discutirlas.

Variables, funciones, clases, propiedades y nombres de fichero van en español, sin tildes ni ñ: precioCentimos, entradasLibres, calcularOcupacion, catalogo-datos.js.

Las excepciones son las que impone el entorno: palabras clave del lenguaje (const, class, return), APIs de Node y del navegador (readFile, createServer, map), y nombres de paquetes (express, mongoose).

¿Por qué sin tildes? Porque un identificador sesión es válido en JavaScript pero se convierte en una fuente de errores en cuanto viaja por una URL, un nombre de fichero o una cabecera HTTP. Mejor evitarlo de raíz.

Estilo: camelCase para variables y funciones, PascalCase para clases, MAYUSCULAS_CON_GUION_BAJO para constantes globales.

Toda fecha se almacena como cadena AAAA-MM-DDTHH:mm:ss.

Tres razones:

1. Se ordena correctamente como texto, sin convertir a Date.
2. No es ambiguo: 03/10/2026 es 3 de octubre en España y 10 de marzo en Estados Unidos.
3. Sobrevive al viaje por JSON. Un objeto Date se convierte en texto al serializar y no vuelve a ser Date al deserializar; si ya guardas texto, no hay sorpresas.

El formateo a 03/10/2026 20:00 es responsabilidad de la capa de presentación, nunca del almacenamiento.

Todo importe monetario se guarda como número entero de céntimos. 2500 significa 25,00 EUR.

El tipo number de JavaScript es un flotante de doble precisión (IEEE 754) y no puede representar exactamente 0,1. Con dinero, ese error se acumula y acaba en un descuadre contable. Trabajando con enteros el problema desaparece: solo se divide entre 100 en el último momento, para mostrar.

Convención de nombres: cualquier campo monetario lleva el sufijo Centimos (precioCentimos, totalCentimos, descuentoCentimos). Así es imposible confundirse.

Cada entrada tiene un código con el formato:

¿Por qué este formato y no un identificador aleatorio largo?

• Es legible por teléfono. Alguien puede dictarlo a atención al cliente sin errores.
• Es ordenable y su año es visible a simple vista.
• Es corto para imprimirlo bajo un código de barras.

Su contrapartida es que es predecible: si conoces un código puedes adivinar el siguiente. Por eso el código nunca es la prueba de propiedad; la validación en la puerta comprueba además el estado de la entrada en la base de datos. Es una decisión consciente, del tipo que se toma constantemente en un proyecto real.

Todos los datos de este curso son inventados. Las salas, los eventos, los organizadores, los correos y los pedidos que aparecerán a partir del Módulo 7 no corresponden a personas ni empresas reales.

Esto no es un formalismo: es una práctica profesional que debes trasladar a tu trabajo.

• Nunca uses datos reales de clientes en desarrollo, en pruebas ni en demostraciones. Ni siquiera "solo esta vez", ni siquiera una copia de la base de datos de producción en tu portátil.
• Las bases de datos de desarrollo se pueblan con datos sintéticos, generados o anonimizados. En el Módulo 7 veremos cómo escribir semillas para eso.
• Los datos personales están regulados. Nombres, correos, teléfonos y datos de pago tienen obligaciones legales de tratamiento y minimización.
• Nunca subas secretos al repositorio: claves de la pasarela de pago, contraseñas de base de datos o tokens. Van en variables de entorno (Módulo 11) y por eso el .gitignore incluye .env desde la primera lección.

Cuando en el Módulo 8 registremos al usuario [email protected], fíjate en el dominio .test: está reservado por norma para pruebas y nunca corresponderá a un buzón real.

Error 1: guardar los precios como decimales "porque es más cómodo". Lo es durante dos semanas. Después llega el primer descuadre de un céntimo en un informe de 3.000 pedidos y no hay forma de saber de dónde sale.

Error 2: usar formatos de fecha locales en los datos. 03/10/2026 obliga a saber quién lo escribió para interpretarlo. ISO 8601 en el almacenamiento, formato local solo al mostrar.

Error 3: poner el aforo en el evento en lugar de en la sesión. Funciona hasta la primera sesión con aforo reducido, y entonces hay que migrar datos.

Error 4: dejar el fichero JSON con una única línea gigante. Cada cambio aparece en el control de versiones como "toda la línea modificada" y las revisiones se vuelven imposibles. null, 2 siempre.

Error 5: mezclar idiomas en los identificadores. getEventoById, listarEvents, precioPrice. Elige uno —en este curso, español— y sé sistemático.

Consejo 1: vuelve a la hoja de ruta al empezar cada módulo. Saber qué pieza estás construyendo cambia por completo la forma de estudiar una API.

Consejo 2: usa git desde el primer día. Un git commit al terminar cada lección te da un punto de retorno y un histórico de tu propio aprendizaje.

Consejo 3: no adelantes trabajo. Es tentador montar ya el servidor Express. Cada módulo introduce los conceptos en un orden pensado; saltárselo suele acabar en código que funciona sin entender por qué.

Consejo 4: cuando dudes, mira el modelo de dominio. Buena parte de las decisiones de código se responden solas mirando la tabla de entidades.

Deja el proyecto listo para el Módulo 2. Debe cumplir:

1. La carpeta escena-viva/ contiene src/, datos/ e informes/.
2. datos/eventos.json existe con los tres eventos y es JSON válido.
3. informes/ está bajo control de versiones aunque esté vacía (pista: .gitkeep).
4. .gitignore excluye node_modules/, .env, *.log y el contenido generado de informes/ sin excluir la carpeta.
5. .nvmrc contiene la versión LTS instalada.
6. Existe un README.md con el nombre del proyecto, los tres eventos y los comandos para arrancar.
7. Un primer commit de git con todo lo anterior.

Escribe la secuencia completa de comandos y el contenido de cada fichero.

Añade a datos/eventos.json un cuarto evento con estas características:

• Título: Cuentos al Anochecer
• Sala: Teatro Almendra (organizador org-almendra)
• Categoría: familiar, duración 55 minutos, estado publicado
• Tres sesiones los sábados 7, 14 y 21 de noviembre de 2026 a las 18:00
• Aforo 200 en cada sesión (el Teatro Almendra reserva parte del patio de butacas para este formato)
• Entradas vendidas: 200, 145 y 30 respectivamente
• Precio: 1200 céntimos las dos primeras y 900 la tercera

Respeta los formatos de id, de fecha y de precio del proyecto. Después, verifica con comandos node -p que:

1. El fichero sigue siendo JSON válido y tiene 4 eventos.
2. El catálogo tiene ahora 10 sesiones.
3. El aforo total del Teatro Almendra (sumando todos sus eventos) es correcto.
4. Hay exactamente una sesión agotada.

Un compañero ha escrito este fragmento. Reescríbelo respetando todas las convenciones del proyecto y explica cada cambio.

Solución 1

.gitignore (punto 4). La clave es la excepción con !, para ignorar el contenido pero conservar la carpeta:

README.md (punto 6):

Verificación y primer commit (puntos 2 y 7):

Solución 2

Bloque a insertar al final del array de datos/eventos.json (recuerda la coma tras la llave de cierre del evento anterior):

Verificaciones:

Nota sobre el punto 4: ses-002-1 tiene 118 de 120 vendidas, así que no está agotada. La única agotada es la primera sesión del evento nuevo.

Solución 3

Cambios aplicados y su motivo:

Comprobación del cálculo: 118 × 1800 + 45 × 1800 = 212.400 + 81.000 = 293.400 céntimos = 2.934,00 EUR. Con precios decimales el resultado habría sido el mismo en este caso concreto, pero basta un precio de 18,99 y unos cientos de operaciones para que empiecen a aparecer céntimos fantasma.

Escena Viva ya no es un decorado: es un proyecto con contexto, actores, modelo de dominio, datos y reglas propias. Has visto quién usa la plataforma —asistente, organizador y administrador— y cómo esa separación anticipa el control por roles; has formalizado las entidades evento, sesion, entrada, pedido, usuario, organizador y sala, con sus relaciones y sus estados; has escrito el fichero semilla datos/eventos.json que será la fuente de datos hasta que aparezca la base de datos escena_viva; y has fijado las convenciones que no volverán a discutirse: identificadores en español sin tildes, fechas ISO 8601, precios en céntimos como entero, códigos de entrada EV-2026-000123, JSON con null, 2 y datos siempre ficticios.

Sobre todo, tienes la hoja de ruta. Sabes que en el Módulo 3 el catálogo dejará de estar incrustado en el código para leerse de disco, que en el Módulo 4 se asomará por HTTP, que en el Módulo 7 se mudará a una base de datos con transacciones que impidan sobrevender el aforo, y que en el Módulo 10 aprenderás a sostener el pico de tráfico de la apertura de venta de un festival.

Con esto cerramos el Módulo 1. Tienes el entorno instalado con una versión LTS gestionada por .nvmrc, sabes ejecutar y depurar un script, manejas el REPL como laboratorio, dominas el JavaScript moderno que usaremos y tienes el proyecto en pie con su semilla de datos.

Lo que aún no sabes es cómo funciona Node.js por dentro, y es la pieza que falta para escribir código de servidor de verdad. En el Módulo 2: Conceptos Básicos abriremos la caja: la arquitectura de Node, el bucle de eventos y sus fases, los callbacks, las promesas y async/await, los eventos con EventEmitter y el sistema de módulos con require y module.exports. Ahí, por fin, el array de eventos incrustado en src/catalogo-datos.js se convertirá en un módulo reutilizable, nacerán las clases Evento y Sesion en src/dominio/, y el camarero que no espera de la primera lección dejará de ser una analogía para convertirse en el código que escribes.