Visao Geral do Starter Application

O Copera Starter Application (tambem chamado de Base Application) e uma implementacao de referencia open-source que mostra aos desenvolvedores exatamente como construir uma aplicacao completa e pronta para producao em cima dos Copera Boards usando o @copera.ai/sdk. E o caminho mais rapido para sair do zero e ter uma aplicacao personalizada funcionando com seus dados do Copera.

O Que e o Starter Application?

Em sua essencia, o Starter Application trata o seu Copera Board como um banco de dados. Cada tabela do seu board e uma fonte de dados, cada linha e um registro e cada coluna e 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 e a unica fonte de verdade.

A implementacao de referencia vem como um portal de Central de Ajuda / Tickets de Suporte: os usuarios podem fazer login, abrir tickets e visualizar o historico dos seus chamados. Mas esse e apenas um exemplo. Como a mecanica subjacente e generica, voce pode adaptar o mesmo codigo para construir praticamente qualquer aplicacao que seus clientes precisem.

dica

Pense no Starter Application como uma tela em branco com toda a infraestrutura ja pronta. Substitua as tabelas de tickets por catalogos de produtos, vagas de emprego, registros de funcionarios ou solicitacoes de servico — a arquitetura permanece a mesma.

O Que Voce Pode Construir

Aqui estao exemplos de aplicacoes que clientes construiram ou estao construindo em cima dos Copera Boards:

Tipo de Aplicacao	Board como Banco de Dados
Central de Ajuda / Portal de Suporte	Tabela de tickets, tabela de usuarios, coluna de status
Loja Virtual (E-commerce)	Tabela de produtos, tabela de pedidos, colunas de estoque
Portal de RH para Funcionarios	Tabela de funcionarios, tabela de departamentos, tabela de solicitacoes de licenca
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 Inscricao em Eventos	Tabela de eventos, tabela de inscritos, coluna de presenca

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

Arquitetura

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

base-application-api

Uma API REST com Fastify que fica entre o frontend e o Copera. Ela cuida da autenticacao, valida as requisicoes, grava dados no seu Copera Board via SDK e armazena registros localmente no MongoDB para leituras rapidas.

Responsabilidades principais:

• Autenticacao — Login baseado em JWT usando linhas do board como repositorio de usuarios. O metodo authenticateTableRow do SDK valida as credenciais diretamente nas colunas da sua tabela de usuarios.
• Integracao com o SDK — Todas as operacoes no board (criar linha, listar linhas, atualizar linha) passam pelo @copera.ai/sdk. Voce configura o Board ID e os Table IDs em um unico arquivo config.ts.
• Cache local — Apos gravar uma linha no Copera, a API salva uma copia leve no MongoDB. Isso significa que consultas de listagem sao leituras locais rapidas, em vez de chamadas a API do Copera a cada requisicao.
• Endpoints REST padrao — Os controllers seguem um padrao limpo baseado em classes usando fastify-decorators, facilitando a adicao de novos tipos de recursos.

Stack tecnologica: Fastify 4, MongoDB (Typegoose), JWT com criptografia AES-CBC, @copera.ai/sdk, logging com Pino, validacao com Yup/Zod.

base-application-web

Um aplicativo de pagina unica em React que fornece a interface do usuario. Ele se comunica exclusivamente com a base-application-api e nunca acessa o Copera diretamente.

Responsabilidades principais:

• Fluxo de autenticacao — Um AuthProvider baseado em contexto armazena o JWT, protege as rotas e redireciona usuarios nao autenticados para a pagina de login.
• Busca de dados — O React Query gerencia todo o estado do servidor, incluindo cache, atualizacao automatica e atualizacoes otimistas. As query keys sao centralizadas para um gerenciamento de cache consistente.
• Componentes de UI — Construidos com shadcn/ui (primitivos do Radix UI) e estilizados com Tailwind CSS, oferecendo uma biblioteca de componentes moderna e acessivel ja 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 tecnologica: React 18, Vite 6, Tailwind CSS 4, shadcn/ui, 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 e a chave para personalizar o Starter Application para o seu proprio caso de uso:

1. Um usuario interage com o frontend React — por exemplo, enviando um novo ticket de suporte.
2. O frontend envia uma requisicao POST para a base-application-api com os dados do formulario.
3. A API grava a linha no Copera via SDK: copera.board.tables.<nomeTabela>.createRow({ ... }).
4. A API salva um registro em cache no MongoDB local, armazenando o ID da linha do Copera junto com quaisquer campos necessarios localmente.
5. A API retorna o novo registro ao frontend, onde o React Query atualiza a lista em cache imediatamente.
6. Sua equipe ve o ticket no Copera — no board deles, na tabela correta, pronto para ser gerenciado com todas as ferramentas nativas do Copera: visualizacoes, automacoes, funcionalidades de IA e muito mais.

Esse padrao significa que seus clientes interagem com uma interface personalizada e limpa, enquanto sua equipe interna trabalha dentro do Copera usando todas as ferramentas que ja conhece.

Configuracao do Board

Toda a conexao com o board e controlada por um unico objeto de configuracao na API. Voce fornece o Board ID e os Table IDs para cada tipo de dado que sua aplicacao usa. Os Column IDs indicam ao SDK quais colunas especificas 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 pagina Column IDs para aprender como encontrar os IDs corretos das tabelas e colunas do seu board.

Open Source

O Starter Application sera publicado como open source no GitHub. Voce e 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.

Proximos Passos

• Como Comecar — Configure o Starter Application localmente em menos de 15 minutos.
• Usando IA para Construir — Saiba como usar assistentes de codificacao com IA para acelerar o desenvolvimento em cima do Starter Application.
• Column IDs — Encontre o Board ID, os Table IDs e os Column IDs necessarios para configurar o SDK.