Contexto técnico

Modelei o produto como um monólito modular bem delimitado: uma API NestJS expõe o domínio em casos de uso, com JWT + RBAC e validação de entrada consistente; o front é Next.js com React, consumindo a API com contratos tipados e formulários/validação guiados por Zod, e TanStack Query para orquestrar estado de servidor. Persistência com Prisma e PostgreSQL em esquema compartilhado: troquei o custo operacional de database-per-tenant pela exigência de disciplina de engenharia em todo acesso (use cases + invariantes + constraints). O candidato não é “um perfil por empresa”: tratei 1 usuário → 1 perfil global, o que simplifica UX e consistência, mas exige regras claras de anonimização (estilo LGPD) sem destruir o rastro operacional do processo seletivo.

Para multi-tenant, fixei o tenant nas rotas B2B a partir do próprio token (evitando trust em header solto) e propaguei o contexto em armazenamento assíncrono local; em paralelo, estendi o client Prisma para aplicar filtro/injeção de tenantId em agregados sensíveis, como rede de segurança quando algum caminho esquecer o filtro; um trade-off consciente: mais “RLS em aplicação” do que apenas “confio no controller”. Para mídia, padronizei URLs pré-assinadas (upload direto do browser para armazenamento compatível com S3) e persistência só da chave do objeto, reduzindo superfície na API e custo de egress interno. E-mail transacional foi tratado como melhor esforço: falha de envio não deve reverter contratação/rejeição/candidatura; o domínio ganha resiliência percebida, com risco gerido por observabilidade e políticas de retentativa no entorno.

Desafios de engenharia (como e por quê)

• Dois eixos de workflow na candidatura: separei movimento de status macro (ex.: contratado, rejeitado) do avanço de etapas configuráveis (questionário, upload, link de entrevista), cada um com histórico; isso evita misturar “estado do negócio” com “UX do processo” e mantém evolução do produto menos acoplada.
• Pipeline versionado por vaga: clonei template do tenant para estágios da vaga no momento da criação, congelando o desenho após publicação; o trade-off é não retroagir mudanças em vagas antigas, em troca de previsibilidade para recrutadores e candidatos.
• Onboarding B2B sem senha definida por terceiros: convites com token opaco entregue fora da banda, persistindo apenas digest no banco; se o envio falhar, revogo o convite para não deixar token “ativo” sem entrega, uma decisão de segurança que fecha uma classe comum de inconsistência operacional.
• Sourcing por e-mail como máquina de decisão: o mesmo endpoint distingue convite de cadastro, envio de link público da vaga e curto-circuito quando já existe candidatura; isso reduz suporte e estados fantasmas no pipeline.
• Exposição pública controlada: site por empresa e marketplace agregado reutilizam endpoints públicos com regras de visibilidade de vaga (rascunho não vaza), mantendo a mesma base de domínio da área logada.
• Operação e CI: health com liveness sem dependências e readiness checando PostgreSQL; pipeline de integração separando API (testes + build + geração Prisma) e Web (checagem + build), alinhado a escala de time e falhas localizadas.

Contexto técnico

Eu tratei o projeto como dois deployables no mesmo repositório: uma API em Hono e uma loja em Astro, compartilhando um contrato HTTP explícito. No backend, Zod não só valida entrada e saída como alimenta a especificação OpenAPI, o que reduz divergência entre documentação e comportamento real e barateia evoluções de cliente (web ou ferramentas de teste).

Escolhi Bun como runtime pela simplicidade de desenvolvimento e build, e Hono pela composição de middlewares (CORS com credenciais, cabeçalhos de segurança, limitação de taxa global e mais restrita em autenticação) sem carregar um framework monolítico. PostgreSQL com Prisma concentra o modelo relacional (usuário, carrinho, pedido, tokens de refresh, catálogo); Redis aparece como cache de revogação de access token e como backbone de filas para e-mail e rotinas como carrinho abandonado. Para mídia de produto, o fluxo de admin passa por URLs pré-assinadas em armazenamento objeto compatível com S3, o que tira upload pesado do processo da API e mantém o bucket como fronteira clara de infraestrutura.

