ByIA — Arquitetura Detalhada

Guia interativo e critico dos 3 projetos que formam a plataforma de atendimento médico via WhatsApp.

Clique em qualquer card para ver a explicacao completa
3
Projetos
11
Agentes IA
12+
Etapas Pipeline
21
Módulos CRM
39
Campos TenantConfig
59
Migrations
202
Testes
📦 Os 3 Projetos
Clique para ver responsabilidades, escopo e detalhes de cada um.
→
🤖

ByIA-API-Agents

Backend Python que processa mensagens WhatsApp via agentes IA.

Python 3.12 PydanticAI ARQ
→
💻

CRM-BANCO

Frontend Next.js para a equipe médica gerenciar pacientes, consultas e NPS.

Next.js 15 React 19 Tailwind v4
→
📖

Playbook-Gerenciador

Documentacao de negocio, vendas, precificacao e operações (não e código).

Markdown HTML/JS
🧠 Tecnologias-chave (clique para entender)
Todo termo técnico explicado em linguagem clara.
PydanticAI
Framework de agentes IA tipado
FastAPI
Framework web Python async
ARQ
Fila de jobs com Redis
asyncpg
Driver PostgreSQL async
Redis
Cache + Queue + Locks
APScheduler
Jobs agendados (cron-like)
Langfuse
Observabilidade de LLMs
Tenacity
Retries com backoff
Supabase Vault
Secrets encriptados per-tenant
Chatwoot
Plataforma open-source de atendimento
Next.js 15
Framework React full-stack
Server Actions
Funções server-side em Next.js
shadcn/ui
Componentes copy-paste
Zod
Validação TypeScript-first
RLS (Row-Level Security)
Segurança por linha no Postgres
TTS
Text-to-Speech (áudio)
STT / Whisper
Speech-to-Text
Jinja2
Template engine para prompts
🔌 Fluxo de Dados Principal
Clique nas caixas coloridas para ver detalhes.
📱 PacienteWhatsApp
→
💬 ChatwootBroker de Mensagens
→
🤖 byia-apiPOST /webhook/chatwoot
↓
⚡ RedisDebounce + Lock + Dedup
→
⚙ ARQ Workerprocess_message async
→
🧠 SupervisorRouter PydanticAI
↓
🗃 SupabaseDual-write + Vault
→
🎤 TTSGoogle / ElevenLabs
→
💬 Chatwoot APIsendMessage (retry 3x)
Fluxo Paralelo: Equipe via CRM
💻 CRM-BANCONext.js Server Actions
↔
🗃 Banco Compartilhadobyiaminiapp schema + RLS
→
💬 ChatwootNotificações diretas
⚙ Pipeline de Processamento (clique em cada etapa)
O pipeline real tem mais que 12 passos — comunicação interna simplifica para 12, mas analisando o código são ~18 sub-etapas sequenciais.
1
Normalizacao de Telefone
Padroniza +55DDD para o banco
2
Buffer + Debounce + Lock
Agrupa mensagens rapidas (Redis)
3
Load TenantDeps (paralelo)
Config, prompts, lead, chat, enums
4
UPSERT Lead + Chat
Cria/atualiza registros (idempotente)
4b
Handoff Guards (3 níveis)
IA silencia durante atendimento humano
5
Auto-Origin Detection
Detecta vindo de Meta Ads / patterns
5b
Media Processing
Whisper STT, Vision, PDF
6
Histórico + Memórias
Contexto + semantic memory
7
Intent Bypass (Transferência)
Atalho sem LLM se pedido explicito
8
Phase Resolution
Máquina de estado: fase da conversa
9
Supervisor Agent (LLM)
Tool registration + roteamento
10
supervisor.run() + Exceções
UsageLimit / Timeout handling
11
Sanitizacao 6 Camadas
Anti-leak: tools, prices, diagnosis
12
Context Engine (LLM)
Atualiza memória condensada
13
Save + Fire-and-forget Jobs
DB + ARQ (memórias, summary)
14
TTS Decision + Síntese
Smart filter + fallback provider
15
Send (Circuit Breaker)
Chatwoot API com retry exponencial
16
Dedup Guard
Absorve resposta identica <30s
17
Enqueue Followup
Avaliação 20min depois (async)
18
Straggler Re-processing
Mensagens que chegaram durante
🤖 11 Agentes IA (clique em cada agente)
Cada agente tem prompt próprio versionado em prompt_versions, podendo usar LLM diferente.
🎯
Supervisor
Router dinâmico
❓
FAQ
Duvidas da clínica
📋
Qualifier
Coleta lead data
📅
Scheduler
Agendamento
💰
Billing
ASAAS
👤
CRM
Updates de dados
⭐
NPS
Pesquisa pós-consulta
👥
Transfer
Handoff humano
🧠
Context Engine
Sumariza histórico
🔎
Followup Evaluator
Merece followup?
✍
Followup Generator
Gera mensagem JIT
🔗 Integração entre Projetos
Como os 3 sistemas conversam — ou não.
→
🗃

