Una guía simple, sin tecnicismos, para que armes tu proyecto apoyado en tu asistente de IA y entiendas cómo encaja con todo lo demás.
Patrón de referencia para construir un proyecto web e integrarlo a nuestra arquitectura: stack, flujo de trabajo y servicios disponibles.
Tu foco es construir tu proyecto. De la infraestructura —dominios, deploy, base de datos y respaldos— nos encargamos nosotros.
Construyes tu proyecto en tu computador, de la mano de tu asistente de IA y siguiendo nuestras convenciones: roles y permisos y validación en frontend y backend.
Cuando tu MVP esté maduro, se lo entregas a TI y montamos el dominio, el repositorio en GitLab y el deploy en Dokploy. Desde ahí, cada cambio que hagas se publica solo.
Desarrollas en local con las convenciones del equipo: control de acceso por roles y permisos, y validación en cliente y servidor.
Entregas el MVP a TI. Provisionamos el dominio (*.ynk.cl en Cloudflare), el repo en GitLab y el deploy en Dokploy. Desde ahí, cada push corre el pipeline de CI/CD y despliega solo.
Instala esto en tu computador antes de empezar a construir.
Instala el toolkit base antes de clonar el proyecto.
Más el runtime de tu stack (Node.js para Next.js).
Antes de empezar, descarga las definiciones del proyecto con los botones de arriba a la derecha: si usas Claude Code, baja CLAUDE.md; si usas otro asistente como Codex, Copilot, Cursor o Gemini, baja AGENTS.md. Ese archivo le entrega a tu asistente de IA todo lo que necesita para trabajar en el proyecto con nuestras reglas y convenciones.
Así se ve un proyecto web una vez que lo publicamos. No necesitas memorizarlo: tu asistente de IA ya lo conoce.
Desliza el diagrama para verlo completo →
Un repaso rápido de cada pieza del diagrama. No necesitas dominarlo —tu asistente de IA ya lo conoce—; esto es para que tú también tengas el mapa.
Tu dominio público (proyecto.ynk.cl) vive en Cloudflare, que filtra el tráfico (WAF) y lo dirige al servidor Dokploy. Por ahí entran todos los usuarios.
El servidor donde corre tu proyecto: lo despliega, lo mantiene en línea y guarda sus variables de entorno. Para casos avanzados, separa ambientes de QAS y producción.
Tu código vive en GitLab. Cada cambio que subes dispara un pipeline que construye y publica tu app en Dokploy, sin pasos manuales.
Cada proyecto trae su propia base PostgreSQL, y Redis como caché si hace falta. Para datos que se comparten entre sistemas, usas el Data Warehouse.
Las apps usan roles y permisos: un usuario puede tener varios roles, los permisos van al rol (no al usuario) y se validan en front y back. Sin login propio, va Google OAuth.
Una base PostgreSQL aparte que reúne datos de todos los sistemas para reportería, organizada por origen y con vistas listas para consultar.
Dominio *.ynk.cl en Cloudflare: DNS, proxy, WAF y TLS, gestionado por TI. Enruta todo el tráfico entrante al servidor Dokploy.
PaaS self-hosted sobre Docker. Maneja deploy, logs, dominios y variables de entorno. Ambientes QAS/PRD separados cuando el proyecto lo amerita.
GitLab self-hosted con runners propios. Cada push dispara el pipeline: build y deploy automático a Dokploy. Lo mismo aplica a cada cambio posterior al lanzamiento, sin pasos manuales.
PostgreSQL por proyecto + Redis para caché y colas. Lo que se comparte entre sistemas se consume desde el Data Warehouse.
RBAC: un usuario, varios roles; permisos al rol, no al usuario. Validación en cliente y servidor. Google OAuth si no hay login propio.
PostgreSQL independiente que consolida los datos de todos los sistemas, con un esquema por origen y vistas listas para reportería.
El ciclo código → build → despliegue está estandarizado sobre GitLab CE y Dokploy. Cada push a main construye en CI una imagen Docker inmutable y el despliegue solo baja esa imagen ya hecha —nunca se reconstruye en producción—. Principio rector: pipeline verde = imagen construida y publicada en el registry; si el lint, los tests o el build fallan, no se publica ni se despliega nada.
El flujo es lineal: GitLab guarda el código y la imagen, GitLab CI construye y publica con kaniko, y Dokploy baja la imagen ya construida (:sha) y la ejecuta.
La etapa quality (lint + tests) corre antes de construir. Si falla, el pipeline se detiene: no se construye, no se publica y no se despliega nada.
El runner no tiene Docker daemon ni modo privilegiado, así que kaniko construye la imagen en espacio de usuario, sin docker build ni docker-in-docker. Se usa la imagen mantenida, fijada a una versión.
Cada build publica registry.ynk.cl/<grupo>/<repo> con dos tags: :<sha> (inmutable, para rollback exacto) y :latest (referencia móvil para el deploy).
Push con el CI_JOB_TOKEN integrado de GitLab; pull desde Dokploy con un deploy token de grupo (read_registry). Los secretos viven en el Environment de Dokploy, nunca en el repo ni horneados en la imagen.
Servicio web: app Docker (registry) en :latest con health-check y auto-rollback. Job batch: contenedor keep-alive más Schedules (cron) que ejecutan el comando real.
registry.ynk.cl resuelve localmente hacia Traefik (/etc/hosts en el host y extra_hosts en el runner). Es load-bearing: si se recrea el VPS o el runner, hay que reponerlo.
Piezas que tu proyecto puede integrar según lo que necesite. Casi todas son opcionales y se habilitan caso a caso, sin afectar el flujo base.
De toda la parte técnica —dónde vive tu proyecto, su seguridad, los respaldos y las conexiones— nos encargamos nosotros. Tú te concentras en construir. ¿Necesitas algún acceso? Escríbenos a dev@ynk.cl.
Toda la infraestructura —DNS, CI/CD, base de datos, respaldos, Data Warehouse e integraciones— la gestiona TI; tú te concentras en el desarrollo. ¿Necesitas un acceso o una integración? Pídelo a dev@ynk.cl. Para usar un modelo de IA por API, indica el proveedor y modelo y justifica su uso.