Estrutura de Pastas

O APAH Assistant segue uma estrutura de pastas organizada e modular, facilitando a navegação e manutenção do código.

Visão Geral

apah-assistant/
├── 📁 src/                    # Código-fonte principal
│   ├── 📁 app/                # Next.js App Router
│   ├── 📁 components/         # Componentes partilhados
│   ├── 📁 hooks/              # React hooks customizados
│   ├── 📁 i18n/               # Internacionalização
│   ├── 📁 lib/                # Utilitários e helpers
│   ├── 📁 server/             # Lógica do servidor
│   ├── 📁 styles/             # Estilos globais
│   ├── 📄 env.mjs             # Validação de ambiente
│   └── 📄 middleware.ts       # Middleware Next.js
├── 📁 drizzle/                # Migrações da BD
├── 📁 public/                 # Ficheiros estáticos
├── 📁 documentation/          # Documentação (Docusaurus)
├── 📄 package.json            # Dependências
├── 📄 docker-compose.yaml     # Configuração Docker
└── 📄 drizzle.config.ts       # Configuração Drizzle

Diretório src/app/

O diretório app segue a estrutura do Next.js App Router:

src/app/
├── 📁 [lang]/                 # Roteamento por idioma
│   ├── 📁 (app)/              # Grupo de rotas da aplicação
│   │   ├── 📁 (administration)/ # Área administrativa
│   │   │   ├── 📁 contact-requests/
│   │   │   ├── 📁 feedback/
│   │   │   ├── 📁 library/
│   │   │   ├── 📁 users/
│   │   │   └── 📄 layout.tsx
│   │   ├── 📄 page.tsx        # Página principal (Chat)
│   │   └── 📄 layout.tsx
│   └── 📁 (auth)/             # Grupo de rotas de autenticação
│       ├── 📁 login/
│       └── 📁 change-password/
├── 📁 _components/            # Componentes do layout global
│   ├── 📄 navbar.tsx
│   ├── 📄 nav-user.tsx
│   └── 📁 chat/
├── 📁 api/                    # API Routes
│   ├── 📁 auth/
│   ├── 📁 chat/
│   └── 📁 library/
├── 📁 font/                   # Fontes customizadas
├── 📄 layout.tsx              # Layout raiz
├── 📄 branding.tsx            # Configurações de marca
└── 📄 theme-provider.tsx      # Provider de tema

Route Groups

Os parênteses () criam Route Groups que organizam rotas sem afetar a URL:

• (app) - Rotas que requerem autenticação
• (auth) - Rotas públicas de autenticação
• (administration) - Rotas administrativas

Dynamic Routes

Os parênteses retos [] criam Dynamic Routes:

• [lang] - Segmento dinâmico para o idioma (pt, en, fr)

Diretório src/components/

Componentes UI reutilizáveis (shadcn/ui):

src/components/
└── 📁 ui/
    ├── 📄 accordion.tsx
    ├── 📄 alert-dialog.tsx
    ├── 📄 alert.tsx
    ├── 📄 avatar.tsx
    ├── 📄 button.tsx
    ├── 📄 card.tsx
    ├── 📄 dialog.tsx
    ├── 📄 dropdown-menu.tsx
    ├── 📄 input.tsx
    ├── 📄 label.tsx
    ├── 📄 scroll-area.tsx
    ├── 📄 select.tsx
    ├── 📄 separator.tsx
    ├── 📄 switch.tsx
    ├── 📄 tooltip.tsx
    └── ...

Diretório src/server/

Lógica do lado do servidor:

src/server/
├── 📁 api/                    # tRPC API
│   ├── 📄 root.ts             # Router raiz
│   ├── 📄 trpc.ts             # Configuração tRPC
│   └── 📁 routers/            # Routers por domínio
│       ├── 📄 user.ts
│       ├── 📄 chat.ts
│       └── 📄 library.ts
├── 📁 auth/                   # Configuração Better Auth
│   ├── 📄 index.ts
│   └── 📄 config.ts
├── 📁 db/                     # Base de dados
│   ├── 📄 index.ts            # Cliente Drizzle
│   ├── 📄 schema.ts           # Schema principal
│   ├── 📁 schema/             # Schemas por domínio
│   │   ├── 📄 auth.ts
│   │   ├── 📄 chat.ts
│   │   ├── 📄 documents.ts
│   │   └── 📄 permissions.ts
│   ├── 📁 tools/              # Ferramentas de BD
│   └── 📄 utils.ts
├── 📁 lib/                    # Bibliotecas do servidor
├── 📄 embeddings.ts           # Gestão de embeddings
└── 📄 utils.ts                # Utilitários do servidor

Diretório src/lib/

Utilitários partilhados:

src/lib/
├── 📁 auth/                   # Helpers de autenticação
├── 📄 email.tsx               # Configuração de email
└── 📄 utils.ts                # Utilitários gerais (cn, etc.)

Diretório src/hooks/

React hooks customizados:

src/hooks/
├── 📄 use-mobile.ts           # Deteção de dispositivo móvel
├── 📄 use-session.ts          # Hook de sessão
├── 📄 useChatHistory.ts       # Gestão de histórico de chat
└── 📄 usePermissions.ts       # Verificação de permissões

Diretório src/i18n/

Configuração de internacionalização:

src/i18n/
├── 📄 i18n.ts                 # Configuração i18next
├── 📄 en.ts                   # Traduções Inglês
├── 📄 fr.ts                   # Traduções Francês
└── 📄 pt.ts                   # Traduções Português

Diretório drizzle/

Migrações e seeds da base de dados:

drizzle/
├── 📄 0000_youthful_paper_doll.sql    # Migração inicial
├── 📄 20250904143429_first_spiral.sql
├── ...
├── 📁 meta/                           # Metadados de migrações
│   ├── 📄 _journal.json
│   └── 📄 *_snapshot.json
└── 📁 seeds/                          # Scripts de seed
    ├── 📄 index.ts
    ├── 📄 seedDB.ts
    └── 📄 createUsersWithRoles.ts

Diretório public/

Ficheiros estáticos servidos diretamente:

public/
├── 📁 docs/                   # Documentos públicos
└── 📁 logos/                  # Logótipos
    └── 📁 logos_apah/

Convenções de Nomenclatura

Ficheiros

Tipo	Convenção	Exemplo
Componentes React	PascalCase	ChatMessage.tsx
Hooks	camelCase com prefixo use	useChatHistory.ts
Utilitários	camelCase	utils.ts
Páginas	page.tsx	page.tsx
Layouts	layout.tsx	layout.tsx
Server Actions	actions.ts	actions.ts

Pastas

Tipo	Convenção	Exemplo
Route Groups	(nome)	(auth)
Dynamic Routes	[param]	[lang]
Componentes privados	_components	_components/
Funcionalidades	kebab-case	contact-requests/

Colocation

O projeto segue o princípio de colocation - ficheiros relacionados ficam próximos:

src/app/[lang]/(app)/users/
├── 📄 page.tsx           # Página principal
├── 📁 _components/       # Componentes específicos desta página
│   ├── 📄 user-table.tsx
│   └── 📄 user-form.tsx
├── 📄 actions.ts         # Server Actions
└── 📄 types.ts           # Tipos específicos