DEV Community: Carolina Gonçalves

Construindo um hub de notificações desacoplado com NestJS, Nx e Design Patterns

Carolina Gonçalves — Tue, 03 Feb 2026 14:52:27 +0000

Nota para desenvolvedores: Se você prefere ir direto ao código, o repositório completo com a implementação desta arquitetura está disponível aqui: github.com/carol8fml/nexus-notification-hub.

Olá, pessoal! 🤟🏾

Há alguns anos, recebi a tarefa de avaliar serviços externos para envio transacional de e-mails. Na época, já utilizávamos o SendGrid em quatro aplicações web e surgiu a necessidade de expandir essa solução para o aplicativo principal da empresa.

A previsão era um acréscimo de 250.000 envios por mês. A partir disso, analisei mais de 10 provedores e encontrei alternativas equivalentes e mais baratas. No entanto, o verdadeiro custo só apareceu no final: a mão de obra dos desenvolvedores.

Substituir o serviço nas aplicações já integradas ao SendGrid exigiria um esforço enorme, porque a lógica estava fortemente acoplada à implementação do provedor, tanto nos projetos com abordagem funcional quanto naqueles estruturados com princípios próximos da Clean Architecture.

Depois de alinhar com o time, ficou claro que essa mudança levaria meses para entrar nas Sprints, já que seria necessário deslocar desenvolvedores das entregas principais exclusivamente para refatoração.

No fim, continuamos com a ferramenta, mesmo não sendo a opção mais econômica. Na prática, a empresa acabou ficando refém do serviço por uma limitação técnica.

Recentemente, durante meus estudos em Arquitetura de Software, decidi ir além do consumo de teoria e aplicar esse conhecimento para resolver problemas reais que enfrentei ao longo da carreira. Foi dessa experiência que surgiu o Nexus Notification Hub: uma POC criada para validar uma arquitetura orientada ao baixo acoplamento, utilizando uma stack robusta (NestJS, Nx) e padrões clássicos, principalmente o Adapter Pattern.

Se tivéssemos essa estrutura na época, o cenário seria outro:

Criar apenas um novo arquivo (o Adapter).
Alterar uma linha de configuração.
Resolver o problema.

A seguir, mostro como implementei essa solução na prática, permitindo trocar o SendGrid pela AWS ou qualquer outro provedor em minutos, e não meses.

A Arquitetura: Adapter Pattern na Prática

A solução se baseia em dois padrões clássicos trabalhando em conjunto: o Adapter Pattern e o Factory Pattern.

O Adapter foi utilizado para impedir que a regra de negócio conhecesse detalhes de provedores externos. Já o Factory centraliza a escolha do provedor e evita condicionais espalhadas pela aplicação.

A ideia é ter uma camada que impede a lógica de negócio de depender de implementações específicas de serviços de e-mail.

1. O Contrato: A Interface `NotificationProvider`

Tudo começa com uma interface que define o contrato mínimo que qualquer provedor de notificação precisa seguir:

export interface NotificationProvider {
  send(to: string, content: string): Promise<void>;
}

Essa interface define o contrato central da arquitetura. Independentemente de estarmos usando SendGrid, AWS SES, Mailtrap ou qualquer outro serviço, todos precisam implementar o método send com essa assinatura.

Na prática: O restante do código (Controller, Factory, Use Cases) não precisa saber qual serviço está sendo utilizado. Ele trabalha apenas com esse contrato.

2. A Implementação: `MailtrapProvider` como Adapter

Cada serviço de e-mail possui sua própria forma de integração (API REST, SDK proprietário, SMTP, etc.). O Adapter Pattern resolve isso criando uma tradução entre a interface comum e a implementação específica.

Veja como ficou o adapter do Mailtrap:

@Injectable()
export class MailtrapProvider implements NotificationProvider {
  private transporter: nodemailer.Transporter;

  constructor(private configService: ConfigService) {
    this.transporter = nodemailer.createTransport({
      host: this.configService.get<string>('MAILTRAP_HOST'),
      port: this.configService.get<number>('MAILTRAP_PORT'),
      auth: {
        user: this.configService.get<string>('MAILTRAP_USER'),
        pass: this.configService.get<string>('MAILTRAP_PASS'),
      },
    });
  }

  async send(to: string, content: string): Promise<void> {
    await this.transporter.sendMail({
      from: 'noreply@nexus.com',
      to,
      subject: 'Notification from Nexus',
      text: content,
      html: `<p>${content}</p>`,
    });
  }
}

