Glossário

Status: canônico · Escopo: Todo termo, sigla e nome próprio usado nos issues e nos docs — explicado para quem chegou hoje · Atualizado em: 2026-08-05

Este documento existe por um motivo simples: quem entra no projeto não deveria precisar perguntar o que é “A2P 10DLC” ou “DFW” para entender uma tarefa. Se você encontrar um termo em algum issue ou doc que não está aqui, isso é um defeito deste arquivo — adicione.

A ordem é por assunto, não alfabética, porque os termos só fazem sentido em grupo.

O negócio

Termo	O que é
Tactflow	A empresa. Este repositório é um componente dela: o runtime de conversa.
HVAC	Heating, Ventilation and Air Conditioning — aquecimento, ventilação e ar-condicionado. Nos Estados Unidos é o nome do ofício de quem instala e conserta ar-condicionado e aquecimento residencial. É o nosso primeiro mercado.
DFW	Dallas–Fort Worth. A região metropolitana de Dallas e Fort Worth, no estado do Texas. Também chamada de “metroplex”. É onde vamos vender primeiro.
TX	Sigla do estado do Texas.
WY	Sigla do estado de Wyoming, onde a empresa americana foi aberta.
Dono-operador	O dono do negócio que também executa o serviço. No nosso caso: o cara que instala o ar-condicionado e é o mesmo que deveria atender o telefone. Por isso ele perde ligação.
Wedge	Literalmente “cunha”. O ponto específico por onde a gente entra no mercado. Não é o limite do produto — é onde a primeira venda acontece.
ICP	Ideal Customer Profile — perfil de cliente ideal. Para nós: dono-operador de HVAC com menos de 5 funcionários e menos de 1 milhão de dólares por ano.
Design partner	Cliente dos primeiros, que paga menos e em troca dá retorno estruturado toda semana. Não é teste grátis: ele paga, e o desconto compra o direito de incomodar.
GTM	Go-to-market — como o produto chega ao cliente: prospecção, preço, venda, onboarding.
Concierge	Fazer na mão o que um dia será automático. Onboarding concierge = você configura o cliente manualmente, sem tela de cadastro. É recomendado nos primeiros clientes.
Runbook	Roteiro escrito passo a passo de uma tarefa operacional, para outra pessoa executar sem te perguntar nada.
SOP	Standard Operating Procedure — procedimento operacional padrão. É o mesmo que runbook.
CSM	Customer Success Manager — pessoa responsável por manter os clientes funcionando e satisfeitos depois da venda.
Outreach	O contato ativo com quem ainda não é cliente: ligação, e-mail, mensagem.
MRR	Monthly Recurring Revenue — receita recorrente mensal. A soma das mensalidades.
Churn	Cliente que cancela.
CRO	Conversion Rate Optimization — otimizar a taxa de conversão de uma página: quantos visitantes viram lead.
SEO	Search Engine Optimization — aparecer bem na busca do Google.
CENTS	Um framework de avaliação de negócio (controle, entrada, necessidade, tempo, escala). Nos nossos docs, o que importa é o T de tempo: se o negócio só funciona com você trabalhando nele, é emprego, não negócio.
Revenue Recovery Cycle	O nosso diferencial declarado: não é “IA atende telefone”, é fechar o ciclo — nunca perder um lead e provar em dólares quanto foi recuperado.
Value report	Relatório semanal para o dono do negócio: quantas ligações entraram, quantas viraram agendamento, quanto isso representa em dinheiro. É o que sustenta o preço.
Take-rate	Cobrar um percentual da receita do cliente. Descartado — gera disputa mensal sobre o que foi mérito de quem.
GHL	GoHighLevel. Uma plataforma pronta que agências revendem para montar automações sem programar. A alternativa que a gente rejeitou: dá menos trabalho, mas não constrói ativo.
ServiceTitan	Software grande de gestão para empresas de serviço de campo. Não é concorrente: atende empresa média e grande; nosso cliente é o dono-operador que não tem ServiceTitan.

Empresa, imposto e papelada

