@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/framework/standards/STANDARDS.json

@@ -62,6 +62,28 @@
         "ddd"
       ]
     },
+    {
+      "id": "architecture-ddd-bounded-contexts",
+      "name": "bounded contexts",
+      "path": "architecture/ddd/bounded-contexts.md",
+      "category": "architecture",
+      "subcategory": "ddd",
+      "tags": [
+        "architecture",
+        "ddd"
+      ]
+    },
+    {
+      "id": "architecture-ddd-complexity-levels",
+      "name": "complexity levels",
+      "path": "architecture/ddd/complexity-levels.md",
+      "category": "architecture",
+      "subcategory": "ddd",
+      "tags": [
+        "architecture",
+        "ddd"
+      ]
+    },
     {
       "id": "architecture-ddd-entities",
       "name": "entities",
@@ -73,6 +95,17 @@
         "ddd"
       ]
     },
+    {
+      "id": "architecture-ddd-ubiquitous-language",
+      "name": "ubiquitous language",
+      "path": "architecture/ddd/ubiquitous-language.md",
+      "category": "architecture",
+      "subcategory": "ddd",
+      "tags": [
+        "architecture",
+        "ddd"
+      ]
+    },
     {
       "id": "architecture-ddd-value-objects",
       "name": "value objects",
@@ -511,6 +544,61 @@
         "design-system"
       ]
     },