Toda a complexidade do nodemailer e da configuração do Mailtrap permanece encapsulada nessa implementação. Se surgir a necessidade de trocar para SendGrid, basta criar um SendGridProvider implementando a mesma interface. O restante do sistema continua funcionando sem alterações.

3. O Factory: Centralizando a Decisão

O Factory Pattern centraliza a lógica de escolha do provedor, evitando if/else espalhados pelo código:

@Injectable()
export class NotificationFactory {
  constructor(private mailtrapProvider: MailtrapProvider) {}

  getProvider(type: 'email'): NotificationProvider {
    switch (type) {
      case 'email':
        return this.mailtrapProvider;
      default:
        throw new Error(`Unsupported notification type: ${type}`);
    }
  }
}

O Factory recebe os providers via Injeção de Dependência do NestJS. Para adicionar um novo provider, basta:

Criar a classe do Adapter.
Injetar no Factory.
Adicionar um case no switch.

4. O Controller: Trabalhando com Abstrações

No Controller, o desacoplamento fica evidente. Ele não precisa conhecer Mailtrap, SendGrid ou qualquer outro serviço:

@Controller('api/notifications')
export class NotificationsController {
  constructor(private notificationFactory: NotificationFactory) {}

  @Post()
  async sendNotification(@Body() dto: SendNotificationDto) {
    const provider = this.notificationFactory.getProvider(dto.type);

    await provider.send(dto.destination, dto.content);

    return {
      success: true,
      message: `Notification sent via ${dto.type}`,
    };
  }
}

Nota arquitetural: Neste exemplo didático, o cliente define o tipo de notificação via DTO. Em um cenário real, essa decisão poderia ser tomada automaticamente pelo backend (considerando regras de failover, custo ou disponibilidade), mantendo o cliente agnóstico quanto ao provedor.

5. A Cola: Injeção de Dependência (NestJS)

O NestJS gerencia o ciclo de vida e a injeção dessas classes através do módulo:

@Module({
  controllers: [NotificationsController],
  providers: [NotificationFactory, MailtrapProvider],
})
export class NotificationsModule {}

Vendo na Prática

Abaixo, uma demonstração do fluxo completo: o frontend (React) enviando uma requisição para o backend (NestJS), que utiliza o Adapter do Mailtrap para realizar o envio.

Escalabilidade na Prática

Supondo que seja necessário adicionar o SendGrid, quantos arquivos precisam ser alterados?

Criar o Adapter (sendgrid.provider.ts) implementando NotificationProvider.
Atualizar o Factory, adicionando o novo provider.
Atualizar o Módulo, registrando o provider.

Resultado:
O Controller permanece intacto.
A lógica de negócio permanece intacta.
Os testes existentes continuam válidos.

Bônus: DTOs Compartilhados (Nx Monorepo)

Como estamos utilizando Nx, aproveitei para compartilhar os DTOs entre Frontend e Backend, garantindo consistência contratual entre as aplicações.

export class SendNotificationDto {
  @IsEnum(['email'])
  @IsNotEmpty()
  type!: 'email';

  @IsString()
  @IsNotEmpty()
  destination!: string;

  // ... outros campos
}

Se o contrato for alterado, o build do Frontend e do Backend falha imediatamente, evitando inconsistências silenciosas de integração.

Conclusão: A Liberdade da Abstração

O Nexus Notification Hub surgiu como uma resposta técnica para um impasse de negócio que vivi no passado. Um problema que antes exigiria meses de refatoração passa a ser resolvido em poucas horas.

Mais do que aplicar padrões ou frameworks, a principal lição foi perceber como decisões arquiteturais influenciam diretamente a capacidade de adaptação de um sistema.

Naquela época, ficamos reféns do SendGrid não porque ele era insubstituível, mas porque o código estava estruturado dessa forma. Com uma arquitetura baseada em abstrações, a decisão volta para as mãos do time e do negócio.

Por outro lado, esse tipo de abordagem também adiciona complexidade e só faz sentido quando existe uma possibilidade real de troca de fornecedor ou crescimento do sistema. Caso contrário, existe o risco de adicionar complexidade sem trazer ganho real para o sistema.

Se hoje surgisse novamente a necessidade de escalar para 250.000 envios mensais trocando de fornecedor, a resposta provavelmente não seria mais "não dá". Seria algo próximo de:

"Ok, me dá uma tarde para implementar o novo Adapter."

