Visão Geral do Starter Application

O Copera Starter Application (também chamado de Base Application) é uma implementação de referência open-source que mostra aos desenvolvedores exatamente como construir uma aplicação completa e pronta para produção em cima dos Copera Boards usando o @copera.ai/sdk. É o caminho mais rápido para sair do zero e ter uma aplicação personalizada funcionando com seus dados do Copera.

O Que é o Starter Application?

Em sua essência, o Starter Application trata o seu Copera Board como um banco de dados. Cada tabela do seu board é uma fonte de dados, cada linha é um registro e cada coluna é um campo. O @copera.ai/sdk oferece uma API TypeScript limpa para ler, gravar, atualizar e excluir linhas — sem SQL, sem esquema de backend personalizado. Seu board é a única fonte de verdade.

A implementação de referência vem como um portal de Central de Ajuda / Tickets de Suporte: os usuários podem fazer login, abrir tickets e visualizar o histórico dos seus chamados. Mas esse é apenas um exemplo. Como a mecânica subjacente é genérica, você pode adaptar o mesmo código para construir praticamente qualquer aplicação que seus clientes precisem.

dica

Pense no Starter Application como uma tela em branco com toda a infraestrutura já pronta. Substitua as tabelas de tickets por catálogos de produtos, vagas de emprego, registros de funcionários ou solicitações de serviço — a arquitetura permanece a mesma.

O Que Você Pode Construir

Aqui estão exemplos de aplicações que clientes construíram ou estão construindo em cima dos Copera Boards:

Tipo de Aplicação	Board como Banco de Dados
Central de Ajuda / Portal de Suporte	Tabela de tickets, tabela de usuários, coluna de status
Loja Virtual (E-commerce)	Tabela de produtos, tabela de pedidos, colunas de estoque
Portal de RH para Funcionários	Tabela de funcionários, tabela de departamentos, tabela de solicitações de licença
Portal de Projetos para Clientes	Tabela de projetos, tabela de tarefas, tabela de marcos
Base de Conhecimento / FAQ	Tabela de artigos, tabela de categorias, coluna de tags
Sistema de Inscrição em Eventos	Tabela de eventos, tabela de inscritos, coluna de presença

Qualquer conjunto de dados estruturado que caiba em um Copera Board pode se tornar o backend de uma aplicação com a sua marca.

Arquitetura

O Starter Application é dividido em dois pacotes separados que trabalham juntos:

base-application-api

Uma API REST que fica entre o frontend e o Copera. Ela cuida da autenticação, valida as requisições, grava dados no seu Copera Board via SDK e armazena registros localmente no banco de dados para leituras rápidas.

Responsabilidades principais:

• Autenticação — Login baseado em JWT usando linhas do board como repositório de usuários. O método authenticateTableRow do SDK valida as credenciais diretamente nas colunas da sua tabela de usuários.
• Integração com o SDK — Todas as operações no board (criar linha, listar linhas, atualizar linha) passam pelo @copera.ai/sdk. Você configura o Board ID e os Table IDs em um único arquivo config.ts.
• Cache local — Após gravar uma linha no Copera, a API salva uma cópia leve no banco de dados. Isso significa que consultas de listagem são leituras locais rápidas, em vez de chamadas à API do Copera a cada requisição.
• Endpoints REST padrão — Os controllers seguem um padrão limpo baseado em classes, facilitando a adição de novos tipos de recursos.

Stack tecnológica: um framework REST para Node.js, um banco de dados de documentos, autenticação JWT com credenciais criptografadas, @copera.ai/sdk, logging com Pino, validação com Yup/Zod.

base-application-web

Um aplicativo de página única em React que fornece a interface do usuário. Ele se comunica exclusivamente com a base-application-api e nunca acessa o Copera diretamente.

Responsabilidades principais:

• Fluxo de autenticação — Um AuthProvider baseado em contexto armazena o JWT, protege as rotas e redireciona usuários não autenticados para a página de login.
• Busca de dados — O React Query gerencia todo o estado do servidor, incluindo cache, atualização automática e atualizações otimistas. As query keys são centralizadas para um gerenciamento de cache consistente.
• Componentes de UI — Construídos com uma biblioteca de componentes acessível (primitivos do Radix UI) e estilizados com um framework CSS utility-first, oferecendo uma UI moderna e acessível já pronta para uso.
• Estado do cliente — O Zustand gerencia o estado leve da interface, como a visibilidade da barra lateral e os itens selecionados.

Stack tecnológica: React 18, uma ferramenta de build moderna, um framework CSS utility-first, uma biblioteca de componentes acessível, React Query (TanStack Query 5), Zustand 4, React Hook Form 7, React Router 7.

Como o Fluxo de Dados Funciona

Entender o fluxo de dados é a chave para personalizar o Starter Application para o seu próprio caso de uso:

1. Um usuário interage com o frontend React — por exemplo, enviando um novo ticket de suporte.
2. O frontend envia uma requisição POST para a base-application-api com os dados do formulário.
3. A API grava a linha no Copera via SDK: copera.board.tables.<nomeTabela>.createRow({ ... }).
4. A API salva um registro em cache no banco de dados local, armazenando o ID da linha do Copera junto com quaisquer campos necessários localmente.
5. A API retorna o novo registro ao frontend, onde o React Query atualiza a lista em cache imediatamente.
6. Sua equipe vê o ticket no Copera — no board deles, na tabela correta, pronto para ser gerenciado com todas as ferramentas nativas do Copera: visualizações, automações, funcionalidades de IA e muito mais.

Esse padrão significa que seus clientes interagem com uma interface personalizada e limpa, enquanto sua equipe interna trabalha dentro do Copera usando todas as ferramentas que já conhece.

Configuração do Board

Toda a conexão com o board é controlada por um único objeto de configuração na API. Você fornece o Board ID e os Table IDs para cada tipo de dado que sua aplicação usa. Os Column IDs indicam ao SDK quais colunas específicas ler e gravar.

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

Consulte a página Column IDs para aprender como encontrar os IDs corretos das tabelas e colunas do seu board.

Open Source

O Starter Application será publicado como open source no GitHub. Você é livre para fazer fork, modificar e implantar como quiser. Ele foi projetado para ser simples o suficiente para ser compreendido rapidamente e estruturado o suficiente para crescer junto com os requisitos do seu produto.

Próximos Passos

• Como Começar — Configure o Starter Application localmente em menos de 15 minutos.
• Usando IA para Construir — Saiba como usar assistentes de codificação com IA para acelerar o desenvolvimento em cima do Starter Application.
• Column IDs — Encontre o Board ID, os Table IDs e os Column IDs necessários para configurar o SDK.