Padrões de Diretórios

Este guia define como novos diretórios, páginas e módulos devem ser organizados no frontend da Smart NX (SNX).
O foco é garantir uma arquitetura baseada em domínio, favorecendo isolamento entre áreas (como Dashboard, Chat, Admin ou Público) e padronização no desenvolvimento de novas features.

Este documento não reflete a estrutura atual, mas o padrão de referência para futuras criações.
Ele define como pensamos e construímos novos módulos, garantindo consistência, previsibilidade e escalabilidade.

Princípios Arquiteturais

Organização por Domínio (Domain-Driven Frontend)
Cada área funcional da aplicação (Dashboard, Chat, Público, Admin etc.) é tratada como um domínio isolado, com sua própria estrutura interna.
Isolamento Contextual
Tudo o que pertence a um domínio deve estar contido nele — componentes, contextos, hooks, helpers e types.
Isso evita dependências cruzadas e mantém o código modular.
Reutilização Consciente
Apenas o que for realmente compartilhável entre domínios deve ser movido para o escopo global (src/components, src/hooks, etc.).
Simplicidade e Escalabilidade
A estrutura deve permitir a adição de novas features sem quebrar o padrão de organização.

Estrutura de Domínios

O diretório src/pages é o núcleo organizacional do frontend.
Cada subdiretório dentro dele representa um domínio funcional do sistema.

Hierarquia de Páginas

src/pages/
├── Attendance/           # Páginas de atendimento ao cliente
├── Chat/                 # Páginas de chat
├── Dashboard/            # Dashboard principal
│   ├── ArtificialIntelligence/
│   ├── Attendance/
│   ├── Billing/
│   ├── Builder/
│   ├── Channels/
│   ├── Config/
│   ├── Home/
│   ├── Monitoring/
│   ├── People/
│   └── Utility/
├── Public/               # Páginas públicas (login, etc.)
└── System/               # Páginas do sistema

O objetivo é que cada domínio represente um contexto funcional completo da aplicação.

Estrutura Interna de um Domínio

Cada domínio (ou subdomínio) segue a mesma estrutura modular:

src/pages/<domain>/
│
├─ components/     → Componentes locais e específicos do domínio
├─ contexts/       → Estados e contextos próprios da área
├─ hooks/          → Hooks customizados usados apenas neste domínio
├─ helpers/        → Funções utilitárias específicas
├─ types/          → Tipos e interfaces locais
├─ services/       → Comunicação com APIs ou lógicas de dados
├─ index.tsx       → Ponto de entrada (página principal)
└─ style.ts        → Estilização principal do domínio

Tudo que for específico daquele domínio deve estar dentro dele.
Se uma página ou funcionalidade é exclusiva do Dashboard, ela deve estar em src/pages/dashboard/... — nunca diretamente em src/pages.

Exemplos de Estrutura por Domínio

1. Páginas Públicas

src/pages/public/
│
├─ login/
│   ├─ index.tsx
│   ├─ style.ts
│   └─ components/
│       ├─ LoginForm/
│       │   ├─ index.tsx
│       │   └─ style.ts
│
├─ register/
│   ├─ index.tsx
│   └─ style.ts
└─ forgot-password/
├─ index.tsx
└─ style.ts

Não possuem dependências de contexto global.
Acesso livre (sem autenticação).
Devem ser simples e focadas em fluxo de entrada do usuário.

2. Dashboard (Área Autenticada)

src/pages/dashboard/
│
├─ relationship/
│   ├─ components/
│   │   ├─ Flows/
│   │   └─ Segments/
│   ├─ contexts/
│   │   └─ RelationshipContext.tsx
│   ├─ hooks/
│   │   └─ useFlows.ts
│   ├─ helpers/
│   │   └─ mapRelationshipData.ts
│   ├─ types/
│   │   └─ relationshipTypes.ts
│   ├─ index.tsx
│   └─ style.ts
│
└─ reports/
├─ components/
├─ hooks/
├─ types/
└─ index.tsx

Cada subpasta dentro de dashboard é um subdomínio funcional (ex: relationship, reports, settings).
Devem ser organizadas de forma autônoma, com o mínimo de dependências entre si.
Contextos e hooks globais do dashboard ficam em src/pages/dashboard/contexts e src/pages/dashboard/hooks.

