NX Suite Frontend - Architecture Guidelines

Documentação de Arquitetura e Padrões para LLMs e Desenvolvedores

Este documento contém informações detalhadas sobre a estrutura, convenções e padrões do projeto NX Suite Frontend, otimizado para auxiliar Large Language Models (LLMs) e desenvolvedores a entenderem e contribuírem de forma consistente.

---

Sumário

1. Visão Geral do Projeto
2. Stack Tecnológica
3. Estrutura de Diretórios
4. Convenções de Nomenclatura
5. Estrutura de Componentes
6. Sistema de Tipos
7. Contextos e Estado Global
8. Testes
9. UI & Estilização
10. Checklists para LLMs

---

Visão Geral do Projeto

NX Suite é a primeira plataforma CXaaS (Customer Experience as a Service) do Brasil, desenvolvida pela Smart NX.

Atributo	Valor
Nome	NX Suite Frontend
Versão	2.0.0
Tipo	React SPA (Single Page Application)
Build Tool	Vite 6.0.7
Package Manager	pnpm (também suporta yarn)
Linguagem	TypeScript 5.6.3 (strict mode)

---

Stack Tecnológica

Core Framework

Biblioteca	Versão	Uso
React	18.3.1	Framework UI
TypeScript	5.6.3	Tipagem estática
Vite	6.0.7	Build tool com SWC
React Router DOM	6.23.1	Roteamento

UI & Estilização

Biblioteca	Versão	Uso
Ant Design (antd)	5.23.0	Biblioteca de componentes principal
Styled Components	6.1.14	CSS-in-JS
Framer Motion	12.16.0	Animações

---

Estrutura de Diretórios

nx-suite-front-novo/
├── src/                          # Código-fonte principal
│   ├── assets/                   # Imagens, ícones, fontes (.png, .svg, .jpg, .webp, .woff, .woff2)
│   ├── components/               # Componentes reutilizáveis da aplicação (específicos do negócio)
│   ├── config/                   # Arquivos de configuração da aplicação
│   ├── contexts/                 # React Contexts para estado global
│   ├── design-system/            # Componentes genéricos do design system
│   ├── enums/                    # Enumerações TypeScript
│   ├── helpers/                  # Funções auxiliares e utilitárias
│   ├── hooks/                    # Custom React Hooks
│   ├── models/                   # Modelos de dados e interfaces TypeScript
│   ├── pages/                    # Páginas da aplicação organizadas por módulo
│   ├── routes/                   # Configuração de rotas
│   ├── services/                 # Serviços (API, Auth, Socket, etc.)
│   ├── styles/                   # Estilos globais e temas
│   ├── types/                    # Definições de tipos TypeScript globais
│   ├── utils/                    # Utilitários diversos
│   ├── tests/                    # Configuração e utilitários de teste
│   ├── App.less                  # Estilos principais da aplicação
│   └── index.tsx                 # Ponto de entrada da aplicação
├── locales/                      # Arquivos de tradução (i18n)
│   ├── translations/             # Traduções (pt-BR.json, en-US.json)
│   └── globalTerms.json          # Termos globais compartilhados
├── public/                       # Arquivos estáticos públicos
├── scripts/                      # Scripts de automação
├── docs/                         # Documentação
├── biome.json                    # Configuração do Biome (linter/formatter)
├── commitlint.config.ts          # Configuração do Commitlint
├── vite.config.ts                # Configuração do Vite
└── package.json                  # Dependências e scripts

---

Convenções de Nomenclatura

Interfaces e Types

Tipo	Prefixo	Formato	Exemplo
Interface	I	PascalCase	IUser, IChatMessage, IMessageResponse
Type	T	PascalCase	TUserType, TStatus, TChannelType

[!IMPORTANT] NUNCA declare interfaces/types no topo do arquivo do componente. SEMPRE crie um arquivo types.ts separado e use import type para imports.

---

Estrutura de Componentes

Template de Componente (types.ts)

import type { Functionalities } from "@enums/functionalities";
import type { Operations } from "@enums/operations";

export interface IComponentNameProps {
  title: string;
  onClick?: () => void;
  children?: React.ReactNode;
  disabled?: boolean;
}

export interface IPermissionProps {
  functionality?: keyof typeof Functionalities;
  operation?: keyof typeof Operations;
  onlyForSuperAdmin?: boolean;
}

export type TComponentVariant = "primary" | "secondary" | "danger";

---

Sistema de Tipos

Modelos de Dados (src/models/)

// src/models/User.ts
import type IQueue from "./Queue";
import type { IUserGroup, IFunctionality } from "./UserManagement";

export interface IUser {
  id: number;
  user_name: string;
  user_email: string;
  user_fullname: string;
  user_type_id: number;
  queues: IQueue[];
  user_group: IUserGroup;
  user_permission_default: {
    functionalities: IFunctionality[];
  };
  language: string;
}

export interface IResponseUsers {
  data: IUser[];
  totalItems: number;
  totalPages: number;
}

---

Contextos e Estado Global

Exemplo de Context (context.ts)

import { createContext } from "react";
import type IClient from "@models/Client";
import type { IUser } from "@models/User";

interface IAuthContextValues {
  user?: IUser | null;
  isAuthenticated: boolean;
  loading: boolean;
  currentClient: IClient | null;
  logout: () => void;
}

const AuthUserContext = createContext<IAuthContextValues>({
  user: null,
  isAuthenticated: false,
  loading: true,
  currentClient: null,
  logout: () => {},
});

export default AuthUserContext;

---

Testes

Template de Teste

import { describe, it, expect, vi, beforeEach } from "vitest";
import { fireEvent, screen } from "@testing-library/react";
import { renderWithProviders } from "@tests/utils/renderWithProviders";
import { ComponentName } from "../index";

describe("ComponentName", () => {
  it("deve renderizar corretamente", () => {
    renderWithProviders(<ComponentName title="Título" />);
    expect(screen.getByText("Título")).toBeInTheDocument();
  });
});

---

Checklists para LLMs

• Definir todas as interfaces no arquivo types.ts
• Prefixar Interfaces com I e Types com T
• Usar path aliases (@components/*)
• Seguir Conventional Commits (feat(scope): message)
• Evitar any - usar unknown ou tipos específicos

---

Última atualização: Abril 2026 Mantido por: Smart NX Team