Frontend - Visão Geral

Stack

Tecnologia	Versão	Uso
Next.js	16+ (App Router)	Framework full-stack
React	19	UI library
TypeScript	Strict mode	Tipagem
Tailwind CSS	4	Styling (utility-first)
shadcn-ui	Latest	Component library base
Zustand	Latest	State management (2 stores)
@xyflow/react	Latest	Editor visual de automações
Recharts	Latest	Gráficos e charts
Supabase	@supabase/ssr	Auth + Realtime
react-hot-toast	Latest	Notificações toast
Lucide React	Latest	Icones
SWR	Latest	Data fetching (páginas legadas)
Zod	4	Validação de schemas

Estrutura de Pastas

src/
  app/                    # Next.js App Router (pages + layouts)
    layout.tsx            # Root layout (Inter font, metadata, Providers)
    providers.tsx         # Client providers (Toaster, TooltipProvider)
    page.tsx              # / -> redirect /login
    login/                # Página de login
    register/             # Página de registro
    privacy/              # Politica de privacidade
    terms/                # Termos de serviço
    auth/
      accept-invite/      # Aceitar convite de equipe
    app/                  # Area protegida (requer auth)
      layout.tsx          # Sidebar + Topbar + ErrorBoundary
      page.tsx            # Dashboard
      chat/               # Chat em tempo real
      contacts/           # Contatos + segmentos
      templates/          # Templates WhatsApp
      automations/        # Funis de automação
      campaigns/          # Campanhas de envio
      analytics/          # Analytics (messages, revenue, rfm, links, ecommerce, metrics)
      orders/             # Pedidos e-commerce
      abandoned-carts/    # Carrinhos abandonados
      webhooks/           # Gerenciamento de webhooks
      tracking/           # Rastreamento de envios
      ai/                 # Configurações de IA
      settings/           # Configurações (layout próprio com sidebar)
    admin/                # Area admin (platform admins only)
      layout.tsx          # Sidebar própria (Dashboard, Contas, Receita)
      page.tsx            # Admin dashboard
      accounts/           # Gerenciamento de contas
      revenue/            # Métricas de receita
  components/             # Componentes React
    ui/                   # shadcn-ui primitives (NAO editar)
    layout/               # Sidebar, Topbar, AccountSwitcher, etc.
    dashboard/            # KpiCard, charts, export
    chat/                 # ConversationList, MessageArea, etc.
    contacts/             # ContactsTable, FilterBuilder, etc.
    automations/          # Editor visual, nodes, toolbox
    templates/            # TemplateBuilder, TemplatePreview, etc.
    campaigns/            # (inline nas pages)
    segments/             # SegmentBuilder, SegmentSelector
    analytics/            # MetricsOverview, charts
    billing/              # PlanOverview, PricingCard, checkout
    settings/             # TeamMembersTable, InviteMemberDialog
    tracking/             # TrackingSidebar, TrackingTimeline
    admin/                # AccountsTable, revenue charts
    shared/               # EmptyState, ConfirmDialog, Breadcrumb, etc.
    onboarding/           # SetupChecklist
    revenue/              # RevenueKpiCards
    webhooks/             # LogDetailModal
  stores/                 # Zustand stores
    auth-store.ts         # Autenticação e conta ativa
    chat-store.ts         # Conversas e mensagens
  hooks/                  # Custom hooks
    use-auth.ts           # Auth com Supabase
    use-api-query.ts      # GET requests com cache
    use-api-mutation.ts   # POST/PUT/DELETE requests
    use-páginated-query.ts     # Páginação offset-based
    use-cursor-páginated-query.ts  # Páginação cursor-based
    use-realtime-conversations.ts  # Supabase Realtime (conversations)
    use-realtime-messages.ts       # Supabase Realtime (messages)
    use-onboarding.ts     # Onboarding steps
    use-undo-redo.ts      # Undo/redo no editor
  lib/                    # Utilities, constants, helpers
  types/                  # TypeScript type definitions

Convenções

Client vs Server Components

• Server Components: usado apenas em páginas de conteúdo estático (privacy, terms) e root layout
• Client Components: todas as páginas interativas usam "use client" (dashboard, chat, settings, etc.)
• providers.tsx é o boundary client: Toaster + TooltipProvider

Utility function

• cn() de @/lib/utils para merge condicional de classes Tailwind
• Algumas páginas tem cn() local (ex: app layout)

Data Fetching

• Principal: useApiQuery<T>(url) — custom hook baseado em fetch + AbortController
• Mutations: useApiMutation<T>({ method, successMessage }) — POST/PUT/DELETE com toast
• Páginação offset: usePáginatedQuery<T>(fetcher, options)
• Páginação cursor: useCursorPáginatedQuery<T>(baseUrl, options)
• Legado: SWR usado em tracking page
• Realtime: Supabase Realtime channels para messages e conversations

Auth Flow

1. useAuth() hook chamado no AppLayout
2. Busca user via supabase.auth.getUser()
3. Busca accounts via /api/accounts
4. Persiste em useAuthStore (Zustand + localStorage)
5. Suporta multi-account (account switcher)
6. Admin detection via PLATFORM_ADMIN_EMAILS

Layout System

Root Layout (src/app/layout.tsx)

• Font: Inter (principal) + Geist Mono (code)
• Lang: pt-BR
• Dark theme only
• <Providers> wraps children

App Layout (src/app/app/layout.tsx)

• Sidebar (collapsible, mobile overlay)
• Topbar (hidden no editor fullscreen)
• SupportBanner + SubscriptionBanner
• ErrorBoundary com resetKey por pathname
• Chat page: padding removido (p-0)
• Editor page: fullscreen mode (sidebar collapsed, no topbar)

Settings Layout (src/app/app/settings/layout.tsx)

• Sidebar própria com 11 itens de navegação
• Area de conteúdo com scroll independente
• Botao de logout

Admin Layout (src/app/admin/layout.tsx)

• Sidebar própria (Dashboard, Contas, Receita)
• Link “Voltar ao app”
• Sem Topbar

Theme

Cores

• Background: #171717
• Cards: #212121
• Borders: #3D3D3D
• Hover: #2B2B2B
• Text primary: #E0E0E0
• Text muted: #9CA3AF (WCAG AA)
• Primary: #2563eb (hover #1d4ed8)
• Accent: #6366f1
• WhatsApp: #25D366
• Error: #dc2626
• PROIBIDO: cyan/teal, laranja

Dark Only

• Não há light mode
• Login/Register são exceção (fundo branco no form)

i18n

• UI text: Portugues (pt-BR) hardcoded nas strings
• Templates WhatsApp: Suporte a pt_BR, en_US, es_AR (seletor de idioma)
• Não há sistema de i18n (next-intl, etc.) — strings diretas nos componentes

Documentos Relacionados

• Mapa de Páginas
• Mapa de Componentes
• Zustand Stores
• Custom Hooks