Primeiros Passos com a Copera Starter Application

A Copera Starter Application e um portal de referencia que mostra como construir um aplicativo web voltado ao cliente, alimentado pelo seu workspace da Copera. Ela usa um Board como banco de dados, permitindo que voce gerencie usuarios e tickets diretamente na Copera enquanto o portal cuida da autenticacao, envio e exibicao.

Pre-requisitos

Antes de comecar, certifique-se de ter o seguinte instalado e disponivel:

Requisito	Versao / Observacoes
Node.js	>= 24.0.0
pnpm	10.16.1
MongoDB	Instancia local ou cluster na nuvem (ex.: MongoDB Atlas)
Workspace da Copera	Um workspace ativo com um Board configurado (veja o Passo 2)

Passo 1: Clonar o Repositorio

A starter application sera publicada em github.com/copera-ai. Quando estiver disponivel, clone-a para sua maquina local:

git clone https://github.com/copera-ai/starter-application.git
cd starter-application

observação

Se o repositorio ainda nao estiver publico, verifique novamente em github.com/copera-ai ou entre em contato com a equipe da Copera para acesso antecipado.

Passo 2: Configurar Seu Board na Copera

A starter application le e escreve dados em um Board da Copera. Voce precisa criar um Board com duas tabelas — Users e Tickets — e depois copiar os IDs relevantes para o arquivo de configuracao da aplicacao.

Criar o Board

No seu workspace da Copera, acesse Colaborar na barra lateral e crie um novo Board. Dê um nome como "Portal Data".

Configurar a Tabela Users

O seu Board tera uma tabela padrao. Renomeie-a para Users e adicione as seguintes colunas:

Nome da Coluna	Tipo de Campo	Observacoes
Name	Text	O nome de exibicao do usuario
Identifier	Text	O endereco de email do usuario (usado para autenticacao)
Password	Password	Armazenado com seguranca; usado para autenticacao no portal
Role	Select (Dropdown)	Adicione duas opcoes: admin e user

Configurar a Tabela Tickets

Adicione uma segunda tabela ao Board e nomeie-a Tickets. Adicione as seguintes colunas:

Nome da Coluna	Tipo de Campo	Observacoes
Title	Text	Um resumo curto do ticket
Details	Paragraph (Text)	Descricao completa da solicitacao
User	Link	Vinculo com a tabela Users
Status	Select (Dropdown)	Adicione opcoes como open, in progress, closed
Request Type	Select (Dropdown)	Adicione opcoes relevantes para o seu caso de uso

Encontrar os IDs do Board, das Tabelas e das Colunas

Voce precisara copiar varios IDs para a configuracao da aplicacao. Veja onde encontrar cada um:

• Board ID — O ID do Board aparece na URL quando o Board esta aberto. Ele tem o formato: app.copera.ai/boards/6abc123.... Copie o trecho apos /boards/.
• Table ID — Abra o Board e clique na aba com o nome da tabela na parte superior. O Table ID e exibido no painel de configuracoes da tabela, ou pode ser encontrado na URL apos navegar ate a tabela.
• Column ID — Clique no icone de configuracoes (engrenagem ou menu de tres pontos) no cabecalho de qualquer coluna. O painel de configuracoes da coluna exibira o ID da coluna. Copie esse valor para cada coluna que voce precisar referenciar.

dica

Mantenha um arquivo de texto aberto enquanto copia os IDs — voce precisara de um Board ID, dois Table IDs e varios Column IDs antes de passar para o proximo passo.

Editar src/config.ts

Abra src/config.ts no repositorio clonado e preencha os IDs coletados:

