@polymorphism-tech/morph-spec 1.0.0

package/content/.morph/examples/api-nextjs/spec.md

@@ -0,0 +1,399 @@
+# API .NET + Next.js - Especificação
+
+## 1. Visão Geral
+
+Arquitetura full-stack moderna com API .NET e frontend Next.js, seguindo boas práticas de separação de responsabilidades.
+
+### 1.1 Objetivos
+
+- Backend robusto com .NET Minimal APIs
+- Frontend moderno com Next.js App Router
+- Autenticação unificada via Clerk
+- Type-safety end-to-end
+- Deploy independente de cada camada
+
+### 1.2 Use Cases
+
+- Dashboards administrativos
+- Aplicações CRUD complexas
+- Sistemas que precisam de SEO (Next.js SSR)
+- Aplicações com múltiplos frontends (web, mobile)
+
+## 2. Requisitos Funcionais
+
+### 2.1 Backend (.NET API)
+
+| ID | Requisito |
+|----|-----------|
+| API-001 | Minimal APIs com OpenAPI/Swagger |
+| API-002 | Autenticação JWT via Clerk |
+| API-003 | Validação com FluentValidation |
+| API-004 | Paginação, filtros e ordenação |
+| API-005 | Rate limiting por usuário |
+| API-006 | Health checks (liveness + readiness) |
+| API-007 | Logging estruturado |
+| API-008 | CORS configurável |
+
+### 2.2 Frontend (Next.js)
+
+| ID | Requisito |
+|----|-----------|
+| WEB-001 | App Router com layouts aninhados |
+| WEB-002 | Server Components para dados estáticos |
+| WEB-003 | Client Components para interatividade |
+| WEB-004 | React Query para cache e mutations |
+| WEB-005 | Forms com React Hook Form + Zod |
+| WEB-006 | UI com Tailwind + shadcn/ui |
+| WEB-007 | Dark mode support |
+| WEB-008 | Loading states e error boundaries |
+
+### 2.3 Autenticação
+
+| ID | Requisito |
+|----|-----------|
+| AUTH-001 | SSO via Clerk |
+| AUTH-002 | Proteção de rotas (middleware) |
+| AUTH-003 | Token refresh automático |
+| AUTH-004 | Role-based access control |
+
+## 3. Requisitos Não-Funcionais
+
+### 3.1 Performance
+
+| ID | Requisito |
+|----|-----------|
+| PERF-001 | API response < 100ms (P95) |
+| PERF-002 | LCP < 2.5s (Core Web Vitals) |
+| PERF-003 | FID < 100ms |
+| PERF-004 | CLS < 0.1 |
+
+### 3.2 Segurança
+
+| ID | Requisito |
+|----|-----------|
+| SEC-001 | HTTPS obrigatório |
+| SEC-002 | CORS restrito a domínios conhecidos |
+| SEC-003 | Input validation em todos endpoints |
+| SEC-004 | SQL injection prevention (EF Core) |
+| SEC-005 | XSS prevention (React default) |
+
+## 4. Arquitetura da API
+
+### 4.1 Estrutura de Camadas
+
+```
+Api/
+├── Endpoints/          # Minimal API endpoints
+├── Middleware/         # Custom middlewares
+├── Filters/            # Exception filters
+└── Program.cs          # Entry point
+
+Application/
+├── Services/           # Business logic
+├── Validators/         # FluentValidation
+└── DTOs/               # Data transfer objects
+
+Domain/
+├── Entities/           # Domain models
+├── Interfaces/         # Repository contracts
+└── Enums/              # Domain enums
+
+Infrastructure/
+├── Data/               # DbContext
+├── Repositories/       # EF Core implementations
+└── Services/           # External service clients
+```
+
+### 4.2 Endpoint Pattern
+
+```csharp
+// Endpoints/ProductEndpoints.cs
+public static class ProductEndpoints
+{
+    public static void MapProductEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/products")
+            .WithTags("Products")
+            .RequireAuthorization();
+
+        group.MapGet("/", GetAll);
+        group.MapGet("/{id:int}", GetById);
+        group.MapPost("/", Create);
+        group.MapPut("/{id:int}", Update);
+        group.MapDelete("/{id:int}", Delete);
+    }
+
+    private static async Task<IResult> GetAll(
+        [AsParameters] PaginationQuery query,
+        IProductService service,
+        CancellationToken ct)
+    {
+        var result = await service.GetAllAsync(query, ct);
+        return Results.Ok(result);
+    }
+}
+```
+
+### 4.3 Pagination
+
+```csharp
+public record PaginationQuery(
+    int Page = 1,
+    int PageSize = 20,
+    string? SortBy = null,
+    bool SortDesc = false,
+    string? Search = null
+);
+
+public record PagedResult<T>(
+    IReadOnlyList<T> Items,
+    int TotalItems,
+    int Page,
+    int PageSize,
+    int TotalPages
+);
+```
+
+## 5. Arquitetura do Frontend
+
+### 5.1 Estrutura de Pastas
+
+```
+app/
+├── (auth)/
+│   ├── sign-in/[[...sign-in]]/page.tsx
+│   └── sign-up/[[...sign-up]]/page.tsx
+├── (dashboard)/
+│   ├── layout.tsx              # Dashboard layout
+│   ├── dashboard/page.tsx
+│   ├── products/
+│   │   ├── page.tsx            # List
+│   │   ├── [id]/page.tsx       # Detail
+│   │   └── new/page.tsx        # Create
+│   └── orders/
+├── api/                        # API routes (BFF)
+├── layout.tsx                  # Root layout
+└── page.tsx                    # Landing
+
+components/
+├── ui/                         # shadcn components
+├── forms/                      # Form components
+├── tables/                     # Table components
+└── shared/                     # Shared components
+
+hooks/
+├── use-products.ts
+├── use-orders.ts
+└── use-pagination.ts
+
+lib/
+├── api-client.ts               # Fetch wrapper
+├── query-client.ts             # React Query config
+└── utils.ts                    # Utility functions
+
+types/
+├── api.ts                      # API response types
+└── entities.ts                 # Domain types
+```
+
+### 5.2 Data Fetching Pattern
+
+```typescript
+// hooks/use-products.ts
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { apiClient } from "@/lib/api-client";
+import type { Product, CreateProductRequest } from "@/types/entities";
+
+export function useProducts(params?: PaginationParams) {
+  return useQuery({
+    queryKey: ["products", params],
+    queryFn: () => apiClient<PagedResult<Product>>("/api/products", { params }),
+  });
+}
+
+export function useProduct(id: number) {
+  return useQuery({
+    queryKey: ["products", id],
+    queryFn: () => apiClient<Product>(`/api/products/${id}`),
+    enabled: !!id,
+  });
+}
+
+export function useCreateProduct() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (data: CreateProductRequest) =>
+      apiClient<Product>("/api/products", {
+        method: "POST",
+        body: JSON.stringify(data),
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["products"] });
+    },
+  });
+}
+```
+
+### 5.3 Form Pattern
+
+```typescript
+// components/forms/product-form.tsx
+"use client";
+
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+import { useCreateProduct } from "@/hooks/use-products";
+
+const schema = z.object({
+  name: z.string().min(1, "Name is required"),
+  price: z.number().positive("Price must be positive"),
+  description: z.string().optional(),
+});
+
+type FormData = z.infer<typeof schema>;
+
+export function ProductForm() {
+  const { mutate, isPending } = useCreateProduct();
+  const form = useForm<FormData>({
+    resolver: zodResolver(schema),
+  });
+
+  const onSubmit = (data: FormData) => {
+    mutate(data);
+  };
+
+  return (
+    <form onSubmit={form.handleSubmit(onSubmit)}>
+      {/* Form fields */}
+    </form>
+  );
+}
+```
+
+## 6. Comunicação API
+
+### 6.1 API Client
+
+```typescript
+// lib/api-client.ts
+import { auth } from "@clerk/nextjs/server";
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL;
+
+interface FetchOptions extends RequestInit {
+  params?: Record<string, string | number | undefined>;
+}
+
+export async function apiClient<T>(
+  endpoint: string,
+  options: FetchOptions = {}
+): Promise<T> {
+  const { params, ...init } = options;
+
+  // Build URL with query params
+  const url = new URL(`${API_URL}${endpoint}`);
+  if (params) {
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== undefined) {
+        url.searchParams.append(key, String(value));
+      }
+    });
+  }
+
+  // Get auth token
+  const { getToken } = auth();
+  const token = await getToken();
+
+  const response = await fetch(url.toString(), {
+    ...init,
+    headers: {
+      "Content-Type": "application/json",
+      ...(token && { Authorization: `Bearer ${token}` }),
+      ...init.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new ApiError(response.status, error.title || "Request failed", error);
+  }
+
+  return response.json();
+}
+
+class ApiError extends Error {
+  constructor(
+    public status: number,
+    message: string,
+    public details?: unknown
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+```
+
+## 7. Configurações
+
+### 7.1 API (appsettings.json)
+
+```json
+{
+  "ConnectionStrings": {
+    "DefaultConnection": "Server=...;Database=...;"
+  },
+  "Clerk": {
+    "Authority": "https://your-clerk-domain.clerk.accounts.dev",
+    "SecretKey": "sk_..."
+  },
+  "Cors": {
+    "AllowedOrigins": ["http://localhost:3000", "https://your-domain.com"]
+  }
+}
+```
+
+### 7.2 Frontend (.env.local)
+
+```env
+NEXT_PUBLIC_API_URL=http://localhost:5000
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_...
+CLERK_SECRET_KEY=sk_...
+```
+
+## 8. Deploy
+
+### 8.1 Docker
+
+```dockerfile
+# API Dockerfile
+FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
+WORKDIR /app
+EXPOSE 8080
+
+FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
+WORKDIR /src
+COPY ["src/api/Api/Api.csproj", "Api/"]
+RUN dotnet restore "Api/Api.csproj"
+COPY src/api/ .
+RUN dotnet build "Api/Api.csproj" -c Release -o /app/build
+
+FROM build AS publish
+RUN dotnet publish "Api/Api.csproj" -c Release -o /app/publish
+
+FROM base AS final
+WORKDIR /app
+COPY --from=publish /app/publish .
+ENTRYPOINT ["dotnet", "Api.dll"]
+```
+
+### 8.2 Container Apps
+
+Dois Container Apps separados:
+- `app-api`: .NET API
+- `app-web`: Next.js (com output: standalone)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.morph/examples/api-nextjs/tasks.md

