LangGraph · FastAPI · Python 3.11 · Docker · OAuth2 · LangSmith · uv (opcional)
Portafolio de 25 casos de uso empresariales construidos con LangGraph y FastAPI: 25 backends completamente operativos (casos 01-25 sin omisiones) con streaming, OAuth2/OIDC opt-in, observabilidad LangSmith,
/metricspor servicio, logging JSON estructurado y reverse proxy nginx + TLS. Ola 3 cerrada en v4.14.0 — portfolio al 100%. v4.15.0: release de hardening de seguridad y mantenibilidad (auditoría adversarial: 4 critical fixes inline +shared/lgrw_common/como fuente canónica +python-jose→joserfc+ CI a los 25 casos).
| 🎯 | Métrica | Valor |
|---|---|---|
| 🟢 | Casos operativos | 25 / 25 (100%) |
| 🏭 | Casos industriales | 3 (09, 10, 13) |
| 📋 | Scaffolds restantes | 0 (Ola 3 cerrada) |
| 🧪 | Tests por caso | 18-30, todos verdes |
| 🔌 | Modo DEMO | 100% sin APIs externas |
| 🔑 | Modo LIVE | Opt-in con OPENAI_API_KEY |
| 🛡️ | Auditoría seguridad | 8 capas (SECURITY.md) |
| ⚡ | Tooling | pip + pip-tools (defecto), uv (~10× opcional) |
| Caso | Tag | Por qué mirarlo |
|---|---|---|
| 04 | 🛡️ SOC | Router de riesgo (3 vías), threat intel, SIEM context |
| 06 | 🛡️ Compliance | ISO/SOC2/GDPR + cadena de custodia SHA-256 encadenada |
| 07 | 🛒 Compras | Score multi-criterio (precio/plazo/riesgo) + router política comité + OC con SHA-256 |
| 13 | 📊 BI | SQL agent endurecido + Chart.js + LLM opt-in |
| 14 | 💰 Finanzas | Matching multi-criterio + z-score outliers determinista |
| 17 | ⚖️ Legal | 3 especialidades + 3 plantillas + asignación de abogado |
| 18 | 📣 Marketing | Doble loop QA: estilo de marca + fact-check con fuentes |
| 22 | 🏢 Backoffice | 3 routers + loop completitud + log inmutable SHA-256 |
| 21 | 📝 Docs | Loop QA condicional (tope 3 iter) + outline adaptativo |
| 25 | 🤝 Multi-agent | Supervisor + 4 workers especializados (DEMO) |
El estándar actual del repositorio se apoya en estos pilares:
| # | Pilar | Descripción |
|---|---|---|
| 1 | 🌐 Portal unificado | index.html como entrada principal para navegar el portafolio |
| 2 | ⚙️ Casos de referencia reales | Backends FastAPI y UIs activas en los casos 01, 02, 03, 04, 05, 06, 07, 08, 09, 10, 13, 14, 17, 18, 19, 21, 22 y 25 |
| 3 | 📐 Estado tipado | Contratos explícitos con TypedDict y flujos compatibles con LangGraph |
| 4 | 🔭 Observabilidad | /health, /ready, /metrics con latencia, errores y modo; LangSmith opt-in |
| 5 | 🔀 Modo dual | Demos offline + ruta clara para activar integraciones reales |
| 6 | 🐳 Operación portable | Docker, nginx+TLS, Hub CLI o entorno local según el caso |
| 7 | 🛡️ Hardening integrado | grype fail-build:true, detect-secrets history, pip-compile, Dependabot |
| 8 | 🔑 Auth multicapa | X-Demo-Token (opt-in) + OAuth2/OIDC JWT (opt-in via USE_OAUTH2=true) |
| 9 | 🔒 Auditoría de seguridad 8 capas | Non-root, 127.0.0.1, HTTP headers, grype, Trojan Source, nginx TLS |
Tip
Consulta el detalle técnico en CHANGELOG.md, SECURITY.md y los docs en docs/.
| ID | Nombre | Estado | Stack principal |
|---|---|---|---|
| 01 | 🎧 Soporte Cliente Omnicanal | ✅ OPERATIVO |
FastAPI · LangGraph · Routing · OAuth2 opt-in |
| 02 | 🖥️ Mesa de Ayuda TI / SRE | ✅ OPERATIVO |
FastAPI · LangGraph · CMDB · HITL |
| 03 | 🚨 Incident Response SRE | ✅ OPERATIVO |
FastAPI · LangGraph · HITL · Runbooks P1/P2/P3 |
| 04 | 🔐 SOC Triage de Alertas | ✅ OPERATIVO |
FastAPI · LangGraph · Threat Intel · Router de riesgo |
| 05 | 📄 Analista de Documentos | ✅ OPERATIVO |
FastAPI · LangGraph · Keyword extraction · Router de riesgo |
| 06 | 🛡️ Compliance & Auditorías | ✅ OPERATIVO |
FastAPI · LangGraph · ISO/SOC/GDPR · Cadena de custodia SHA-256 |
| 07 | 🛒 Compras y Abastecimiento | ✅ OPERATIVO |
FastAPI · LangGraph · Score multi-criterio · Router política comité · OC SHA-256 |
| 08 | 💼 Ventas B2B + CRM | ✅ OPERATIVO |
FastAPI · LangGraph · ICP scoring · CRM stage automático |
| 09 | 👥 RRHH Screening & Agenda | 🏭 INDUSTRIAL |
FastAPI · LangGraph · MemorySaver · Resilience |
| 10 | 🚀 Onboarding de Empleados | 🏭 INDUSTRIAL |
FastAPI · LangGraph · RBAC · Integrations |
| 11 | 🎓 Tutor Adaptativo | ✅ OPERATIVO |
FastAPI · LangGraph · Simulador IRT · 3 routers · Loop adaptativo |
| 12 | 🧠 Psicometría y Evaluaciones | ✅ OPERATIVO |
FastAPI · LangGraph · α Cronbach · Discriminación · DIF · Loop validez |
| 13 | 📊 Analista de Datos BI | 🏭 INDUSTRIAL |
FastAPI · SQL Agent · Chart.js · DEMO/LLM |
| 14 | 💰 Finanzas — Conciliación | ✅ OPERATIVO |
FastAPI · LangGraph · matching multi-criterio · z-score outliers |
| 15 | 🛍️ E-commerce Postventa | ✅ OPERATIVO |
FastAPI · LangGraph · 3 routers · Etiqueta SHA-256 · Convergencia humano |
| 16 | ✅ OPERATIVO |
FastAPI · LangGraph · Itinerario multi-criterio · Travel DEMO | |
| 17 | ⚖️ Legal Intake | ✅ OPERATIVO |
FastAPI · LangGraph · 3 especialidades · 3 plantillas · Asignación |
| 18 | 📣 Marketing con QA | ✅ OPERATIVO |
FastAPI · LangGraph · Doble loop QA · Brand guard · Fact-check |
| 19 | 🔍 DevEx: PR Review | ✅ OPERATIVO |
FastAPI · LangGraph · Security Analysis · Changelog |
| 20 | 🏛️ Migración Legacy | ✅ OPERATIVO |
FastAPI · LangGraph · Inventario · Plan de migración multi-fase |
| 21 | 📝 Documentación Automática | ✅ OPERATIVO |
FastAPI · LangGraph · Outline adaptativo · Loop QA condicional |
| 22 | 🏢 Backoffice Automatización | ✅ OPERATIVO |
FastAPI · LangGraph · 3 routers · Loop completitud · Cadena SHA-256 |
| 23 | 🏥 Salud: Pre-triage | ✅ OPERATIVO |
FastAPI · LangGraph · Triage clínico · Routers de severidad |
| 24 | 📋 Asistente PM | ✅ OPERATIVO |
FastAPI · LangGraph · Backlog · Riesgos · Reportes ejecutivos |
| 25 | 🤝 Supervisor + Workers | ✅ OPERATIVO |
FastAPI · LangGraph · Multi-agente · Due Diligence |
Ola 3 cerrada en v4.14.0 — los 25 casos están operativos. No quedan scaffolds pendientes.
| Perfil | Ruta recomendada | Qué explorar |
|---|---|---|
| 👨💻 Dev / DevOps | Caso 01 | Routing condicional y fallback DEMO/LIVE |
| 🖥️ IT Admin / SRE | Caso 02 | Enriquecimiento de perfil, HITL y runbooks |
| 🤖 Dev / ML Eng | Caso 09 | Resiliencia, streaming y MemorySaver |
| 🏗️ Dev / Arquitecto | Caso 10 | RBAC, flujo empresarial e integraciones |
| 📊 Analista / BI | Caso 13 | SQL seguro, visualización y LLM opcional |
| 🧑💼 Recruiter / HM | docs/RECRUITER.md | Resumen ejecutivo y señales de seniority |
| 🐣 Principiante | docs/BEGINNERS_GUIDE.md | Mapa del repositorio paso a paso |
| 🔒 Auditor / CISO | SECURITY.md | Postura de seguridad, controles y riesgos aceptados |
| Documento | Contenido |
|---|---|
| ROADMAP.md | Hoja de ruta — mapa de todos los documentos, estado de los 25 casos, orden de elevación por olas, mejoras transversales |
| CHANGELOG.md | Historial de cambios por versión |
| CONTRIBUTING.md | Cómo contribuir — estructura, estilo, testing y Docker |
| SECURITY.md | Auditoría 8 capas, riesgos aceptados, hardening |
| CODE_OF_CONDUCT.md | Código de conducta |
| killed.md | Features eliminadas o pausadas |
| Documento | Contenido |
|---|---|
| docs/ARCHITECTURE.md | Estructura del monorepo, patrón DEMO/LIVE, compose y hub |
| docs/TECHNICAL_SPECS.md | Stack, contratos de API, guardrails de seguridad |
| docs/INSTALL.md | Cómo levantar el repo: Docker, local, Hub CLI, uv opt-in |
| docs/UV.md | ⚡ Uso opcional de uv (Astral) — gestor Python ~10× más rápido que pip |
| docs/REQUIREMENTS.md | Requisitos: Git, Python, Docker, APIs opcionales |
| docs/HUB.md | Hub CLI — comandos, guardrails, estado de casos |
| docs/AGENTS_AND_SKILLS.md | Skills de agentes, estándar de un caso completo, orden de trabajo |
| docs/CLOUD_AWS.md | ☁️ Migración a AWS — 3 estrategias (PoC ~25 USD · Producción ~180 USD · Enterprise ~650 USD), mapeo Docker→AWS, paso a paso, costos y FinOps |
| docs/COSTS.md | 💰 Costos DEMO vs LIVE — APIs requeridas por caso, pricing público OpenAI/SaaS, recetas para activar LIVE |
La wiki contiene versiones navegables de la documentación técnica publicadas automáticamente desde docs/wiki/ en cada push a main.
| Página | Contenido |
|---|---|
| Wiki Home | Entrada de la wiki — estado del portfolio, inicio rápido |
| Roadmap | Hoja de ruta — orden de elevación de casos, mejoras pendientes |
| Arquitectura | Estructura del monorepo y patrón DEMO/LIVE |
| Especificaciones Técnicas | Stack, contratos de API, guardrails |
| Seguridad | Auditoría 8 capas |
| Guía para Principiantes | Mapa del repo paso a paso |
| Hub CLI | Comandos del Hub CLI |
# 1. Clonar
git clone https://github.com/vladimiracunadev-create/langgraph-realworld.git
cd langgraph-realworld
# 2. Copiar credenciales (opcional — los casos funcionan en DEMO sin ellas)
cp .env.example .env
# Editar .env con tu OPENAI_API_KEY
# 3. Levantar un caso con Docker
docker compose up case01
# → UI disponible en http://localhost:8001/web/
# 4. O usar el Hub CLI
python hub.py list
python hub.py run --case 01Important
Los casos funcionan en DEMO sin credenciales externas. Agrega OPENAI_API_KEY en .env para activar el modo LIVE con integraciones reales.
- Copia
backend/.env.exampleabackend/.enven el caso que quieras llevar a LIVE. - O abre el portal raíz y usa Configurar APIs del portfolio para exportar el
.envpor caso. - Sin credenciales, todos los casos funcionan en DEMO automáticamente.
Si un backend va a salir de localhost, activa controles adicionales en su .env:
DEMO_AUTH_TOKEN=replace-with-a-long-random-token
RATE_LIMIT_RPM=60
TRUST_PROXY_HEADERS=falseImportant
El portal sólo persiste valores si pulsas Guardar localmente. Los almacena en localStorage del navegador en texto claro. Úsalo sólo en equipos de confianza. Para trabajo serio, inyecta secretos vía .env, variables de entorno o un secret manager externo.
| Nivel | Criterios | Casos |
|---|---|---|
| ✅ OPERATIVO | Backend real, DEMO/LIVE, CI, tests, hardening, OAuth2 opt-in | 01, 02, 03, 04, 05, 06, 07, 08, 11, 12, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25 |
| 🏭 INDUSTRIAL | Backend real, streaming, observabilidad, docs completas | 09, 10, 13 |
| 🔧 SCAFFOLD | Demo estática lista para evolucionar | — (ninguno: Ola 3 cerrada en v4.14.0) |
Este repositorio ha sido auditado por 8 capas de seguridad (v4.15.0). El release v4.15.0 incorpora 4 fixes críticos identificados en la auditoría adversarial v4.14.0 (JWKS cache TTL, aud/iss obligatorios en OAuth2, sanitización HTTP 500, validación pattern en pr_id del caso 19), migración python-jose+ecdsa → joserfc (elimina dependencia abandonada con timing side-channel) y shared/lgrw_common/ como fuente canónica para auth.py y settings.py (sync vía script + CI check). Detalle en CHANGELOG.md y SECURITY.md.
| Capa | Control | Estado |
|---|---|---|
| 🐳 Contenedores | Usuario non-root (appuser/nginx), imágenes pineadas |
✅ |
| 🌐 Red | Puertos vinculados a 127.0.0.1 |
✅ |
| 🔒 Credenciales | detect-secrets + baseline enforced en CI |
✅ |
| 🛡️ Web server | HTTP security headers en los 25 demos nginx | ✅ |
| 🔍 Dependencias | pip-audit + Dependabot semanal |
✅ |
| 🧪 SAST | CodeQL analysis en Python | ✅ |
| 🏗️ CI/CD | Actions pinneadas a SHA, sin persist-credentials |
✅ |
| ⛓️ Supply chain | grype scan, detección Trojan Source (CVE-2021-42574) | ✅ |
Consulta SECURITY.md para el detalle completo, riesgos aceptados y roadmap de hardening.