Supabase · OpenRouter · Stripe · WhatsApp · Google

Arquitectura y stack

Arquitectura pragmática y evolutiva para desarrollar Hampiora con aislamiento multi-tenant, seguridad, observabilidad e integraciones externas.

Principios de arquitectura

Evolutiva, segura y sin sobreingeniería.

Principles

Monolito modular

Velocidad y mantenibilidad para un solo equipo inicial.

Multi-tenant ligero

Organizaciones y workspaces aislados desde la base.

API interna

Integraciones externas y futuras aplicaciones móviles.

Events + queues

Procesamiento de webhooks, audios, documentos e IA.

Arquitectura lógica

Separación clara entre experiencia, núcleo, IA, datos e integraciones.

System

Hampiora Clinic
CRM, agenda, telemedicina, equipos.

Hampiora Passport
Documentos, wallet, médicos, nutrición.

Public Funnels
Landings, quizzes y formularios.

🧠

Application Core

Organizations · Workspaces · CRM · Appointments · Payments · Passport · AI Gateway · Audit

WhatsApp + Email
Mensajes, webhooks y notificaciones.

Google + Payments
Calendar, Meet, ONVO, PayPal y adapters.

AI Providers
OpenRouter y OpenAI Audio.

Stack recomendado

Tecnologías con velocidad de desarrollo, buen ecosistema y menor costo operativo inicial.

Tech stack

Capa	Tecnología	Responsabilidad
Frontend	Next.js + React + TypeScript	Hampiora Clinic, Passport, funnels públicos y PWA.
UI	Tailwind + componentes accesibles	Velocidad y consistencia.
Base de datos	Supabase PostgreSQL	Datos multi-tenant, RLS y relaciones.
Auth	Supabase Auth	Usuarios, sesiones y MFA.
Storage	Supabase Storage	Documentos, imágenes y políticas.
Realtime	Supabase Realtime	Inbox, agenda y actualizaciones.
Vector	pgvector	RAG con permisos.
AI	OpenRouter + OpenAI Audio	Model routing y transcripción.
Payments	Payment Orchestrator	ONVO, PayPal y proveedor de billing; Stripe Connect como hipótesis.
Messaging	WhatsApp Cloud API	Captación, inbox y voice assistant.
Meetings	Google Calendar + Meet	Agenda y videollamadas iniciales.

Arquitectura de pagos

El dominio de citas depende de un contrato interno y no de SDKs específicos.

Adapters

Appointments / Telemedicine
            ↓
      Payment Orchestrator
            ↓
  ┌─────────┼───────────┐
  ONVO     PayPal     Stripe Connect
  activo   activo     hipótesis no aprobada

Contrato común

createCheckout, getPayment, refund, verifyWebhook y reconcile.

Fuente de verdad

El estado final proviene de webhooks firmados y procesados con idempotencia.

Modelo marketplace

Feature flag separado; requiere ledger, payouts, disputas, impuestos y revisión legal.

PaymentProviderAccountPaymentIntentCheckoutSessionProviderWebhookRefundPayoutPlatformFee

Módulos del backend

Límites funcionales claros para mantener bajo acoplamiento.

Modules

IdentityOrganizationsWorkspacesCRMLeadsQuizzesAppointmentsTelemedicinePayment OrchestratorMessagingSurveysDocumentsPassportConsentAI GatewayUsage LedgerAuditNotifications

Entidades principales

Modelo mínimo para comenzar con datos consistentes y extensibles.

Data model

Organization / Workspace

Propiedad, marca, configuración, límites, equipo y funnels.

Lead / Contact / Patient

Ciclo comercial separado de identidad del paciente.

Appointment

Modalidad, profesional, agenda, estado y pago requerido.

Payment

Stripe account, checkout, fee, refund y webhook.

Document / Observation

Archivo, extracción, fuente, estado y procedencia.

Consent / Audit

Alcance, expiración, revocación y acceso.

Seguridad

La seguridad debe diseñarse antes que las integraciones clínicas profundas.

Security

Row Level Security por organización y workspace.

Separación comercial vs. datos sensibles.

Credenciales solo en gestor de secretos.

Webhooks firmados e idempotentes.

Cifrado en tránsito y reposo.

Logs y auditoría por acceso.

Backups y recuperación.

Permisos temporales y revocables.

Entornos y entrega

Separación mínima para desarrollar sin comprometer producción.

DevOps

Local

Desarrollo, datos sintéticos y simuladores.

Staging

Pruebas con integraciones sandbox y QA.

Production

Datos reales, monitoreo, backups y acceso limitado.