Módulo 8: Proyecto Integrador — Deployed AI System

1. Introducción: Proyecto Integrador — Deployed AI System

Descripción

Esta es la cápsula de apertura del Módulo 8, el último módulo de la Guía de Deployment & Cloud Infrastructure. Aquí no aprendes conceptos nuevos — aplicas TODO lo que construiste en los módulos 1 a 7. El resultado es un sistema AI desplegado en producción real, accesible desde internet, con documentación profesional que otro ingeniero puede usar para operar el sistema.

Por qué importa: Siete módulos construyeron skills individuales: decision framework (M1), Docker Compose (M2), Lambda (M3), LocalStack (M4), AWS services (M5), migration patterns (M6), plataformas alternativas (M7). Ahora integras todo en un pipeline de producción end-to-end. No es otro ejercicio — es un deployment de verdad. La dificultad no está en aprender algo nuevo, está en hacer que todas las piezas funcionen juntas. Esto es exactamente lo que pasa en producción real: los problemas aparecen en las interfaces entre sistemas, no dentro de cada sistema.

Al terminar este módulo, tendrás el artefacto más valioso de toda la guía: un sistema AI desplegado en producción, documentado con decision matrix que justifica cada decisión de infraestructura, con runbook operativo para incidencias, y validación automática post-deploy. No es un "proyecto de clase" — es infraestructura que puedes mostrar en una entrevista de trabajo o usar como base para un producto real.

Este módulo es 90% ejecución, 10% conceptos nuevos.

¿Dónde Estamos en la Guía?

Contexto

Esta guía tiene 8 módulos organizados en 3 fases:

Phase 1: Deployment Strategies (Módulos 1-3)
├── Módulo 1: Understanding Deployment Options         ✅ Completado
├── Módulo 2: Local & Container Deployment             ✅ Completado
└── Módulo 3: Serverless & Lambda for AI               ✅ Completado

Phase 2: Cloud Infrastructure & Migration (Módulos 4-6)
├── Módulo 4: LocalStack — AWS Local Development       ✅ Completado
├── Módulo 5: AWS Services for AI                      ✅ Completado
└── Módulo 6: Cloud Migration Patterns                 ✅ Completado

Phase 3: Alternatives & Production (Módulos 7-8)
├── Módulo 7: Alternative Platforms                    ✅ Completado
└── Módulo 8: Proyecto Integrador — Deployed AI System ← ESTÁS AQUÍ

Duración total estimada: 1.5-2 horas (ejecución intensiva).

Lo que integras

Cada módulo anterior aportó una pieza. Este módulo las conecta:

M1: Decision Matrix Framework
    → Documenta POR QUÉ elegiste esta estrategia y plataforma

M2: Docker Compose
    → Tu entorno de desarrollo local funciona con docker compose up

M3: Serverless & Lambda
    → Si tu decision matrix indica serverless, Lambda es parte de la arquitectura

M4: LocalStack
    → Tu entorno de testing de servicios AWS sin coste

M5: AWS Services
    → S3, Lambda, SageMaker pueden ser tu backend de producción

M6: Migration Patterns
    → El flujo local → staging → producción que ejecutas ahora

M7: Alternative Platforms
    → Render, Railway, Fly.io como destino de producción

La integración es el skill. Saber usar Docker, Lambda, AWS individualmente es valioso. Saber integrarlos en un pipeline end-to-end es lo que los empleadores buscan.

Objetivo del Módulo

Al terminar este módulo serás capaz de:

✅ Desplegar un sistema AI completo en una plataforma de producción real (AWS, Render, Railway, o Fly.io), accesible desde internet
✅ Integrar Docker images optimizados con CI/CD pipeline para deployment automático desde git push
✅ Ejecutar validación post-deploy automatizada: health checks que verifican que la API responde Y que la inferencia funciona
✅ Documentar decision matrix aplicada: qué estrategia eligió (M1), qué plataforma eligió (M7), y por qué
✅ Crear runbook operativo: qué hacer cuando el servicio cae, cómo rollbackear un deploy malo
✅ Establecer performance baseline: latency targets, cost monitoring, error rate targets
✅ Producir un deployment guide que otro ingeniero pueda seguir para replicar el setup desde cero

Objetivo profesional

