@polymorphism-tech/morph-spec 1.0.0

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

@@ -0,0 +1,236 @@
+# Micro-SaaS - Especificação
+
+## 1. Visão Geral
+
+Sistema Micro-SaaS multi-tenant com gestão de assinaturas e billing integrado via Asaas.
+
+### 1.1 Objetivos
+
+- Permitir criação de tenants isolados
+- Gerenciar assinaturas e pagamentos
+- Fornecer dashboard administrativo por tenant
+- Escalar de forma econômica (scale-to-zero)
+
+### 1.2 Personas
+
+| Persona | Descrição |
+|---------|-----------|
+| **Tenant Owner** | Cria e administra o tenant |
+| **Tenant Admin** | Gerencia usuários e configurações |
+| **Tenant Member** | Usuário regular do sistema |
+| **Platform Admin** | Administrador da plataforma (super admin) |
+
+## 2. Requisitos Funcionais
+
+### 2.1 Autenticação & Autorização
+
+| ID | Requisito |
+|----|-----------|
+| AUTH-001 | Login via Clerk (email, Google, Microsoft) |
+| AUTH-002 | Criação automática de tenant no primeiro login |
+| AUTH-003 | Convite de usuários para tenant existente |
+| AUTH-004 | Roles: Owner, Admin, Member, Viewer |
+| AUTH-005 | Permissões granulares por role |
+
+### 2.2 Multi-Tenancy
+
+| ID | Requisito |
+|----|-----------|
+| MT-001 | Isolamento completo de dados por tenant |
+| MT-002 | Subdomínio customizado (acme.app.com) |
+| MT-003 | Domínio customizado opcional |
+| MT-004 | Configurações independentes por tenant |
+| MT-005 | Branding básico (logo, cores) |
+
+### 2.3 Subscription & Billing
+
+| ID | Requisito |
+|----|-----------|
+| SUB-001 | Planos: Free, Starter, Pro, Enterprise |
+| SUB-002 | Ciclos: Mensal e Anual |
+| SUB-003 | Métodos: PIX, Boleto, Cartão de Crédito |
+| SUB-004 | Trial period de 14 dias |
+| SUB-005 | Upgrade/Downgrade de plano |
+| SUB-006 | Cancelamento com período de carência |
+| SUB-007 | Webhooks Asaas para status de pagamento |
+
+### 2.4 Dashboard
+
+| ID | Requisito |
+|----|-----------|
+| DASH-001 | Overview com métricas principais |
+| DASH-002 | Gestão de usuários do tenant |
+| DASH-003 | Histórico de pagamentos |
+| DASH-004 | Configurações do tenant |
+| DASH-005 | Upgrade de plano |
+
+## 3. Requisitos Não-Funcionais
+
+### 3.1 Performance
+
+| ID | Requisito |
+|----|-----------|
+| PERF-001 | Tempo de resposta < 200ms (P95) |
+| PERF-002 | Scale-to-zero quando inativo |
+| PERF-003 | Auto-scaling até 10 instâncias |
+
+### 3.2 Segurança
+
+| ID | Requisito |
+|----|-----------|
+| SEC-001 | HTTPS obrigatório |
+| SEC-002 | Validação de webhook signature |
+| SEC-003 | Rate limiting por tenant |
+| SEC-004 | Audit log de ações críticas |
+
+### 3.3 Disponibilidade
+
+| ID | Requisito |
+|----|-----------|
+| AVAIL-001 | SLA 99.5% |
+| AVAIL-002 | Health checks ativos |
+| AVAIL-003 | Retry automático em falhas |
+
+## 4. Planos e Limites
+
+| Feature | Free | Starter | Pro | Enterprise |
+|---------|------|---------|-----|------------|
+| Usuários | 2 | 5 | 20 | Ilimitado |
+| Storage | 100MB | 1GB | 10GB | 100GB |
+| API Requests/mês | 1K | 10K | 100K | Ilimitado |
+| Suporte | Community | Email | Priority | Dedicated |
+| Preço/mês | R$0 | R$49 | R$149 | R$499 |
+
+## 5. Integrações
+
+### 5.1 Asaas
+
+- Customer management
+- Subscription lifecycle
+- Payment processing
+- Webhook handling
+
+### 5.2 Clerk
+
+- User authentication
+- Session management
+- Organization (tenant) mapping
+
+## 6. Arquitetura
+
+### 6.1 Componentes
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        Blazor Server                         │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
+│  │   Pages     │  │ Components  │  │    Services         │  │
+│  │  /dashboard │  │ NavMenu     │  │ TenantContext       │  │
+│  │  /settings  │  │ DataGrid    │  │ SubscriptionService │  │
+│  │  /billing   │  │ Charts      │  │ UserService         │  │
+│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Application Layer                        │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │  Commands: CreateTenant, InviteUser, ChangePlan     │    │
+│  │  Queries: GetDashboard, GetUsers, GetPayments       │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                     Infrastructure                           │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  EF Core     │  │  Asaas       │  │  Clerk           │  │
+│  │  Repository  │  │  Client      │  │  Integration     │  │
+│  └──────────────┘  └──────────────┘  └──────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  SQL Database │  Azure Storage  │  Key Vault (secrets)     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 6.2 Tenant Resolution
+
+1. Subdomínio: `{tenant}.app.com`
+2. Header: `X-Tenant-ID`
+3. Route: `/tenant/{slug}/...`
+4. Claim: JWT tenant_id
+
+## 7. Modelo de Dados
+
+### 7.1 Entidades Principais
+
+```
+Tenant
+├── Id (int)
+├── Name (string)
+├── Slug (string) [unique]
+├── Status (Active, Suspended, Deleted)
+├── AsaasCustomerId (string)
+├── CurrentSubscription → Subscription
+└── Users → TenantUser[]
+
+TenantUser
+├── Id (int)
+├── TenantId → Tenant
+├── ExternalUserId (string) [Clerk ID]
+├── Email (string)
+├── Role (Owner, Admin, Member, Viewer)
+└── Status (Pending, Active, Inactive)
+
+Plan
+├── Id (int)
+├── Name (string)
+├── PriceMonthly (decimal)
+├── PriceYearly (decimal)
+├── Features (JSON)
+└── Limits (JSON)
+
+Subscription
+├── Id (int)
+├── TenantId → Tenant
+├── PlanId → Plan
+├── AsaasSubscriptionId (string)
+├── Status (Trial, Active, PastDue, Canceled)
+├── BillingCycle (Monthly, Yearly)
+├── CurrentPeriodStart (DateTime)
+└── CurrentPeriodEnd (DateTime)
+```
+
+## 8. APIs
+
+### 8.1 Tenant Management
+
+| Endpoint | Method | Descrição |
+|----------|--------|-----------|
+| `/api/tenants` | POST | Criar tenant |
+| `/api/tenants/{id}` | GET | Obter tenant |
+| `/api/tenants/{id}` | PUT | Atualizar tenant |
+| `/api/tenants/{id}/users` | GET | Listar usuários |
+| `/api/tenants/{id}/users` | POST | Convidar usuário |
+
+### 8.2 Subscription
+
+| Endpoint | Method | Descrição |
+|----------|--------|-----------|
+| `/api/subscriptions` | POST | Criar subscription |
+| `/api/subscriptions/{id}` | GET | Obter subscription |
+| `/api/subscriptions/{id}/upgrade` | POST | Upgrade de plano |
+| `/api/subscriptions/{id}/cancel` | POST | Cancelar |
+
+### 8.3 Webhooks
+
+| Endpoint | Method | Descrição |
+|----------|--------|-----------|
+| `/webhooks/asaas` | POST | Eventos Asaas |
+| `/webhooks/clerk` | POST | Eventos Clerk |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

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