Termo	O que é
LLC	Limited Liability Company — o tipo de empresa americana mais comum para negócio pequeno. Equivalente aproximado da nossa LTDA. Pode ser aberta 100% remoto, sem visto e sem morar nos Estados Unidos.
SMLLC	Single-Member LLC — LLC com um único sócio. É o nosso caso.
EIN	Employer Identification Number — o número de identificação fiscal da empresa nos Estados Unidos. É o “CNPJ americano”. Sai de graça no IRS e não exige SSN.
IRS	Internal Revenue Service — a Receita Federal americana.
SSN	Social Security Number — o número de identificação de pessoa física americana. Estrangeiro não tem, e não precisa para tirar EIN.
ITIN	Individual Taxpayer Identification Number — identificação fiscal para pessoa física estrangeira. Não precisamos dele para o EIN.
KYC	Know Your Customer — o processo de verificação de identidade que banco e processador de pagamento fazem antes de abrir conta.
Form 5472	Declaração anual obrigatória para LLC de dono estrangeiro. É informativa (não é imposto), mas a multa por não entregar é de cerca de 25 mil dólares.
LTDA	O tipo de empresa brasileira. Está na fila para quando a receita justificar o custo da estrutura.
Fator R	Regra do Simples Nacional brasileiro: se a folha de pagamento for pelo menos 28% do faturamento, a empresa de serviço paga imposto pelo Anexo III (mais barato) em vez do Anexo V (mais caro).
Anexo III / Anexo V	As duas tabelas de alíquota do Simples Nacional que podem se aplicar a empresa de serviço. A diferença de imposto entre elas é grande.
IRPF / IRPJ / INSS / ISS / PIS / COFINS / CSLL / IRRF / DAS / CNAE	Tributos e códigos brasileiros. IRPF = imposto de renda de pessoa física; IRPJ = de pessoa jurídica; INSS = previdência; ISS = imposto municipal sobre serviço; PIS/COFINS = contribuições federais; CSLL = contribuição sobre o lucro; IRRF = imposto retido na fonte; DAS = a guia única do Simples; CNAE = o código que classifica a atividade da empresa.
OCDE	Organização para a Cooperação e Desenvolvimento Econômico. Aparece nos docs por causa de regras de tributação internacional.
PI	Propriedade intelectual — quem é o dono do código e da marca.
VC	Venture capital — investidor de risco. A escolha de estado da empresa muda se a gente for captar (Delaware) ou não (Wyoming).
Break-glass	Literalmente “quebrar o vidro”. O procedimento de emergência para recuperar acesso quando o caminho normal falhou — por exemplo, perder o celular do segundo fator.
2FA	Two-Factor Authentication — segundo fator de autenticação: além da senha, um código do celular ou de um aplicativo.
Cofre	Gerenciador de senhas compartilhado (usamos Bitwarden). Guarda login, segundo fator, cartão e chaves de API.

Telefonia, mensagem e conformidade

Termo	O que é
Twilio	A empresa que nos vende os números de telefone americanos e entrega SMS.
Vapi	O serviço que hospeda o agente de voz: ele recebe a ligação, transcreve, chama o modelo de linguagem, sintetiza a resposta em áudio e gerencia os turnos da conversa. A voz não passa pelo nosso serviço de LLM — passa pela Vapi.
SMS	Short Message Service — a mensagem de texto comum do celular, a que funciona sem internet.
A2P 10DLC	Application-to-Person, 10-Digit Long Code. É o registro obrigatório para um sistema enviar SMS a partir de um número americano comum de dez dígitos. Exigência das operadoras, não do Twilio. Sem esse registro, a mensagem não é entregue. Exige empresa americana com EIN. É o nosso bloqueador número um para operar comercialmente.
TCR	The Campaign Registry — a entidade que administra o registro A2P 10DLC para as operadoras.
Brand / Campaign	As duas partes do registro A2P. Brand é quem envia (a empresa). Campaign é para quê (confirmação de agendamento, por exemplo). Cada um tem status próprio e pode ser reprovado separadamente.
TCPA	Telephone Consumer Protection Act — a lei federal americana que regula ligação e mensagem para consumidor. Manda em consentimento e horário.
Mini-TCPA	Versão estadual da TCPA. Cada estado tem a sua, algumas mais duras que a federal.
SB 140	Lei do Texas em vigor desde 1º de setembro de 2025 que trouxe SMS para dentro da mini-TCPA local. Multa de 500 a 1.500 dólares por mensagem — mas mensagem com consentimento é isenta.
FTSA	Florida Telephone Solicitation Act — a lei da Flórida, conhecida por gerar ação coletiva. Um dos motivos de escolhermos o Texas.
FCC	Federal Communications Commission — a agência americana que regula telecomunicação.
Opt-in / opt-out	Opt-in é o consentimento explícito para receber mensagem. Opt-out é a saída — nos Estados Unidos, responder STOP ou UNSUBSCRIBE tem de funcionar sempre, e isso é obrigatório, não opcional.
ISV	Independent Software Vendor — fornecedor independente de software. No Twilio é um tipo de conta feito para quem atende vários clientes: uma conta principal com uma subconta por cliente.
Subconta	Conta filha dentro da conta principal do Twilio. Isola número, credencial e cobrança de cada cliente.
Trust Hub	A área do Twilio onde ficam os perfis de identidade e conformidade da empresa e dos clientes.
SID	String Identifier — o formato de identificador do Twilio. AccountSid, BrandSid, CampaignSid, SubAccountSid, CustomerProfileSid são os identificadores de conta, marca, campanha, subconta e perfil de cliente.
PSTN	Public Switched Telephone Network — a rede telefônica tradicional. O áudio dela é de banda estreita (8 kHz, formato μ-law), e isso piora a transcrição e a voz sintetizada. É por isso que o mesmo agente soa melhor no navegador que no telefone.
μ-law	O formato de compressão de áudio da telefonia americana. Banda estreita.
DTMF	Dual-Tone Multi-Frequency — o tom que o telefone emite quando você aperta uma tecla. Usamos para capturar número digitado, porque falar número em linha telefônica erra demais.
E.164	O padrão internacional de formato de número de telefone: +16826228174.
Area code	O código de área americano, equivalente ao nosso DDD. O nosso número usa 682, de Arlington, Texas.
Portabilidade	Levar um número de uma operadora para outra. Não é o nosso caso: mover número entre contas do mesmo Twilio é transferência interna, bem mais simples.
Text-back	Ligação não atendida gera SMS automático na hora. É o coração da promessa de nunca perder um lead.