Cuando completes este módulo, no dirás "sé deployar." Dirás: "Tengo un sistema AI en producción con URL pública, health checks automatizados, runbook operativo, y documentación de cada decisión de infraestructura." Eso es lo que diferencia a un developer que hace tutoriales de uno que opera sistemas reales.

Roadmap del Módulo

Mapa de cápsulas

#	Cápsula	Qué harás	Tipo
01	Introducción (esta)	Entender qué integras, el plan de ejecución, qué entregas	Intro
02	Architecture Integration	Conectar Docker + CI/CD + plataforma en un flujo coherente	Técnica
03	Deployment Automation	Automatizar deploy desde git push, environment promotion	Técnica
04	Post-Deploy Validation	Health checks + smoke tests que verifican inferencia real	Técnica
05	Runbook Operativo	Procedimientos para incidencias: caídas, rollback, costes	Técnica
06	Decision Matrix Final	Integrar M1 + M7 en la decisión aplicada con justificación	Técnica
07	Performance Baseline	Establecer targets de latencia, costes, error rate	Técnica
08	Proyecto: Deployed Production AI System	El entregable final: sistema desplegado + documentación	Proyecto

Flujo de ejecución

La progresión es deliberada. Primero conectas la arquitectura — cómo las piezas encajan (cápsula 02). Luego automatizas el deployment — de git push a producción (cápsula 03). Después validas que funciona de verdad — no solo 200 OK, sino inferencia real (cápsula 04). Creas el runbook para operar el sistema (cápsula 05). Documentas por qué elegiste esta configuración (cápsula 06). Estableces baselines de performance (cápsula 07). Y finalmente integras todo en el proyecto final (cápsula 08).

La progresión es: arquitectura → automatización → validación → operación → decisión → performance → proyecto.

Este no es un módulo de lectura. Es un módulo de hacer.

Qué Entregas al Final

Dos entregables con peso igual

Entregable 1: Sistema desplegado

