Onboarding · Prácticas DAW

Documentación de proyectos

Todo lo que se ha montado en los repositorios de Coco Global Media: qué es cada proyecto, con qué tecnologías está construido, cómo arrancarlo en tu ordenador y dónde está desplegado. Pensado para que alguien que llega nuevo pueda entenderlo y ponerse a trabajar.

👋 Introducción

Bienvenido/a. En Coco Global Media desarrollamos webs y aplicaciones para clientes (restaurantes, hoteles, etc.). Cada cliente suele tener varios repositorios que trabajan juntos.

La convención de nombres te dice el rol de cada repo:

carta / web / front

La web pública

Lo que ve el cliente final

panel

El panel de gestión

Backoffice para el negocio

server

La API / backend

Base de datos y lógica

Muchos repos comparten el mismo nombre base (p. ej. ...-carta, ...-panel, ...-server). Fíjate siempre en el sufijo para saber qué parte estás tocando.

Cómo usar esta guía: usa el buscador de la izquierda para filtrar por proyecto o tecnología. Cada repo tiene su ficha con stack, estructura, pasos de arranque en local, variables de entorno y hosting.

🔑 Accesos y credenciales

Para cualquier credencial o información sensible (accesos a hosting, paneles de administración, bases de datos, claves de API, dominios, correos, etc.) solicítala en el documento de datos de Google de la agencia. No se guardan credenciales en el código, en los repositorios ni en esta documentación.

Si necesitas un dato que no aparece aquí (una URL de producción, una clave, un acceso concreto), pídelo por ahí antes de bloquearte.

🧰 Requisitos previos

Instala esto una sola vez en tu equipo antes de empezar con cualquier proyecto.

Node.js

v20 LTS o superior

La Perla web pide v22.12+. Usa nvm-windows para cambiar de versión.

npm

v11+

Viene con Node. Comprueba con npm -v.

Git

Última versión

Y acceso a la organización CocoGlobalMedia en GitHub.

Editor

VS Code

Recomendado. Extensiones: Angular, ESLint, Prettier, Astro.

Base de datos

Según proyecto

PostgreSQL (local o Neon) o MongoDB. Ver cada ficha.

Cuenta Vercel

Opcional

La mayoría se despliega en Vercel.

⚙️ Flujo de trabajo genérico

Casi todos los proyectos siguen los mismos pasos para arrancar en local. Las diferencias concretas están en cada ficha.

Clona el repositorio desde GitHub.
Entra en la carpeta del proyecto.
Instala dependencias con npm install.
Configura el entorno: si hay un .env.example, cópialo a .env y rellénalo (típico en backends y apps Next.js).
Base de datos: si usa Prisma, ejecuta las migraciones y el seed.
Arranca el servidor de desarrollo (npm run dev o npm start).

# 1-3 · Clonar, entrar e instalar
git clone https://github.com/CocoGlobalMedia/<nombre-del-repo>.git
cd <nombre-del-repo>
npm install

# 4 · Entorno (solo si existe .env.example)
cp .env.example .env    # en Windows PowerShell: copy .env.example .env

# 6 · Arrancar
npm run dev             # Angular usa: npm start

Orden importante: en los proyectos con panel o front que consumen una API, primero arranca el server (normalmente en localhost:3000) y luego el frontend.

🌿 Flujo de ramas (Git)

Cómo trabajamos con las ramas en todos los repositorios. La regla de oro: nunca se hace commit directo a main — todo pasa por Pull Request (PR).

main

Producción · no se toca

Rama estable. Solo recibe merges de develop vía PR.

develop

Integración · rama de trabajo

Donde se juntan las features terminadas.

