---
name: saas-arquitetura
description: Skill S2.5 do Ecossistema SaaS Imperatriz. Aplica os 6 padrões Atlassian no contexto de SaaS com IA no centro. Lê SAAS-CONTEXT.md e SAAS-S2-FEATURES.md para gerar stack recomendada por camada, diagrama de blocos ASCII, mapa de segurança, estratégia de IA por feature e riscos top 5. Salva em .saas/SAAS-S2B-ARQUITETURA.md. Use quando o usuário pedir "arquitetura do meu SaaS", "qual stack usar", "como organizar os serviços", "segurança do SaaS", "como integrar IA sem acoplar", "blueprint técnico do meu produto", "decisões fundadoras de tech". Versão especializada para SaaS — a /arquitetura-imperatriz original continua disponível para projetos genéricos Node/TS.
---

# /saas-arquitetura

> Skill S2.5 do Ecossistema SaaS Imperatriz — Arquitetura Técnica do SaaS

Esta skill é a versão especializada para SaaS da `/arquitetura-imperatriz`. Aplica os 6 padrões Atlassian no contexto específico de um produto SaaS com IA no centro, lendo o contexto do projeto da pasta `.saas/` para não repetir perguntas já respondidas.

**Posição na cadeia:** Entre S2 (/ai-feature-map) e S3 (/gatilho-preguica-canvas)

**Uso isolado:** também pode ser usada standalone com qualquer projeto SaaS, mesmo sem a cadeia completa.

---

## FASE 0 — Leitura do Contexto do Projeto (OBRIGATÓRIO)

> **ANTES DE QUALQUER OUTRA AÇÃO:** leia os arquivos `.saas/` da pasta do projeto.

**Arquivos a ler:**

1. `.saas/SAAS-CONTEXT.md` — contexto-mãe do projeto
   → Use: NOME (nome do produto), SETOR (define stack comum do setor), MODELO (mensal/anual/usage afeta decisões de billing), REGULAÇÃO (define requisitos de segurança e compliance técnico)
   → Se não existe: instrua a rodar `/saas-context-doc` primeiro

2. `.saas/SAAS-S2-FEATURES.md` — output do /ai-feature-map
   → Use: FEATURE-PRINCIPAL (define o módulo core da arquitetura), TABELA-FEATURES coluna "Modelo IA" (define qual LLM/ML integrar e onde), TABELA-FEATURES coluna "Custo marginal" (afeta decisão de cache vs. realtime), TABELA-FEATURES coluna "Dependências" (revela integrações de terceiros necessárias), FEATURES-REGULATORIAS (módulos mandatórios de compliance)
   → Se não existe: avise e peça listagem mínima das features principais

**Campos que esta skill NÃO precisa perguntar (se os arquivos existem):**
- Stack tecnológica já usada → inferida do SETOR do SAAS-CONTEXT.md
- Features a arquitetar → SAAS-S2-FEATURES.md (já mapeadas com modelos IA)
- Modelo de negócio → SAAS-CONTEXT.md campo MODELO (define billing architecture)
- Regulação → SAAS-CONTEXT.md campo REGULAÇÃO (define security tier)
- Nome do produto → SAAS-CONTEXT.md campo NOME

---

## SOBRE ESTA SKILL

A `/saas-arquitetura` aplica **6 padrões Atlassian** ao contexto SaaS-com-IA:

1. **Separação de responsabilidades** — cada serviço tem UMA função; IA é um serviço separado, não acoplado à lógica de negócio
2. **Contratos de interface** — toda comunicação entre módulos via interface tipada; o modelo de IA pode mudar sem quebrar o resto
3. **Observabilidade first** — logs estruturados, traces distribuídos e métricas antes de qualquer feature
4. **Segurança por design** — autenticação, autorização, criptografia e rate limiting definidos na arquitetura, não adicionados depois
5. **Escalabilidade antecipada** — decisões de cache, fila e worker desde o início, mesmo que o MVP não precise ainda
6. **Portabilidade** — containerização e variáveis de ambiente desde o dia 1; nunca hardcode de config

---

## MODOS DE USO

### MODO 1 — `/saas-arquitetura` (padrão)
Gera a arquitetura técnica completa do SaaS a partir dos dados do `.saas/`.

