{"id":32692889,"url":"https://github.com/marcosotomac/proyecto-cloud","last_synced_at":"2026-04-12T06:31:47.633Z","repository":{"id":317934766,"uuid":"1069429415","full_name":"marcosotomac/proyecto-cloud","owner":"marcosotomac","description":"Plataforma cloud de microservicios con IA para chat conversacional, generación de imágenes y síntesis de voz. Arquitectura distribuida con API Gateway, Docker, MongoDB, AWS S3. Guía completa de deployment en AWS.","archived":false,"fork":false,"pushed_at":"2025-10-18T18:29:48.000Z","size":937,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-01T16:07:21.056Z","etag":null,"topics":["aws","framer-motion","mongodb","nestjs","nextjs","postgresql","python","s3-bucket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marcosotomac.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-03T23:32:59.000Z","updated_at":"2025-10-18T18:29:52.000Z","dependencies_parsed_at":"2025-10-04T01:31:00.399Z","dependency_job_id":null,"html_url":"https://github.com/marcosotomac/proyecto-cloud","commit_stats":null,"previous_names":["marcosotomac/proyecto-cloud"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/marcosotomac/proyecto-cloud","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fproyecto-cloud","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fproyecto-cloud/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fproyecto-cloud/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fproyecto-cloud/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marcosotomac","download_url":"https://codeload.github.com/marcosotomac/proyecto-cloud/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marcosotomac%2Fproyecto-cloud/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31706764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-12T06:22:27.080Z","status":"ssl_error","status_checked_at":"2026-04-12T06:21:52.710Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","framer-motion","mongodb","nestjs","nextjs","postgresql","python","s3-bucket"],"created_at":"2025-11-01T16:02:06.080Z","updated_at":"2026-04-12T06:31:47.625Z","avatar_url":"https://github.com/marcosotomac.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 LLM Microservices Platform\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Docker](https://img.shields.io/badge/Docker-Compose-blue)](https://www.docker.com/)\n[![Next.js](https://img.shields.io/badge/Next.js-15.5-black)](https://nextjs.org/)\n[![NestJS](https://img.shields.io/badge/NestJS-10-red)](https://nestjs.com/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-green)](https://fastapi.tiangolo.com/)\n\nPlataforma empresarial de microservicios para APIs LLM con autenticación JWT, almacenamiento S3, analíticas en tiempo real y frontend moderno. Arquitectura escalable diseñada para procesamiento de IA, generación de contenido multimedia y análisis de datos.\n\n## 📋 Tabla de Contenidos\n\n- [Características Principales](#-características-principales)\n- [Arquitectura del Sistema](#️-arquitectura-del-sistema)\n- [Servicios Implementados](#-servicios-implementados)\n- [Stack Tecnológico](#-stack-tecnológico)\n- [Inicio Rápido](#-inicio-rápido)\n- [Configuración del Entorno](#-configuración-del-entorno)\n- [Desarrollo Local](#️-desarrollo-local)\n- [APIs y Endpoints](#-apis-y-endpoints)\n- [Autenticación y Seguridad](#-autenticación-y-seguridad)\n- [Almacenamiento y Bases de Datos](#️-almacenamiento-y-bases-de-datos)\n- [Frontend Dashboard](#-frontend-dashboard)\n- [Deployment](#-deployment)\n- [Testing](#-testing)\n- [Monitoreo y Logs](#-monitoreo-y-logs)\n- [Troubleshooting](#-troubleshooting)\n- [Roadmap](#-roadmap)\n- [Contribución](#-contribución)\n- [Licencia](#-licencia)\n\n## ✨ Características Principales\n\n- 🔐 **Autenticación JWT robusta** con access y refresh tokens\n- 🎨 **Generación de imágenes con IA** usando Pollinations.ai\n- 🔊 **Text-to-Speech multiidioma** con soporte para 20+ idiomas\n- 💬 **Chat LLM** integrado con GitHub Models (GPT-4o)\n- 📊 **Analytics en tiempo real** con MongoDB\n- 🌐 **API Gateway unificado** para enrutamiento centralizado\n- 🖥️ **Dashboard moderno** con Next.js 15 y React 19\n- 🗄️ **Almacenamiento S3** compatible con MinIO\n- 🐳 **Containerización completa** con Docker Compose\n- 📈 **Escalabilidad horizontal** por microservicio\n- 🔒 **Seguridad por capas** con validación y sanitización\n- 📝 **Historial completo** de todas las operaciones\n\n## 🏗️ Arquitectura del Sistema\n\n```mermaid\ngraph TB\n    Client[Cliente Web/Móvil\u003cbr/\u003eNext.js 15]\n    Gateway[API Gateway\u003cbr/\u003eFastAPI:8080]\n\n    Client --\u003e|HTTPS/JWT| Gateway\n\n    Gateway --\u003e|/auth/*| Users[Users Service\u003cbr/\u003eNestJS:3000]\n    Gateway --\u003e|/chat/*| LLM[LLM Chat Service\u003cbr/\u003eFastAPI:8002]\n    Gateway --\u003e|/image/*| Image[Text-to-Image\u003cbr/\u003eFastAPI:8000]\n    Gateway --\u003e|/tts/*| Speech[Text-to-Speech\u003cbr/\u003eFastAPI:8001]\n    Gateway --\u003e|/analytics/*| Analytics[Analytics Service\u003cbr/\u003eFastAPI:8005]\n\n    Users --\u003e|SQL| PG[(PostgreSQL\u003cbr/\u003eUsers DB\u003cbr/\u003e:5432)]\n    Speech --\u003e|SQL| PGTTS[(PostgreSQL\u003cbr/\u003eTTS DB\u003cbr/\u003e:5434)]\n    LLM --\u003e|NoSQL| Mongo[(MongoDB\u003cbr/\u003e:27017)]\n    Analytics --\u003e|NoSQL| Mongo\n\n    Image --\u003e|S3| Bucket[Bucket S3\u003cbr/\u003e:9000/9001]\n    Speech --\u003e|S3| Bucket\n\n    LLM --\u003e|API| GitHub[GitHub Models\u003cbr/\u003eGPT-4o]\n    Image --\u003e|API| Poll[Pollinations.ai]\n    Speech --\u003e|API| GTTS[Google TTS]\n\n    style Gateway fill:#ff6b6b\n    style Client fill:#4ecdc4\n    style Users fill:#45b7d1\n    style LLM fill:#96ceb4\n    style Image fill:#ffeaa7\n    style Speech fill:#dfe6e9\n    style Analytics fill:#a29bfe\n    style PGTTS fill:#74b9ff\n```\n\n## 🎯 Servicios Implementados\n\n### ✅ Frontend Dashboard (Next.js 15)\n\n- **Puerto:** 3001 (desarrollo)\n- **Framework:** Next.js 15 + React 19\n- **UI:** Tailwind CSS + shadcn/ui + Radix UI\n- **Características:**\n  - 🎨 Dashboard moderno con tema claro/oscuro\n  - 🔐 Sistema completo de autenticación (login/registro)\n  - 🖼️ Interfaz de generación de imágenes con preview\n  - 🔊 Generador de audio text-to-speech\n  - 💬 Chat interactivo con LLM\n  - 📊 Visualización de historial y estadísticas\n  - 📱 Diseño responsive y optimizado\n  - ⚡ Turbopack para desarrollo ultra-rápido\n  - 🎭 Animaciones con Framer Motion\n  - 📋 Formularios con React Hook Form + Zod\n\n### ✅ API Gateway (FastAPI)\n\n- **Puerto:** 8080\n- **Framework:** FastAPI + Python 3.11\n- **Características:**\n  - 🔀 Enrutamiento centralizado a todos los servicios\n  - 🔐 Validación JWT en el gateway\n  - 📊 Métricas y logging centralizado\n  - 🚦 Rate limiting y throttling\n  - 🔄 Proxy reverso con balanceo de carga\n  - 📝 Documentación OpenAPI unificada\n\n### ✅ Users/Auth Service (NestJS)\n\n- **Puerto:** 3000\n- **Framework:** NestJS + TypeScript\n- **Base de datos:** PostgreSQL 16\n- **Características:**\n  - 👤 Registro y autenticación de usuarios\n  - 🔑 JWT con access tokens (15min) y refresh tokens (30d)\n  - 🔄 Gestión de sesiones persistentes\n  - 🔒 Hash de contraseñas con bcrypt\n  - 📧 Validación de email único\n  - 🛡️ Guards y decoradores personalizados\n  - 📝 Logs estructurados\n\n### ✅ LLM Chat Service (FastAPI)\n\n- **Puerto:** 8002\n- **Framework:** FastAPI + Python 3.11\n- **Base de datos:** MongoDB 7\n- **Proveedor:** GitHub Models (GPT-4o, GPT-4o-mini)\n- **Características:**\n  - 💬 Chat conversacional con contexto\n  - 🧠 Múltiples modelos LLM disponibles\n  - 📝 Historial de conversaciones\n  - 👤 Chats por usuario autenticado\n  - 🌊 Streaming de respuestas (opcional)\n  - 📊 Analytics de uso por modelo\n  - 🔧 Configuración de parámetros (temperatura, max_tokens)\n\n### ✅ Text-to-Image Service (FastAPI)\n\n- **Puerto:** 8000\n- **Framework:** FastAPI + Python 3.11\n- **Almacenamiento:** MinIO (S3-compatible)\n- **Proveedor:** Pollinations.ai\n- **Características:**\n  - 🎨 Generación de imágenes desde prompts\n  - 📐 Múltiples tamaños (512x512, 1024x1024, etc.)\n  - 🗄️ Almacenamiento en S3 con metadatos\n  - 👤 Soporte para usuarios autenticados y anónimos\n  - 📋 Historial organizado por fecha\n  - 🔗 URLs firmadas temporales para descarga\n  - 🖼️ Formatos PNG/JPG\n\n### ✅ Text-to-Speech Service (FastAPI)\n\n- **Puerto:** 8001\n- **Framework:** FastAPI + Python 3.11\n- **Base de datos:** PostgreSQL 16 (TTS DB)\n- **Almacenamiento:** MinIO (S3-compatible)\n- **Proveedor:** Google Text-to-Speech (gTTS)\n- **Características:**\n  - 🔊 Síntesis de voz desde texto\n  - 🌍 20+ idiomas soportados (en, es, fr, de, it, pt, ja, zh-CN, ko, etc.)\n  - 🎚️ Modelos: gtts (normal), gtts-slow (velocidad lenta)\n  - 🗄️ Almacenamiento dual: S3 para audio + PostgreSQL para metadata\n  - 📊 Persistencia relacional de todas las conversiones TTS\n  - 🔍 Búsquedas eficientes con índices en user_id y created_at\n  - 📈 Tracking de latencia, tamaño de archivos y costos\n  - 👤 Soporte para usuarios autenticados y anónimos\n  - 📋 Historial completo con metadata JSON flexible\n  - 🔗 URLs firmadas temporales para descarga\n  - 🎵 Formato MP3\n\n### ✅ Analytics Service (FastAPI)\n\n- **Puerto:** 8005\n- **Framework:** FastAPI + Python 3.11\n- **Base de datos:** MongoDB 7\n- **Características:**\n  - 📊 Tracking de todas las operaciones\n  - 📈 Estadísticas de uso por servicio\n  - 👥 Análisis por usuario\n  - ⏱️ Métricas de rendimiento\n  - 📉 Costos y consumo de recursos\n  - 🔍 Queries agregadas y reportes\n  - 📅 Historial temporal\n\n## � Stack Tecnológico\n\n### Frontend\n\n- **Framework:** Next.js 15.5 con React 19.1\n- **Lenguaje:** TypeScript 5\n- **Estilos:** Tailwind CSS 3.4\n- **Componentes:** shadcn/ui + Radix UI\n- **Formularios:** React Hook Form + Zod\n- **Animaciones:** Framer Motion 12\n- **HTTP:** Axios\n- **Temas:** next-themes\n\n### Backend\n\n- **Node.js:** NestJS 10 (Users Service)\n- **Python:** FastAPI 0.115 (Gateway, LLM, Image, Speech, Analytics)\n- **TypeScript/JavaScript:** Node.js 18+\n- **Validación:** Pydantic, class-validator\n\n### Bases de Datos\n\n- **PostgreSQL 16:**\n  - Users DB (:5432) - Datos relacionales (usuarios, sesiones)\n  - TTS DB (:5434) - Conversiones text-to-speech con metadata\n- **MongoDB 7:** Datos no estructurados (chats, analytics)\n- **MinIO:** Almacenamiento S3-compatible (imágenes, audios)\n\n### Infraestructura\n\n- **Containerización:** Docker + Docker Compose\n- **Orquestación:** Docker Compose con healthchecks\n- **Networking:** Bridge network interna\n- **Volúmenes:** Persistencia de datos local\n\n### APIs Externas\n\n- **GitHub Models:** GPT-4o, GPT-4o-mini\n- **Pollinations.ai:** Generación de imágenes\n- **Google TTS:** Síntesis de voz\n\n### Desarrollo\n\n- **Gestor de Paquetes:** pnpm (frontend), npm (users), pip (python services)\n- **Linters:** ESLint, Prettier\n- **Build:** Turbopack (Next.js), esbuild (NestJS)\n\n## 🚀 Inicio Rápido\n\n### Prerrequisitos\n\nAsegúrate de tener instalado:\n\n- **Docker** \u003e= 20.10\n- **Docker Compose** \u003e= 2.0\n- **Git**\n- (Opcional) **Node.js** \u003e= 18 para desarrollo local\n- (Opcional) **Python** \u003e= 3.11 para desarrollo local\n- (Opcional) **pnpm** para desarrollo frontend\n\n### 1. Clonar el Repositorio\n\n```bash\ngit clone https://github.com/marcosotomac/proyecto-cloud.git\ncd proyecto-cloud\n```\n\n### 2. Configurar Variables de Entorno\n\n```bash\n# Ejecutar script de configuración automática\n./setup.sh\n\n# O manualmente crear archivos .env en cada servicio\n# Ver sección \"Configuración del Entorno\" para detalles\n```\n\n### 3. Levantar la Plataforma Completa\n\n```bash\n# Construir y levantar todos los servicios\nmake up-build\n\n# O usando docker-compose directamente\ndocker-compose up -d --build\n```\n\n### 4. Verificar Estado de los Servicios\n\n```bash\n# Ver estado de todos los contenedores\nmake status\n\n# Verificar salud de los servicios\nmake healthcheck\n\n# Ver logs en tiempo real\nmake logs\n```\n\n### 5. Acceder a las Interfaces\n\n- **Frontend Dashboard:** http://localhost:3001\n- **API Gateway:** http://localhost:8080/docs\n- **Users Service:** http://localhost:3000\n- **LLM Chat Service:** http://localhost:8002/docs\n- **Image Service:** http://localhost:8000/docs\n- **Speech Service:** http://localhost:8001/docs\n- **Analytics Service:** http://localhost:8005/docs\n- **MinIO Console:** http://localhost:9001 (usuario: `minio`, password: `minio123`)\n\n### 6. Probar la Plataforma\n\n```bash\n# Ejecutar suite de tests automatizados\nmake test-all\n\n# O probar manualmente\nmake test-auth        # Autenticación\nmake test-image       # Generación de imágenes\nmake test-speech      # Text-to-speech\nmake test-chat        # Chat LLM\n```\n\n## ⚙️ Configuración del Entorno\n\n### Variables de Entorno Requeridas\n\n#### Frontend (`frontend/.env.local`)\n\n```bash\nNEXT_PUBLIC_API_URL=http://localhost:8080\nNEXT_PUBLIC_GATEWAY_URL=http://localhost:8080\n```\n\n#### Users Service (`users/.env.dev`)\n\n```bash\nNODE_ENV=development\nPORT=3000\nDATABASE_HOST=postgres\nDATABASE_PORT=5432\nDATABASE_USER=postgres\nDATABASE_PASSWORD=postgres\nDATABASE_NAME=postgres\nJWT_ACCESS_SECRET=your-super-secret-access-key-change-in-production\nJWT_REFRESH_SECRET=your-super-secret-refresh-key-change-in-production\nJWT_ACCESS_EXPIRES_IN=15m\nJWT_REFRESH_EXPIRES_IN=30d\n```\n\n#### LLM Chat Service (`llm-api/.env`)\n\n```bash\nNODE_ENV=development\nPORT=8002\nMONGO_URI=mongodb://mongo:27017/llm_chat\nMONGO_DB_NAME=llm_chat\nGITHUB_TOKEN=your_github_personal_access_token\nGITHUB_API_BASE=https://models.inference.ai.azure.com\nGITHUB_DEFAULT_MODEL=gpt-4o-mini\nJWT_ACCESS_SECRET=your-super-secret-access-key-change-in-production\nUSERS_SERVICE_URL=http://users-service:3000\nLOG_LEVEL=INFO\n```\n\n#### Text-to-Image Service (`text_image_api/.env.dev`)\n\n```bash\n# Servicio\nSERVICE_NAME=text-image-api\nSERVICE_VERSION=1.0.0\nENVIRONMENT=development\nPORT=8000\nLOG_LEVEL=INFO\n\n# S3/MinIO\nS3_ENDPOINT=http://minio:9000\nS3_ACCESS_KEY=minio\nS3_SECRET_KEY=minio123\nS3_BUCKET_NAME=llmhist-image-dev\nS3_REGION=us-east-1\n\n# Auth\nJWT_ACCESS_SECRET=your-super-secret-access-key-change-in-production\nUSERS_SERVICE_URL=http://users-service:3000\n\n# API Externa\nPOLLINATIONS_API_URL=https://image.pollinations.ai/prompt\n```\n\n#### Text-to-Speech Service (`text_speech_api/.env.dev`)\n\n```bash\n# Similar a text_image_api\nS3_BUCKET_NAME=llmhist-tts-dev\nPORT=8000\n# ... resto de variables\n```\n\n#### Analytics Service (`analytics_api/.env`)\n\n```bash\nPORT=8005\nMONGO_URI=mongodb://mongo:27017/llm_analytics\nMONGO_DB_NAME=llm_analytics\nJWT_ACCESS_SECRET=your-super-secret-access-key-change-in-production\nUSERS_SERVICE_URL=http://users-service:3000\n```\n\n#### API Gateway (`gateway_api/.env`)\n\n```bash\nPORT=8080\nUSERS_SERVICE_URL=http://users-service:3000\nLLM_SERVICE_URL=http://llm-chat-service:8002\nIMAGE_SERVICE_URL=http://text-image-service:8000\nSPEECH_SERVICE_URL=http://text-speech-service:8000\nANALYTICS_SERVICE_URL=http://analytics-service:8005\nJWT_ACCESS_SECRET=your-super-secret-access-key-change-in-production\n```\n\n### Obtener GitHub Token (para LLM Service)\n\n1. Ve a https://github.com/settings/tokens\n2. Crea un nuevo **Personal Access Token (classic)**\n3. No requiere permisos especiales para GitHub Models\n4. Copia el token y úsalo en `GITHUB_TOKEN`\n\n## 🛠️ Desarrollo Local\n\n### Opción 1: Desarrollo con Docker (Recomendado)\n\n```bash\n# Levantar solo las bases de datos\ndocker-compose up -d postgres mongo minio\n\n# Desarrollar cada servicio por separado\nmake dev-frontend    # Frontend en localhost:3001\nmake dev-users       # Users en localhost:3000\nmake dev-llm         # LLM en localhost:8002\nmake dev-image       # Image en localhost:8000\nmake dev-speech      # Speech en localhost:8001\nmake dev-analytics   # Analytics en localhost:8005\nmake dev-gateway     # Gateway en localhost:8080\n```\n\n### Opción 2: Desarrollo Nativo (Sin Docker)\n\n#### Frontend\n\n```bash\ncd frontend\npnpm install\npnpm dev\n# Disponible en http://localhost:3001\n```\n\n#### Users Service\n\n```bash\ncd users\npnpm install\npnpm start:dev\n# Disponible en http://localhost:3000\n```\n\n#### Python Services (LLM, Image, Speech, Analytics, Gateway)\n\n```bash\ncd \u003cservice_directory\u003e\npython -m venv venv\nsource venv/bin/activate  # En Windows: venv\\Scripts\\activate\npip install -r requirements.txt\nuvicorn main:app --reload --port \u003cPORT\u003e\n```\n\n### Hot Reload\n\n- **Frontend:** Turbopack con hot reload automático\n- **Users:** NestJS con watch mode\n- **Python Services:** Uvicorn con `--reload`\n\n## 📡 APIs y Endpoints\n\n### API Gateway (Puerto 8080)\n\nEl gateway centraliza todas las rutas:\n\n```bash\n# Autenticación\nPOST   /auth/register\nPOST   /auth/login\nPOST   /auth/refresh\nPOST   /auth/logout\nGET    /users/me\n\n# Chat LLM\nPOST   /chat/completions\nGET    /chat/history\nGET    /chat/conversations/{id}\nDELETE /chat/conversations/{id}\n\n# Generación de Imágenes\nPOST   /image/generate\nGET    /image/{id}\nGET    /image/{id}/download\nGET    /admin/images\n\n# Text-to-Speech\nPOST   /tts/generate\nGET    /tts/{id}\nGET    /tts/{id}/download\nGET    /admin/audios\n\n# Analytics\nGET    /analytics/stats\nGET    /analytics/user/{userId}\nGET    /analytics/service/{service}\nGET    /analytics/usage\n```\n\n### Documentación Interactiva\n\nCada servicio FastAPI incluye documentación Swagger:\n\n- **Gateway:** http://localhost:8080/docs\n- **LLM Chat:** http://localhost:8002/docs\n- **Image:** http://localhost:8000/docs\n- **Speech:** http://localhost:8001/docs\n- **Analytics:** http://localhost:8005/docs\n\n### Ejemplos de Uso\n\n#### 1. Registro e Inicio de Sesión\n\n```bash\n# Registrar nuevo usuario\ncurl -X POST \"http://localhost:8080/auth/register\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"usuario@example.com\",\n    \"password\": \"Password123!\"\n  }'\n\n# Iniciar sesión\ncurl -X POST \"http://localhost:8080/auth/login\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"email\": \"usuario@example.com\",\n    \"password\": \"Password123!\"\n  }'\n\n# Respuesta:\n{\n  \"accessToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"refreshToken\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n  \"user\": {\n    \"id\": \"uuid\",\n    \"email\": \"usuario@example.com\"\n  }\n}\n```\n\n#### 2. Chat con LLM\n\n```bash\n# Chat conversacional\ncurl -X POST \"http://localhost:8080/chat/completions\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -d '{\n    \"prompt\": \"Explica qué es un microservicio\",\n    \"model\": \"gpt-4o-mini\",\n    \"temperature\": 0.7,\n    \"max_tokens\": 500\n  }'\n\n# Respuesta:\n{\n  \"id\": \"conv_uuid\",\n  \"response\": \"Un microservicio es...\",\n  \"model\": \"gpt-4o-mini\",\n  \"usage\": {\n    \"prompt_tokens\": 15,\n    \"completion_tokens\": 150,\n    \"total_tokens\": 165\n  },\n  \"created_at\": \"2025-10-03T12:00:00Z\"\n}\n```\n\n#### 3. Generar Imagen\n\n```bash\n# Generar imagen con autenticación\ncurl -X POST \"http://localhost:8080/image/generate\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -d '{\n    \"prompt\": \"A futuristic cyberpunk city at night with neon lights\",\n    \"size\": \"1024x1024\",\n    \"seed\": 42\n  }'\n\n# Respuesta:\n{\n  \"id\": \"img_uuid\",\n  \"prompt\": \"A futuristic cyberpunk city at night...\",\n  \"size\": \"1024x1024\",\n  \"status\": \"completed\",\n  \"download_url\": \"http://localhost:8080/image/img_uuid/download\",\n  \"created_at\": \"2025-10-03T12:00:00Z\"\n}\n\n# Descargar imagen\ncurl -L \"http://localhost:8080/image/img_uuid/download\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -o imagen.png\n```\n\n#### 4. Text-to-Speech\n\n```bash\n# Generar audio en español\ncurl -X POST \"http://localhost:8080/tts/generate\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -d '{\n    \"prompt\": \"Hola, este es un mensaje de prueba en español\",\n    \"voice\": \"es\",\n    \"model\": \"gtts\"\n  }'\n\n# Respuesta:\n{\n  \"id\": \"audio_uuid\",\n  \"prompt\": \"Hola, este es un mensaje...\",\n  \"voice\": \"es\",\n  \"model\": \"gtts\",\n  \"status\": \"completed\",\n  \"download_url\": \"http://localhost:8080/tts/audio_uuid/download\",\n  \"duration\": 3.5,\n  \"created_at\": \"2025-10-03T12:00:00Z\"\n}\n\n# Descargar audio\ncurl -L \"http://localhost:8080/tts/audio_uuid/download\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n  -o audio.mp3\n```\n\n#### 5. Obtener Analytics\n\n```bash\n# Estadísticas generales\ncurl -X GET \"http://localhost:8080/analytics/stats\" \\\n  -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n\n# Respuesta:\n{\n  \"total_requests\": 1523,\n  \"total_users\": 42,\n  \"requests_by_service\": {\n    \"chat\": 856,\n    \"image\": 423,\n    \"tts\": 244\n  },\n  \"avg_response_time_ms\": 245,\n  \"period\": \"last_30_days\"\n}\n```\n\n## 🗄️ Almacenamiento\n\n### PostgreSQL (Puerto 5432)\n\n- **Usuario:** postgres\n- **Contraseña:** postgres\n- **Tablas:** users, sessions\n\n### MinIO (Puertos 9000/9001)\n\n- **Console:** http://localhost:9001\n- **Usuario:** minio\n- **Contraseña:** minio123\n- **Buckets:**\n  - llmhist-image-dev (Text-to-Image)\n  - llmhist-tts-dev (Text-to-Speech)\n\n### Estructura S3 - Text-to-Image\n\n```\nllmhist-image-dev/\n├── requests/{yyyy}/{mm}/{dd}/{id}/\n│   ├── input.json      # Parámetros entrada\n│   ├── record.json     # Metadatos completos\n│   └── image/original.png # Imagen generada\n└── users/{userId}/image/history/\n    └── {yyyy}/{mm}/{dd}.jsonl # Índice por usuario\n```\n\n### Estructura S3 - Text-to-Speech\n\n```\nllmhist-tts-dev/\n├── requests/{yyyy}/{mm}/{dd}/{id}/\n│   ├── input.json      # Parámetros entrada (prompt, voice)\n│   ├── record.json     # Metadatos completos\n│   └── audio/output.mp3 # Audio generado\n└── users/{userId}/tts/history/\n    └── {yyyy}/{mm}/{dd}.jsonl # Índice por usuario\n```\n\n## 🛠️ Comandos Útiles\n\n```bash\n# Construcción y despliegue\nmake build              # Construir imágenes\nmake up                 # Levantar servicios\nmake down               # Detener servicios\nmake clean              # Limpiar todo\n\n# Logs y debugging\nmake logs               # Ver todos los logs\nmake logs-users         # Logs servicio usuarios\nmake logs-image         # Logs servicio imágenes\nmake logs-speech        # Logs servicio text-to-speech\nmake healthcheck        # Verificar salud servicios\n\n# Testing\nmake test-auth          # Probar autenticación\nmake test-image         # Probar generación imagen\nmake test-speech        # Probar generación audio\nmake test-protected     # Probar endpoint protegido\n\n# Desarrollo\nmake dev-users          # Ejecutar users en dev\nmake dev-image          # Ejecutar image en dev\nmake dev-speech         # Ejecutar speech en dev\nmake setup-dev          # Configurar .env files\n```\n\n## 🔧 Desarrollo Local\n\n### Requisitos\n\n- Docker \u0026 Docker Compose\n- Node.js 18+ (para users service)\n- Python 3.11+ (para image y speech services)\n- pnpm (para users service)\n\n### Setup\n\n```bash\n# Clonar e instalar\ngit clone \u003crepo\u003e\ncd llm-microservices\n\n# Configurar entorno\nmake setup-dev\n\n# Instalar dependencias\nmake install-deps\n\n# Levantar servicios\nmake up-build\n```\n\n## 🔐 Autenticación\n\nLa plataforma usa **JWT con refresh tokens**:\n\n1. **Registro/Login** → `accessToken` (15min) + `refreshToken` (30d)\n2. **Headers** → `Authorization: Bearer \u003caccessToken\u003e`\n3. **Renovación** → `POST /auth/refresh` con `refreshToken`\n4. **Logout** → Revoca la sesión del `refreshToken`\n\n## 📊 Próximas Características\n\n- [ ] **API Gateway** (NestJS)\n- [ ] **Analytics Service** (FastAPI + MongoDB)\n- [ ] **Summarizer Service** (FastAPI + S3)\n- [ ] **Chat Service** (FastAPI + S3)\n- [ ] **Frontend Dashboard** (React/Next.js)\n- [ ] **Rate Limiting**\n- [ ] **Métricas Prometheus**\n\n## 🚨 Troubleshooting\n\n### Servicios no inician\n\n```bash\n# Verificar estado\nmake status\n\n# Ver logs específicos\nmake logs-users\nmake logs-image\n\n# Limpiar y reiniciar\nmake clean\nmake up-build\n```\n\n### Errores de autenticación\n\n```bash\n# Verificar users service\ncurl http://localhost:3000/\n\n# Verificar JWT token válido\ncurl -H \"Authorization: Bearer TOKEN\" http://localhost:3000/users/me\n```\n\n### Problemas con S3/MinIO\n\n```bash\n# Acceder a MinIO Console\nopen http://localhost:9001\n\n# Verificar bucket existe\ndocker exec llm-minio mc ls minio/llmhist-image-dev/\n```\n\n## 📝 Notas de Producción\n\n- [ ] Usar secretos seguros para JWT\n- [ ] Configurar HTTPS/TLS\n- [ ] Implementar rate limiting\n- [ ] Configurar logs centralizados\n- [ ] Establecer monitoreo\n- [ ] Backup de bases de datos\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcosotomac%2Fproyecto-cloud","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarcosotomac%2Fproyecto-cloud","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarcosotomac%2Fproyecto-cloud/lists"}