millions/docs/20_PROJECT_STRUCTURE.md

Project Structure

Objetivo

Definir uma estrutura de projeto clara, previsível e adequada a desenvolvimento assistido por agentes de IA.

Estrutura de alto nível

app/
components/
features/
lib/
server/
prisma/
docs/
public/

Estrutura recomendada detalhada

src/
  app/
    (dashboard)/
    api/
    login/
    layout.tsx
    page.tsx

  components/
    ui/
    shared/
    layout/
    tables/
    forms/
    status/

  features/
    suppliers/
      components/
      actions/
      schemas/
      utils/
    purchase-orders/
      components/
      actions/
      schemas/
      utils/
    receipts/
      components/
      actions/
      schemas/
      utils/
    inventory/
      components/
      actions/
      schemas/
      utils/
    listings/
      components/
      actions/
      schemas/
      utils/
    sales/
      components/
      actions/
      schemas/
      utils/
    shipments/
      components/
      actions/
      schemas/
      utils/
    dashboard/
      components/
      queries/
      utils/

  lib/
    auth/
    utils/
    constants/
    validators/

  server/
    db/
      client.ts
    repositories/
    services/
    queries/
    permissions/
    audit/

  prisma/
    schema.prisma
    migrations/
    seeds/

  docs/
    *.md

  public/
    images/
    icons/

Regras de organização

• app/ contém rotas, layouts e entry points do Next.js
• components/ contém componentes reutilizáveis sem lógica de negócio forte
• features/ organiza a aplicação por domínio funcional
• server/ concentra lógica do lado do servidor
• prisma/ concentra schema, migrations e seeds
• docs/ contém a documentação do projeto

Padrão por feature

Cada feature deve, idealmente, conter:

• components/
• actions/
• schemas/
• utils/

Opcionalmente:

• queries/
• types/
• tests/

Separação recomendada de responsabilidades

UI

Componentes visuais, tabelas, formulários, badges, cards, filtros.

Actions / handlers

Entradas da aplicação para mutações e operações ligadas ao utilizador.

Schemas

Validação com Zod.

Services

Regras de negócio e fluxos operacionais.

Repositories

Acesso aos dados e queries Prisma.

Queries

Leituras complexas e agregações para dashboard e listagens.

Convenções de naming

• kebab-case para nomes de pastas de features
• PascalCase para componentes React
• camelCase para funções e variáveis
• nomes explícitos e orientados ao domínio
• evitar abreviações ambíguas

Estrutura inicial mínima da V1

• auth
• suppliers
• purchase-orders
• receipts
• inventory
• sales
• shipments
• dashboard