Como Estruturar uma Arquitetura Laravel Unificada para Web e Aplicativos Mobile

Manter uma plataforma web existente e, simultaneamente, expandir sua operação para aplicativos móveis (iOS e Android) é um marco comum no crescimento de produtos digitais. No entanto, essa transição frequentemente expõe gargalos arquiteturais: lógica de negócio duplicada, endpoints inconsistentes, falhas de sincronização e autenticações frágeis.

Quando o back-end em PHP Laravel precisa atender tanto à interface web tradicional quanto às requisições do aplicativo mobile, a estrutura do código precisa ser planejada para evitar retrabalho e quebras de compatibilidade.

1. O Desafio da Duplicação de Regras de Negócio

Em projetos legados ou monolíticos convencionais, é comum encontrar validações e regras de negócio acopladas diretamente aos controllers web. Quando surge a necessidade de alimentar um app mobile, o erro mais frequente é criar controllers de API copiando trechos do código web.

Essa abordagem gera custos dobrados de manutenção e brechas de inconsistência (por exemplo, um cálculo de desconto atualizado na web que continua desatualizado no app).

Solução: Camada de Serviços e Actions

Para resolver o desacoplamento, a lógica de negócio deve ser extraída dos controllers para classes de serviço dedicadas ou Single Action Classes:

php
// app/Actions/Orders/CreateOrderAction.php
namespace AppActionsOrders;

use AppModelsOrder;
use AppDTOsOrderData;

class CreateOrderAction
{
public function execute(OrderData $data): Order
{
// Regras de negócio, cálculo de taxas e persistência
return Order::create($data->toArray());
}
}

Com essa estrutura, tanto o controller da web (Blade/Livewire) quanto o controller da API REST (Mobile) invocam a mesma Action, garantindo paridade absoluta entre as plataformas.

2. Autenticação Híbrida e Segura

A coexistência de web e mobile exige estratégias distintas de gerenciamento de sessão:

• Web: Utiliza sessões baseadas em cookies criptografados (proteção CSRF padrão).
• Mobile: Requer tokens persistentes para requisições stateless via cabeçalho Authorization: Bearer.

O ecossistema Laravel resolve esse cenário através do Laravel Sanctum. O Sanctum permite autenticação baseada em cookies para SPAs/Web interna e geração de tokens de acesso pessoal (Personal Access Tokens) para dispositivos móveis, aplicando permissões granulares (abilities) sem sobrecarregar a infraestrutura com a complexidade de um servidor OAuth2 completo.

3. Versionamento e Transformação de Dados

Ao atualizar um sistema web, o deploy reflete instantaneamente para todos os usuários. No ecossistema mobile, usuários continuam executando versões antigas do app baixadas nas lojas de aplicativos por semanas ou meses. Alterar o schema de uma resposta no back-end pode travar o aplicativo de milhares de clientes.

Boas práticas essenciais:

1. API Versioning: Isole rotas por versão (/api/v1/, /api/v2/).
2. Eloquent API Resources: Nunca retorne modelos do Eloquent diretamente. Utilize JsonResource para encapsular a saída, garantindo que alterações no banco de dados não quebrem contratos de dados legados do app.

php
// app/Http/Resources/V1/ProductResource.php
public function toArray(Request $request): array
{
return [
‘id’ => $this->id,
‘title’ => $this->name,
‘pricecents’ => $this->priceincents,
‘isavailable’ => $this->status === ‘active’,
];
}

4. Fluxo de Modernização de um Ecossistema Laravel

Em sistemas que desenvolvo e modernizo, a transição para uma arquitetura híbrida (Web + Mobile) segue etapas previsíveis:

1. Auditoria e Isolamento: Identificação de dependências de sessão e refatoração de regras de negócio em Actions reutilizáveis.
2. Definição de Contratos de API: Especificação de endpoints, parâmetros e payloads de resposta com OpenAPI/Swagger.
3. Camada de Autenticação Centralizada: Configuração de políticas de segurança e tokens com Sanctum/Passport.
4. Otimização de Payload: Redução do volume de dados transferidos e implementação de cache estratégico com Redis para endpoints de alta demanda mobile.
5. Monitoramento e Logs: Rastreamento de erros isolando falhas web de falhas específicas de integrações móveis.

Planejando a Evolução da sua Plataforma

Expandir um sistema Laravel existente para suportar aplicativos móveis não precisa significar reescrever o código do zero ou lidar com instabilidades constantes. Com a arquitetura adequada, é possível manter um único back-end robusto, seguro e fácil de manter para ambas as frentes.

Se a sua empresa precisa estruturar, refatorar ou escalar uma arquitetura Laravel para atender aplicações web e mobile com alto desempenho, entre em contato para avaliarmos seu projeto técnico e desenharmos a solução ideal.