Descripción general de la Starter Application

La Starter Application de Copera (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 totalmente funcional y lista para producción sobre los Boards de Copera usando el @copera.ai/sdk. Es el camino más rápido para pasar de cero a una app personalizada en funcionamiento, impulsada por tus datos de Copera.

¿Qué es la Starter Application?

En esencia, la Starter Application trata tu Board de Copera 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 de TypeScript limpia para leer, escribir, actualizar y eliminar filas — sin SQL, sin necesidad de un esquema 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 este 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 infraestructura ya lista. Reemplaza 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.

Qué puedes construir

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

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 e-commerce	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 Board de Copera puede convertirse en el backend de una aplicación con tu propia marca.

Arquitectura

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

base-application-api

Una API REST que se sitúa entre tu frontend y Copera. Gestiona la autenticación, valida las solicitudes, escribe datos en tu Board de Copera 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 usando 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 agregar 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, logging con Pino, validación con Yup/Zod.

base-application-web

Una aplicación de página única (SPA) de 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 almacena el JWT, protege las rutas privadas 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 almacenamiento en caché, las recargas y las actualizaciones optimistas. Las query keys están centralizadas para una gestión consistente de la 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 desde el primer momento.
• Estado del cliente — Zustand gestiona 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 build 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 según 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 fila de Copera junto con cualquier campo necesario 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 significa que tus clientes interactúan 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 para cada tipo de dato que use tu aplicación. Los IDs de columna le indican al SDK qué columnas específicas debe 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 Finding Column IDs para aprender a encontrar los IDs correctos para las tablas y columnas de tu board.

Código abierto

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

Próximos pasos

• Getting Started — Configura la Starter Application localmente en menos de 15 minutos.
• Building with AI Tools — Aprende a usar asistentes de programación con IA para acelerar el desarrollo sobre la Starter Application.
• Finding Column IDs — Encuentra el Board ID, los Table IDs y los Column IDs que necesitas para configurar el SDK.