Resumen de la Starter Application

La Copera Starter Application (también llamada Base Application) es una implementación de referencia de código abierto que muestra a los desarrolladores exactamente cómo construir una aplicación completamente funcional y lista para producción sobre Copera Boards usando el @copera.ai/sdk. Es el camino más rápido desde cero hasta una app personalizada en funcionamiento, impulsada por tus datos de Copera.

¿Qué es la Starter Application?

En esencia, la Starter Application trata tu Copera Board como una base de datos. Cada tabla de tu board es una fuente de datos, cada fila es un registro y cada columna es un campo. El @copera.ai/sdk proporciona una API limpia en TypeScript para leer, escribir, actualizar y eliminar filas — sin SQL, sin esquema de backend personalizado. Tu board es la única fuente de verdad.

La implementación de referencia se entrega como un portal de Centro de Ayuda / Tickets de Soporte: los usuarios pueden iniciar sesión, enviar tickets y ver su historial de tickets. Pero esto es solo un ejemplo. Como la mecánica subyacente es genérica, puedes adaptar la misma base de código para construir prácticamente cualquier aplicación que tus clientes necesiten.

consejo

Piensa en la Starter Application como un lienzo en blanco con la fontanería ya instalada. Sustituye las tablas de tickets por catálogos de productos, ofertas de empleo, registros de empleados o solicitudes de servicio — la arquitectura sigue siendo la misma.

Lo que puedes construir

Estos son ejemplos de aplicaciones que los clientes han construido o están construyendo sobre Copera Boards:

Tipo de aplicación	Board como base de datos
Centro de Ayuda / Portal de Soporte	Tabla de tickets, tabla de usuarios, columna de estado
Tienda de comercio electrónico	Tabla de productos, tabla de pedidos, columnas de inventario
Portal de empleados de RR. HH.	Tabla de empleados, tabla de departamentos, tabla de solicitudes de ausencia
Portal de proyectos para clientes	Tabla de proyectos, tabla de tareas, tabla de hitos
Base de conocimiento / Preguntas frecuentes	Tabla de artículos, tabla de categorías, columna de etiquetas
Sistema de registro de eventos	Tabla de eventos, tabla de inscritos, columna de asistencia

Cualquier conjunto de datos estructurado que quepa dentro de un Copera Board puede convertirse en el backend de una aplicación con tu propia marca.

Arquitectura

La Starter Application se divide en dos paquetes separados que funcionan juntos:

base-application-api

Una API REST que se sitúa entre tu frontend y Copera. Maneja la autenticación, valida las solicitudes, escribe datos en tu Copera Board a través del SDK y guarda en caché los registros localmente en la base de datos para lecturas rápidas.

Responsabilidades clave:

• Autenticación — Inicio de sesión basado en JWT que usa las filas del board como almacén de usuarios. El método authenticateTableRow del SDK valida las credenciales directamente contra las columnas de tu tabla de usuarios.
• Integración con el SDK — Todas las operaciones del board (crear fila, listar filas, actualizar fila) pasan por el @copera.ai/sdk. Configuras qué board y qué IDs de tabla usar en un único archivo config.ts.
• Caché local — Después de escribir una fila en Copera, la API guarda una copia ligera en la base de datos. Esto significa que las consultas de listado son lecturas locales rápidas en lugar de viajes de ida y vuelta a la API de Copera en cada solicitud.
• Endpoints REST estándar — Los controladores siguen un patrón limpio basado en clases, lo que facilita añadir nuevos tipos de recursos.

Stack tecnológico: un framework REST de Node.js, una base de datos documental, autenticación JWT con credenciales cifradas, @copera.ai/sdk, registro con Pino, validación con Yup/Zod.

base-application-web

Una aplicación de página única (SPA) en React que proporciona la interfaz de usuario. Se comunica exclusivamente con base-application-api y nunca toca Copera directamente.

Responsabilidades clave:

• Flujo de autenticación — Un AuthProvider basado en contexto guarda el JWT, protege las rutas restringidas y redirige a los usuarios no autenticados a la página de inicio de sesión.
• Obtención de datos — React Query gestiona todo el estado del servidor, incluyendo el caché, las recargas y las actualizaciones optimistas. Las claves de consulta están centralizadas para una gestión coherente del caché.
• Componentes de UI — Construidos con una biblioteca de componentes accesible (primitivas de Radix UI) y estilizados con un framework de CSS utility-first, lo que te da una UI moderna y accesible lista para usar.
• Estado del cliente — Zustand maneja el estado ligero de la UI, como la visibilidad de la barra lateral y los elementos seleccionados.

Stack tecnológico: React 18, una herramienta de compilación moderna, un framework de CSS utility-first, una biblioteca de componentes accesible, React Query (TanStack Query 5), Zustand 4, React Hook Form 7, React Router 7.

Cómo funciona el flujo de datos

Entender el flujo de datos es la clave para personalizar la Starter Application para tu propio caso de uso:

1. Un usuario interactúa con el frontend de React — por ejemplo, enviando un nuevo ticket de soporte.
2. El frontend envía una solicitud POST a base-application-api con los datos del formulario.
3. La API escribe la fila en Copera a través del SDK: copera.board.tables.<tableName>.createRow({ ... }).
4. La API guarda un registro en caché en una base de datos local, almacenando el ID de la fila de Copera junto con los campos que se necesiten localmente.
5. La API devuelve el nuevo registro al frontend, donde React Query actualiza la lista en caché de inmediato.
6. Tu equipo ve el ticket en Copera — en su board, en la tabla correcta, listo para gestionarse con todas las herramientas integradas de Copera: vistas, automatizaciones, funciones de IA y más.

Este patrón hace que tus clientes interactúen con una interfaz personalizada y limpia, mientras tu equipo interno trabaja dentro de Copera usando todas las herramientas que ya conocen.

Configuración del board

Toda la conexión con el board se controla mediante un único objeto de configuración en la API. Proporcionas tu Board ID y los Table IDs de cada tipo de dato que usa tu aplicación. Los Column IDs le indican al SDK qué columnas específicas leer y escribir.

// apps/base-application-api/src/config.ts
export const COPERA_CONFIG = {
  boardId: 'your-board-id',
  usersTable: {
    usersTableId: 'your-users-table-id',
    identifierColumnId: 'email-column-id',
    passwordColumnId: 'password-column-id',
  },
  ticketsTable: {
    ticketsTableId: 'your-tickets-table-id',
  },
};

Consulta la página de Column IDs para aprender a encontrar los IDs correctos de las tablas y columnas de tu board.

Código abierto

La Starter Application se publicará como código abierto en GitHub. Eres libre de bifurcarla, modificarla y desplegarla como prefieras. Está diseñada para ser lo bastante simple como para entenderla rápidamente y lo bastante estructurada como para escalar con los requisitos de tu producto.

Próximos pasos

• Primeros pasos — Configura la Starter Application en local en menos de 15 minutos.
• Construir con IA — Aprende a usar asistentes de programación con IA para acelerar el desarrollo sobre la Starter Application.
• Column IDs — Encuentra el Board ID, los Table IDs y los Column IDs que necesitas para configurar el SDK.