Un sistema AI accesible desde internet:
├── URL pública funcional (ej: https://tu-app.railway.app)
├── Health check endpoint que responde ✅
├── Inference endpoint que procesa prompts reales
├── CI/CD: git push → deploy automático
└── Multi-entorno: local → staging → producción

Entregable 2: Documentación operativa

Documentación que otro ingeniero puede usar:
├── Decision Matrix v_final (estrategia + plataforma + justificación)
├── Runbook operativo (qué hacer cuando algo falla)
├── Deployment guide (cómo replicar el setup desde cero)
├── Performance baseline (latency, cost, error rate targets)
└── Post-deploy validation report (health checks + smoke tests)

Un sistema sin documentación no es production-ready — es un prototipo que funciona hoy y nadie sabe cómo operar mañana. Ambos entregables tienen el mismo peso.

Plataforma: Elige la Tuya

Este módulo es agnóstico de plataforma

Tu decision matrix de los módulos 1 y 7 determinó dónde despliegas. Este módulo funciona con cualquiera:

Plataforma	Free Tier	Deploy desde Git	Tiempo de setup
Render	Sí (750 hrs/mes)	Sí	~15 min
Railway	Sí ($5 crédito/mes)	Sí	~10 min
Fly.io	Sí (3 VMs compartidas)	Con CLI	~20 min
AWS (Lambda + API GW)	Sí (1M req/mes)	Con GitHub Actions	~45 min

Todas las plataformas tienen free tiers que hacen posible un deployment real sin coste. No hay excusa para "simular" un deploy.

Conexión con el Proyecto

Este módulo ES el proyecto integrador

El proyecto final de esta guía — Deployed Production AI System — integra todos los mini-proyectos anteriores:

Módulo 1: Decision Matrix → framework para decidir
    ↓
Módulo 2: Docker Compose → entorno local funcionando
    ↓
Módulo 3: Lambda → si aplica según tu decision matrix
    ↓
Módulo 4: LocalStack → testing de AWS sin coste
    ↓
Módulo 5: AWS Services → backend de producción (si elegiste AWS)
    ↓
Módulo 6: Migration → flujo local → staging → producción
    ↓
Módulo 7: Platform Choice → destino de producción elegido
    ↓
Módulo 8: TODO INTEGRADO → sistema desplegado + documentación

Conexión con la guía #18 (Monitoring & Observability)

Este es el último módulo de esta guía. Al completarlo, estás preparado para la guía #18 que toma el sistema desplegado en producción y le añade observabilidad: métricas, logs estructurados, tracing, alertas, y dashboards. La transición natural: "Tienes un sistema AI en producción → ahora necesitas ver qué pasa dentro de él."

Prerequisitos

Lo que ya debes tener

Para ejecutar este módulo necesitas artefactos concretos de módulos anteriores:

De módulo	Artefacto	Por qué lo necesitas
M1	Decision matrix v1	Base de tu justificación de estrategia
M2	Dockerfile + docker-compose.yml	Tu app AI containerizada
M7	Decision matrix v2 (con plataformas)	Decisión de dónde desplegar
#15	Conocimiento Docker	Build y push de images
#16	CI/CD pipeline básico	GitHub Actions para automatizar

Herramientas verificadas

# Docker y Docker Compose
docker --version        # 24.0+
docker compose version  # v2.20+

# Python
python --version        # 3.10+

# Git y GitHub CLI
git --version
gh --version            # Para crear releases (opcional)

# Tu app AI funcional localmente
docker compose up -d
curl http://localhost:8000/health  # Debe responder OK

Estructura de archivos esperada

tu-proyecto-ai/
├── Dockerfile                 # Image optimizado (M2)
├── docker-compose.yml         # Multi-container local (M2)
├── .github/
│   └── workflows/
│       └── deploy.yml         # CI/CD pipeline (este módulo)
├── src/
│   └── main.py                # Tu app FastAPI
├── tests/
│   └── test_smoke.py          # Smoke tests (este módulo)
├── docs/
│   ├── decision-matrix.md     # Decision matrix v_final (este módulo)
│   ├── runbook.md             # Runbook operativo (este módulo)
│   └── deployment-guide.md    # Guía de deployment (este módulo)
├── scripts/
│   └── validate-deploy.sh     # Validación post-deploy (este módulo)
├── .env.example               # Template de variables de entorno
└── README.md                  # Documentación del proyecto

Mentalidad de Este Módulo: Integración > Herramientas Individuales

El skill que más valor tiene

Saber usar Docker es valioso. Saber configurar GitHub Actions es valioso. Saber deployar en Railway es valioso. Pero saber hacer que Docker + GitHub Actions + Railway funcionen juntos en un pipeline coherente es lo que los empleadores realmente buscan.

La integración es difícil porque los problemas no aparecen dentro de cada herramienta — aparecen en las interfaces entre herramientas:

Problemas DENTRO de una herramienta:        Problemas de INTEGRACIÓN:
├── Dockerfile syntax error                 ├── Docker build funciona local, falla en CI
├── GitHub Actions YAML inválido            ├── CI/CD pasa pero el deploy no se activa
├── Railway config incorrecta               ├── Deploy funciona pero health check falla
└── Fácil de diagnosticar y resolver        ├── Todo funciona pero las env vars no se pasan
                                            └── Difícil de diagnosticar, requiere entender el flujo

Este módulo te entrena en diagnosticar y resolver problemas de integración. Es la habilidad que más aplicas en producción real.

La diferencia entre "funciona en mi máquina" y "funciona en producción"

"Funciona en mi máquina":
├── Docker compose up → funciona ✅
├── .env cargado localmente
├── Ports accesibles en localhost
├── Sin SSL, sin dominio público
└── Solo tú puedes usarlo

"Funciona en producción":
├── URL pública con HTTPS
├── Secrets gestionados por la plataforma
├── Health checks automáticos
├── CI/CD despliega sin intervención
├── Documentación para que OTRO ingeniero lo opere
├── Monitoreo externo detecta si se cae
└── Runbook define qué hacer cuando falla

El gap entre estas dos realidades es lo que cubren las cápsulas de este módulo.

Los errores que solo aparecen en producción

Hay una categoría de errores que nunca ves en desarrollo local:

Cold starts: Tu app tarda 10 segundos en responder el primer request porque la plataforma dormía el container
Memory limits: Tu app usa 2GB de RAM localmente sin problema, pero la plataforma solo le asigna 512MB
Network latency: La llamada a OpenAI tarda 1s local, 2.5s en producción por routing
Secret rotation: Tu API key expira y nadie se da cuenta hasta que la app deja de funcionar
Concurrent requests: 10 requests simultáneos funcionan local, pero en producción 100 simultáneos crashean tu single-threaded server

La única forma de descubrir estos errores es desplegando de verdad. Por eso este módulo requiere deployment real, no simulado.

Cómo Abordar Este Módulo

La estrategia de ejecución

Este módulo es 90% ejecución. La estrategia óptima:

1. Lee la cápsula 01 (esta) completa — entender el plan (15 min)
2. Para cada cápsula 02-07:
   a. Lee la sección de teoría (5 min)
   b. Ejecuta el código / crea el artefacto (20-30 min)
   c. Verifica que funciona (5 min)
3. Cápsula 08: integra todo en el proyecto final (45-60 min)
4. Verifica con el checklist de completitud

No leas todas las cápsulas primero y ejecutes después. Lee una, ejecuta, lee la siguiente. El aprendizaje está en la ejecución, no en la lectura.

Lo que debes tener antes de empezar

# Verifica esto AHORA, no cuando estés en la cápsula 03:

# 1. Tu app AI funciona localmente
docker compose up -d
curl http://localhost:8000/health
# Debe responder 200

# 2. Tu repo está en GitHub
git remote -v
# Debe mostrar un remote de GitHub

# 3. Tienes cuenta en tu plataforma elegida
# Railway: railway.app (login con GitHub)
# Render: render.com (login con GitHub)
# Fly.io: fly.io (registro + CLI)

# 4. Tienes API key de OpenAI (o tu LLM provider)
echo $OPENAI_API_KEY | head -c 10
# Debe mostrar "sk-..."

Si alguno de estos falla, resuélvelo antes de continuar.

Límites: Qué NO Cubre Este Módulo

❌ Kubernetes — Orquestación avanzada está fuera del scope de esta guía
❌ Terraform / Infrastructure as Code — Automatización de infra a nivel enterprise
❌ Monitoring avanzado — Eso es la guía #18 (Monitoring & Observability)
❌ Auto-scaling avanzado — Configuración de scaling policies y load balancers
❌ Multi-region deployment — Un solo deployment en una región es suficiente
❌ Networking avanzado — VPCs, subnets, load balancers se mencionan pero no se configuran
❌ Bases de datos en producción — PostgreSQL, Redis como servicios managed están fuera del scope
❌ Custom domains — Funcionar con el subdominio de la plataforma (*.railway.app) es suficiente

Evidencia de Éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Tienes una URL pública que responde a requests desde cualquier navegador
✅ Un health check automatizado verifica que el sistema está vivo
✅ Un smoke test envía un prompt real y verifica que la inferencia funciona
✅ Un git push dispara build → test → deploy automáticamente
✅ Tu decision matrix documenta POR QUÉ elegiste esta estrategia y plataforma
✅ Tu runbook tiene procedimientos para al menos 4 escenarios de incidencia
✅ Otro ingeniero puede replicar tu setup siguiendo tu deployment guide
✅ Tienes baselines de latencia y coste documentados

Test rápido de autoevaluación

Si puedes responder estas preguntas, estás listo:

¿Cuál es la URL de tu sistema AI desplegado?
¿Qué pasa cuando haces git push a main?
¿Cómo verificas que la inferencia funciona después de un deploy?
¿Qué haces si el servicio se cae a las 3am?
¿Por qué elegiste esta plataforma y no otra?

Resumen

Este módulo es 90% ejecución, 10% conceptos nuevos — aplicas lo construido en M1-M7
Dos entregables con peso igual: sistema desplegado + documentación operativa
El deployment debe ser real: URL pública, accesible desde internet, con free tiers
La dificultad es la integración: Docker + CI/CD + plataforma + validación
La documentación no es "extra" — es producción: decision matrix, runbook, deployment guide
Este es tu portfolio piece: el artefacto más valioso de toda la guía
Funciona con cualquier plataforma: AWS, Render, Railway, Fly.io
Después de este módulo → guía #18 (Monitoring & Observability)

Acabas de llegar al último módulo. Lo que sigue es poner tu sistema AI en producción — esto es real.

Recursos Adicionales

The Twelve-Factor App — Principios para apps production-ready
AWS Well-Architected Framework — Framework de evaluación de arquitectura
Architecture Decision Records (ADR) — Formato estándar para documentar decisiones
Render Documentation — Docs de Render para deployment
Railway Documentation — Docs de Railway
Fly.io Documentation — Docs de Fly.io
GitHub Actions Documentation — CI/CD con GitHub Actions

← Anterior8. Proyecto: Deploy to Platform of Choice Siguiente →2. Architecture Integration — Conectando las Piezas