O produto e o código

Termo	O que é
Runtime de conversa	O nome do que este repositório é: o sistema que conduz a conversa, em voz, SMS ou chat.
Tenant	Um cliente nosso dentro do sistema. Todo dado é isolado por tenant — o cliente A nunca vê o dado do cliente B.
Unit	Uma unidade do cliente (uma filial, uma praça). Um tenant pode ter várias.
Slug	O apelido curto e sem espaço que identifica algo na URL, tipo arlington-hvac.
Endpoint	Duas coisas, dependendo do contexto. (1) Um endereço da nossa API que recebe requisição. (2) Na tabela channel_endpoints, o canal de entrada de um cliente — o número de telefone dele, por exemplo.
Webhook	Endereço nosso que um serviço de fora chama quando algo acontece. A Vapi chama o nosso webhook quando entra uma ligação; o Twilio chama quando chega um SMS.
Tool call	Quando o modelo de linguagem decide chamar uma função nossa no meio da conversa — consultar horário livre, agendar. É como a conversa vira ação de verdade.
STT	Speech-to-Text — transformar fala em texto (transcrição). Usamos Deepgram através da Vapi.
TTS	Text-to-Speech — transformar texto em fala. Usamos ElevenLabs (11labs) através da Vapi.
LLM	Large Language Model — modelo de linguagem grande, o “cérebro” que entende e responde. Na voz é o GPT-4o, configurado por nós a cada ligação.
Deepgram	O fornecedor de transcrição. O modelo nova-2-phonecall é a versão treinada para áudio de telefone.
11labs / ElevenLabs	O fornecedor da voz sintetizada.
Endpointing	A decisão de quando o cliente terminou de falar. Se errar, a IA atropela ou demora — é a principal causa de soar robótico.
Barge-in	Quando o cliente interrompe a IA no meio da fala e ela para de falar.
Latência por turno	Quanto tempo passa entre o cliente parar de falar e a IA começar a responder. Alvo: menos de 1,5 segundo.
WER	Word Error Rate — taxa de erro de palavra. A métrica de qualidade de transcrição.
Intake	A coleta das informações do chamado: qual o problema, se é urgente, endereço, nome, telefone de retorno.
Offering	Um serviço do catálogo do cliente, com duração e preço. Exemplo: service-call (visita comum) e emergency (urgência).
Freebusy	A consulta ao Google Calendar que devolve só os horários ocupados, sem revelar o conteúdo dos compromissos.
Fixture	Dado de exemplo fixo, usado em teste e em demonstração. A nossa é arlington-hvac.
Seed	Popular o banco com o dado inicial de um cliente. pnpm seed:demo faz isso a partir de um arquivo JSON.
Smoke test	Teste rápido que só verifica se o básico está de pé, sem entrar em detalhe.
Snapshot	Uma foto do estado atual. No funil do site, é o conjunto de respostas do visitante até aquele momento.
Upsert	Gravar criando se não existe, atualizando se existe.
Idempotência	A propriedade de uma operação poder ser repetida sem causar efeito duplicado. É o que impede o cliente de receber a mesma mensagem duas vezes se algo for reprocessado.
Stub	Implementação falsa que responde no formato certo, para o front-end poder ser construído antes do backend existir.
Floor	Arredondar para baixo. Usado no funil para o número exibido nunca exagerar.

