Fundação SaaS

Kit de fundação para projetos SaaS novos. Extraído dos padrões comprovados em um sistema real e confrontado com documentação oficial. Versão inicial: 0.4.5 · referência analisada em 2026-08-01.

Estado: pronto para um piloto real de perfil Standard, ainda não para ser tratado como golden path estável. O que falta está em 11-critica-e-plano-de-correcao.md.

Quero criar um projeto novo

Vá direto para INICIO.md — do zero ao primeiro commit, com um gerador de estrutura. O resto deste README é o mapa do kit.

npm run novo -- --destino ../meu-produto --nome "Meu Produto"

O que é isto

“Boilerplate” sugere uma cópia rígida; “padrão de projetos” sugere que uma única arquitetura serve para tudo. Esta fundação é uma paved road: um caminho seguro e rápido, com perfis e pontos de decisão explícitos.

Este repositório não é um produto e não depende de nenhum. Nasceu da extração dos aprendizados de um sistema real (Controle de Portarias), que aparece apenas como estudo de caso em 08: nenhum código, schema, permissão ou regra daquele domínio foi trazido para cá — e 08 tem uma seção explícita sobre o que não copiar de lá.

O que este kit resolve

• reduz o custo de descoberta e de contexto para humanos e LLMs;
• oferece arquitetura modular por domínio, SaaS multitenant e RBAC como opções prontas, sem misturar regras do produto de origem;
• cria uma cadeia única de documentação: produto, estado, arquitetura, domínio, segurança, operação e dívida;
• define gates proporcionais ao risco, com teste negativo para auth/RLS/PII;
• separa build, release e deploy, promovendo artefato imutável por commit;
• fornece templates copiáveis, checklists e um prompt de instanciação.

Como navegar

| Arquivo | Uso | | --- | --- | | INICIO.md | comece aqui: criar um projeto novo, passo a passo | | 00-diagnostico-e-critica.md | o que foi aprendido, recusado e melhorado | | 01-principios-e-decisoes.md | núcleo obrigatório e decisões variáveis | | 02-arquitetura-referencia.md | arquitetura de aplicação e fronteiras | | 03-multitenancy-auth-rbac.md | modelo SaaS, usuários, tenants e autorização | | 04-pipeline-qualidade-deploy.md | escada local, CI, CD, releases e rollback | | 05-seguranca-privacidade-operacoes.md | baseline de segurança, LGPD e operação | | 06-perfis-e-modulos-opcionais.md | Lite, Standard e Crítico; módulos opcionais | | 07-guia-de-adocao.md | roteiro para criar ou migrar um projeto | | 08-matriz-reuso-projeto-atual.md | o que copiar, adaptar ou não copiar | | 09-fontes.md | fontes oficiais e data de consulta | | 10-prompt-de-instanciacao.md | discovery portátil, exportação de perfil e prompt para gerar um repositório | | 11-critica-e-plano-de-correcao.md | revisão independente da v0.1.0 e correções pendentes | | templates/ | arquivos que entram no projeto novo | | docs/adr/ | decisões sobre o próprio kit | | tools/novo-projeto.mjs | gera o esqueleto de governança de um projeto novo | | tools/check-fundacao.mjs | lint do próprio kit: links, índice, versão e segredos | | package.json | atalhos sem dependências para novo, check, sync e publicação |

Assunto → capítulo dono

Não carregue o kit inteiro. Vá ao dono do assunto:

| Se a pergunta é sobre… | Leia | | --- | --- | | que decisões preciso tomar antes de codar | 01 + templates/PROJECT_PROFILE.md | | camadas, módulos, fronteiras e dependências | 02 | | tenant, papéis, permissões, RLS e testes negativos | 03 | | gates locais, CI, matriz de superfícies, deploy e release | 04 | | segurança, LGPD/privacidade, orçamento e operação | 05 | | o que instalar neste projeto e o que deixar de fora | 06 | | como começar (novo ou brownfield) e como manter o kit | 07 | | o que reusar do projeto de origem | 08 | | como se trabalha com IA no dia a dia | templates/CONTRIBUTING.md | | portabilidade entre Codex, Antigravity e Claude Code | templates/AGENTS.md § Adaptadores | | por que o kit está assim / o que ainda falta | 00 + 11 |

Início rápido

1. Escolha o perfil em 06-perfis-e-modulos-opcionais.md.
2. Preencha templates/PROJECT_PROFILE.md; ele é o pacote curto de contexto.
3. Registre as decisões marcadas como DECIDIR antes de instalar dependências.
4. Copie os templates do núcleo; copie módulos opcionais somente quando usados.
5. Gere o app com o gerador oficial da stack escolhida e fixe runtime/lockfile.
6. Instancie migrations e RLS localmente; nunca copie SQL de domínio do projeto de origem.
7. Ative CI em modo “sempre reporta”; torne os checks obrigatórios na branch.
8. Faça uma entrega vertical pequena e use-a para validar a fundação.

Regra de contexto para LLMs

Uma tarefa comum não deve carregar este diretório inteiro. A ordem é:

1. AGENTS.md do projeto novo;
2. PROJECT_PROFILE.md;
3. documento dono do assunto;
4. código/subgrafo estritamente relacionado;
5. histórico apenas quando a decisão atual não explicar o porquê.

Essa disciplina economiza tokens com seleção de contexto, não removendo testes, revisão ou evidência.

Limite da versão 0.1

Esta entrega é um kit documental e de governança copiável. Ela não contém um CLI gerador nem workflows executáveis porque versões de runtimes, Actions, Supabase e Vercel envelhecem. O passo seguinte recomendado é transformar os templates estáveis e os scripts realmente portáveis em um repositório-template versionado, com testes e releases próprios.