export const config = {
  boardId: 'SEU_BOARD_ID',
  tables: {
    users: {
      tableId: 'SEU_USERS_TABLE_ID',
      columns: {
        name: 'SEU_NAME_COLUMN_ID',
        identifier: 'SEU_IDENTIFIER_COLUMN_ID',
        password: 'SEU_PASSWORD_COLUMN_ID',
        role: 'SEU_ROLE_COLUMN_ID',
      },
    },
    tickets: {
      tableId: 'SEU_TICKETS_TABLE_ID',
      columns: {
        title: 'SEU_TITLE_COLUMN_ID',
        details: 'SEU_DETAILS_COLUMN_ID',
        user: 'SEU_USER_COLUMN_ID',
        status: 'SEU_STATUS_COLUMN_ID',
        requestType: 'SEU_REQUEST_TYPE_COLUMN_ID',
      },
    },
  },
};

Passo 3: Configurar as Variaveis de Ambiente

A aplicacao usa um arquivo .env para armazenar segredos e detalhes de conexao. Copie o arquivo de exemplo para comecar:

cp .env.example .env

Abra o .env e preencha os seguintes valores:

Variavel	Descricao
MONGODB_URI	A string de conexao para a sua instancia do MongoDB (ex.: mongodb://localhost:27017/starter ou o URI do Atlas)
APP_TOKEN	Qualquer string secreta usada para assinar JWTs para o gerenciamento de sessoes do portal (ex.: uma string aleatoria longa)
COPERA_API_KEY	Sua chave de API do workspace, encontrada em Configuracoes do Workspace > API na Copera

Para o aplicativo web (frontend), defina uma variavel adicional:

Variavel	Descricao
VITE_SERVER_URL	A URL onde o servidor de API sera executado (ex.: http://localhost:3000)

dica

Voce pode gerar uma string aleatoria segura para APP_TOKEN usando openssl rand -hex 32 no seu terminal.

Encontrar Sua Chave de API da Copera

1. Na Copera, clique no nome do seu workspace no canto superior esquerdo.
2. Va para Configuracoes > API.
3. Gere ou copie sua chave de API.

Passo 4: Instalar Dependencias e Executar

Com a configuracao concluida, instale as dependencias e inicie tanto a API quanto o aplicativo web juntos:

pnpm install
pnpm dev

Isso inicia ambos os servicos simultaneamente:

• Servidor de API — executado na porta definida no seu .env (padrao: http://localhost:3000)
• Aplicativo web — executado no servidor de desenvolvimento Vite (padrao: http://localhost:5173)

Abra seu navegador e acesse a URL do aplicativo web. Voce vera a pagina de autenticacao do portal.

Passo 5: Criar Seu Primeiro Usuario

O portal nao possui um formulario de registro publico por padrao — os usuarios sao gerenciados diretamente no seu Board da Copera. Para criar o primeiro usuario:

1. Na Copera, abra o Board configurado e navegue ate a tabela Users.
2. Adicione uma nova linha e preencha as colunas Name, Identifier (email), Password e Role.
3. Retorne ao aplicativo web no seu navegador.
4. Faca login usando o email e a senha que voce acabou de inserir.

observação

As senhas inseridas no Board sao tratadas pela camada de autenticacao da aplicacao. O comportamento exato depende de como a starter app processa as credenciais — consulte os arquivos src/config.ts e do servico de autenticacao para mais detalhes.

O Que Vem a Seguir

Agora que a aplicacao esta em execucao, veja algumas direcoes para ir mais alem:

• Personalizar o portal para o seu caso de uso — Ajuste a interface, adicione novas paginas ou modifique os campos do formulario de tickets para corresponder ao seu fluxo de trabalho.
• Adicionar colunas ao seu Board — Qualquer nova coluna adicionada na Copera pode ser referenciada no aplicativo incluindo seu Column ID em src/config.ts.
• Usar ferramentas de IA para construir novos recursos — A starter app e projetada como ponto de partida. Use assistentes de codificacao por IA junto com a API da Copera para acelerar o desenvolvimento.
• Explorar a API da Copera — Consulte a referencia de API para entender quais operacoes de dados estao disponiveis alem do que a starter app demonstra.

dica

Ao adicionar uma nova coluna ao seu Board na Copera, lembre-se de tambem adicionar seu Column ID na secao relevante de src/config.ts para que a aplicacao possa ler e gravar esse campo.