A arquitetura do Markmedi: monólito modular, DDD e eventos de domínio
33 contextos delimitados, Actions, máquinas de estado em enum, ports and adapters e eventos depois do commit: como organizei um SaaS grande para ser mantido por uma pessoa.
O Markmedi começou como agenda online e hoje tem prontuário, telemedicina com transcrição, receitas e atestados com assinatura digital, CRM, automações, campanhas de e-mail, reputação no Google, financeiro com faturamento de convênios (TISS), estoque e portal do paciente. Quem mantém tudo isso sou eu. A arquitetura precisa responder a uma pergunta prática: daqui a seis meses, quando eu abrir um módulo que não toco há tempo, vou conseguir mudar uma regra sem quebrar outra?
A resposta que encontrei é um monólito modular em Laravel, organizado por domínio, com regras de negócio explícitas e comunicação entre módulos por eventos.
Por que um monólito
Microsserviços resolvem problemas de organização de times grandes e de escala independente. Eu não tenho nenhum dos dois. Teria todos os custos: deploy coordenado, consistência eventual entre bancos, rastreamento distribuído, contratos de API versionados entre serviços que eu mesmo escrevo. Um monólito bem dividido me dá transação de banco atravessando módulos quando preciso (agendar uma consulta e reservar uma sala acontece numa transação só), um deploy só e refatorações que o IDE consegue acompanhar.
A disciplina que um time distribuído impõe com fronteiras de rede, eu imponho com fronteiras de pasta, convenções e testes.
Um diretório por contexto
Todo o código de negócio fica em app/Domain/<Contexto>. São 33 contextos delimitados e cerca de 1.500 arquivos PHP. Os maiores são Finance (com o subcontexto de faturamento TISS), Patient, Appointment, Billing, EmailMarketing, Clinic, Messaging e Prescription. Cada contexto tem as próprias pastas de blocos de construção, e o app/Http/Controllers do Laravel ficou praticamente vazio.
Bloco | Arquivos | Papel |
|---|---|---|
Controllers | 240 | Só HTTP: validar, autorizar, chamar uma Action, devolver página Inertia |
Actions | 237 | Um caso de uso por classe, com um método |
Requests | 207 | Validação de entrada |
Models | 190 | Persistência e relações |
Enums | 149 | Estados, tipos e transições permitidas |
Services | 95 | Lógica reutilizada por várias Actions |
Policies | 43 | Autorização por recurso |
Contracts | 13 | Portas para serviços externos |
Actions como unidade de regra de negócio
Cada caso de uso é uma classe pequena com um método execute(): calcular horários livres, conferir se uma janela está livre, cotar o preço de uma consulta, remarcar, iniciar atendimento. Controllers, jobs, comandos agendados e listeners chamam a mesma Action, então a regra existe num lugar só. Isso também deixa o teste direto: na maior parte dos casos testo a Action com o banco e sem HTTP.

Os estados ficam em enums com transições explícitas. O status de uma consulta, por exemplo, sabe para quais estados pode ir:
enum AppointmentStatus: string
{
// Scheduled, Confirmed, InProgress, Completed, Cancelled, NoShow
public function canTransitionTo(self $next): bool
{
return match ($this) {
self::InProgress => $next === self::Completed,
self::Completed, self::Cancelled, self::NoShow => false,
// ...
};
}
}Uma requisição atrasada que tenta confirmar uma consulta já concluída esbarra no enum, não num if espalhado pelo controller.
Valores que carregam regra
Alguns conceitos ganharam tipo próprio. Dinheiro é armazenado em centavos inteiros por um cast, para nunca existir 0.1 + 0.2 num fechamento de caixa. Datas são imutáveis (CarbonImmutable como padrão da aplicação), o que elimina uma família inteira de bugs em cálculo de agenda, onde somar 30 minutos a um horário não pode alterar o horário original. Telefone, texto de SMS, preço de consulta e horário de chegada têm classes de apoio com as próprias regras, e os dados que atravessam fronteiras (uma mensagem de WhatsApp, o resultado de um envio, o grafo de uma automação) são DTOs imutáveis.
Portas e adaptadores para o mundo externo
O Markmedi conversa com provedores de WhatsApp, SMS, pagamento, IA, transcrição, calendário e e-mail. Cada integração fica atrás de uma interface no contexto que a usa, e a implementação concreta é escolhida no container. WhatsApp tem dois provedores reais e um adaptador que só registra em log; SMS tem dois provedores e o mesmo adaptador de log; pagamento, IA e transcrição também ficam atrás de contratos.
O adaptador de log é usado automaticamente quando faltam credenciais. Em desenvolvimento, nos testes e em ambientes de revisão, nenhuma mensagem real sai para um paciente por acidente, e trocar de provedor de WhatsApp foi uma mudança de configuração, não uma refatoração.

