Começar na Soccius

O que estamos construindo

A Soccius é um CRM B2B personalizado por cliente, vendido junto de consultoria de processo comercial. Não é um SaaS: o cliente não se cadastra e sai usando. Ele recebe um sistema com a cara e o processo dele.

Isso tem uma consequência que organiza todo o resto: um cliente, uma instalação, um banco exclusivo. Nada é compartilhado entre clientes.

Personalizado não quer dizer banco diferente. O schema é o mesmo em todo cliente — ele é o produto. O que muda é a configuração (funis, etapas, campos, produtos, vocabulário) e, quando o produto não atende, um módulo só daquele cliente.

Os dois repositórios nossos

E cada cliente ganha um repositório privado próprio, inst-<slug>. O slug é o apelido curto do cliente (acme) e é a mesma palavra no repositório, no banco e na hospedagem — é o que liga tudo.

A dinâmica

Você conversa. Não precisa saber o nome de nenhum comando nem de nenhuma skill: o agente entende o pedido em português e traduz.

Não existe etapa fixa

Implantar software vai e volta: tela, backend, volta para a tela, dados, integração, regra nova, ajusta tudo. Quando alguém disser “volta na tela porque o backend mudou”, isso é normal — não é retrabalho e não é erro de planejamento.

O planejamento de cada cliente guarda continuidade, não ordem: o que já foi definido, o que está em andamento, as decisões tomadas, as que continuam abertas e o que depende de quê. Mexer no backend traz de volta a tela que dependia dele, em vez de deixá-la marcada como pronta quando já não está.

O que abre uma sessão de trabalho

/soccius-start

Ele pergunta se é cliente novo ou existente, lista os clientes por nome, e conduz daí. Dizer “vamos começar” ou “continua a ACME” chega no mesmo lugar.

Instalar na sua máquina

São quatro passos, e cada um destrava o seguinte. Antes de começar, confira que você tem:

node --version    # precisa ser 24 ou maior
pnpm --version
gh auth status    # precisa estar logado no GitHub
claude --version  # precisa ser 2.1.233 ou maior

1. Clonar a fábrica Escolha uma pasta fora do OneDrive — o OneDrive sincronizando node_modules deixa tudo lento e às vezes corrompe.
   TerminalCopiar

   git clone https://github.com/Soccius/soccius-foundry.git
   cd soccius-foundry
   pnpm install

   agora você tem a ferramenta, mas o Claude ainda não sabe onde ela está
2. Dizer ao Claude onde a fábrica está Grava o caminho em ~/.soccius/foundry.json. Só um caminho, nenhum segredo.
   Terminal · dentro de soccius-foundryCopiar

   node packages/cli/src/index.ts vincular --escrever

   agora o comando funciona de qualquer pasta, não só desta
3. Instalar o plugin
   TerminalCopiar

   claude plugin marketplace add Soccius/soccius-foundry
   claude plugin install soccius-foundry-operator@soccius

   agora o Claude tem as 14 skills e o comando /soccius-start
4. Reiniciar o Claude Code Plugin novo só entra em sessão nova. Feche e abra. Depois, de qualquer pasta: /soccius-start.

Autorizar o download dos pacotes

Os pacotes do produto ficam num registry privado, e o registry do GitHub sempre pede autenticação — até para ler. Uma vez por máquina:

gh auth token
# se der erro de escopo:
gh auth refresh -s read:packages

Copie o token e coloque no arquivo .npmrc da sua pasta de usuário (C:\Users\seu-nome\.npmrc no Windows):

//npm.pkg.github.com/:_authToken=COLE_O_TOKEN_AQUI

Atualizar depois

São dois passos porque são duas coisas: o plugin traz as skills, o clone traz a ferramenta.

cd soccius-foundry && git pull && pnpm install
claude plugin marketplace update soccius
claude plugin update soccius-foundry-operator@soccius

O @soccius no fim não é opcional: sem ele o comando responde Plugin not found. E reinicie a sessão depois.

Criar o banco de um cliente