@@ -0,0 +1,150 @@
+# Micro-SaaS - Tasks
+
+## Fase 1: Setup do Projeto
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T001 | Criar solution e projetos | - | S |
+| T002 | Configurar packages NuGet | T001 | S |
+| T003 | Criar estrutura de pastas | T001 | S |
+| T004 | Configurar appsettings.json | T001 | S |
+
+## Fase 2: Domain Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T005 | Criar BaseEntity | T001 | S |
+| T006 | Criar Tenant entity | T005 | M |
+| T007 | Criar TenantUser entity | T005 | M |
+| T008 | Criar Plan entity | T005 | S |
+| T009 | Criar Subscription entity | T005 | M |
+| T010 | Criar SubscriptionPayment entity | T005 | M |
+| T011 | Definir enums | T005 | S |
+
+## Fase 3: Infrastructure Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T012 | Criar AppDbContext | T006-T011 | M |
+| T013 | Configurar EF Core mappings | T012 | M |
+| T014 | Criar TenantRepository | T012 | M |
+| T015 | Criar TenantUserRepository | T012 | M |
+| T016 | Criar SubscriptionRepository | T012 | M |
+| T017 | Criar PlanRepository | T012 | S |
+| T018 | Criar PaymentRepository | T012 | M |
+| T019 | Implementar AsaasClient | T002 | L |
+| T020 | Implementar AsaasWebhookHandler | T019 | M |
+
+## Fase 4: Application Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T021 | Criar TenantService | T014, T015 | M |
+| T022 | Criar TenantUserService | T015 | M |
+| T023 | Criar SubscriptionService | T016, T019 | L |
+| T024 | Criar PlanService | T017 | S |
+| T025 | Criar DashboardService | T014-T018 | M |
+| T026 | Criar WebhookService | T020, T016, T018 | M |
+
+## Fase 5: Web Layer - Auth
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T027 | Configurar Clerk authentication | T002 | M |
+| T028 | Implementar TenantContext | T014 | M |
+| T029 | Criar middleware de tenant resolution | T028 | M |
+| T030 | Configurar policies de autorização | T027 | S |
+
+## Fase 6: Web Layer - Components
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T031 | Criar MainLayout | T027 | M |
+| T032 | Criar NavMenu | T031 | S |
+| T033 | Criar componentes shared (DataGrid, Card, etc) | T031 | M |
+
+## Fase 7: Web Layer - Pages
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T034 | Criar página Dashboard | T025, T031 | M |
+| T035 | Criar página Users | T022, T033 | M |
+| T036 | Criar página Settings | T021, T033 | M |
+| T037 | Criar página Billing | T023, T033 | L |
+| T038 | Criar página Plans | T024, T033 | M |
+
+## Fase 8: Web Layer - APIs
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T039 | Criar endpoints Tenant | T021 | M |
+| T040 | Criar endpoints Users | T022 | M |
+| T041 | Criar endpoints Subscription | T023 | M |
+| T042 | Criar endpoint Webhook | T026 | M |
+
+## Fase 9: Infrastructure (IaC)
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T043 | Criar main.bicep | - | M |
+| T044 | Configurar Container App | T043 | M |
+| T045 | Configurar SQL Database | T043 | M |
+| T046 | Configurar Key Vault | T043 | S |
+| T047 | Configurar App Insights | T043 | S |
+
+## Fase 10: Testes e Documentação
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T048 | Criar testes unitários Domain | T006-T011 | M |
+| T049 | Criar testes integração Services | T021-T026 | L |
+| T050 | Criar testes E2E | T034-T042 | L |
+| T051 | Documentar APIs (OpenAPI) | T039-T042 | M |
+
+## Checkpoints
+
+| Checkpoint | Após Tasks | Validação |
+|------------|------------|-----------|
+| CP1 | T004 | Projeto compila |
+| CP2 | T011 | Domain layer completo |
+| CP3 | T020 | Infrastructure layer completo |
+| CP4 | T026 | Application layer completo |
+| CP5 | T033 | Layout e componentes prontos |
+| CP6 | T038 | Todas as páginas funcionando |
+| CP7 | T042 | APIs funcionando |
+| CP8 | T047 | IaC pronto para deploy |
+| CP9 | T051 | Projeto completo |
+
+## Legenda
+
+- **S** = Small (< 1h)
+- **M** = Medium (1-3h)
+- **L** = Large (3-8h)
+
+## Ordem de Execução Recomendada
+
+```
+T001 → T002 → T003 → T004 (CP1)
+  ↓
+T005 → T006-T011 (CP2)
+  ↓
+T012 → T013 → T014-T020 (CP3)
+  ↓
+T021-T026 (CP4)
+  ↓
+T027 → T028 → T029 → T030
+  ↓
+T031 → T032 → T033 (CP5)
+  ↓
+T034-T038 (CP6)
+  ↓
+T039-T042 (CP7)
+  ↓
+T043-T047 (CP8)
+  ↓
+T048-T051 (CP9)
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.morph/examples/multi-agent/README.md

@@ -0,0 +1,309 @@
+# Multi-Agent Example
+
+Exemplo de sistema multi-agente usando Microsoft Agent Framework com Semantic Kernel.
+
+## Stack
+
+| Camada | Tecnologia |
+|--------|------------|
+| **Framework** | Microsoft Agent Framework |
+| **AI Kernel** | Semantic Kernel |
+| **LLM** | Azure OpenAI / OpenAI |
+| **Orchestration** | Agent Orchestrator |
+| **Storage** | Azure Cosmos DB / SQL |
+| **Infra** | Azure Container Apps |
+
+## Visão Geral
+
+Sistema de agentes cooperativos que trabalham juntos para resolver tarefas complexas.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User Request                              │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Orchestrator Agent                        │
+│  - Analisa requisição                                       │
+│  - Decompõe em subtarefas                                   │
+│  - Delega para agentes especialistas                        │
+│  - Consolida resultados                                     │
+└─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
+│  Research Agent  │ │  Analysis Agent  │ │  Writing Agent   │
+│  - Web search    │ │  - Data analysis │ │  - Text generation│
+│  - Doc retrieval │ │  - Comparisons   │ │  - Summaries     │
+│  - RAG           │ │  - Insights      │ │  - Reports       │
+└──────────────────┘ └──────────────────┘ └──────────────────┘
+              │               │               │
+              └───────────────┼───────────────┘
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    Consolidated Response                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Estrutura do Projeto
+
+```
+src/
+├── MultiAgent.Core/
+│   ├── Agents/
+│   │   ├── OrchestratorAgent.cs
+│   │   ├── ResearchAgent.cs
+│   │   ├── AnalysisAgent.cs
+│   │   └── WritingAgent.cs
+│   ├── Plugins/
+│   │   ├── WebSearchPlugin.cs
+│   │   ├── DocumentPlugin.cs
+│   │   └── DataAnalysisPlugin.cs
+│   ├── Memory/
+│   │   ├── ConversationMemory.cs
+│   │   └── SemanticMemory.cs
+│   └── Orchestration/
+│       ├── TaskDecomposer.cs
+│       └── ResultAggregator.cs
+│
+├── MultiAgent.Infrastructure/
+│   ├── Services/
+│   │   ├── AzureOpenAIService.cs
+│   │   └── EmbeddingService.cs
+│   └── Storage/
+│       ├── ConversationStore.cs
+│       └── VectorStore.cs
+│
+└── MultiAgent.Api/
+    ├── Endpoints/
+    │   ├── ChatEndpoints.cs
+    │   └── AgentEndpoints.cs
+    └── Program.cs
+```
+
+## Quick Start
+
+```bash
+# 1. Configure Azure OpenAI
+# Crie um recurso Azure OpenAI e configure:
+# - Deployment para gpt-4
+# - Deployment para text-embedding-ada-002
+
+# 2. Configure appsettings.json
+cp appsettings.example.json appsettings.json
+# Edite com suas credenciais
+
+# 3. Run
+cd src/MultiAgent.Api
+dotnet run
+
+# 4. Test
+curl -X POST http://localhost:5000/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "Compare the top 3 cloud providers for a SaaS startup"}'
+```
+
+## Agentes
+
+### 1. Orchestrator Agent
+
+O agente principal que coordena todos os outros.
+
+**Responsabilidades**:
+- Analisar a intenção do usuário
+- Decompor tarefas complexas
+- Delegar para agentes especialistas
+- Consolidar respostas
+
+### 2. Research Agent
+
+Especialista em busca e recuperação de informações.
+
+**Capabilities**:
+- Web search (Bing API)
+- Document retrieval (RAG)
+- Knowledge base queries
+
+### 3. Analysis Agent
+
+Especialista em análise de dados e comparações.
+
+**Capabilities**:
+- Data analysis
+- Trend identification
+- Comparative analysis
+- Insight generation
+
+### 4. Writing Agent
+
+Especialista em geração de conteúdo.
+
+**Capabilities**:
+- Text summarization
+- Report generation
+- Content formatting
+- Translation
+
+## Plugins
+
+### WebSearchPlugin
+
+```csharp
+[KernelFunction("search_web")]
+[Description("Search the web for information")]
+public async Task<string> SearchWebAsync(
+    [Description("The search query")] string query,
+    [Description("Number of results")] int maxResults = 5)
+{
+    // Implementação com Bing Search API
+}
+```
+
+### DocumentPlugin
+
+```csharp
+[KernelFunction("retrieve_documents")]
+[Description("Retrieve relevant documents from the knowledge base")]
+public async Task<IEnumerable<Document>> RetrieveDocumentsAsync(
+    [Description("The query to search for")] string query,
+    [Description("Maximum documents to return")] int limit = 3)
+{
+    // Implementação com Vector Store
+}
+```
+
+## Fluxo de Execução
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant API
+    participant Orchestrator
+    participant Research
+    participant Analysis
+    participant Writing
+
+    User->>API: "Compare cloud providers for SaaS"
+    API->>Orchestrator: Process request
+
+    Orchestrator->>Orchestrator: Decompose task
+    Note over Orchestrator: 1. Research providers<br/>2. Analyze features<br/>3. Write comparison
+
+    Orchestrator->>Research: Get info on AWS, Azure, GCP
+    Research->>Research: Web search + RAG
+    Research-->>Orchestrator: Provider data
+
+    Orchestrator->>Analysis: Compare features, pricing
+    Analysis->>Analysis: Analyze data
+    Analysis-->>Orchestrator: Comparison insights
+
+    Orchestrator->>Writing: Create comparison report
+    Writing->>Writing: Generate formatted report
+    Writing-->>Orchestrator: Final report
+
+    Orchestrator-->>API: Consolidated response
+    API-->>User: Comparison report
+```
+
+## Configuração
+
+### appsettings.json
+
+```json
+{
+  "AzureOpenAI": {
+    "Endpoint": "https://your-resource.openai.azure.com/",
+    "ApiKey": "your-api-key",
+    "ChatDeployment": "gpt-4",
+    "EmbeddingDeployment": "text-embedding-ada-002"
+  },
+  "BingSearch": {
+    "ApiKey": "your-bing-api-key",
+    "Endpoint": "https://api.bing.microsoft.com/v7.0/search"
+  },
+  "VectorStore": {
+    "Type": "InMemory",
+    "CosmosDbEndpoint": "",
+    "CosmosDbKey": ""
+  }
+}
+```
+
+## Custos Estimados
+
+| Recurso | Tier | Custo Estimado |
+|---------|------|----------------|
+| Azure OpenAI (GPT-4) | Pay-per-token | ~$0.03/1K tokens |
+| Azure OpenAI (Embeddings) | Pay-per-token | ~$0.0001/1K tokens |
+| Bing Search API | S1 | $7/1K transactions |
+| Container Apps | Consumption | ~$0-10/mês |
+| Cosmos DB (opcional) | Serverless | ~$0-5/mês |
+
+**Nota**: Custos variam significativamente com uso. Para desenvolvimento, use modelos menores (GPT-3.5-turbo).
+
+## Extensibilidade
+
+### Adicionando um Novo Agente
+
+```csharp
+public class CustomAgent : BaseAgent
+{
+    public CustomAgent(Kernel kernel) : base(kernel)
+    {
+        SystemPrompt = """
+            You are a specialized agent for [purpose].
+            Your capabilities include:
+            - [capability 1]
+            - [capability 2]
+            """;
+    }
+
+    public override async Task<AgentResponse> ProcessAsync(AgentRequest request)
+    {
+        // Implementação específica
+    }
+}
+```
+
+### Adicionando um Novo Plugin
+
+```csharp
+public class CustomPlugin
+{
+    [KernelFunction("custom_function")]
+    [Description("Description of what this function does")]
+    public async Task<string> CustomFunctionAsync(
+        [Description("Parameter description")] string param)
+    {
+        // Implementação
+    }
+}
+```
+
+## Padrões de Comunicação
+
+### 1. Request-Response
+
+Agente recebe request, processa e retorna response.
+
+### 2. Pub-Sub (Event-Driven)
+
+Agentes publicam eventos que outros agentes podem consumir.
+
+### 3. Handoff
+
+Agente transfere contexto completo para outro agente.
+
+## Boas Práticas
+
+1. **Prompts claros**: Defina system prompts específicos para cada agente
+2. **Fallbacks**: Implemente fallbacks quando um agente falhar
+3. **Rate limiting**: Controle chamadas à API para evitar throttling
+4. **Logging**: Log todas as interações para debugging
+5. **Cost tracking**: Monitore tokens consumidos
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*