No front, Astro faz o trabalho de SSR nas vitrines e listagens (SEO e primeiro paint estável) e delega interatividade a Preact onde o estado muda no browser; Tailwind centraliza o design system. O trade-off consciente foi cookies HttpOnly em vez de guardar tokens em armazenamento acessível ao script da página: a web precisa sempre enviar credentials, repassar Cookie no SSR e tratar 401 com fluxo de refresh centralizado. Isso aumenta um pouco a complexidade de integração, mas alinha segurança e modelo de sessão com o navegador moderno.

Desafios de engenharia (como e por quê)

• Pedido como unidade atômica: consolidei criação de pedido em transação de banco: carregamento de produtos e opções, validação de variante, snapshot de preço e imagem nos itens, decremento de estoque só quando há quantidade suficiente (updateMany condicional) e ajuste de flags de disponibilidade, com esvaziamento do carrinho quando a origem é o carrinho ativo. Isso evita estado inconsistente sob concorrência moderada sem espalhar locks na aplicação.

• Sessão com revogação real: além de refresh token persistido e rotação lógica no login, usei blocklist em Redis por JTI do access token até o TTL natural e versão de sessão após troca de senha para invalidar tokens antigos. O objetivo é que logout e incidentes de credencial tenham efeito antes do access expirar sozinho.

• Integração Astro e API sem “dois mundos”: no SSR, as chamadas repassam o header de cookie para o backend; no cliente, um cliente HTTP único aplica credentials: include, trata erros de validação de forma uniforme e serializa refresh para não disparar corridas de renovação. Isso mantém a mesma semântica de sessão em páginas estáticas e ilhas interativas.

• Operação e observabilidade desde o ambiente local: subi PostgreSQL, Redis, fila de e-mail para desenvolvimento, Prometheus e Grafana via Compose, com emulador de serviços de nuvem para o fluxo de armazenamento. Na API, há verificação de dependências na subida, retry com backoff na conexão com o banco e endpoint de métricas para acompanhar saúde e throughput em ambientes próximos de produção.

• Painel admin e uploads: o gate de /admin usa uma chamada autorizada à listagem restrita de usuários; uploads passam pelo fluxo pré-assinado para não expor segredos de infraestrutura ao browser e para desacoplar largura de banda da compute da API.

• Limite conhecido tratado como fronteira de produto: o checkout na web hoje fecha o fluxo na camada de apresentação enquanto a API já implementa POST /orders com as regras de estoque. Eu documentei essa separação de propósito: prioriza contrato e domínio estáveis antes de acoplar o botão final do wizard ao fechamento, o que evita “meio checkout” que quebra pedido sob carga.

Problema

Eu precisava disponibilizar conhecimento interno em formato de conversa, mas sem abrir mão de privacidade e previsibilidade de custo, evitando dependência de APIs externas. O conteúdo estava espalhado em textos e registros estruturados, o que exigia uma forma consistente de transformar isso em contexto recuperável. Além disso, era importante reduzir respostas “inventadas” e conseguir justificar a resposta com referências ao material usado. Por fim, eu precisava de uma experiência de uso responsiva, com resposta incremental, sem travar a interface em consultas mais longas.

Solução

Eu implementei um pipeline de ingestão que varre documentos, normaliza formatos comuns e divide o conteúdo em trechos com sobreposição para melhorar a recuperação. Esses trechos são vetorizados por um modelo local de embeddings e persistidos em um banco vetorial, permitindo busca por similaridade com score.

No runtime do chat, eu aplico filtros por distância e limites de contexto para controlar ruído, além de deduplicar trechos repetidos antes de montar o prompt. A resposta é gerada por um modelo local e entregue via streaming em eventos, com cancelamento automático quando o cliente desconecta para evitar trabalho desnecessário.

Destaques

• Pipeline de ingestão com normalização e chunking com sobreposição
• Embeddings locais + banco vetorial para busca por similaridade com score
• Controles de qualidade: filtros, limites de contexto e deduplicação no retrieval
• Resposta com streaming e cancelamento em desconexão para evitar desperdício

Impacto

Na prática, o sistema passou a responder com base em evidências do conteúdo indexado, reduzindo alucinações e tornando a saída mais auditável por meio de fontes. A separação entre ingestão, retrieval e geração deixou ajustes de qualidade e desempenho concentrados em parâmetros, sem reescrever o fluxo principal. O streaming melhorou a latência percebida e a rotina de abort em desconexões evitou desperdício de CPU e filas no modelo local. O resultado foi uma base conversacional que escala por volume de documentos com reindexação repetível e manutenção simples, já que cada integração crítica fica isolada e testável por comportamento.