Estrutura de pastas

Os projetos HedHog são organizados como um monorepo Turbo. O projeto gerado começa com uma base pequena, e você o expande adicionando bibliotecas e pacotes compartilhados ao longo do tempo.

O scaffold padrão criado pelo HedHog inclui apenas:

apps/
  admin/
  api/
libraries/
packages/

Este repositório de desenvolvimento contém aplicações adicionais como hedhog, class, partners e training, mas essas fazem parte do próprio workspace do framework e não devem ser interpretadas como a estrutura mínima gerada para um novo projeto.

apps/
  admin/
  api/
  ...optional apps in the framework workspace
libraries/
  core/
  your-domain-library/
packages/
  api/
  api-prisma/
  ui/
docs/
scripts/

A pasta apps contém aplicações executáveis.

• apps/admin: o painel administrativo em Next.js usado para gerenciar dados, usuários, permissões, configurações e fluxos de negócio personalizados.
• apps/api: o entrypoint NestJS que carrega os módulos de negócio definidos em libraries/*.
• Outras aplicações podem existir no repositório de desenvolvimento do HedHog, mas são exemplos opcionais ou aplicações internas do framework, não parte do scaffold base do projeto.

Use apps/* para composição e bootstrapping em tempo de execução, não para regras de negócio centrais.

A pasta libraries é o coração de um projeto HedHog.

Cada biblioteca representa uma capacidade de negócio ou domínio, por exemplo core, finance, crm, lms, ou um módulo personalizado criado para o seu projeto.

É aqui que a lógica de negócio deve morar:

• Módulos, controllers, services e DTOs do NestJS
• Permissões específicas do domínio e seeds de rotas
• Arquivos YAML do HedHog para tabelas e dados de seed
• Integração com dashboard ou admin pertencente àquele domínio

Na prática, apps/api importa as bibliotecas, mas as regras e casos de uso pertencem a libraries/*.

A pasta packages contém blocos de construção técnicos reutilizáveis, compartilhados entre apps e bibliotecas.

Exemplos comuns deste repositório incluem:

• packages/api: helpers de backend compartilhados
• packages/api-prisma: helpers de acesso e integração com o Prisma
• packages/api-pagination: comportamento de paginação compartilhado
• packages/next-app-provider: providers de aplicação frontend e integração de cliente compartilhada
• packages/ui: primitivos e componentes de UI reutilizáveis

Use packages/* para infraestrutura transversal ou abstrações reutilizáveis que não estão atreladas a um único domínio de negócio.

• docs/: fontes de documentação, schemas e material de referência usados pelo framework.
• scripts/: automação do repositório para setup, geração de código, atualizações de schema e tarefas de manutenção.
• apps/api/prisma/: migrations do Prisma e ativos de integração de banco de dados para a aplicação da API.
• storage/: armazenamento local em tempo de execução usado por partes do workspace.

Essas pastas dão suporte ao monorepo, mas não são onde você deve colocar comportamento de domínio.

• Coloque a lógica de negócio em libraries/*.
• Coloque os entrypoints e o bootstrapping da aplicação em apps/*.
• Coloque o código técnico compartilhado em packages/*.
• Evite mover regras de domínio para apps/admin ou apps/api só porque essas aplicações consomem a funcionalidade.

Se você adicionar uma nova funcionalidade de cobrança (billing):

• Crie ou estenda uma biblioteca como libraries/finance.
• Implemente controllers, services, DTOs, YAML e permissões nessa biblioteca.
• Exponha o módulo através de apps/api.
• Construa as telas de administração em apps/admin consumindo a API.
• Extraia helpers reutilizáveis ou primitivos de UI para packages/* apenas quando forem realmente compartilhados.

Essa separação mantém o monorepo escalável à medida que o número de módulos cresce.