Hoje entendo que essa diferença está menos ligada a escrever código e mais a construir soluções que conseguem evoluir com o tempo.

Código Fonte

O projeto completo, incluindo a configuração do Monorepo Nx, o frontend em React e todos os testes, está disponível no GitHub.

github.com/carol8fml/nexus-notification-hub. 🤟🏾

Como criar um menu hambúrguer acessível com a "armadilha de foco" (Focus Trap)

Carolina Gonçalves — Sun, 12 Oct 2025 15:50:39 +0000

Olá, pessoal!

Vamos direto ao ponto: seu menu hambúrguer provavelmente está quebrado para usuários de leitores de tela.

Eu descobri isso da pior maneira. Em 2022, enquanto desenvolvia o site de um evento sobre acessibilidade digital, o designer responsável me fez a seguinte pergunta:

“Você já testou o layout com leitor de tela? O evento é sobre acessibilidade, precisamos dar o exemplo...”

Fui testar no mobile e encontrei o problema: o leitor de tela lia todos os links de um menu visualmente fechado. A pessoa ouvia “Contato, link”, pressionava o "Enter" e nada acontecia. Era um link fantasma.

Tomei aquele "puxão de orelha" e aprendi uma lição: a experiência do usuário tem que ser a mesma para todos, esconder um menu só com CSS não resolve o problema. Era preciso gerenciar o estado (aberto/fechado) e, principalmente, o foco do teclado.

E a solução que encontrei foi implementar a "Focus Trap" (armadilha de foco) usando JavaScript e atributos ARIA. Vou te mostrar o passo a passo:

(Para quem já quiser ver na prática, acesse o resultado final e o projeto completo no CodeSandbox.)

A estrutura HTML do menu

Tudo começa com um HTML semântico dividido em duas partes: o botão que dispara a ação e o painel que guarda os links.

1. O botão de ativação

É onde o usuário clica para abrir o menu. E a dúvida mais comum nessa parte é: por que o leitor de tela precisa ouvir “botão” e não “link”?

Pense assim:

Um link é como uma porta: leva o usuário pra outro lugar.
Um botão é como um interruptor: executa uma ação onde ele já está.

Se o leitor de tela anuncia “Menu, link”, a experiência fica confusa. Por isso usamos role="button", que comunica ao leitor de tela que o elemento executa uma ação local.

Agora, talvez você se pergunte: por que usar <a> e não <button> de vez?

A resposta é simples: a tag <a> com href serve como plano B. Se o JavaScript falhar (erro, conexão ruim, bloqueio por extensão), o href ainda leva o usuário até a seção do menu. Um <button> puro não funcionaria.

<a 
  id="pageHeaderHamburgerIcon"
  href="#pageContainerMainNavMobile"
  role="button"
  aria-controls="navigation"
  aria-expanded="false"
  aria-label="Abrir menu de navegação"
  title="Abrir menu de navegação">
  ☰<span class="sr-only">Abrir menu</span>
</a>

Resumindo a função de cada um:

role="button": Ajusta a expectativa do leitor de tela, anunciando “botão”.
href: Garante o fallback se o JavaScript falhar.
id: Identifica o botão para que o JavaScript possa manipulá-lo.
aria-controls: Conecta o botão ao menu que ele controla.
aria-expanded: Indica o estado atual, false (fechado) ou true (aberto).
aria-label e title: Garantem que a função do botão seja sempre clara. Quando o menu está aberto, o JavaScript atualiza o texto para "Fechar menu", e vice-versa, mantendo o usuário sempre informado sobre a próxima ação.

2. O painel de navegação

É o bloco que guarda os links e que aparece e desaparece.

<nav id="pageContainerMainNavMobile">
  <h2 class="sr-only" id="mainNavigationLabelMobile">Menu Principal</h2>
  <ul id="mainNavigationMobile">
    <li><a href="#" title="Saiba mais sobre o festival">Sobre</a></li>
    <li><a href="#" title="Veja quem realiza o evento">Realização</a></li>
    <li><a href="#" title="Entre em contato conosco">Contato</a></li>
  </ul>
</nav>

O essencial aqui:

<nav> com id: A tag <nav> é a correta para um bloco de links principal. O id é o "alvo" do aria-controls do botão.
<h2 class="sr-only">: Este título invisível é uma prática recomendada, pois o leitor de tela o utiliza para dizer ao usuário onde ele está antes de listar as opções de navegação.

Onde a mágica acontece: o JavaScript