Infraestrutura

Termo	O que é
Cloudflare Workers	Onde o nosso código roda: pequenos processos na borda da rede, próximos do usuário, em vez de um servidor tradicional.
Durable Object	Recurso do Cloudflare que guarda estado e permite agendar despertadores. É o que sustenta uma conversa em andamento e os lembretes.
Queue	Fila de mensagens. Garante que uma tarefa seja processada mesmo se algo falhar no meio.
R2	O armazenamento de arquivo do Cloudflare, equivalente ao S3 da Amazon.
Neon	O banco de dados PostgreSQL que usamos, hospedado.
RLS	Row-Level Security — segurança em nível de linha do PostgreSQL. O banco em si recusa devolver linha de outro tenant. Configurado como fail-closed: na dúvida, nega.
DDL	Data Definition Language — os comandos de SQL que criam e alteram tabela.
Migration	Arquivo numerado que altera o banco. Aplicado em ordem, nunca editado depois de aplicado.
wrangler	A ferramenta de linha de comando do Cloudflare, usada para rodar e publicar o Worker.
CLI	Command-Line Interface — programa de linha de comando, sem tela.
CORS	Cross-Origin Resource Sharing. A regra do navegador que decide se uma página de um domínio pode ler a resposta de outro domínio. Precisamos dela porque o site está em tactflow.io e a API em api.tactflow.io.
Turnstile	O verificador de “não sou robô” do Cloudflare. Protege endereço público de abuso.
JWT	JSON Web Token — formato de token assinado, usado para autenticar por tempo curto.
SDK	Software Development Kit — a biblioteca oficial de um fornecedor.
API	Application Programming Interface — a forma como dois sistemas conversam por programa em vez de por tela.
HTTP / POST / GET	O protocolo da web e os dois verbos que mais usamos: GET para ler, POST para enviar ou criar.
URL	O endereço de uma página ou de um endpoint.
WebRTC	A tecnologia que permite áudio ao vivo direto no navegador, sem passar por telefone. É como a demonstração de voz do site funciona.
KV	Key-Value — armazenamento simples de chave e valor do Cloudflare.
OAuth	O protocolo em que o usuário autoriza o nosso sistema a acessar a conta dele em outro serviço, sem entregar a senha. Usamos para o Google Calendar.
SPF / DKIM / DMARC	Os três registros de DNS que provam que um e-mail enviado em nome do nosso domínio é legítimo. Sem eles, o e-mail cai no spam.
Resend / SendGrid	Serviços de envio de e-mail transacional (confirmação, recuperação de senha).
Render	Onde o serviço Python de LLM esteve hospedado até 11/08/2026. Saiu do mapa — ver ADR 0005.
SLA	Service Level Agreement — o compromisso formal de disponibilidade ou tempo de resposta.

O site de marketing

Termo	O que é
marketing-web	O site público em tactflow.io — apps/marketing-web. Publica no projeto Cloudflare Pages tactflow-site, que é o nome do deployable e não da pasta. Era um repositório separado (tactflow/tactflow-site, apagado em 10/08/2026 — a discussão dos 15 PRs está preservada em docs/archive/tactflow-site-prs.md). O sufixo -web o distingue de booking-web: os dois são site, e chamar um só de site obrigava a lembrar qual.
Taly	O nome do agente de voz do site — o que qualifica o visitante e vende a Tactflow. É diferente do agente do telefone, que agenda serviço para o cliente do nosso cliente.
Funil	A sequência de passos do /talk: apresentação, setor, ligações perdidas, valor do serviço, resultado. Existe como máquina de estados pura, sem tela e sem voz.
Máquina de estados	Um pedaço de código que só guarda “em que passo estamos e o que já foi respondido”, e recusa transição inválida. Ser pura (sem tela, sem rede) é o que permite testá-la sem navegador.
Driver	Quem opera a máquina do funil. São dois e usam os mesmos métodos: o clique do visitante e a voz da Taly.
Astro	O framework do site. Gera HTML estático e só hidrata com JavaScript o que precisa.
SPA	Single-Page Application — site que troca de tela sem recarregar a página.
GSAP / Lenis	Bibliotecas de animação e de rolagem suave usadas no site.
CTA	Call to Action — o botão principal que a gente quer que a pessoa clique.
Soft 404	Quando um endereço que não existe responde “200 OK” com a página inicial em vez de responder “404 não encontrado”. Ruim para busca, porque indexa conteúdo duplicado.
Breakdown	A conta que o visitante viu na tela: ligações perdidas por mês, agendamentos perdidos, valor de cada um, total.