Banco Compartilhado

Principal ponto de integração: mesmo schema Supabase.

→
💬

Chatwoot como Bus

Mensagens fluem apenas atraves do Chatwoot — não ha API direta.

→
🏢

Multi-Tenancy

3 tabelas (organizations, accounts, user_accounts) com RLS.

→
🔒

Secrets per-tenant

Vault do Supabase armazena API keys encriptadas por organizacao.

→
✍

Sync de Prompts

Prompts .md em repo separado, sincronizados ao banco via GitHub Actions.

→
📞

Normalizacao de Telefone

CRM e Chatwoot tem formatos diferentes — exige conversão constante.

💡 Análise Critica — O que Eu Mudaria
Uma avaliação honesta de decisões arquiteturais que podem causar problemas no medio prazo.
Alta

Dual-write legacy (n8n_historico)

→

Gravar em duas tabelas paralelas cria divergencia sutil ao longo do tempo. O custo de manter isso "so para compatibilidade" tende ao infinito.

Alta

Integração CRM ↔ byia-api via banco compartilhado

→

Acoplamento forte por schema. Qualquer mudança em uma tabela pode quebrar o outro sistema sem aviso. Falta contrato explicito.

Alta

Pipeline de 18 sub-etapas como função única

→

O handle_message() concentra toda a logica. Dificil testar, debugar e evoluir. Cada passo deveria ser um step isolado em um workflow engine ou state machine explicita.

Media

Sanitizador de 6 camadas baseado em regex

→

Tratar sintomas em vez de causas. Se o LLM vaza tool calls, a solucao e estruturar saida (Pydantic output model) em vez de sanitizar texto depois.

Media

Prompts em repo separado sincronizados via Actions

→

Prompts são código. Versionar em outro repo com sync por GitHub Actions adiciona complexidade sem ganho claro sobre versionar dentro do byia-api.

Media

39 campos em uma tabela tenant_configs

→

God table. Mistura feature flags, credenciais, prompts, config de TTS, NPS, reminders. Deveria ser dividida (feature_flags, integrations, messaging_config).

Media

Cliente Supabase legacy coexistindo com novo padrão

→

CRM tem dois padrões ativos: client-side (supabaseByiaminiapp) e server actions. Migração parcial cria inconsistencia — ou termina ou remove.

Baixa

Misturar portugues e ingles em identificadores

→

contatos, consultas, pacientes ao lado de account_id, organization_id. Padronizar (ingles para código, portugues so para UI).

Baixa

eslint: ignoreDuringBuilds: true

→

Desabilitar lint no build esconde problemas. O próprio CLAUDE.md lista como "TODO avaliar" — já passou da hora.

Alta

Zero API tipada entre CRM e byia-api

→

CRM chama BYIA_API_URL para invalidar cache. Deveria haver um contrato OpenAPI/tRPC entre os dois para evitar quebras silenciosas.

Media

Tratamento de erro via texto ("TRANSFER_OK", "PROPOSTA_PENDENTE")

→

Tools retornam strings magicas para controle de fluxo. Deveriam retornar objetos tipados com status discriminado (union types).

Positivo

O que esta bem feito

→

Apesar das criticas — várias decisões são solidas. Ver o que preservar.