O Supabase dá duas coisas de uma vez: o banco Postgres e a autenticação (o login do usuário). Um projeto Supabase por cliente, sempre — é o isolamento que a gente prometeu.

1. Entrar na conta da Soccius supabase.com/dashboard, com a conta administrativa da Soccius. Se você entrar com a sua conta pessoal, o projeto nasce no lugar errado.
2. New project Dentro da organização da Soccius, não numa pessoal.
3. Preencher

   Campo	O que pôr
   Name	inst-acme — o mesmo slug do repositório
   Database password	gere uma forte e guarde antes de continuar
   Region	South America (São Paulo)

   o projeto leva alguns minutos para ficar pronto
4. Pegar as três informações que o sistema precisa Em Project Settings:

   Onde	O que copiar
   Settings › Database › Connection string	a string de conexão — vira DATABASE_URL
   Settings › API › Project URL	vira NEXT_PUBLIC_SUPABASE_URL
   Settings › API › chave publicável	vira NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
   Settings › API › chave secreta	vira SUPABASE_SECRET_KEY — só para o bootstrap

   com isso dá para rodar as migrations e criar o primeiro usuário

Sobre o plano grátis

Serve para experimentar e para o CRM nosso, usado todo dia. Para cliente pagando, o plano pago — e aí a pausa e o backup deixam de ser problema.

As variáveis

O sistema precisa de quatro variáveis, e elas nunca entram no Git. O repositório declara os nomes; os valores vivem fora.

Como um passa para o outro

Quando o projeto na hospedagem existir, ele é a fonte: as variáveis moram lá e cada um puxa.

vercel link       # uma vez, liga a pasta ao projeto
vercel env pull   # baixa as variáveis para .env.local

Uma fonte só. Trocou uma chave? Troca lá, e todos puxam de novo. Ninguém manda segredo por conversa, e ninguém fica com uma versão velha.

Antes de a hospedagem existir, quem criou o banco passa os valores por canal privado, uma vez — e o primeiro ato depois disso é colocá-los na hospedagem, para não repetir.

Subir o sistema

Com o banco criado e as variáveis na mão, três comandos deixam o sistema rodando com um usuário que entra.

1. Escrever o .env Na pasta apps/web do soccius-software.
   apps/web/.envCopiar

   DATABASE_URL=...
   NEXT_PUBLIC_SUPABASE_URL=...
   NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=...
   SUPABASE_SECRET_KEY=...

2. Criar as tabelas As migrations aplicam o schema num banco vazio.
   Terminal · raiz do soccius-softwareCopiar

   pnpm --filter @soccius/db db:migrate

   o banco passa a ter as 49 tabelas do produto, vazias
3. Criar a empresa e o primeiro usuário Cria a empresa da instalação, o perfil de administração, o catálogo de permissões e a conta de login. Roda uma vez só por instalação.
   Terminal · dentro de apps/webCopiar

   pnpm bootstrap:dev --empresa "Soccius" --nome "Seu nome" --email voce@soccius.com

   ele imprime um link para você definir a senha e entrar
4. Rodar
   Terminal · raiz do soccius-softwareCopiar

   pnpm dev

   localhost:3000 — e o login já funciona

Publicar na internet

A Vercel pega o repositório, builda e põe no ar. Um projeto Vercel por cliente, ligado ao repositório daquele cliente.

1. Entrar com a conta da Soccius vercel.com/new, na equipe da Soccius.
2. Importar o repositório do cliente Add New › Project, escolher inst-acme. A Vercel reconhece que é Next.js sozinha — não mexa nos comandos de build.
3. Colocar as variáveis Em Environment Variables, as três primeiras — DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL e NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY.

   A chave secreta do Supabase não entra aqui. O sistema rodando não precisa dela.

   agora o build tem como falar com o banco
4. Deploy O primeiro leva alguns minutos. Depois disso, todo merge na branch principal publica sozinho.
5. Ajustar a região Project Settings › Functions, escolher São Paulo (gru1). Sem isso o sistema responde do outro lado do mundo e tudo fica lento.
6. Baixar o teto de gasto O padrão é alto para o nosso tamanho. Ajuste nas configurações de faturamento da equipe — é o que evita susto no fim do mês.