**Entrega:**
- Stack recomendada por camada (Frontend / API / IA / Banco / Infra)
- Diagrama de blocos em ASCII (módulos + integrações)
- Mapa de segurança: autenticação, autorização, criptografia por módulo
- Decisões de escalabilidade: o que entra em fila, o que vai para cache, o que é realtime
- Integrações de IA: qual modelo por feature, estratégia de fallback, custos
- Riscos técnicos top 5 com mitigação

### MODO 2 — `/saas-arquitetura --stack`
Foca apenas na recomendação de stack, com justificativa por critério (custo, manutenção, ecossistema, IA-friendliness).

**Entrega:**
- Tabela comparativa de opções por camada
- Recomendação final com justificativa
- Dependências críticas de terceiros (APIs pagas, limites, SLAs)

### MODO 3 — `/saas-arquitetura --seguranca`
Foca no mapa de segurança e compliance técnico, especialmente para setores regulados.

**Entrega:**
- Tier de segurança requerido (Low/Medium/High/Critical) pelo setor
- Checklist de implementação de segurança por módulo
- Requisitos LGPD técnicos (criptografia em repouso, logs de acesso, direito ao esquecimento)
- Requisitos setoriais adicionais (CFM para saúde, BACEN para fintech, etc.)

### MODO 4 — `/saas-arquitetura --diagrama`
Gera apenas o diagrama de blocos ASCII expandido, pronto para documentar ou apresentar.

---

## WORKFLOW PADRÃO (Modo 1)

### Fase 1 — Briefing Arquitetural (apenas o que não está no .saas/)

Se os arquivos `.saas/` existirem com dados completos, pule direto para a Fase 2. Caso contrário, colete:

**Pergunta 1:** Qual a stack técnica que você já domina ou prefere usar?
(Ex: Node.js, Python, Next.js — ou deixa a IA recomendar)

**Pergunta 2:** Qual o volume esperado de usuários simultâneos no lançamento?
(Ex: até 100, até 1.000, 10.000+)

**Pergunta 3:** Existe alguma integração já definida que é obrigatória?
(Ex: Stripe, WhatsApp, Gemini, Supabase, etc.)

### Fase 2 — Análise e Geração

Com os dados do `.saas/` + perguntas acima, gere:

**BLOCO 1 — Stack por Camada**

| Camada | Tecnologia | Justificativa | Alternativa |
|--------|------------|---------------|-------------|
| Frontend | [rec] | [por quê] | [alt] |
| API/Backend | [rec] | [por quê] | [alt] |
| Banco Relacional | [rec] | [por quê] | [alt] |
| Cache | [rec] | [por quê] | [alt] |
| Fila/Worker | [rec] | [por quê] | [alt] |
| IA/LLM | [rec] | [por quê] | [alt] |
| Storage | [rec] | [por quê] | [alt] |
| Infra/Deploy | [rec] | [por quê] | [alt] |
| Monitoramento | [rec] | [por quê] | [alt] |

**BLOCO 2 — Diagrama de Blocos**

```
[FRONTEND]          [API GATEWAY]         [SERVIÇOS]
Next.js/React  →    Express/Fastify   →   Auth Service
                                      →   [FEATURE-PRINCIPAL] Service
                                      →   IA Orchestrator
                                               ↓
                                          [LLM Provider]
                                          (com fallback)

[BANCO]             [CACHE]               [FILA]
PostgreSQL/MySQL ←  Redis            ←    BullMQ/SQS
                    (sessions, IA)        (jobs longos)

[INFRA]             [OBSERVABILIDADE]
Docker/VPS      →   Logs estruturados
Nginx           →   Traces (OpenTelemetry)
                →   Métricas (Prometheus/Grafana)
```
(adaptar ao produto específico com base no SAAS-S2-FEATURES.md)

**BLOCO 3 — Mapa de Segurança**

Por módulo do produto:
- Autenticação: [método — JWT/session/OAuth]
- Autorização: [RBAC/ABAC/scopes por plano]
- Dados sensíveis: [criptografia em repouso / em trânsito]
- Rate limiting: [por tier de plano]
- Auditoria: [o que logar, por quanto tempo, retenção LGPD]

**BLOCO 4 — Estratégia de IA**

