Visão Geral da Starter Application

A Copera Starter Application (também chamada de Base Application) é uma implementação de referência open-source que mostra aos desenvolvedores exatamente como construir uma aplicação totalmente funcional e pronta para produção em cima dos Copera Boards usando o @copera.ai/sdk. É o caminho mais rápido do zero até um app customizado funcionando, alimentado pelos seus dados do Copera.

O Que É a Starter Application?

Em essência, a 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 fornece uma API TypeScript limpa para ler, escrever, atualizar e excluir linhas — sem SQL, sem schema de backend customizado. Seu board é a única fonte da 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 ver seu histórico de tickets. Mas isso é apenas um exemplo. Como a mecânica por baixo é genérica, você pode adaptar o mesmo código para construir praticamente qualquer aplicação que seus clientes precisem.

dica

Pense na Starter Application como uma tela em branco com a infraestrutura já no lugar. Troque 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 de 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 férias
Portal de Projetos voltado ao Cliente	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 dentro de um Copera Board pode se tornar o backend de uma aplicação com marca própria.

Arquitetura

A Starter Application é dividida em dois pacotes separados que trabalham juntos:

base-application-api

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

Principais responsabilidades:

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

Tech stack: um framework REST 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

Uma single-page application React que fornece a interface do usuário. Ela se comunica exclusivamente com o base-application-api e nunca toca no Copera diretamente.

Principais responsabilidades:

• Fluxo de autenticação — Um AuthProvider baseado em context armazena o JWT, protege rotas restritas e redireciona usuários não autenticados para a página de login.
• Data fetching — O React Query gerencia todo o estado do servidor, incluindo cache, refetching e optimistic updates. 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, dando a você uma UI moderna e acessível pronta para uso.
• Estado do cliente — O Zustand cuida de estados leves de UI, como visibilidade da sidebar e itens selecionados.

Tech stack: 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 customizar a 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 ao base-application-api com os dados do formulário.
3. A API escreve a linha no Copera pelo SDK: copera.board.tables.<tableName>.createRow({ ... }).
4. A API salva um registro de cache em um 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. Seu time vê o ticket no Copera — no board deles, na tabela correta, pronto para ser gerenciado com todas as ferramentas nativas do Copera: views, automações, recursos de IA e muito mais.

Esse padrão significa que seus clientes interagem com uma interface customizada e limpa, enquanto seu time interno 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 seu Board ID e os Table IDs para cada tipo de dado que sua aplicação usa. Os Column IDs dizem ao SDK quais colunas específicas ler e escrever.

// 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',
  },
};

Veja a página Encontrando Column IDs para aprender como encontrar os IDs corretos para as tabelas e colunas do seu board.

Open Source

A Starter Application será publicada como open source no GitHub. Você é livre para fazer fork, modificar e fazer deploy como quiser. Ela foi projetada para ser simples o suficiente para entender rapidamente e estruturada o suficiente para escalar com os requisitos do seu produto.

Próximos Passos

• Primeiros Passos — Configure a Starter Application localmente em menos de 15 minutos.
• Construindo com Ferramentas de IA — Aprenda como usar assistentes de código com IA para acelerar o desenvolvimento em cima da Starter Application.
• Encontrando Column IDs — Encontre o Board ID, os Table IDs e os Column IDs que você precisa para configurar o SDK.