HISPATEC — Documento Técnico del Ecosistema

Arquitectura, módulos, algoritmos y modelo operativo de la plataforma técnica hispana.

1. Resumen ejecutivo

HISPATEC es una plataforma técnica independiente diseñada para conectar a profesionales, empresas e instituciones del mundo hispano a través de proyectos tangibles. No es una asociación cultural, ni un foro ideológico, ni un colegio profesional: es una red técnica de confianza orientada a resultados medibles.

Este documento describe la implementación técnica del ecosistema: nueve módulos funcionales, motor matemático propio (Gini, Trust Rank, Metcalfe adaptado, Monte Carlo, HCI), cuarenta y dos endpoints REST, nueve herramientas MCP para la integración con agentes de IA, y un modelo de datos sobre PostgreSQL con quince tablas.

2. Visión y posicionamiento estratégico

Proposición de valor diferencial

Sectores prioritarios

• Ecosistema y soberanía digital — plataformas propias, modelos de IA en español, reducción de dependencia externa.
• Agroindustria y energía estratégica — exportación con estándares comunes, gestión de recursos vitales.
• Infraestructura civil y logística — transporte, telecomunicaciones, redes energéticas intrahispanas.
• Ciencia, salud y talento joven — investigación médica, mentorías generacionales.

3. Arquitectura del sistema

Capas

Frontend         : HTML + CSS + JavaScript vanilla (SPA)
                   /hispatec/          landing pública
                   /hispatec/dashboard/  panel del miembro (9 módulos)

Backend          : Node.js + Express
                   Router central       /hispatec/api
                   10 sub-routers       auth, members, match, projects,
                                        exchange, payments, metrics, mcp,
                                        admin, health

Motor matemático : src/utils/hispatec-math.js (714 líneas, JS puro)

Base de datos    : PostgreSQL (Render)
                   15 tablas, arrays nativos, JSONB, índices

Autenticación    : JWT (7 días) + bcrypt (12 rondas)

Pagos            : Stripe (suscripciones + escrow de proyectos)

MCP              : 9 herramientas expuestas vía /hispatec/api/mcp/tools
                   para orquestación por agentes de IA (Claude, etc.)

Flujo extremo a extremo

Usuario (navegador)
     |  HTTPS
     v
/hispatec/dashboard/   <-- SPA, fetch con Bearer JWT
     |
     v