O JavaScript é o nosso mestre da bateria: ele dá o ritmo, controla o abre/fecha, atualiza os atributos ARIA e, o mais importante, gerencia o foco do teclado.

Vamos ver a lógica passo a passo:

1. Preparando o terreno

Antes de qualquer ação, nosso script precisa "conhecer" os elementos do HTML. Por isso, começamos selecionando o botão, o menu e o último link em variáveis para usarmos depois.

document.addEventListener('DOMContentLoaded', function() {
  const keys = {
    tab: 9,
    esc: 27,
  };

  const menuButton = document.getElementById('pageHeaderHamburgerIcon');
  const navMenu = document.getElementById('pageContainerMainNavMobile');
  const menuLinks = navMenu.querySelectorAll('a');
  const lastLink = menuLinks[menuLinks.length - 1];

  document.body.classList.add('js');

2. As funções `openMenu` e `closeMenu`

Estas são as duas funções que controlam o estado do menu, atualizando os atributos e controlando a visibilidade.

  const openMenu = () => {
    // Atualiza os atributos para o estado "Aberto"
    menuButton.setAttribute('aria-expanded', 'true');
    menuButton.setAttribute('aria-label', 'Fechar menu de navegação');
    menuButton.setAttribute('title', 'Fechar menu de navegação');

    // Troca o ícone e mostra o menu
    menuButton.innerHTML = '\u00D7<span class="sr-only">Fechar menu</span>';
    navMenu.style.display = 'block';
  };

  const closeMenu = () => {
    // Atualiza os atributos para o estado "Fechado"
    menuButton.setAttribute('aria-expanded', 'false');
    menuButton.setAttribute('aria-label', 'Abrir menu de navegação');
    menuButton.setAttribute('title', 'Abrir menu de navegação');

    // Troca o ícone e esconde o menu
    menuButton.innerHTML = '\u2630<span class="sr-only">Abrir menu</span>';
    navMenu.style.display = 'none';
  };

3. O gatilho e a armadilha de foco

Agora conectamos as funções aos eventos do usuário (clique e teclado) para controlar o foco.

Primeiro, fazemos o menu fechar automaticamente ao clicar em um link:

  // Fecha o menu ao clicar em um dos seus links
  menuLinks.forEach(link => {
    link.addEventListener('click', () => {
      closeMenu();
    });
  });

Em seguida, configuramos o gatilho do menu e a navegação por teclado:

  // Gatilho do clique no botão
  menuButton.addEventListener('click', (e) => {
    e.preventDefault();
    const isExpanded = menuButton.getAttribute('aria-expanded') === 'true';
    isExpanded ? closeMenu() : openMenu();
  });

  // Tecla ESC fecha o menu
  navMenu.querySelectorAll('*').forEach(el => {
    el.addEventListener('keydown', (e) => {
      if (e.keyCode === keys.esc) {
        closeMenu();
        menuButton.focus();
      }
    });
  });

  // Tab no último item volta para o botão (o loop do foco)
  lastLink.addEventListener('keydown', (e) => {
    if (e.keyCode === keys.tab && !e.shiftKey) { 
      e.preventDefault();
      menuButton.focus();
    }
  });

  // Shift+Tab no botão (com menu aberto) vai para o último item
  menuButton.addEventListener('keydown', (e) => {
    const isExpanded = menuButton.getAttribute('aria-expanded') === 'true';
    if (isExpanded && e.keyCode === keys.tab && e.shiftKey) {
      e.preventDefault();
      lastLink.focus();
    }
  });
});

Resultado

O menu agora é funcional para todos, visível e navegável por teclado. Teste com leitores de tela (NVDA, VoiceOver) e navegação por teclado (Tab, Shift+Tab, Esc).

Demonstração do menu acessível com a 'Armadilha de Foco' em funcionamento.

Resultado final: Acesse a demo
Projeto completo: Acesse o código no CodeSandbox

Conclusão

Uma coisa que eu sempre falo: só podemos dizer que um site seguiu as boas práticas quando ele é acessível ao maior número de pessoas possível.

Da próxima vez que você for codificar um menu, um modal ou um simples botão, faça aquela pergunta: "Eu testei com leitor de tela?".

A diferença na experiência do usuário é enorme.

Como defer me ajudou a equilibrar performance e acessibilidade

Carolina Gonçalves — Thu, 07 Aug 2025 20:19:43 +0000

Olá, pessoal!

Quero compartilhar uma solução simples que resolveu um dilema comum: como garantir acessibilidade sem prejudicar a performance?