Por feature com IA (extraída da SAAS-S2-FEATURES.md):
- Modelo principal: [qual LLM/ML — claude-sonnet-4-6, gemini-1.5-flash, etc.]
- Estratégia de cache: [sim/não, TTL sugerido, chave de cache]
- Fallback: [modelo menor / resposta estática / fila assíncrona]
- Custo estimado por request: [R$ ou USD]
- Limite por plano: [tokens/dia ou requests/hora por tier]

**BLOCO 5 — Riscos Top 5**

| # | Risco | Probabilidade | Impacto | Mitigação |
|---|-------|---------------|---------|-----------|
| 1 | Custo de IA explode com escala | Alta | Alto | Cache agressivo + rate limit por plano |
| 2 | [risco específico do setor] | [prob] | [impacto] | [mitigação] |
| 3 | Vendor lock-in do LLM | Média | Alto | Interface abstrata + suporte a 2 provedores |
| 4 | LGPD: dado sensível vazado via IA | Média | Crítico | Mascaramento antes de enviar ao LLM |
| 5 | [risco específico do produto] | [prob] | [impacto] | [mitigação] |

### Fase 3 — Decisões Fundadoras

Liste as 5 decisões técnicas mais importantes que devem ser tomadas ANTES de escrever a primeira linha de código:

1. [Decisão] — [por que é fundadora] — [recomendação]
2. [Decisão] — [por que é fundadora] — [recomendação]
3. [Decisão] — [por que é fundadora] — [recomendação]
4. [Decisão] — [por que é fundadora] — [recomendação]
5. [Decisão] — [por que é fundadora] — [recomendação]

---

## SALVAR OUTPUT (fazer ao finalizar esta skill)

Ao concluir a arquitetura, salve como `.saas/SAAS-S2B-ARQUITETURA.md`:

```markdown
# SAAS-S2B-ARQUITETURA.md
> Gerado: [data] | via /saas-arquitetura

STACK-FRONTEND: [tecnologia escolhida]
STACK-API: [tecnologia escolhida]
STACK-BANCO: [tecnologia escolhida]
STACK-CACHE: [tecnologia escolhida]
STACK-FILA: [tecnologia escolhida]
STACK-IA: [modelo principal] + fallback: [modelo fallback]
STACK-INFRA: [VPS/Cloud + container]

DIAGRAMA-ASCII:
[diagrama completo copiado do Bloco 2, adaptado ao produto]

SEGURANCA-TIER: [Low/Medium/High/Critical]
LGPD-TECNICO: [requisitos técnicos específicos do setor]

IA-CACHE-STRATEGY: [sim/não] | TTL: [Xs] | chave: [campo que vira chave de cache]
IA-FALLBACK: [estratégia completa]
IA-CUSTO-POR-REQUEST: [estimativa em R$ ou USD]

RISCOS-TOP3:
  R1: [risco] → [mitigação]
  R2: [risco] → [mitigação]
  R3: [risco] → [mitigação]

DECISOES-FUNDADORAS:
  D1: [decisão] → [recomendação]
  D2: [decisão] → [recomendação]
  D3: [decisão] → [recomendação]
  D4: [decisão] → [recomendação]
  D5: [decisão] → [recomendação]
```

Após salvar: confirme "`.saas/SAAS-S2B-ARQUITETURA.md` salvo ✓" e então mostre o OUTPUT PARA PRÓXIMA SKILL.

---

## OUTPUT PARA PRÓXIMA SKILL

**Próxima skill recomendada:** /gatilho-preguica-canvas

**O que levar:** o `SAAS-S2B-ARQUITETURA.md` já define quais módulos existem e quais têm IA — use como base para mapear os gatilhos de preguiça por tela/serviço.

**Arquivo gerado:** `.saas/SAAS-S2B-ARQUITETURA.md`

**Campos mais importantes para S3 (/gatilho-preguica-canvas):**
- `STACK-IA` → define o vocabulário de domínio técnico que a IA reconhece nos gatilhos
- `IA-CACHE-STRATEGY` → gatilhos cacheados = resposta instantânea no UI; realtime = indicar loading state
- `DIAGRAMA-ASCII` → use os módulos/serviços como as "telas" para mapear gatilhos por funcionalidade
- `SEGURANCA-TIER` → gatilhos que tocam dados sensíveis precisam de confirmação humana obrigatória

**Nota:** A skill `/arquitetura-imperatriz` original continua disponível para projetos que não são SaaS ou para aprofundamento em qualquer arquitetura técnica Node/TS. Esta skill é complementar, não substituta.