O endereço do cliente

Cada cliente entra num subdomínio nosso — acme.soccius.com — vê a tela de login dele e usa o sistema.

1. Declarar na Vercel Project Settings › Domains, adicionar acme.soccius.com. Ela mostra o registro de DNS que falta.
2. Apontar no DNS No painel do domínio soccius.com, criar o registro que a Vercel pediu. Leva de minutos a algumas horas para propagar. o cliente passa a entrar pelo endereço dele

Trabalhar em dois sem se atropelar

Cada um na sua branch, no seu tempo. Ninguém edita a branch principal direto.

git checkout -b lucca/tela-de-produtos   # sua branch
# ... trabalha, testa local ...
git add -A && git commit -m "feat: ..."
git push -u origin lucca/tela-de-produtos
gh pr create                              # abre o PR

A Vercel cria uma URL de preview para cada PR. Você vê online, antes de integrar. Quando estiver bom, merge — e o merge publica.

Código e dado seguem caminhos diferentes

Isso importa na prática: para um ver o que o outro cadastrou, os dois precisam apontar para o mesmo banco. Cada um no banco da própria máquina, o trabalho não se encontra.

Configurar o CRM

Aqui é onde a personalização de verdade acontece, e nada disso é código: é configuração, feita dentro do sistema rodando.

1. Configurações › Vocabulários Preencha, no mínimo, Tipos de funil. Depois, com o cliente: origens do negócio, motivos de perda, segmentos, unidades de medida. cada cliente tem o vocabulário dele — não existe padrão nosso
2. Configurações › Funis Crie o funil e as etapas. Lembre: etapa não é situação — Ganho e Perdido não são etapas, são o desfecho. agora é possível criar negócio
3. Produtos Cadastre o catálogo do cliente: famílias, grupos, itens. Imagem de produto ainda não sobe — a parte de arquivos não foi construída.
4. Clientes e negócios Aí o CRM está operando, e a conversa passa a ser sobre o processo do cliente.

Padrões visuais

Se você for construir tela, ela segue o Design System — que vive em docs/design-system/ na fábrica. Ele é consultado, nunca copiado: um token copiado para outro lugar vira uma segunda versão que ninguém atualiza.

Uma cor de ação, e só uma

signal (#1FB6C1) é a marca, o botão Criar, o foco, o item ativo e a etapa corrente. Nada mais compete com ela. Verde só para ganho, vermelho só para erro e perda, âmbar só para aviso.

Grotesca para a fala, mono para o dado

Hanken Grotesk faz texto, interface e títulos. Space Mono carrega o que é técnico: identificador, número de negócio, valor em reais. Um valor monetário em Hanken parece errado dentro da Soccius.

O sistema é reto

Raio máximo de 5px, nenhuma pílula, e elemento aninhado nunca tem raio maior que o pai. Borda de 1px é a ferramenta principal de separação; sombra é discreta e funcional.

O que não se negocia

• Interface em pt-BR, Sentence case, sem emoji.
• Nenhuma tela desenha o próprio cabeçalho — o shell é da Soccius.
• Detalhe é página, nunca modal.
• Toda listagem segue o padrão da tela de Clientes.
• Toast para todo retorno, uma linha. Nunca alert.
• Ação destrutiva pede confirmação que diz o que muda e quanto.
• O vazio explica e oferece saída — nunca “Nada aqui”.
• Sem foto, ilustração, textura ou gradiente decorativo.
• Nenhuma tela assume quantidade fixa de campos, etapas ou colunas.

A última é arquitetural, não estética: a Soccius é personalizável por construção, e uma tela que assume três etapas quebra no cliente que tem sete.

O que existe e o que não existe

Esta é a seção mais importante para não prometer o que o sistema não faz.

Quando travar

E o caminho que sempre funciona: pergunte ao Claude. Com o plugin instalado ele conhece o sistema, sabe o que existe e o que não existe, e diz onde parar em vez de inventar.