Eventos de domínio, sempre depois do commit
Os módulos se comunicam por eventos. Quando algo relevante acontece (consulta agendada, confirmada, concluída, paciente cadastrado, negócio ganho no CRM, pagamento registrado), a Action dispara um evento, e os outros contextos reagem sem que o código de agenda precise conhecer financeiro ou CRM.
Todos os eventos de domínio implementam ShouldDispatchAfterCommit. Se a transação faz rollback, o evento nunca existiu. Esse detalhe evita uma classe de bug bem desagradável: o listener que manda a confirmação ao paciente de um agendamento que não foi gravado.
Para ter ideia do alcance, veja o que acontece quando uma consulta é concluída:
- as orientações pós-procedimento são publicadas para o paciente;
- o CRM avança o contato no funil e registra a sessão no negócio;
- uma pesquisa de NPS é criada;
- o financeiro gera o lançamento a receber;
- a guia do convênio é emitida, com retentativas próprias;
- se o procedimento tem manutenção, a data da próxima sessão é calculada;
- as automações configuradas pela clínica são avaliadas.

O que pode falhar ou demorar roda em listeners enfileirados, com backoff próprio; o que precisa ser imediato roda síncrono. A conclusão da consulta não espera a emissão da guia nem trava se o provedor do convênio estiver fora.
Um listener genérico para automações
As clínicas montam automações visuais do tipo "quando a consulta for confirmada, espere 2 dias e mande uma mensagem". Em vez de um listener por gatilho, existe um listener enfileirado que assina oito eventos de domínio e entrega o evento ao motor de automações, que avalia o grafo de cada fluxo. Adicionar um gatilho novo é registrar mais um evento nesse listener e descrever o contexto que ele oferece.
Frontend: Inertia, Vue e rotas tipadas
O frontend é Vue 3 com TypeScript, servido por Inertia, então não há uma API REST interna para manter só para o painel. São cerca de 200 páginas e 600 componentes, com uma camada de componentes base e uma de componentes da marca. As rotas e as Actions do backend são expostas ao TypeScript pelo Laravel Wayfinder: quando renomeio uma rota ou mudo um parâmetro, o build do frontend acusa o erro antes do deploy. As rotas do backend são divididas em arquivos por área (agenda, financeiro, TISS, público), espelhando os contextos.
O que eu não faço
Não uso event sourcing. Tenho tabelas de auditoria e eventos de domínio, que resolvem o que eu preciso (histórico de quem fez o quê e desacoplamento entre módulos) sem o custo de reconstruir estado a partir de eventos. Também não criei repositórios genéricos em cima do Eloquent: os models ficam nos contextos e as consultas complexas ficam em Actions ou Services com nome de negócio.
Como uma Action é a mesma para controller, job e comando, o TDD fica natural; escrevi sobre isso em TDD e CI no Markmedi. A separação de dados por clínica, que atravessa todos os contextos, está em multitenancy e segurança.
Este texto faz parte da série sobre o Markmedi.