Na empresa onde trabalho, é comercializado um plugin de acessibilidade. E como é padrão no desenvolvimento web, o script dele era inserido no final da página dos clientes, o famoso joga no final do <body>.

Mas aí surgiu um problema.

Usuários de leitores de tela precisavam percorrer todo o conteúdo da página até finalmente encontrarem o plugin. E como esses leitores seguem a ordem do DOM, o plugin só era lido lá no fim da navegação, o que tornava a experiência cansativa.

Alguns clientes, tentando melhorar a acessibilidade, moveram o script para o <head> do HTML. Isso de fato resolveu a ordem de leitura, mas acabou gerando outro problema: o site passou a demorar mais para carregar, já que o script bloqueava o carregamento da página.

Foi aí que, depois de alguns testes, encontrei uma solução simples e eficaz que pode ser útil para vários cenários parecidos: o atributo defer.

O que é o `defer`?

defer é um atributo HTML que você coloca na tag <script> para otimizar o desempenho do carregamento da página.

Na prática, ele diz ao navegador: "Pode baixar esse script agora, mas só executa depois que o HTML estiver todo carregado."

Ou seja:

O script é baixado em paralelo com o HTML;
Mas só é executado no final, quando o DOM já estiver pronto.

Exemplo:

<script defer src="script.js"></script>

Assim, você pode colocar seus scripts no <head> sem se preocupar com bloqueios ou com a ordem de carregamento do DOM.

Sem `defer`, o que acontece?

<script src="script.js"></script>

Se estiver no <head>, o navegador pausa o carregamento do HTML para baixar e executar o script. Isso pode prejudicar a performance, especialmente em conexões mais lentas, e causar a sensação de que o site está travando.

Com `defer`, o fluxo muda:

1. O HTML carrega normalmente;
2. O script é baixado ao mesmo tempo, em segundo plano;
3. Só roda depois que o HTML estiver 100% carregado.

Ou seja: você não precisa mais se preocupar com eventos como DOMContentLoaded ou ficar jogando script pro fim do HTML só pra evitar bloqueio.

`defer` vs `<body>`

Colocar o script no final do <body> também funciona (é o clássico, né?), mas se você tem múltiplos scripts ou quiser centralizar suas importações, o defer é uma ótima solução.

Com ele, você mantém os scripts no <head>, deixando o HTML mais limpo e o carregamento mais previsível.

Resumo

Onde e como?	Comportamento
`<script>` no `<head>`	❌ Bloqueia o carregamento da página
`<script defer>` no `<head>`	✅ Baixa em paralelo e executa depois do HTML
`<script>` no final do `<body>`	✅ Executa após o HTML, mas exige mais atenção com organização

Conclusão

Se você quer um site mais rápido e organizado, o defer é uma escolha moderna e eficiente para manipular o DOM com segurança.

Às vezes, a diferença entre um site lento e uma experiência fluida está na palavrinha de cinco letras.

DEV Community: Carolina Gonçalves

Construindo um hub de notificações desacoplado com NestJS, Nx e Design Patterns

A Arquitetura: Adapter Pattern na Prática

1. O Contrato: A Interface NotificationProvider

2. A Implementação: MailtrapProvider como Adapter

3. O Factory: Centralizando a Decisão

4. O Controller: Trabalhando com Abstrações

5. A Cola: Injeção de Dependência (NestJS)

Vendo na Prática

Escalabilidade na Prática

Bônus: DTOs Compartilhados (Nx Monorepo)

Conclusão: A Liberdade da Abstração

Código Fonte

Como criar um menu hambúrguer acessível com a "armadilha de foco" (Focus Trap)

Olá, pessoal!

A estrutura HTML do menu

1. O botão de ativação

2. O painel de navegação

Onde a mágica acontece: o JavaScript

1. Preparando o terreno

2. As funções openMenu e closeMenu

3. O gatilho e a armadilha de foco

Resultado

Conclusão

Como defer me ajudou a equilibrar performance e acessibilidade

Olá, pessoal!

O que é o defer?

Sem defer, o que acontece?

Com defer, o fluxo muda:

defer vs <body>

Resumo

Conclusão

1. O Contrato: A Interface `NotificationProvider`

2. A Implementação: `MailtrapProvider` como Adapter

2. As funções `openMenu` e `closeMenu`

O que é o `defer`?

Sem `defer`, o que acontece?

Com `defer`, o fluxo muda:

`defer` vs `<body>`