Arquitetura dos Sites Públicos

Documento canônico: 06-public-sites/architecture.md

Status: ✅ APROVADO PARA EXECUÇÃO — 03 Maio 2026
Issue: #42
Repositórios públicos ativos: TECH-HUMAN/techhuman-docs, TECH-HUMAN/techhuman-playbook e TECH-HUMAN/techhuman-website

1. Objetivo

Criar uma camada pública, premium e escalável para sites comerciais da Tech Human e do ecossistema, sem transformar páginas de conversão em cópias brutas do Docs ou do Playbook guiado.

O objetivo não é substituir o Docs nem o Playbook. O objetivo é criar uma ponte:

Docs integral → Playbook guiado → narrativa comercial → site comercial → aquisição → relacionamento → entrega

2. Princípio de Separação

Camada	Visibilidade	Função
Repositório canônico	Privado	Governança editorial, histórico, issues, PRs e materiais fonte
Docs	Público	Leitura navegável do conteúdo integral aprovado
Playbook guiado	Público	Entendimento visual, progressivo e orientado por audiência
Site público	Público	Narrativa comercial, posicionamento, prova, captação e conversão
Materiais públicos	Público ou controlado	One-pagers, páginas de produto, apresentações curadas

Essa separação evita dois riscos:

confundir um site comercial com documentação estratégica longa;
transformar o Playbook em repositório de documento bruto;
empobrecer a narrativa de aquisição com excesso de arquitetura interna.

3. Repositórios

Repositório	Visibilidade	Responsabilidade
`TECH-HUMAN/th-new-business-model`	Privado	Fonte canônica e governança editorial
`TECH-HUMAN/techhuman-docs`	Público	Distribuidor GitHub Pages de `docs.techhuman.com.br`
`TECH-HUMAN/techhuman-playbook`	Público	Distribuidor GitHub Pages de `playbook.techhuman.com.br`
`TECH-HUMAN/techhuman-website`	Público	Site comercial público da Tech Human
`needyuai/trustyu-docs`	Privado	Decisões técnicas, ADRs e documentação de referência
`needyuai/trustyu-template`	Privado	Template de implementação para produtos e sites
`needyuai/trustyu-infra`	Privado	CI/CD, padrões de Node, pnpm e deploy

Regra de criação de novos sites

Novos sites comerciais devem nascer como repositórios públicos separados quando o objetivo for marca, aquisição, conteúdo ou presença institucional.

Exemplos futuros:

Repositório futuro	Uso provável
`trustyu-website`	Site público da Trustyu
`needyu-website`	Site público do produto NeedyU.ai
`jarvis-website`	Site público institucional/metodológico, se aprovado
`trust-score-website`	Site de campanha ou produto dedicado, se necessário

4. Stack Técnica Padrão

Camada	Decisão
Framework	Next.js App Router
Rendering inicial	Static export
Linguagem	TypeScript strict
UI	shadcn/ui + Radix
Estilo	Tailwind CSS
Design tokens	Brand Kit Tech Human
Tipografia	Raleway
Ícones	lucide-react
Package manager	pnpm
Node.js	22 LTS
CI	lint + typecheck + test + build

Por que Next.js

Next.js permite começar com páginas estáticas rápidas e evoluir para rotas dinâmicas, integrações, experimentos, formulários, CMS e internacionalização sem trocar a base.

Por que shadcn/ui

shadcn/ui entrega componentes acessíveis, editáveis e controlados pelo próprio repositório. Isso combina com a necessidade de marca premium sem depender de uma biblioteca visual fechada.

5. Deploy

Fase 1 — sites comerciais estáticos

Usar export estático:

pnpm build → out/

Opções recomendadas:

Opção	Quando usar
GitHub Pages	Docs, Playbook e fallbacks estáticos simples com domínio próprio
Netlify Drop	Validações rápidas e páginas estáticas pontuais
Netlify Git deploy	Quando houver fluxo contínuo de PR, preview e domínio fora do Pages
Vercel Git integration	Quando o site evoluir para recursos dinâmicos mais nativos do Next.js

Fase 2 — recursos dinâmicos

Migrar para Git deploy com runtime gerenciado quando houver:

formulários server-side;
CMS;
personalização por campanha;
autenticação;
analytics avançado;
rotas dinâmicas ou API routes.

6. Fluxo Editorial

1. Fonte canônica aprovada
2. Curadoria comercial
3. Texto público seguro
4. PR no repositório público
5. Validação técnica
6. Deploy preview
7. Publicação

Checklist antes de publicar

O texto é público?
Não revela margem, pipeline, nomes de clientes ou dados não autorizados?
A mensagem começa por dor, resultado e confiança antes de explicar arquitetura?
A linguagem está alinhada ao Brand Kit e às mensagens por audiência?
O conteúdo deriva de fonte aprovada no Docs/repositório canônico?

7. Domínios

Domínio	Papel recomendado
`techhuman.com.br`	Site comercial principal
`www.techhuman.com.br`	Alias do site principal
`docs.techhuman.com.br`	Portal público dos documentos integrais
`playbook.techhuman.com.br`	Playbook guiado do ecossistema
`pipeline.techhuman.com.br`	Cockpit operacional comercial, inicialmente público-seguro e depois restrito se houver dados reais
`hub.techhuman.com.br`	Possível área pública/semipública de materiais e onboarding
`trustyu.ai`	Site público da Trustyu
`needyu.ai`	Site público do produto NeedyU.ai

onboarding.techhuman.com.br pode ser usado para processos específicos de cliente, mas não deve ser o nome principal do hub de conteúdo estratégico. Para referência integral, use docs; para entendimento guiado, use playbook; para materiais e onboarding, avalie hub.

pipeline.techhuman.com.br deve seguir uma regra diferente: ele não é camada de aquisição nem de treinamento. Ele existe para execução comercial. Pode começar como página estática com dados anonimizados, mas nomes reais, contatos, valores e status sensíveis devem ficar no CRM próprio Tech Human em construção ou em outra base com controle de acesso equivalente.

Quando os AGENTS SDR IA entrarem em operação, eles devem atuar conectados ao CRM e ao pipeline: pesquisando, qualificando, sugerindo porta, preparando follow-up e registrando evidência. Mensagens externas, propostas, negociação e handoff Trustyu continuam exigindo aprovação humana até existir política formal em contrário.

8. Guardrails

Pode ir para site comercial	Deve ficar no Docs/repo canônico
Posicionamento comercial	Tese de negócio completa
Propostas de valor curadas	Margens, pricing interno e hipóteses financeiras
Ofertas e resultados esperados	Processo operacional detalhado
Cases autorizados	Dados de cliente sem autorização
Manifesto e visão	Roadmap sensível
Conteúdo educativo	Documentos integrais e playbooks brutos

9. Roadmap

Fase	Entregável
1	Criar `TECH-HUMAN/techhuman-website` público
2	Consolidar `docs.techhuman.com.br` como camada integral via `TECH-HUMAN/techhuman-docs`
3	Evoluir `playbook.techhuman.com.br` como experiência guiada via `TECH-HUMAN/techhuman-playbook`
4	Publicar home institucional estática com Next.js + shadcn
5	Configurar GitHub Pages, Vercel Git integration ou Netlify Git conforme necessidade de runtime
6	Criar páginas por oferta: Trust Score, AI-First Blueprint, Governança Contínua
7	Criar camada de conteúdo: artigos, FAQs, one-pagers e landing pages
8	Adicionar analytics privacy-friendly, formulários e CRM
9	Repetir padrão para Trustyu, NeedyU.ai e demais marcas aprovadas