feature/*

Nueva característica

Se crea desde develop para cada tarea. Efímera.

Ciclo de vida de una feature

Sitúate en develop y actualízala (git pull).
Crea una rama feature/<nombre-descriptivo> desde develop.
Desarrolla la característica y haz commits en esa rama.
Abre un PR de feature/* → develop.
Se revisa el PR; una vez aprobado se mergea y se cierra/borra la rama feature.
Cuando están terminadas todas las tareas, se abre un PR de develop → main para llevar los cambios a producción.

En comandos

# 1-2 · Partir de develop actualizada y crear la feature
git checkout develop
git pull origin develop
git checkout -b feature/mi-nueva-caracteristica

# 3 · Trabajar y subir la rama
git add .
git commit -m "feat: descripción del cambio"
git push -u origin feature/mi-nueva-caracteristica

# 4-5 · Abrir el PR hacia develop (desde GitHub) → revisar → merge → borrar rama

# 6 · Al terminar todas las tareas: PR de develop hacia main (desde GitHub)

Resumen del recorrido: feature/* →(PR + revisión)→ develop →(PR final)→ main. Cada flecha es un Pull Request revisado; nunca se mergea sin PR.

Buenas prácticas: nombres de rama claros (feature/login-usuarios), un PR por tarea, y no dejes ramas feature/* vivas una vez mergeadas.

Convención de nombres de commits

Usamos Conventional Commits: el mensaje empieza por un tipo, dos puntos y una descripción breve en imperativo y en minúscula.

<tipo>: descripción breve en imperativo

# Ejemplos
feat: añade filtro por categoría en la carta
fix: corrige el cálculo del precio por media unidad
docs: actualiza el README del panel
style: ajusta espaciado del header (sin cambios de lógica)
refactor: extrae la lógica de auth a un servicio
chore: sube versión de dependencias

Tipo	Cuándo usarlo
`feat`	Nueva característica o funcionalidad.
`fix`	Corrección de un error.
`docs`	Solo documentación (README, comentarios, esta guía).
`style`	Formato/estilos sin cambiar la lógica (espacios, CSS, prettier).
`refactor`	Reestructurar código sin cambiar el comportamiento.
`perf`	Mejora de rendimiento.
`test`	Añadir o corregir tests.
`chore`	Tareas de mantenimiento (dependencias, config, build).

El mismo criterio sirve para los PR: pon un título claro con su tipo (p. ej. feat: reservas online) y una descripción de qué incluye y cómo probarlo.

🔌 Puertos y comandos por tecnología

Tecnología	Arrancar	Puerto local	Build
Angular (carta / panel / Suki)	`npm start`	`4200`	`npm run build` → `dist/`
Astro (La Romana, La Perla web)	`npm run dev`	`4321`	`npm run build` → `dist/`
Next.js (apps de reseñas)	`npm run dev`	`3000`	`npm run build`
React CRA (app La Romana)	`npm start`	`3000`	`npm run build` → `build/`
Express (APIs / server)	`npm run dev`	`3000`	`npm run build` → `dist/`
Estático (landing Suki Sushi)	`npx serve .`	—	Sin build

🏗️ Arquitecturas recurrentes

Verás estos mismos patrones repetidos en varios clientes. Entender uno te sirve para entender los demás.

🍽️ Patrón "carta + panel + server"

El más completo. Lo usan Bossa Nova y La Perla de Canet. Tres piezas:

Carta pública — Angular 21 con SSR (renderizado en servidor). Muestra el menú.
Panel — Angular 21 (+ Angular CDK, drag & drop). El negocio gestiona la carta.
Server — API REST con Express + TypeScript, PostgreSQL con SQL directo (pg), Prisma para el modelo/seed, autenticación JWT y roles (admin / camarero).

⭐ Plantilla "reseñas" (reviews)

Una misma app reutilizada para captar valoraciones y filtrar las negativas. La usan La Bolita Coqueta y El Siglo (hotel y restaurante).

Next.js 16 (App Router + React Server Components), React 19, Tailwind CSS v4.
Prisma ORM + Neon (PostgreSQL serverless).
Login por cookies HTTP-only firmadas (jose), validación con zod.
Emails con Resend + un cron diario (definido en vercel.json) que avisa de reseñas negativas.

🚀 Webs con Astro

La Romana (carta) y La Perla (web) usan Astro: HTML muy optimizado, ideal para webs de contenido. Se despliegan en Vercel.

Bossa Nova Wine Bar

Carta digital, panel de gestión y API para el wine bar. Sitio: bossanovawinebar.com

Arquitectura: carta (Angular SSR) → server (Express + PostgreSQL) ← panel (Angular)

Carta pública carta-bossa-nova Ver en GitHub ↗

Carta digital pública: explora el menú por categorías con carga dinámica y filtrado.

Angular 21SSR (@angular/ssr)Express 5TypeScript strictSCSSVitestrama: main

Estructura

src/app/core (layout), features/home (menú), shared/ui/header, src/styles (variables globales).

Arrancar en local

npm install
npm start            # http://localhost:4200 (con HMR)
npm run build        # build de producción
npm run serve:ssr:carta-bossa-nova  # sirve el build SSR

Hosting

Vercel (estático). vercel.json define outputDirectory: dist/carta-bossa-nova/browser.

Dato útil: la carta pública se sirve desde un JSON estático (vercel.json reescribe /api/menu → /assets/data/menu.json), no llama a la API en producción.

API / Backend carta-bossa-nova-server Ver en GitHub ↗

API REST: platos, vinos, bebidas, picoteo y menú semanal. Autenticación JWT y control por roles. Producción: api.bossanovawinebar.com

Node 18+Express 4TypeScriptPostgreSQL (Railway)pg (SQL directo)Prisma 5 (schema/seed)JWT + bcryptMulter

Arrancar en local

npm install
Crea un .env en la raíz (ver tabla).
npm run prisma:generate y npm run prisma:migrate
npm run prisma:seed (datos iniciales)
npm run dev → http://localhost:3000

Variables de entorno (.env)

Variable	Uso
DATABASE_URL	Cadena de conexión a PostgreSQL
JWT_SECRET	Secreto para firmar los tokens
PORT	Puerto (por defecto 3000)
CORS_ORIGIN	Orígenes permitidos (whitelist, separados por coma)
UPLOAD_DIR	Carpeta de subidas (uploads)
NODE_ENV	development / production

Otros comandos

npm run build        # compila a dist/
npm start            # ejecuta el build
npm run typecheck    # comprueba tipos
npm run lint         # ESLint (0 warnings)
npm test             # Jest
npm run prisma:studio # explora la BD en el navegador

Hosting

Vercel como función serverless (@vercel/node, entrada api/index.ts). Base de datos en Railway.

Roles: admin y camarero. Las rutas públicas (GET de productos activos) no requieren login; crear/editar requiere camarero; eliminar y reordenar requieren admin.

Panel carta-bossa-nova-panel Ver en GitHub ↗

Panel de administración de la carta, usuarios y cuenta. Producción: panel.bossanovawinebar.com

Angular 21Angular CDKsortablejs (drag & drop)SCSS

Arrancar en local

npm install
npm start            # http://localhost:4200

Necesita el backend corriendo en http://localhost:3000. La URL de la API se configura en src/environments/environment.ts (local) y environment.prod.ts (producción).

Hosting

Vercel (estático, SPA). vercel.json apunta a dist/frontend con redirección SPA a index.html.

La Romana

Stack mixto de 4 repos: carta (Astro), app de cliente (React), panel (Angular) y API (Express + MongoDB).

Arquitectura: carta (Astro) · front (React) · panel (Angular 19) → server (Express + MongoDB)

A diferencia de Bossa Nova / La Perla (PostgreSQL), el backend de La Romana usa MongoDB. Y su panel es Angular 19 con Bootstrap, no Angular 21 con SCSS.

Carta / Web laromana-carta Ver en GitHub ↗

Web/carta construida con Astro.

Astro 5Tailwind 3MDXsitemappartytownoutput: staticrama: master

Arrancar en local

npm install
npm run dev          # http://localhost:4321
npm run build        # genera ./dist
npm run preview      # previsualiza el build

Hosting

Vercel (adaptador @astrojs/vercel, salida estática).

El README del repo es todavía la plantilla por defecto de Astro (sin personalizar). La info real está en el código y aquí.

App cliente appRomanaFront Ver en GitHub ↗

Aplicación web de cara al cliente (SPA).

React 18Create React Appaxiosreact-router-dom 7zustand (estado)

Aclaración: aunque se hablaba de una "app con Ionic", este repositorio en realidad es una app React (Create React App), no Ionic. La documentación refleja lo que hay en el código. Si existe un proyecto Ionic aparte, habría que añadir su repo.

Arrancar en local

npm install
npm start            # http://localhost:3000
npm run build        # genera ./build

Entorno

Usa un archivo .env (variables REACT_APP_*, típicamente la URL de la API). No está incluido en el repo; pídelo o créalo según la API.

Hosting

No hay vercel.json en el repo. Al ser un build estático de CRA (build/) se despliega en cualquier hosting estático (Vercel / Netlify).

Panel appRomanaPanel Ver en GitHub ↗

Panel de administración / dashboard con gráficas.

Angular 19Bootstrap 5ApexCharts / Chart.jsSweetAlert2jQueryKarma/Jasmine

Arrancar en local

npm install
npm start            # ng serve · http://localhost:4200
npm run build        # genera dist/app-romana-panel

API / Backend appRomanaServer Ver en GitHub ↗

Backend de La Romana.

Node + Express 4MongoDB (mongoose)JWT + bcryptmorganResend (emails)

Arrancar en local

npm install
npm run dev          # nodemon · entrada src/app.js
npm start            # producción

Entorno

Necesita un .env (no incluido) con al menos la URI de MongoDB, JWT_SECRET y la API key de Resend. Pídelo al responsable del proyecto.

Hosting

Vercel (@vercel/node, entrada src/app.js).

La Bolita Coqueta

App de reseñas: capta votos anónimos, dirige las reseñas positivas a Google y avisa de las negativas por email.

Arquitectura: app única Next.js (full-stack) + Neon PostgreSQL — plantilla "reseñas"

Full-stack bolita-coqueta-reviews Ver en GitHub ↗

Next.js 16 (App Router)React 19 (RSC)Tailwind v4Prisma + Neon Postgresjose (auth cookies)zodResend

Arrancar en local

Crea una base de datos en Neon y copia la cadena de conexión.
Copia .env.example a .env y rellena las variables.
npm i
npx prisma migrate dev --name init
npx prisma db seed
npm run dev (ejecuta la migración antes de levantar Next.js) → localhost:3000

Variables de entorno (.env)

Variable	Uso
DATABASE_URL	PostgreSQL de Neon
GOOGLE_REVIEW_URL	Enlace a Google donde redirigir reseñas positivas
SESSION_SECRET	Secreto de sesión (cookies firmadas)
ADMIN_EMAIL / ADMIN_PASSWORD	Credenciales del panel admin
RESEND_API_KEY	Envío de emails
EMAIL_FROM / EMAIL_TO	Remitente y destinatario de avisos
CRON_SECRET	Token para proteger el cron

Hosting

Vercel + Neon. Tras el primer deploy: npx prisma migrate deploy y npm run db:seed desde la consola de Vercel. El vercel.json define un cron diario (07:00 UTC) que envía el resumen de reseñas negativas.

Suki Ramen

Dos repos: la web del grupo (Angular SSR) y una landing estática de preapertura.

Web oficial suki-restaurantes Ver en GitHub ↗

Web oficial del grupo Suki Ramen (Xúquer, Colón, Cullera, Santiago y Sapporo) y sus cartas.

Angular 21SSR (@angular/ssr)Express 5TypeScript strictSCSSVitestNode 20+

Arrancar en local

npm install
npm start            # http://localhost:4200
npm run build        # build de producción
npm run serve:ssr:suki-restaurantes  # sirve SSR

Rutas principales

/ (home) · /restaurantes/:slug (detalle) · /restaurantes/:slug/carta (carta).

Hosting

App Angular con SSR. El README no fija plataforma; se despliega como el resto (Vercel o un Node host que ejecute el build SSR).

Landing estática suki_sushi_ramen Ver en GitHub ↗

Landing "próximamente / en construcción" para Suki Sushi Ramen (Cullera). Sin backend ni build.

HTML5CSS3JS vanillaSin build

Arrancar en local

# Opción 1: abrir index.html directamente en el navegador
# Opción 2: servidor estático
npx serve .
# o
python -m http.server

Estructura

index.html, proximamente.html, css/styles.css, js/script.js, assets/img/.

Hosting

Cualquier hosting estático: GitHub Pages, Netlify o Vercel.

Limpieza: el repo contiene un archivo residual bash.exe.stackdump que se puede borrar sin problema.

El Siglo

Dos repos que usan la misma plantilla de reseñas que La Bolita Coqueta (Next.js + Neon).

Aunque un repo se llama el_siglo_hotel y otro el_siglo_restaurante, ambos comparten exactamente el mismo código (package name el-siglo-restaurantes). Son dos instancias del mismo proyecto — normalmente con dos bases de datos Neon distintas.

Full-stack el_siglo_hotel Ver en GitHub ↗

Next.js 16React 19Tailwind v4Prisma + NeonjoseResend + cron

Mismo arranque, variables de entorno y hosting que La Bolita Coqueta. Consulta esa ficha para los pasos detallados.

Full-stack el_siglo_restaurante Ver en GitHub ↗

Next.js 16React 19Tailwind v4Prisma + NeonjoseResend + cron

Idéntico a el_siglo_hotel. Arranque y variables como en La Bolita Coqueta.

La Perla de Canet

Restaurante del Club Náutico de Canet d'en Berenguer. Tres repos: web (Astro), panel (Angular) y API (Express + PostgreSQL).

Arquitectura: web (Astro) · panel (Angular 21) → server (Express + PostgreSQL)

La web y el panel referencian el backend como carta-la-perla-de-canet-server, pero el repo real se llama la_perla_de_canet_server. Es el mismo backend.

Web pública la_perla_de_canet_web Ver en GitHub ↗

Web pública del restaurante. Consume la API de la carta, envía candidaturas de "Trabaja con nosotros" (Resend), integra feed de Instagram (Behold.so) y reservas (widget de Cover Manager).

Astro 7TypeScript strictNode ≥22.12GSAPResendi18n es/enBehold.so

Arrancar en local

npm install
cp .env.example .env   # rellena las variables
npm run dev            # http://localhost:4321

Variables de entorno (.env)

Variable	Uso
CARTA_API_URL	URL base de la API de la carta (`http://localhost:3000` en local)
RESEND_API_KEY	Envío del formulario de candidatura
RESEND_FROM	Remitente del email
CANDIDATURA_TO	Buzón que recibe las candidaturas
BEHOLD_FEED_ID	ID del feed de Instagram (Behold.so)

El README describe SSR con @astrojs/node standalone, pero el astro.config.mjs actual está en output: "static" con i18n (es sin prefijo, en bajo /en/). Si al desplegar necesitas SSR real, revisa esa configuración con el responsable.

Hosting

Astro en Vercel. Idiomas: español (sin prefijo) e inglés (/en/).

Panel la_perla_de_canet_panel Ver en GitHub ↗

Panel de gestión de carta (productos, vinos, categorías) y cuenta.

Angular 21Angular CDKsortablejs (drag & drop)SCSS

Arrancar en local

npm install
npm start            # http://localhost:4200

Necesita el backend en http://localhost:3000. URL de API en src/environments/environment.ts. En producción, configura apiUrl en environment.prod.ts.

Hosting

Vercel (estático). vercel.json → dist/la-perla-de-canet-panel con redirección SPA.

API / Backend la_perla_de_canet_server Ver en GitHub ↗

API REST: productos (carta), vinos y alérgenos. JWT y roles. Puede importar la carta desde un Excel.

Node 18+Express 4TypeScriptPostgreSQL (pg)Prisma 5JWT + bcryptMulterResendxlsx

Arrancar en local

npm install
Crea el .env (ver tabla).
npm run prisma:generate · npm run prisma:migrate
npm run prisma:seed (usuario admin + alérgenos)
npm run dev → http://localhost:3000

Variables de entorno (.env)

Variable	Uso
DATABASE_URL	Conexión a PostgreSQL
JWT_SECRET	Secreto de los tokens
JWT_EXPIRES_IN	Expiración (p. ej. 8h)
PORT	Puerto (3000)
CORS_ORIGIN	Orígenes permitidos
UPLOAD_DIR	Carpeta de subidas
NODE_ENV	development / production

Comando extra

npm run import:carta importa productos y vinos desde un Excel.

Hosting

Vercel serverless (@vercel/node, api/index.ts) + PostgreSQL.

Clientes con WordPress

Sitios construidos con WordPress + Elementor (no tienen repositorio de código como los proyectos anteriores; se gestionan desde el propio WordPress).

El acceso a cada WordPress (usuario/contraseña, panel del hosting, FTP/BBDD) está en el documento de datos de Google. Aquí solo se indica dónde está alojado cada sitio.

Cliente	Hosting
64 Restaurante	Hosting de Coco (Raiola Networks)
The Obsession	Hosting de Coco (Raiola Networks)
Asecam	Hosting propio del cliente
Clinic Veres	Hosting propio del cliente
El Siglo	Hosting propio del cliente
PDH (Peritos de Hogar)	Hosting propio del cliente
Chapapria	Hosting propio del cliente
Mareta Meua	Hosting propio del cliente

Sobre "El Siglo": además de la web WordPress (hosting propio), tiene las apps de reseñas en Next.js — ver el proyecto El Siglo en la sección de código.

Leyenda: "Hosting de Coco" = servidores de la agencia (Raiola Networks). "Hosting propio" = servidor contratado por el propio cliente.

🏢 Agencia e infraestructura

Hosting de Coco

Raiola Networks

Donde se alojan los sitios propios de la agencia.

Repos de código

GitHub · CocoGlobalMedia

Proyectos Angular / Astro / Next.js / React.

Despliegue apps

Vercel (+ Neon / Railway)

Bases de datos gestionadas en la nube.

Credenciales

Documento de datos (Google)

Fuente única para accesos e info sensible.

Para cualquier acceso o dato adicional (hosting Raiola, paneles de cliente, dominios, correos, claves), consulta el documento de datos de Google.

📚 Glosario para prácticas (DAW)

Términos que aparecen mucho en estos proyectos, explicados en corto.

SSR

Server-Side Rendering: el HTML se genera en el servidor (mejor SEO y primera carga). Angular y Astro lo usan.

SPA

Single Page Application: la app se carga una vez y navega sin recargar (Angular panel, React).

API REST

Servidor que expone datos por HTTP (GET/POST/PUT/DELETE). Aquí, con Express.

JWT

JSON Web Token: "carné" firmado que identifica al usuario tras el login.

Prisma

ORM: define el modelo de datos y genera migraciones/seed para la base de datos.

Cliente de PostgreSQL en Node. Aquí se usa SQL directo (raw) con un pool de conexiones.

Neon / Railway

PostgreSQL en la nube. Neon es serverless; Railway es un host de servicios y BBDD.

Migración

Cambio versionado del esquema de la BD (crear tablas/columnas).

Seed

Datos iniciales que se cargan en la BD (usuario admin, categorías…).

.env

Archivo con variables secretas (claves, conexiones). Nunca se sube a Git.

HMR

Hot Module Replacement: recarga en caliente al guardar, sin refrescar toda la página.

Resend

Servicio para enviar emails desde el código (avisos, formularios).

✅ Checklist del primer día

Pide acceso a la organización CocoGlobalMedia en GitHub.
Instala Node 20+, Git y VS Code.
Elige un proyecto y localiza sus repos por el sufijo (carta/web/front, panel, server).
Clona el repo, ejecuta npm install y revisa si hay .env.example.
Si tiene backend con base de datos, pide las credenciales del .env (o crea una BD de pruebas en Neon).
Arranca primero el server, luego el panel/front.
Abre el proyecto en el navegador y compara con la web/panel en producción.
Ante cualquier duda, pregunta antes de tocar datos de producción.

Seguridad: nunca subas archivos .env ni claves a GitHub, y no ejecutes migraciones o seed contra bases de datos de producción sin confirmarlo.