Documentação é o mapa para um código sustentável.
Ayla Painel
Frontend — Next.js 15
Visão Geral
O frontend é uma aplicação Next.js 15 com TypeScript, rodando na porta 3002. Utiliza o App Router (não o Pages Router), NextAuth v5 para autenticação, Tailwind CSS v4 para estilização e Axios para comunicação com o backend. Os componentes seguem o padrão de design atômico (Átomos → Moléculas → Organismos).
Estrutura de Rotas
As rotas estão organizadas em dois grupos principais dentro de src/app/:
(admin) — Rotas protegidas
Todas as rotas abaixo exigem autenticação. Possuem layout com sidebar e header.
| Rota | Descrição |
|---|---|
/dashboard | Visão geral / painel principal |
/home | Grade de módulos e navegação |
/agentes | Gerenciamento de agentes de IA |
/automacoes | Configuração de rotinas de automação |
/conhecimento/biblioteca | Biblioteca de documentos |
/conhecimento/documentos | Documentos da base de conhecimento |
/conhecimento/prompts | Prompts configurados |
/conhecimento/treinamentos | Treinamentos dos agentes |
/configuracoes/permissoes | Permissões de acesso |
/configuracoes/usuarios | Gerenciamento de usuários |
/financeiro | Módulo financeiro |
/integracoes | Integrações com serviços externos |
/marketing | Módulo de marketing |
/minha-conta | Perfil do usuário |
/projetos | Seleção e gerenciamento de projetos |
(login) — Rotas públicas
Acessíveis sem autenticação. Não possuem layout com sidebar.
| Rota | Descrição |
|---|---|
/login | Tela de login (email/senha e OAuth) |
Autenticação
A autenticação é gerenciada pelo NextAuth v5 com estratégia JWT.
- Providers suportados: Credentials (email/senha), Google OAuth, Facebook OAuth.
- Middleware: Protege automaticamente todas as rotas, exceto
/login,/_nexte/api/auth. Redireciona usuários não autenticados para/login. - Callbacks:
signIn— Valida login social com o backend.jwt— Armazena token e dados do usuário.session— Injeta dados do usuário na sessão.
Serviços (Services)
Os serviços ficam em src/services/ e são responsáveis por toda a comunicação com a API.
| Arquivo | Descrição |
|---|---|
base-service/api.ts | Instância Axios com interceptors (injeta token JWT e X-Projeto-Id) |
base-service/api-no-token.ts | Instância Axios pública (sem autenticação) |
auth.service.ts | Login, registro e autenticação social |
projeto.service.ts | CRUD de projetos |
esqueleto.service.ts | Gerenciamento de templates/esqueletos |
Interceptors do Axios
- Injeta o token JWT do session em toda requisição.
- Adiciona o header
X-Projeto-Idcom o projeto ativo. - Normaliza datas nas requisições e respostas.
- Trata erros 401 fazendo logout automático.
- Exibe notificações de erro via toast.
Gerenciamento de Estado
Context API
O estado global do projeto ativo é gerenciado via React Context (src/contexts/projeto.context.tsx):
ProjetoProvider— Provedor que carrega e mantém o projeto selecionado.- A seleção é persistida no
localStorage. - Acessível em qualquer componente via hook
useProjeto().
Hooks Customizados
| Hook | Descrição |
|---|---|
useProjeto() | Acessa e altera o projeto ativo |
useTokenPronto() | Aguarda o token de autenticação estar disponível |
Componentes
Os componentes seguem o padrão de design atômico dentro de src/components/:
Átomos
Elementos base: Alert, Avatar, Badge, Botões, Card, Controles, Ícones, Loading, Modal, Skeleton, Text, Toast, Tooltip, Value.
Moléculas
- data/ — Tabelas, listas e exibição de dados.
- feedback/ — Notificações e alertas.
- form/ — Controles de formulário, inputs e selects.
- layout/ — Moléculas de estrutura de página.
Layout Principal
SidebarComponent— Barra de navegação lateral.HeaderComponent— Barra superior de navegação.PageHeaderMolecule— Título e breadcrumbs da página.ChatDrawerComponent— Gaveta de chat/assistência.
Variáveis de Ambiente
Crie o arquivo packages/frontend/.env.local:
NEXT_PUBLIC_API_URL=http://localhost:9002
NEXT_PUBLIC_BASE_URL=http://localhost:9002
AUTH_SECRET=chave-secreta-aleatoria
AUTH_GOOGLE_ID=seu-google-client-id
AUTH_GOOGLE_SECRET=seu-google-client-secret
AUTH_FACEBOOK_ID=seu-facebook-app-id
AUTH_FACEBOOK_SECRET=seu-facebook-app-secret
NEXT_PUBLIC_AMBIENTE=DEVELOPMENTBoas Práticas
- Use os tipos do pacote
@ayla/sharedpara tipar dados da API. - Toda comunicação com a API deve passar pelos serviços em
src/services/. - Use o hook
useProjeto()para acessar o projeto ativo. - Para requisições autenticadas, use a instância
api.ts(com interceptors). - Componentes devem seguir o padrão atômico: Átomo → Molécula → Organismo → Página.
- Use
React Hook Form+Zodpara validação de formulários.