@@ -0,0 +1,168 @@
+# API .NET + Next.js - Tasks
+
+## Fase 1: Setup do Projeto
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T001 | Criar solution .NET | - | S |
+| T002 | Criar projeto Next.js | - | S |
+| T003 | Configurar Docker Compose | T001, T002 | M |
+| T004 | Configurar packages (.NET e npm) | T001, T002 | S |
+
+## Fase 2: Backend - Domain Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T005 | Criar BaseEntity | T001 | S |
+| T006 | Criar Product entity | T005 | S |
+| T007 | Criar Order e OrderItem entities | T005 | M |
+| T008 | Criar Customer entity | T005 | S |
+| T009 | Definir interfaces de repository | T005 | S |
+
+## Fase 3: Backend - Infrastructure Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T010 | Criar AppDbContext | T006-T008 | M |
+| T011 | Configurar EF Core mappings | T010 | M |
+| T012 | Criar ProductRepository | T010 | M |
+| T013 | Criar OrderRepository | T010 | M |
+| T014 | Criar CustomerRepository | T010 | M |
+| T015 | Criar migrations | T011 | S |
+
+## Fase 4: Backend - Application Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T016 | Criar DTOs | T006-T008 | M |
+| T017 | Criar ProductService | T012 | M |
+| T018 | Criar OrderService | T013 | M |
+| T019 | Criar CustomerService | T014 | M |
+| T020 | Criar validators (FluentValidation) | T016 | M |
+| T021 | Criar DashboardService | T017-T019 | M |
+
+## Fase 5: Backend - API Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T022 | Configurar Program.cs base | T001 | M |
+| T023 | Configurar autenticação JWT/Clerk | T022 | M |
+| T024 | Criar ProductEndpoints | T017, T020 | M |
+| T025 | Criar OrderEndpoints | T018, T020 | M |
+| T026 | Criar CustomerEndpoints | T019, T020 | M |
+| T027 | Criar DashboardEndpoints | T021 | S |
+| T028 | Configurar Swagger/OpenAPI | T024-T027 | S |
+| T029 | Configurar CORS | T022 | S |
+| T030 | Configurar Health Checks | T022 | S |
+
+## Fase 6: Frontend - Setup
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T031 | Configurar Tailwind CSS | T002 | S |
+| T032 | Instalar shadcn/ui components | T031 | M |
+| T033 | Configurar Clerk | T002 | M |
+| T034 | Criar API client | T002 | M |
+| T035 | Configurar React Query | T002 | S |
+
+## Fase 7: Frontend - Layout
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T036 | Criar root layout | T031 | M |
+| T037 | Criar dashboard layout | T036 | M |
+| T038 | Criar sidebar navigation | T037 | M |
+| T039 | Criar header com user menu | T033, T037 | M |
+
+## Fase 8: Frontend - Components
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T040 | Criar DataTable component | T032 | L |
+| T041 | Criar Form components | T032 | M |
+| T042 | Criar Card components | T032 | S |
+| T043 | Criar Modal/Dialog components | T032 | M |
+| T044 | Criar Loading/Error states | T032 | S |
+
+## Fase 9: Frontend - Hooks
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T045 | Criar useProducts hook | T034, T035 | M |
+| T046 | Criar useOrders hook | T034, T035 | M |
+| T047 | Criar useCustomers hook | T034, T035 | M |
+| T048 | Criar useDashboard hook | T034, T035 | S |
+| T049 | Criar usePagination hook | T035 | S |
+
+## Fase 10: Frontend - Pages
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T050 | Criar landing page | T036 | M |
+| T051 | Criar sign-in page | T033 | S |
+| T052 | Criar sign-up page | T033 | S |
+| T053 | Criar dashboard page | T048, T042 | M |
+| T054 | Criar products list page | T045, T040 | M |
+| T055 | Criar product detail page | T045, T042 | M |
+| T056 | Criar product form page | T045, T041 | M |
+| T057 | Criar orders list page | T046, T040 | M |
+| T058 | Criar order detail page | T046, T042 | M |
+
+## Fase 11: Infrastructure (IaC)
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T059 | Criar main.bicep | - | M |
+| T060 | Configurar Container App (API) | T059 | M |
+| T061 | Configurar Container App (Web) | T059 | M |
+| T062 | Configurar SQL Database | T059 | M |
+| T063 | Configurar App Insights | T059 | S |
+
+## Fase 12: Testes e Deploy
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T064 | Criar testes unitários backend | T017-T021 | L |
+| T065 | Criar testes de integração API | T024-T027 | L |
+| T066 | Criar testes E2E frontend | T050-T058 | L |
+| T067 | Configurar CI/CD pipeline | T059-T063 | M |
+
+## Checkpoints
+
+| Checkpoint | Após Tasks | Validação |
+|------------|------------|-----------|
+| CP1 | T004 | Projetos compilam |
+| CP2 | T015 | Database pronto |
+| CP3 | T021 | Services funcionando |
+| CP4 | T030 | API completa com Swagger |
+| CP5 | T039 | Layout pronto |
+| CP6 | T049 | Hooks funcionando |
+| CP7 | T058 | Frontend completo |
+| CP8 | T063 | IaC pronto |
+| CP9 | T067 | Deploy funcional |
+
+## Legenda
+
+- **S** = Small (< 1h)
+- **M** = Medium (1-3h)
+- **L** = Large (3-8h)
+
+## Ordem de Execução Paralela
+
+```
+Backend Path:
+T001 → T005 → T006-T009 → T010-T015 → T016-T021 → T022-T030
+
+Frontend Path (pode iniciar após T028):
+T002 → T031-T035 → T036-T039 → T040-T044 → T045-T049 → T050-T058
+
+IaC Path (pode iniciar independente):
+T059-T063
+
+Testes (após ambos paths):
+T064-T066 → T067
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.morph/examples/micro-saas/README.md

@@ -0,0 +1,125 @@
+# Micro-SaaS Example
+
+Exemplo completo de um Micro-SaaS com Blazor Server + Asaas para billing.
+
+## Stack
+
+| Camada | Tecnologia |
+|--------|------------|
+| **Frontend** | Blazor Server |
+| **Backend** | .NET 8 Minimal APIs |
+| **Database** | SQL Server / PostgreSQL |
+| **Auth** | Clerk ou Azure Identity |
+| **Billing** | Asaas (PIX, Boleto, Cartão) |
+| **Infra** | Azure Container Apps |
+
+## Features
+
+- Multi-tenancy com isolamento por tenant
+- Subscription management com Asaas
+- Dashboard administrativo
+- User management por tenant
+- Webhooks para eventos de pagamento
+
+## Estrutura
+
+```
+src/
+├── MicroSaaS.Domain/
+│   ├── Entities/
+│   │   ├── Tenant.cs
+│   │   ├── TenantUser.cs
+│   │   ├── Subscription.cs
+│   │   └── Plan.cs
+│   └── Interfaces/
+├── MicroSaaS.Infrastructure/
+│   ├── Data/
+│   ├── Repositories/
+│   └── Services/
+│       └── AsaasService.cs
+├── MicroSaaS.Application/
+│   ├── Commands/
+│   ├── Queries/
+│   └── Services/
+└── MicroSaaS.Web/
+    ├── Components/
+    │   ├── Layout/
+    │   ├── Pages/
+    │   └── Shared/
+    └── Program.cs
+```
+
+## Quick Start
+
+```bash
+# 1. Clone e configure
+dotnet new blazor -n MicroSaaS.Web -o src/MicroSaaS.Web
+cd src/MicroSaaS.Web
+
+# 2. Adicione packages
+dotnet add package Microsoft.EntityFrameworkCore.SqlServer
+dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
+
+# 3. Configure appsettings.json
+# Veja exemplo em appsettings.example.json
+
+# 4. Run migrations
+dotnet ef migrations add Initial
+dotnet ef database update
+
+# 5. Start
+dotnet run
+```
+
+## Fluxo de Onboarding
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App
+    participant Clerk
+    participant Asaas
+
+    User->>App: Acessa /signup
+    App->>Clerk: Cria usuário
+    Clerk-->>App: User ID
+    App->>App: Cria Tenant
+    App->>Asaas: Cria Customer
+    Asaas-->>App: Customer ID
+    App->>App: Associa User ao Tenant
+    App-->>User: Redirect /dashboard
+```
+
+## Fluxo de Subscription
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App
+    participant Asaas
+
+    User->>App: Seleciona plano
+    App->>Asaas: Cria Subscription
+    Asaas-->>App: Subscription ID
+    Asaas->>App: Webhook PAYMENT_CREATED
+    App->>App: Registra pagamento pendente
+    User->>Asaas: Realiza pagamento
+    Asaas->>App: Webhook PAYMENT_RECEIVED
+    App->>App: Ativa subscription
+    App-->>User: Acesso liberado
+```
+
+## Custos Estimados
+
+| Recurso | Tier | Custo/mês |
+|---------|------|-----------|
+| Container Apps | Consumption | ~$0 (scale-to-zero) |
+| SQL Database | Free 32GB | $0 |
+| Storage | LRS | ~$0.50 |
+| Asaas | Por transação | 2.99% + R$0.49 |
+
+**Total estimado**: < $5/mês para baixo volume
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*