3. Chat (Domínio Isolado)

src/pages/chat/
│
├─ components/
│   ├─ ChatWindow/
│   ├─ MessageInput/
│   └─ UserList/
├─ contexts/
│   └─ ChatContext.tsx
├─ hooks/
│   ├─ useChatMessages.ts
│   ├─ useConnection.ts
│   └─ useTypingStatus.ts
├─ services/
│   └─ chatService.ts
├─ types/
│   └─ chatTypes.ts
├─ index.tsx
└─ style.ts

Pode usar contextos próprios de conexão ou estado.
Totalmente desacoplado do Dashboard.
Comunicação via WebSocket, com isolamento técnico completo.

Critérios para Novos Diretórios

Caso	Onde criar	Observações
Nova página pública	`src/pages/public/<page>`	Acessível sem autenticação. Simples e isolada.
Nova página autenticada	Dentro de `src/pages/dashboard/<module>`	Deve herdar layout e contexto do Dashboard.
Nova área independente	`src/pages/<domain>`	Domínio isolado, como Chat ou Admin.
Componente compartilhado	`src/components/<ComponentName>`	Reutilizado em múltiplos domínios.
Hook ou helper global	`src/hooks/` ou `src/helpers/`	Genérico, sem dependência de contexto.
Nova API Service	`src/services/<domain>.service.ts`	Representa um endpoint específico de domínio.

Diretrizes de Criação

Prefira proximidade ao escopo
→ Se um componente ou hook é usado apenas dentro de um domínio, mantenha-o localmente.
Evite criar pastas globais sem necessidade.
Crie um index.ts sempre que houver múltiplos exports
→ Isso simplifica imports e evita caminhos longos.
Mantenha a hierarquia rasa
→ Evite mais de 3 níveis de aninhamento (ex: components/ButtonGroup/Button/index.tsx).
Nomeie de forma previsível e semântica
→ Exemplo: relationship, reports, settings, chat, public.
Evite sobreposição de domínios
→ Uma feature deve pertencer claramente a um domínio.
Se precisar interagir com outro, faça isso via serviços ou hooks de integração, nunca importando diretamente os componentes do outro domínio.

Convenções de Nomenclatura

Tipo	Convenção	Exemplo
Interfaces	`I` + PascalCase	`IUser`, `IFunctionality`
Tipos	`T` + PascalCase	`TStatus`, `TChannelType`
Componentes	PascalCase	`UserCard.tsx`, `DashboardHeader.tsx`
Hooks	use + PascalCase	`useChatMessages.ts`, `useUserSession.ts`
Helpers / Utils	camelCase	`formatDate.ts`, `parseUserData.ts`
Arquivos de estilo	`.style.ts`	`Button.style.ts`, `Header.style.ts`
Diretórios	camelCase	`relationship`, `userSettings`, `chatWindow`
Contextos	PascalCase + “Context”	`ChatContext.tsx`, `ThemeContext.tsx`
Testes	`.test.ts(x)`	`Button.test.tsx`, `useAuth.test.ts`
Idioma	Inglês (100%)	Código, nomes e comentários.

Decisão Arquitetural

Camada Global: fornece componentes e utilitários reutilizáveis.
Camada de Domínio: cada área (Dashboard, Chat, Público) tem autonomia estrutural.
Camada de Feature: cada página representa uma feature isolada com suas dependências locais.

Essa separação facilita a evolução da aplicação, testes independentes e modularização progressiva (eventualmente suportando microfrontends).

Histórico de Versões

Data	Versão	Autor / Revisor	Alterações
08/04/2026	`v1.1.0`	Juathan Coelho Duarte	Alinhamento com o Master Guideline e prefixos I/T
29/10/2025	`v1.0.0`	@Matheus Telles	Criação inicial e estrutura base do documento

Princípios Arquiteturais​

Estrutura de Domínios​

Hierarquia de Páginas​

Estrutura Interna de um Domínio​

Exemplos de Estrutura por Domínio​

1. Páginas Públicas​

2. Dashboard (Área Autenticada)​

3. Chat (Domínio Isolado)​

Critérios para Novos Diretórios​

Diretrizes de Criação​

Convenções de Nomenclatura​

Decisão Arquitetural​

Histórico de Versões​