+    {
+      "id": "frontend-nextjs-app-router",
+      "name": "app router",
+      "path": "frontend/nextjs/app-router.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
+    {
+      "id": "frontend-nextjs-components",
+      "name": "components",
+      "path": "frontend/nextjs/components.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
+    {
+      "id": "frontend-nextjs-data-fetching",
+      "name": "data fetching",
+      "path": "frontend/nextjs/data-fetching.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
+    {
+      "id": "frontend-nextjs-forms",
+      "name": "forms",
+      "path": "frontend/nextjs/forms.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
+    {
+      "id": "frontend-nextjs-naming-conventions",
+      "name": "naming conventions",
+      "path": "frontend/nextjs/naming-conventions.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
     {
       "id": "frontend-nextjs-nextjs-patterns",
       "name": "nextjs patterns",
@@ -522,6 +610,39 @@
         "nextjs"
       ]
     },
+    {
+      "id": "frontend-nextjs-project-structure",
+      "name": "project structure",
+      "path": "frontend/nextjs/project-structure.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
+    {
+      "id": "frontend-nextjs-state-management",
+      "name": "state management",
+      "path": "frontend/nextjs/state-management.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
+    {
+      "id": "frontend-nextjs-testing",
+      "name": "testing",
+      "path": "frontend/nextjs/testing.md",
+      "category": "frontend",
+      "subcategory": "nextjs",
+      "tags": [
+        "frontend",
+        "nextjs"
+      ]
+    },
     {
       "id": "infrastructure-azure-azure",
       "name": "azure",

package/framework/standards/architecture/ddd/bounded-contexts.md

@@ -0,0 +1,105 @@
+# DDD Bounded Contexts
+
+> **Scope:** universal
+> **Layer:** 2
+> **Keywords:** bounded-context, ddd, domain, context-map, modular-monolith, integration-events
+
+Bounded Context (BC) é a fronteira onde um modelo de domínio tem significado único.
+Use apenas em sistemas com múltiplos domínios distintos (Nível 3 de complexidade).
+
+---
+
+## Estrutura de Pastas (Nível 3)
+
+```
+src/{App}.Domain/
+  Billing/
+    Aggregates/
+      Subscription.cs
+      Invoice.cs
+    ValueObjects/
+      PlanTier.cs
+      BillingCycle.cs
+    Events/
+      SubscriptionCreatedEvent.cs
+    Exceptions/
+      SubscriptionNotFoundException.cs
+
+  Orders/
+    Aggregates/
+      Order.cs
+    ValueObjects/
+      Money.cs
+    Events/
+      OrderConfirmedEvent.cs
+
+src/{App}.Application/
+  Billing/
+    Commands/
+      CreateSubscriptionCommand.cs
+    Queries/
+      GetActiveSubscriptionQuery.cs
+    Handlers/
+      CreateSubscriptionHandler.cs
+
+src/{App}.Infrastructure/
+  Billing/
+    Repositories/
+      SubscriptionRepository.cs
+    Configurations/
+      SubscriptionConfiguration.cs
+```
+
+---
+
+## Regras de Comunicação Cross-BC
+
+```csharp
+// ✅ CORRETO: referenciar outro BC por ID
+public class Order : AggregateRoot
+{
+    public Guid CustomerId { get; private set; }  // ID, não navigation property
+}
+
+// ✅ CORRETO: comunicação via Integration Events
+public class OrderConfirmedHandler : INotificationHandler<OrderConfirmedIntegrationEvent>
+{
+    public async Task Handle(OrderConfirmedIntegrationEvent notification, CancellationToken ct)
+    {
+        await _billingService.ChargeForOrderAsync(notification.OrderId, ct);
+    }
+}
+
+// ❌ ERRADO: acesso direto ao repositório de outro BC
+public class OrderService
+{
+    private readonly ICustomerRepository _customerRepo; // cross-BC — PROIBIDO
+}
+```
+
+---
+
+## Linguagem Ubíqua por BC
+
+O mesmo termo pode ter significados diferentes em BCs distintos:
+
+| Termo | BC: Orders | BC: Support |
+|-------|-----------|-------------|
+| `Customer` | Quem fez pedido, tem `Orders[]` | Quem abriu ticket, tem `SLA` |
+| `Status` | `Draft/Confirmed/Shipped` | `Open/InProgress/Resolved` |
+
+Documente em `1-design/ubiquitous-language.md` por feature.
+
+---
+
+## Quando NÃO usar Bounded Contexts
+
+- App single-domain (ex: sistema de agendamentos)
+- MVP ou projeto com um único time
+- Quando os "domínios" compartilham o mesmo modelo sem conflito
+
+Em todos esses casos: use Nível 2 (Aggregates sem BC isolation).
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/architecture/ddd/complexity-levels.md

@@ -0,0 +1,108 @@
+# DDD Complexity Levels
+
+> **Scope:** universal
+> **Layer:** 2
+> **Keywords:** ddd, complexity, aggregate, crud, bounded-context, domain, level
+
+Define o nível de complexidade de domínio para cada feature. O nível determina qual
+template de contracts.cs será usado e quais padrões DDD são mandatórios.
+
+---
+
+## Os 3 Níveis
+
+### Nível 1 — CRUD
+
+**Quando usar:**
+- Feature é essencialmente Create/Read/Update/Delete
+- Entidade não tem regras de negócio (apenas validações de campos)
+- Nenhum outro domínio precisa reagir às mudanças desta entidade
+- Exemplos: `Category`, `Tag`, `UserProfile`, `Notification`
+
+**O que gerar:**
+- `Entity` simples (sem AggregateRoot)
+- Service interface CRUD
+- DTOs (record)
+- Repository interface básica
+- **SEM** Domain Events, **SEM** Value Objects obrigatórios, **SEM** CQRS
+
+---
+
+### Nível 2 — Business Logic
+
+**Quando usar:**
+- Entidade tem estados com transições controladas por regras (ex: Draft → Confirmed → Shipped)
+- Invariants existem: "só pode cancelar se estiver Ativo"
+- Cálculos derivados (Total, Saldo, Desconto)
+- Outros módulos precisam reagir a mudanças desta entidade
+- Exemplos: `Order`, `Subscription`, `Invoice`, `Project`, `Ticket`
+
+**O que gerar:**
+- `AggregateRoot` com factory method estático
+- Value Objects para tipos com regras (Money, Email, PhoneNumber)
+- Domain Events para mudanças de estado relevantes
+- Commands + Queries (CQRS com MediatR)
+- Repository interface por aggregate root
+- **SEM** Bounded Context isolation (módulos se comunicam diretamente)
+
+---
+
+### Nível 3 — Bounded Context
+
+**Quando usar (opt-in explícito apenas):**
+- Sistema tem 3+ domínios distintos onde o mesmo conceito tem modelos diferentes
+  - Exemplo: "Customer" em Billing ≠ "Customer" em Support
+- Times distintos trabalharão em cada domínio
+- Domínios precisam evoluir independentemente
+- Exemplos: plataforma multi-produto, marketplace, ERP
+
+**O que gerar:**
+- Tudo do Nível 2 +
+- Pasta `{BoundedContext}/` em Domain + Application
+- Integration Events para comunicação cross-BC (via MediatR/Service Bus)
+- Referências cross-BC por ID (nunca navigation properties)
+- Glossário de Linguagem Ubíqua por BC
+
+**⚠️ Não use Nível 3 por default.** Declare explicitamente na proposta.
+
+---
+
+## Como Detectar o Nível
+
+O `domain-architect` analisa a proposta e responde:
+
+```
+1. A entidade principal tem estados com transições? → Sim = Nível 2+
+2. Existem invariants de negócio? → Sim = Nível 2+
+3. Cálculos derivados existem? → Sim = Nível 2+
+4. Outros domínios precisam reagir a mudanças? → Sim = Nível 2+
+5. Diferentes contextos usam modelos diferentes do mesmo conceito? → Sim = Nível 3
+6. O usuário declarou explicitamente Bounded Context? → Sim = Nível 3
+Se nenhuma das anteriores: Nível 1
+```
+
+---
+
+## Template por Nível
+
+| Nível | Template |
+|-------|----------|
+| 1 | `code/dotnet/contracts/contracts-level1.cs` |
+| 2 | `code/dotnet/contracts/contracts-level2.cs` |
+| 3 | `code/dotnet/contracts/contracts-level3.cs` |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Nível Afetado | Correção |
+|---|---|---|
+| AggregateRoot para CRUD simples | Nível 1 desnecessário | Use Entity simples |
+| Domain Events sem consumidores | Nível 2 excessivo | Remova ou use Nível 1 |
+| Bounded Context para app single-domain | Nível 3 prematuro | Use Nível 2 |
+| Entidade anêmica com regras no Service | Todos | Mova regras para o Aggregate |
+| Value Objects para todo primitivo | Nível 2 excessivo | Só quando há regras/validação |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/architecture/ddd/ubiquitous-language.md

@@ -0,0 +1,58 @@
+# DDD Ubiquitous Language
+
+> **Scope:** universal
+> **Layer:** 2
+> **Keywords:** ubiquitous-language, ddd, glossary, domain-terms, naming
+
+Linguagem Ubíqua é o vocabulário compartilhado entre devs e domínio de negócio.
+Elimina ambiguidade e alinha código com a linguagem do negócio.
+
+---
+
+## Formato do Glossário
+
+```markdown
+# Ubiquitous Language: {Feature/BoundedContext}
+
+## Termos do Domínio
+
+| Termo | Definição | Contexto | Código |
+|-------|-----------|----------|--------|
+| Subscription | Contrato ativo de uso por um tenant | Billing | `Subscription` (AggregateRoot) |
+| PlanTier | Nível do plano (Free/Pro/Enterprise) | Billing | `PlanTier` (ValueObject) |
+| Activation | Ato de ativar Subscription após pagamento | Billing | `Subscription.Activate()` |
+
+## Estados e Transições
+
+| Estado | Descrição | Transições |
+|--------|-----------|-----------|
+| Draft | Criada, aguardando pagamento | → Active |
+| Active | Paga e em uso | → Suspended, Cancelled |
+| Cancelled | Encerrada definitivamente | (terminal) |
+
+## Invariants em Linguagem Natural
+
+- "Uma Subscription só pode ser Cancelada se estiver Active ou Suspended"
+- "Um Tenant não pode ter duas Subscriptions Active simultaneamente"
+```
+
+---
+
+## Regras de Nomenclatura
+
+1. Use termos do glossário como nomes de classe/método
+2. Eventos no passado: `OrderConfirmed`, não `OrderConfirmation`
+3. Commands no imperativo: `CreateOrder`, não `OrderCreation`
+4. Value Objects no substantivo: `Money`, `Email`
+5. Métodos do Aggregate espelham ações do negócio: `order.Confirm()`, não `order.SetStatusToConfirmed()`
+
+---
+
+## Quando Gerar
+
+- **Nível 2:** Seção inline no `spec.md` (Aggregate Blueprint)
+- **Nível 3:** Arquivo separado `1-design/ubiquitous-language.md` por BC
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/app-router.md

@@ -0,0 +1,123 @@
+# Next.js App Router Standard
+
+> **Scope:** frontend/nextjs/app-router
+> **Layer:** 2 (on keyword)
+> **Keywords:** next.js, app router, server component, client component, page, layout, route
+> **Load When:** editing files in `app/` or `features/` directories
+
+Next.js App Router with TypeScript strict mode. Server Components by default, Client Components only when interactivity is required.
+
+## Core Rules
+
+- ALWAYS default to Server Components — add `'use client'` only when needed
+- ALWAYS keep `app/` directory for routing only — no business logic in page files
+- NEVER put data fetching in Client Components when a Server Component can do it
+- NEVER use `useEffect` to fetch data — use Server Components or TanStack Query
+- ALWAYS co-locate loading/error UI: `loading.tsx`, `error.tsx` next to `page.tsx`
+- ALWAYS use TypeScript — no `.js` or `.jsx` files in the project
+
+## Server vs Client Components
+
+| Use Server Component | Use Client Component |
+|---------------------|---------------------|
+| Fetching from .NET API on load | onClick, onChange, form submit |
+| Rendering static or user-specific data | useState, useEffect, useRef |
+| Accessing backend environment variables | Browser APIs (localStorage, geolocation) |
+| SEO-critical content | TanStack Query hooks |
+| No interactivity needed | shadcn/ui interactive components |
+
+## Decision Tree
+
+```
+Does this component need user interaction (click, input, hover state)?
+  YES → 'use client'
+  NO  → Does it fetch data?
+          YES → Server Component (fetch directly)
+          NO  → Server Component (static)
+```
+
+## App Directory Structure
+
+```
+src/app/
+├── (auth)/
+│   ├── login/
+│   │   └── page.tsx           # Server Component — renders login form
+│   └── register/
+│       └── page.tsx
+├── (dashboard)/
+│   ├── layout.tsx             # Shared layout for dashboard routes
+│   ├── page.tsx               # Dashboard home
+│   └── users/
+│       ├── page.tsx           # User list (Server Component)
+│       ├── [id]/
+│       │   └── page.tsx       # User detail
+│       ├── loading.tsx        # Suspense fallback
+│       └── error.tsx          # Error boundary
+└── layout.tsx                 # Root layout — providers, fonts, metadata
+```
+
+## File Conventions
+
+| File | Purpose | Type |
+|------|---------|------|
+| `page.tsx` | Route segment UI | Server Component (default) |
+| `layout.tsx` | Shared UI wrapper | Server Component |
+| `loading.tsx` | Suspense fallback | Server Component |
+| `error.tsx` | Error boundary | **Must be Client Component** |
+| `not-found.tsx` | 404 page | Server Component |
+| `route.ts` | API route (avoid — use .NET API) | — |
+
+## Server Component Data Fetch Pattern
+
+```tsx
+// app/(dashboard)/users/page.tsx
+import { UserList } from '@/features/users/components/user-list';
+
+async function getUsers(): Promise<User[]> {
+  const res = await fetch(`${process.env.API_URL}/api/users`, {
+    next: { revalidate: 60 },
+  });
+  if (!res.ok) throw new Error('Failed to fetch users');
+  return res.json();
+}
+
+export default async function UsersPage() {
+  const users = await getUsers();
+  return <UserList initialUsers={users} />;
+}
+```
+
+## Root Layout — Required Providers
+
+```tsx
+// app/layout.tsx
+import { QueryProvider } from '@/lib/query-client';
+import { Toaster } from '@/components/ui/sonner';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="pt-BR">
+      <body>
+        <QueryProvider>
+          {children}
+          <Toaster />
+        </QueryProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| `'use client'` on every component | Only add when needed | Kills SSR benefits, bloats JS bundle |
+| `useEffect(() => { fetch(...) }, [])` | Server Component fetch or TanStack Query | Two renders, no caching, no SSR |
+| Business logic in `page.tsx` | Move to `features/` | pages are routes, not controllers |
+| `fetch` without error handling | Always check `res.ok` | Silent failures in production |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/standards/frontend/nextjs/components.md

@@ -0,0 +1,132 @@
+# Next.js Component Standards
+
+> **Scope:** frontend/nextjs/components
+> **Layer:** 2 (on keyword)
+> **Keywords:** component, shadcn, reusable, shared, ui, three-tier
+> **Load When:** creating or editing React components
+
+Three-tier component hierarchy. `components/ui/` is shadcn primitives (never edit). `components/` is composed shared (no business logic). `features/*/components/` is feature-scoped.
+
+## Core Rules
+
+- NEVER edit files in `components/ui/` — they are regenerated by shadcn CLI
+- NEVER import from `features/` inside `components/` — components know nothing about domain
+- ALWAYS compose shadcn primitives in `components/` instead of editing them
+- ALWAYS add `'use client'` only if the component uses hooks, events, or browser APIs
+- NEVER pass raw API data directly to a component — transform to props first
+
+## Three-Tier Hierarchy
+
+```
+Tier 1: components/ui/         ← shadcn/ui CLI output (DO NOT EDIT)
+           ↓ composed into
+Tier 2: components/            ← shared project components (no business logic)
+           ↓ used by
+Tier 3: features/*/components/ ← feature-scoped (knows about users, billing, etc.)
+```
+
+## Tier 1 — shadcn/ui Primitives
+
+```bash
+# Add shadcn components via CLI — never write them manually
+npx shadcn@latest add button card dialog form input table
+```
+
+If you need to change a shadcn component's behavior, wrap it — do not edit the source file.
+
+## Tier 2 — Shared Composed Components
+
+```tsx
+// components/data-table.tsx — composes shadcn Table + TanStack Table
+'use client';
+
+import {
+  Table, TableBody, TableCell, TableHead, TableHeader, TableRow
+} from '@/components/ui/table';
+import {
+  type ColumnDef, flexRender, getCoreRowModel, useReactTable
+} from '@tanstack/react-table';
+
+interface DataTableProps<TData> {
+  columns: ColumnDef<TData>[];
+  data: TData[];
+}
+
+export function DataTable<TData>({ columns, data }: DataTableProps<TData>) {
+  const table = useReactTable({ data, columns, getCoreRowModel: getCoreRowModel() });
+  return (
+    <Table>
+      <TableHeader>
+        {table.getHeaderGroups().map((hg) => (
+          <TableRow key={hg.id}>
+            {hg.headers.map((h) => (
+              <TableHead key={h.id}>
+                {flexRender(h.column.columnDef.header, h.getContext())}
+              </TableHead>
+            ))}
+          </TableRow>
+        ))}
+      </TableHeader>
+      <TableBody>
+        {table.getRowModel().rows.map((row) => (
+          <TableRow key={row.id}>
+            {row.getVisibleCells().map((cell) => (
+              <TableCell key={cell.id}>
+                {flexRender(cell.column.columnDef.cell, cell.getContext())}
+              </TableCell>
+            ))}
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+## Tier 3 — Feature Components
+
+```tsx
+// features/users/components/user-list.tsx
+'use client';
+
+import { DataTable } from '@/components/data-table';
+import { useUsers } from '@/features/users/hooks/use-users';
+import type { ColumnDef } from '@tanstack/react-table';
+import type { User } from '@/features/users/types/user.types';
+
+const columns: ColumnDef<User>[] = [
+  { accessorKey: 'name', header: 'Name' },
+  { accessorKey: 'email', header: 'Email' },
+];
+
+export function UserList() {
+  const { data: users = [], isLoading } = useUsers();
+  if (isLoading) return <div>Loading...</div>;
+  return <DataTable columns={columns} data={users} />;
+}
+```
+
+## Component Props Conventions
+
+```tsx
+interface UserCardProps {
+  user: User;
+  onEdit?: (id: string) => void;
+  className?: string; // Always allow className for Tailwind override
+}
+
+export function UserCard({ user, onEdit, className }: UserCardProps) {}
+```
+
+## Common Mistakes
+
+| Wrong | Right | Why |
+|-------|-------|-----|
+| Edit `components/ui/button.tsx` | Wrap in `components/action-button.tsx` | shadcn CLI overwrites it |
+| `import { useUsers } from '@/features/users'` in `components/` | Move to a feature component | Breaks tier isolation |
+| `'use client'` on all components | Only on interactive ones | Unnecessary client JS |
+| Pass raw fetch response as prop | Type and validate with Zod first | Runtime type safety |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*