/hispatec/api/*        <-- Express, middleware authMiddleware + requireAccess
     |
     v
hispatec-math.js       <-- Gini, coseno, Trust Rank, Monte Carlo, HCI
     |
     v
PostgreSQL             <-- consultas Sequelize (raw + ORM), SSL obligatorio
     |
     v
Stripe / clientes MCP  <-- integraciones externas

4. Los 6 ejes estratégicos y su traducción técnica

5. Módulos de la plataforma

5.1 Panel General

Pantalla de entrada. Muestra tarjetas agregadas (total de miembros, proyectos activos, RFQ abiertas, HCI actual), gráficos de barras por región y tipo de membresía, y una tabla histórica de 30 días. Consume GET /metrics/dashboard.

5.2 Mi Perfil

Formulario editable con datos personales y profesionales. Panel lateral de Trust Score con el desglose de los cinco componentes (V, R, P, A, M) y sus pesos. Datos persistidos en hispatec_members.

5.3 Directorio

Búsqueda y navegación paginada de miembros con filtros por región, sector, país, tipo de membresía y texto libre (ILIKE sobre nombre y empresa). Cada ficha muestra el nivel de verificación y las especialidades.

5.4 Matching IA

El corazón de la red. El usuario describe una necesidad o proyecto; el motor construye un vector de perfil ponderado, aplica similitud coseno contra todos los miembros activos, corrige por coeficiente de Gini para favorecer a regiones infrarrepresentadas, multiplica por el Trust Score y devuelve el ranking final. Cada consulta se archiva en hispatec_matches.

5.5 Proyectos

Ciclo de vida de 6 fases: propuesta → análisis → equipo → recursos → ejecución → completado. Incluye evaluación Monte Carlo (10.000 iteraciones) que devuelve probabilidades de coste y plazo, percentiles p10-p95, puntuación de viabilidad (0-100) y semáforo VERDE/AMARILLO/ROJO.

5.6 Intercambio

Marketplace B2B con tres submódulos:

• Empresas: fichas registradas por los miembros (hispatec_companies).
• RFQ: solicitudes de presupuesto con respuestas, adjudicación y cambio automático de estados.
• Oportunidades: convocatorias, licitaciones y proyectos externos compartidos por la red.

5.7 Métricas

Visualiza los cuatro indicadores maestros del ecosistema: Gini (por región o sector), HCI compuesto, valor de red Metcalfe adaptado y Trust Score individual.

5.8 Pagos

Gestión de la suscripción (Numerario, Protector, Patrono, Fundador), historial de transacciones y administración del escrow de proyectos. Integración con Stripe para la creación del cliente y el cobro.

5.9 Administración

Panel restringido a los roles superadmin, admin_global y admin_regional. Permite la asignación de cargos de gobernanza, la verificación de miembros, el cambio de estado de proyectos y la visualización de estadísticas completas del sistema.

6. Motor matemático e IA

Todos los algoritmos residen en src/utils/hispatec-math.js — JavaScript puro, sin dependencias externas, auditable línea a línea.

6.1 Coeficiente de Gini

Mide la desigualdad de distribución (0 = equidad perfecta, 1 = máxima desigualdad). Se calcula sobre el número de oportunidades, proyectos o miembros por región o sector. Umbral de activación de la corrección: 0,40.

6.2 Factor de corrección Gini

Con α=0,3 y salvaguarda clamp [0,5, 2,0]. Se multiplica por la puntuación de matching para favorecer a las regiones con menor exposición.

6.3 Vector de perfil (pesos dimensionales)

6.4 Similitud coseno

6.5 Trust Rank (variante PageRank)

V = verificación, R = calidad promedio de las referencias, P = tasa de éxito de proyectos, A = antigüedad (máximo 5 años), M = nivel de membresía. Se propaga iterativamente con amortiguación d=0,85 durante hasta 50 iteraciones.

6.6 Valor de red (Metcalfe adaptado)

Representa el valor total generado por la red, ponderado por la confianza promedio. Versión simplificada utilizada en el panel; la versión completa usa suma pareada con afinidades C_ij.

6.7 Simulación Monte Carlo

Para el riesgo de proyecto. Distribución triangular sobre presupuesto y cronograma:

10.000 iteraciones. Resultado: probabilidades de cumplir coste y plazo, percentiles p10-p95, semáforo.

6.8 Índice Compuesto HISPATEC (HCI)

Objetivo operativo: HCI ≥ 0,65. Instantánea diaria en hispatec_network_metrics.

7. Modelo de datos

PostgreSQL con SSL obligatorio. 15 tablas principales:

8. Referencia de API

Base: /hispatec/api. Todas las rutas autenticadas requieren Authorization: Bearer <jwt>.

Autenticación

• POST /auth/register — alta; devuelve JWT (7 días)
• POST /auth/login — autenticación
• GET /auth/me — perfil actual

Miembros

• GET /members — directorio paginado con filtros
• GET /members/:id — perfil público
• PUT /members/:id — actualización del propio perfil
• POST /members/:id/verify — solicitud de verificación

Matching

• POST /match — matching con IA y corrección Gini
• GET /match/history — historial de consultas

Proyectos

• GET /projects — listado con filtros
• POST /projects — nueva propuesta
• GET /projects/:id — detalle y equipo
• PUT /projects/:id — actualización (autor o admin)
• POST /projects/:id/advance — avanzar de fase
• POST /projects/:id/join — unirse al equipo
• POST /projects/:id/evaluate — viabilidad Monte Carlo
• POST /projects/:id/assign — sugerencia de equipo

Intercambio

• GET/POST/PUT /exchange/companies[/:id]
• GET/POST /exchange/rfqs[/:id], /exchange/rfqs/:id/respond, /exchange/rfqs/:id/award
• GET/POST /exchange/opportunities

Métricas

• GET /metrics/gini, /metrics/hci, /metrics/network-value, /metrics/trust/:id, /metrics/dashboard

Pagos

• POST /payments/membership, /payments/escrow, /payments/release
• GET /payments/history, /payments/pricing

Administración

• GET/PUT/DEL /admin/roles[/:member_id]
• GET/PUT /admin/members[/:id/status|verify|membership]
• PUT /admin/projects/:id/status
• GET /admin/regions, /admin/system/stats, /admin/my-access

9. Autenticación, roles y gobierno

Flujo de autenticación

1. Registro o inicio de sesión contra /auth/* → devuelve un JWT firmado (HS256, 7 días).
2. El cliente lo almacena en localStorage bajo la clave hispatec_token.
3. Cada petición lleva la cabecera Authorization: Bearer <token>.
4. El middleware authMiddleware verifica y adjunta req.member con el payload decodificado.
5. El middleware requireAccess(...niveles) comprueba que access_level esté en la lista permitida.

Jerarquía de gobierno

Verificación escalonada

• none: registro básico.
• email: correo verificado — V = 0,5 en el Trust Score.
• id_complete: KYC completo — V = 1,0.

10. Integración MCP para agentes de IA

Nueve herramientas expuestas en /hispatec/api/mcp/tools, invocables por cualquier agente compatible con el Model Context Protocol:

1. match_members — matching de miembros.
2. evaluate_project — viabilidad mediante Monte Carlo.
3. calc_gini — coeficiente de desigualdad.
4. calc_trust — Trust Score individual.
5. find_opportunities — oportunidades relevantes para un perfil.
6. optimize_allocation — asignación óptima de equipo.
7. risk_montecarlo — escenarios de riesgo.
8. gen_report — informes de actividad, financieros, de impacto o HCI.
9. network_value — valor de red total.

Invocación: POST /mcp/tools/call con { name, parameters }. Devuelve { success, data: { tool, result, execution_time_ms } }.

11. Despliegue y operación

• Plataforma: Render (despliegue automático al hacer push a main).
• Tiempo de despliegue: unos 90-120 segundos.
• URL de desarrollo: https://aiagent.ringlypro.com/hispatec/
• Base de datos: PostgreSQL gestionado en Render (SSL obligatorio).
• Variables de entorno clave: DATABASE_URL, CRM_DATABASE_URL, JWT_SECRET, STRIPE_SECRET_KEY.
• Comprobación de salud: GET /hispatec/api/health.