Como um issue é classificado

Cada issue carrega quatro informações independentes. Três delas são campos nativos do GitHub, e não etiquetas — campo nativo aparece em coluna, ordena e filtra de verdade, e não some quando alguém renomeia uma etiqueta.

Onde	Valores	Responde
Priority (campo)	Urgent · High · Low	Quanto isso urge
Type (campo)	Bug · Feature · Task	Que natureza de trabalho é
Effort (campo)	High · Medium · Low	Quanto custa. Ainda não preenchido — estimativa chutada é pior que campo vazio
Etiquetas	dois eixos, abaixo	Quem faz e sobre o que é

O que cada prioridade significa aqui, que não é o significado genérico:

Valor	Significa
Urgent	Bloqueia o primeiro cliente pagante. Se isso não estiver pronto, não há venda.
High	Importante e não bloqueia a venda.
Low	Só depois da validação com os design partners.

Medium existe na lista do GitHub e está deliberadamente vazio: a nossa escala real tem três níveis, e inventar um quarto seria precisão falsa.

Etiqueta, eixo 1: quem faz

Exatamente uma por issue, sempre.

Etiqueta	Significa
owner:founder-only	Só a mão do fundador: assinatura, dinheiro, verificação de identidade, decisão de negócio, conversa humana.
owner:founder-unblocks	Uma ação curta do fundador destrava trabalho que outra pessoa faz: criar conta, gerar chave, mexer em DNS, decidir sobre dado.
owner:delegable	Pode sair da mão do fundador com supervisão.

Etiqueta, eixo 2: sobre o que é

Uma ou mais por issue.

Etiqueta	Significa
area:voice	Canal de voz: Vapi, transcrição, turnos, comportamento na ligação.
area:site	Site de marketing e o funil /talk, incluindo o backend que só existe para servi-lo.
area:infra	Contas, credenciais, deploy, domínio, secrets.
area:gtm	Prospecção, preço, design partners, onboarding.
area:compliance	Regulação de telecom e de consumidor: A2P 10DLC, TCPA, consentimento, saída da lista.
area:legal-tax	Entidade, banco, contador, Form 5472, contrato e privacidade.
area:ops	Como a empresa é operada: alocação de tempo, delegação, portões de contratação, sucessão.
area:docs	Documento canônico divergindo do código.

O que saiu, e por quê

• p0-bloqueia-venda, p1-importante, p2-depois → viraram o campo Priority.
• bug, enhancement → viraram o campo Type. Como etiqueta eram aplicadas em 16 de 51 issues; como campo estão em todos.
• founder-ops → redundante. Todo issue que a tinha também tinha so-fundador: era subconjunto estrito, não acrescentava filtro nenhum. Ela dizia quem faz, que é o eixo 1. O que sobrou de assunto legítimo virou area:ops.
• documentation, duplicate, good first issue, help wanted, invalid, question, wontfix → padrão do GitHub, zero uso em 54 issues.

Nossos comandos

Comando	O que faz
pnpm quality	Roda tudo: lint, tipos, testes, fronteiras de dependência, docs, schema. É o portão antes de subir código.
pnpm boundaries	Verifica se nenhuma camada importou outra que não devia. Quebra o build se sim.
pnpm docs:lint	Verifica se os documentos seguem o padrão (idioma, metadados, estrutura, links).
pnpm seed:demo	Cria um cliente no banco a partir de um arquivo de configuração.
pnpm smoke:voice	Verifica rapidamente se o caminho da voz está de pé.
pnpm dev:worker	Sobe o Worker localmente para desenvolver.