# 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

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

## Estrutura recomendada detalhada

```text
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