Referencia de la aplicación. Esta es una arquitectura ilustrativa y una lista de comprobación del alcance, no un proyecto de cliente verificado ni un despliegue con métricas. Las tecnologías, el alcance de la integración y los elementos de entrega se acuerdan para el briefing real.
Escenario y restricciones
Un producto que presta servicio a muchas organizaciones cliente desde un único despliegue. La decisión que determina todo es el modelo de aislamiento: tablas compartidas con una columna de tenant, un esquema por tenant o una base de datos por tenant. Elegir por defecto en lugar de hacerlo deliberadamente es el error más costoso en esta categoría, porque cambiarlo posteriormente implica migrar datos de clientes en producción.
Arquitectura
Capas y responsabilidades
| Capa | Tecnología | De qué se responsabiliza |
|---|---|---|
| Web | Next.js (SSR para marketing y SEO, SPA tras iniciar sesión) | Las páginas públicas utilizan renderizado en servidor para mejorar la visibilidad en buscadores; el producto autenticado no lo necesita y permanece como una aplicación cliente. |
| API | Go + Gin, tenant resuelto por solicitud | El contexto del tenant se resuelve a partir del subdominio o del token antes de que se ejecute cualquier handler y se transmite en cada consulta. |
| Almacenamiento | PostgreSQL, esquema compartido con alcance de tenant a nivel de fila | Una base de datos con un tenant_id en cada tabla propiedad de un tenant, aplicado en la capa de repositorio y, cuando sea compatible, mediante seguridad a nivel de fila como segunda línea de defensa. |
| Caché | Redis, claves con prefijo de tenant | Sesiones, límites de frecuencia y configuración de acceso frecuente. El uso de prefijos en las claves evita la colisión clásica de claves de caché que filtra los datos de un tenant a otro. |
| Facturación | Stripe o una pasarela regional | El estado de la suscripción se replica localmente para que las comprobaciones de derechos de acceso nunca dependan de una llamada activa al proveedor de pagos. |
| Tareas | Workers de cola con contexto de tenant | Trabajo programado y asíncrono; el contexto del tenant viaja con la carga útil de la tarea en lugar de inferirse durante la ejecución. |
Modelo de datos
Las tablas siguientes contienen las reglas de las que depende todo lo demás. Equivocarse aquí es lo que convierte una demo funcional en un sistema que no puede ampliarse.
Entidades principales
| Entidad | Campos clave, relaciones y reglas |
|---|---|
| tenant | Registro de la organización con plan, estado, región y flags de funcionalidades. Cada tabla propiedad de un tenant incluye tenant_id y ninguna consulta puede omitirlo. |
| usuario / membresía | Un usuario puede pertenecer a varios tenants con un rol diferente en cada uno, por lo que la identidad es global mientras que los permisos son propios de cada membresía. Modelar el usuario y la membresía como una sola tabla es lo que hace imposible admitir varias organizaciones más adelante. |
| rol / permiso | Permisos concedidos a los roles, roles asignados por membresía y cada comprobación realizada en el backend. Ocultar elementos en el frontend es presentación, nunca aplicación de permisos. |
| suscripción / derecho de acceso | Plan, puestos, periodo y derechos de acceso derivados. El acceso a las funcionalidades consulta el derecho local, de modo que una interrupción del proveedor de pagos no deja a los clientes fuera del producto. |
| audit_log | Actor, tenant, acción, objetivo y carga útil anterior/posterior. Permite revisar la seguridad y analizar incidentes; acuerde los requisitos de conservación, acceso y auditoría antes de la implementación. |
| tenant_config | Configuración, identidad de marca y anulaciones de funcionalidades por tenant, resueltas con una precedencia documentada sobre los valores predeterminados del plan. |
Interfaces clave
Endpoints que contienen las reglas de negocio
| Endpoint | Propósito y notas sobre concurrencia |
|---|---|
| POST /api/v1/auth/login | Autentica la identidad y después devuelve las membresías de tenant disponibles; el tenant se selecciona explícitamente en lugar de inferirse a partir de la última sesión. |
| GET /api/v1/{resource} | Cada lectura con alcance de tenant pasa por un repositorio que inyecta tenant_id. El alcance se mantiene en un único lugar para que ningún handler pueda olvidarlo, la fuente más común de filtraciones entre tenants. |
| POST /api/v1/webhooks/billing | Webhook del proveedor de pagos, idempotente según el id del evento, que actualiza localmente el estado de la suscripción y de los derechos de acceso. |
| POST /api/v1/tenants/{id}/invite | Flujo de invitación que crea una membresía con un rol, limitado por frecuencia por tenant para evitar abusos de invitaciones. |
| GET /api/v1/audit | Consulta de auditoría con alcance de tenant y paginación, disponible para los administradores del tenant como respuesta de cumplimiento de autoservicio. |
Decisiones técnicas
- Esquema compartido con tenant_id, elegido deliberadamente. Es la opción más económica de operar y migrar, y se adapta a la mayoría de los productos. Cuando un contrato con un cliente exige separación física, la misma base de código puede ejecutarse en un despliegue dedicado; esa posibilidad se diseña desde el inicio en lugar de descubrirse durante una negociación comercial.
- Alcance de tenant aplicado en una única capa de repositorio. Depender de que cada desarrollador recuerde una cláusula WHERE es la forma en que se producen filtraciones entre tenants. Centralizarla dificulta escribir accidentalmente una consulta insegura.
- Derechos de acceso replicados localmente. Consultar al proveedor de pagos en cada solicitud añade latencia y una dependencia crítica. La réplica local significa que una interrupción del proveedor degrada las operaciones de facturación, no el producto en sí.
- Registro de auditoría desde la primera versión. Rellenar el historial de auditoría posteriormente es imposible. Confirme los requisitos de auditoría del comprador y conserve el historial acordado desde la primera versión.
- SSR solo para páginas públicas. Las páginas de marketing y documentación necesitan visibilidad en buscadores; el producto autenticado no la necesita, y forzar SSR en él añade costes sin retorno.
Objetivos de diseño hipotéticos
Las cifras siguientes son ejemplos hipotéticos para la planificación de capacidad, no resultados medidos de clientes, una recomendación de dimensionamiento validada ni un SLA. Establezca objetivos de aceptación específicos del proyecto después de definir la carga de trabajo, los dispositivos, los datos, el hardware y las dependencias de terceros; verifíquelos mediante un piloto y pruebas de carga antes de comprometerse con un objetivo de producción.
Objetivos de capacidad y rendimiento
| Objetivo | Valor y supuesto |
|---|---|
| Latencia de la API | p95 inferior a 250 ms para lecturas con alcance de tenant y con índices compuestos correctos cuyo primer campo sea tenant_id. |
| Aislamiento de tenants | Exigir un conjunto de pruebas automatizadas que intente acceder entre tenants en cada endpoint y haga fallar la compilación ante cualquier acceso no autorizado. La implementación debe superar estas comprobaciones; esta referencia no demuestra que se haya completado una prueba de seguridad. |
| Incorporación | Nuevo tenant aprovisionado en segundos, ya que se trata de una fila y un registro de configuración, no de trabajo de infraestructura. |
| Escala | Dimensionado para unos pocos miles de tenants en una única instancia de PostgreSQL; más allá de ese punto, la ruta prevista son réplicas de lectura y después particionamiento por tenant, planificado pero no implementado prematuramente. |
Qué incluye la entrega
- Código fuente del frontend de Next.js, del backend de Go y del panel de administración en su repositorio
- Esquema de base de datos con alcance de tenant, índices y tablas de auditoría documentados, además del historial de migraciones
- Conjunto de pruebas de aislamiento entre tenants ejecutable en su CI
- Integración de facturación, gestión de webhooks y documentación de los derechos de acceso
- Notas de despliegue para Docker y Nginx, configuración del entorno y procedimiento de copia de seguridad y restauración
Planificación para su negocio
Los módulos anteriores son un punto de partida, no un paquete cerrado. Normalmente reducimos la primera versión a un flujo principal y un flujo de administración, y después ampliamos cuando el uso real muestra dónde están realmente la carga y los casos límite. Envíe un briefing con el alcance y lo contrastaremos con esta arquitectura para indicarle qué partes todavía no necesita.