forjajs 5.0.1 → 5.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (268) hide show
  1. package/CHANGELOG.md +114 -2
  2. package/README.md +40 -5
  3. package/README.pt-BR.md +42 -4
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/apps/cli/src/index.d.ts +0 -1
  50. package/dist/apps/cli/src/index.js +43 -32
  51. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  52. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  53. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  54. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  55. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  56. package/dist/apps/server/src/forja-nest.module.js +55 -0
  57. package/dist/apps/server/src/main.d.ts +21 -4
  58. package/dist/apps/server/src/main.js +79 -57
  59. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  60. package/dist/apps/server/src/task-planning-service.js +195 -0
  61. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  62. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  63. package/dist/bin/forja.js +3 -2
  64. package/dist/bin/init-project.js +1 -0
  65. package/dist/lib/agent-evals.d.ts +138 -0
  66. package/dist/lib/agent-evals.js +349 -0
  67. package/dist/lib/cli-output.js +14 -2
  68. package/dist/lib/code-context.d.ts +33 -5
  69. package/dist/lib/code-context.js +70 -5
  70. package/dist/lib/context-builder.d.ts +49 -4
  71. package/dist/lib/context-builder.js +114 -47
  72. package/dist/lib/core/coverage-gate.d.ts +59 -0
  73. package/dist/lib/core/coverage-gate.js +58 -0
  74. package/dist/lib/core/doc-graph.d.ts +38 -0
  75. package/dist/lib/core/doc-graph.js +83 -0
  76. package/dist/lib/core/health.js +286 -5
  77. package/dist/lib/core/journey.js +36 -0
  78. package/dist/lib/core/registry.js +81 -6
  79. package/dist/lib/docs-reference.d.ts +35 -0
  80. package/dist/lib/docs-reference.js +57 -0
  81. package/dist/lib/generators/memory-generator.d.ts +0 -11
  82. package/dist/lib/generators/memory-generator.js +5 -161
  83. package/dist/lib/generators/readme-generator.js +1 -1
  84. package/dist/lib/llm/json-output.d.ts +14 -0
  85. package/dist/lib/llm/json-output.js +77 -0
  86. package/dist/lib/project-wiring.d.ts +8 -0
  87. package/dist/lib/project-wiring.js +79 -3
  88. package/dist/lib/session-memory.d.ts +38 -0
  89. package/dist/lib/session-memory.js +206 -0
  90. package/dist/lib/spec-trace.d.ts +46 -0
  91. package/dist/lib/spec-trace.js +184 -0
  92. package/dist/lib/validators/structure-validator.js +0 -1
  93. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  94. package/dist/packages/adapter-nest/src/index.js +59 -1
  95. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  96. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  97. package/dist/packages/context/src/index.d.ts +2 -0
  98. package/dist/packages/context/src/index.js +36 -15
  99. package/dist/packages/contracts/src/index.d.ts +64 -0
  100. package/dist/packages/core/src/index.d.ts +9 -1
  101. package/dist/packages/core/src/index.js +28 -3
  102. package/dist/packages/graph/src/index.js +14 -5
  103. package/dist/packages/llm/src/index.js +12 -2
  104. package/dist/packages/mcp/src/index.d.ts +8 -0
  105. package/dist/packages/mcp/src/index.js +12 -1
  106. package/dist/packages/observability/src/index.d.ts +11 -0
  107. package/dist/packages/observability/src/index.js +3 -0
  108. package/dist/packages/orchestration/src/index.d.ts +15 -1
  109. package/dist/packages/orchestration/src/index.js +127 -21
  110. package/dist/packages/planner/src/index.d.ts +7 -1
  111. package/dist/packages/planner/src/index.js +67 -10
  112. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  113. package/dist/packages/planner/src/proposal-store.js +109 -0
  114. package/dist/packages/policy/src/index.d.ts +9 -16
  115. package/dist/packages/policy/src/index.js +114 -31
  116. package/dist/packages/runtime/src/index.d.ts +16 -2
  117. package/dist/packages/runtime/src/index.js +176 -61
  118. package/dist/scripts/build-smart-context.d.ts +2 -0
  119. package/dist/scripts/build-smart-context.js +12 -3
  120. package/dist/scripts/code-context.d.ts +3 -1
  121. package/dist/scripts/code-context.js +13 -3
  122. package/dist/scripts/coverage-gate.d.ts +2 -0
  123. package/dist/scripts/coverage-gate.js +101 -0
  124. package/dist/scripts/eval-agents.d.ts +11 -0
  125. package/dist/scripts/eval-agents.js +96 -0
  126. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  127. package/dist/scripts/gen-commands-doc.js +18 -0
  128. package/dist/scripts/hook-session-memory.d.ts +9 -0
  129. package/dist/scripts/hook-session-memory.js +20 -0
  130. package/dist/scripts/hook-session-start.js +34 -0
  131. package/dist/scripts/llm-fit.js +23 -1
  132. package/dist/scripts/spec-trace.d.ts +10 -0
  133. package/dist/scripts/spec-trace.js +73 -0
  134. package/dist/scripts/sync-universal-memory.js +69 -4
  135. package/dist/scripts/token-benchmark.d.ts +33 -1
  136. package/dist/scripts/token-benchmark.js +179 -5
  137. package/dist/scripts/token-economy.js +3 -1
  138. package/dist/scripts/tools-doctor.d.ts +16 -1
  139. package/dist/scripts/tools-doctor.js +58 -17
  140. package/docs/commands.md +155 -0
  141. package/docs/fluxo.md +11 -7
  142. package/docs/init-project.md +3 -1
  143. package/docs/llm-fit-loop.md +36 -0
  144. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  145. package/docs/produto/factsheet-marketing.md +7 -5
  146. package/docs/produto/roteiro-demo.md +14 -5
  147. package/docs/quick-reference.md +3 -3
  148. package/docs/token-optimization.md +10 -6
  149. package/memory/90-decisions/0088-templates-validados.md +3 -0
  150. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  151. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  152. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  153. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  154. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  155. package/package.json +4 -2
  156. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  157. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  158. package/specs/memoria-de-sessao/spec.md +48 -0
  159. package/specs/skills-do-projeto/plan.md +40 -0
  160. package/specs/skills-do-projeto/spec.md +63 -0
  161. package/specs/skills-do-projeto/tasks.md +27 -0
  162. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  163. package/specs/v6-core-consolidation/spec.md +70 -0
  164. package/specs/v6-docs-drift/spec.md +85 -0
  165. package/specs/v6-quality-gates/spec.md +99 -0
  166. package/specs/v6-token-economy/spec.md +84 -0
  167. package/templates/evals/agents/adr.json +25 -0
  168. package/templates/evals/agents/memoria.json +32 -0
  169. package/templates/evals/agents/proxima-acao.json +29 -0
  170. package/templates/evals/agents/spec-nova.json +26 -0
  171. package/templates/evals/agents/teste-do-criterio.json +29 -0
  172. package/templates/project/AGENTS.md +16 -0
  173. package/templates/project/CLAUDE.md +3 -2
  174. package/templates/project/agents/context-engineer.md +3 -0
  175. package/templates/project/agents/governance.md +3 -0
  176. package/templates/project/agents/marketing.md +3 -0
  177. package/templates/project/agents/orchestrator.md +3 -0
  178. package/templates/project/agents/product.md +3 -0
  179. package/templates/project/agents/sdd-architect.md +3 -0
  180. package/templates/project/skills/README.md +14 -0
  181. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  182. package/templates/project/skills/api-design/SKILL.md +77 -0
  183. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  184. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  185. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  186. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  187. package/templates/project/skills/commit-message/SKILL.md +143 -0
  188. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  189. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  190. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  191. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  192. package/templates/project/skills/event-storming/SKILL.md +95 -0
  193. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  194. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  195. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  196. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  197. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  198. package/templates/project/skills/observability/SKILL.md +93 -0
  199. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  200. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  201. package/templates/project/skills/pull-request/SKILL.md +101 -0
  202. package/templates/project/skills/query-performance/SKILL.md +83 -0
  203. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  204. package/templates/project/skills/release-notes/SKILL.md +87 -0
  205. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  206. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  207. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  208. package/templates/project/skills/testing/SKILL.md +109 -0
  209. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  210. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  211. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  212. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  213. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  214. package/templates/project/skills/web-performance/SKILL.md +72 -0
  215. package/boilerplates/02-saas-starter/.env.example +0 -25
  216. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  217. package/boilerplates/02-saas-starter/INFO.md +0 -252
  218. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  219. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  220. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  221. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  222. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  223. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  224. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  225. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  226. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  227. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  228. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  229. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  230. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  231. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  232. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  233. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  234. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  235. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  236. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  237. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  238. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  239. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  240. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  241. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  242. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  243. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  244. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  245. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  246. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  247. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  248. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  249. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  250. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  251. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  252. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  253. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  254. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  255. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  256. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  257. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  258. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  259. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  260. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  261. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  262. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  263. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  264. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  265. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  266. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  267. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  268. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -1,195 +0,0 @@
1
- # Personas
2
-
3
- ## 1. Sarah — SaaS Founder
4
-
5
- **Perfil**
6
- - Age: 32, Tech co-founder
7
- - Background: Full-stack engineer, 2 startups anteriores
8
- - Pain: "Não quero gastar 6 meses em infrastructure"
9
- - Goal: Lançar em produção em 4 semanas
10
-
11
- **Needs**
12
- - Autenticação que funciona out-of-box
13
- - Subscriptions com planos escaláveis
14
- - Multi-tenant architecture
15
- - Documentação clara
16
- - TypeScript (evitar bugs)
17
-
18
- **Success Metric**
19
- - Implementou 3 planos
20
- - 10 clientes beta
21
- - Churn < 5%
22
-
23
- ---
24
-
25
- ## 2. Dev — Backend Engineer
26
-
27
- **Perfil**
28
- - Age: 28, Senior backend engineer
29
- - Background: 5 anos Node.js + NestJS
30
- - Pain: "Não quero ver mais boilerplates ruins"
31
- - Goal: Código limpo, patterns claros, fácil manutenção
32
-
33
- **Needs**
34
- - Patterns SOLID applicados
35
- - Dependency injection funcionando
36
- - Tests E2E que fazem sentido
37
- - Modular, fácil de estender
38
- - Memory/context bem documentada
39
-
40
- **Success Metric**
41
- - Adicionou 2 novos domínios (messaging, analytics)
42
- - 0 bugs em produção
43
- - Contribui PRs de volta
44
-
45
- ---
46
-
47
- ## 3. Ops — DevOps Engineer
48
-
49
- **Perfil**
50
- - Age: 31, Platform engineer
51
- - Background: Kubernetes, Terraform, observability
52
- - Pain: "Quero infra como código, não setup manual"
53
- - Goal: Deploy automatizado, observável, resiliente
54
-
55
- **Needs**
56
- - Docker-compose funcional
57
- - Env vars documentadas
58
- - Health checks implementados
59
- - Logging estruturado (JSON)
60
- - Prometheus metrics
61
- - Error tracking hooks
62
-
63
- **Success Metric**
64
- - Deploy em <5 mins
65
- - Uptime > 99.9%
66
- - Issue detection < 5min from error
67
-
68
- ---
69
-
70
- ## 4. PM — Product Manager
71
-
72
- **Perfil**
73
- - Age: 29, Fintech PM
74
- - Background: Produto, não técnico
75
- - Pain: "Não entendo o código, mas preciso trackear features"
76
- - Goal: Dashboard de features, roadmap claro, metrics
77
-
78
- **Needs**
79
- - Memory/roadmap.md atualizado
80
- - Métricas de negócio (MRR, churn)
81
- - Feature flags (on/off sem deploy)
82
- - User behavior tracking
83
- - Relatórios automáticos
84
-
85
- **Success Metric**
86
- - Roadmap 3 meses planejado
87
- - Decision-making em <1 dia
88
- - Feature adoption tracking
89
-
90
- ---
91
-
92
- ## 5. Compliance — Security Officer
93
-
94
- **Perfil**
95
- - Age: 45, Compliance officer
96
- - Background: Banking, healthcare
97
- - Pain: "Preciso de audit trails e GDPR compliance"
98
- - Goal: Segurança, compliance, sem falsos positivos
99
-
100
- **Needs**
101
- - JWT + MFA ready (hooks)
102
- - Tenant isolation garantida
103
- - Audit logging completo
104
- - Data export (GDPR)
105
- - Encryption at rest (hooks)
106
- - PII redaction em logs
107
-
108
- **Success Metric**
109
- - SOC2 readiness check: ✅
110
- - 0 security issues em audit
111
- - Compliance dashboard
112
-
113
- ---
114
-
115
- ## User Journey Map: Sarah (Founder)
116
-
117
- ```
118
- Day 0: Descobre SaaS Starter
119
- → Lê README
120
- → Vê que tem auth + subscriptions
121
- → Decision: "Vou tentar"
122
-
123
- Day 1: Setup
124
- → Clone repo
125
- → docker-compose up
126
- → npm run seed
127
- → Tests passam ✅
128
- → Decision: "Funciona!"
129
-
130
- Days 2-3: Customização
131
- → Estuda patterns.md
132
- → Adiciona 3º plano customizado
133
- → Cria 2 novos endpoints
134
- → Tests continuam passando ✅
135
- → Decision: "Posso fazer"
136
-
137
- Days 4-7: Integração
138
- → Integra frontend
139
- → Testa flow signup → upgrade
140
- → Deploy em staging
141
- → QA aprova
142
- → Decision: "Produção amanhã"
143
-
144
- Week 2: Produção
145
- → Deploy em prod
146
- → 5 clientes criados
147
- → Monitor metrics
148
- → 1 bug encontrado, fix in 30min
149
- → Success: "É rápido e fácil"
150
- ```
151
-
152
- ---
153
-
154
- ## Feature Prioritization (por persona)
155
-
156
- | Feature | Sarah | Dev | Ops | PM | Compliance |
157
- |---------|-------|-----|-----|----|----|
158
- | JWT Auth | 🔴 | 🟡 | 🟢 | 🟢 | 🔴 |
159
- | Subscriptions | 🔴 | 🟡 | 🟢 | 🔴 | 🟢 |
160
- | Mock Billing | 🔴 | 🟢 | 🟢 | 🟡 | 🟡 |
161
- | Multi-tenant | 🟡 | 🔴 | 🟢 | 🟡 | 🔴 |
162
- | E2E Tests | 🟡 | 🟡 | 🟢 | 🟢 | 🟢 |
163
- | Observability | 🟢 | 🟡 | 🔴 | 🟢 | 🟡 |
164
- | Memory/Docs | 🟡 | 🔴 | 🟢 | 🔴 | 🟢 |
165
-
166
- 🔴 = Critical | 🟡 = Important | 🟢 = Nice to have
167
-
168
- ---
169
-
170
- ## Usage Scenarios
171
-
172
- ### Scenario 1: SaaS Founder Launch
173
- ```
174
- Week 1: Setup + customize plans
175
- Week 2: Frontend integration
176
- Week 3: QA + staging
177
- Week 4: Production launch
178
- → 4 weeks to first revenue
179
- ```
180
-
181
- ### Scenario 2: Enterprise Team
182
- ```
183
- Day 1: Setup
184
- Day 2-5: Architecture review + customization
185
- Week 2-4: Integration with existing systems
186
- → 3 weeks to production-ready
187
- ```
188
-
189
- ### Scenario 3: Freelancer/Agency
190
- ```
191
- Day 1: Understand patterns
192
- Days 2-5: Extend for client
193
- Week 2: Deploy for client
194
- → Invoice client, 40 hours billable
195
- ```
@@ -1,63 +0,0 @@
1
- # Visão do Produto
2
-
3
- ## Elevator Pitch
4
-
5
- **SaaS Starter** é uma plataforma de gestão de subscriptions SaaS com:
6
- - Autenticação JWT + multi-tenant
7
- - Planos flexíveis (free, pro, enterprise)
8
- - Billing mock Stripe-like
9
- - RBAC completo
10
- - Pronto para produção
11
-
12
- ## Proposição de Valor
13
-
14
- | Valor | Descrição |
15
- |-------|-----------|
16
- | **Time to Market** | Deploy em 1 semana, não 3 meses |
17
- | **Segurança** | JWT + RBAC + Tenant isolation out-of-box |
18
- | **Escalabilidade** | PostgreSQL + Redis, pronto para 100k+ users |
19
- | **Developer Experience** | TypeScript + NestJS + tipos fortes |
20
- | **Production Ready** | E2E tests, error handling, observability |
21
-
22
- ## Diferencial Competitivo
23
-
24
- 1. **Boilerplate vs Plataforma**: Fornecemos código customizável, não SaaS locked-in
25
- 2. **Multi-tenant First**: Desde o início, não retrofitted
26
- 3. **Agent-Ready**: Orquestração de agentes IA como cidadão de primeira classe
27
- 4. **Documentation as Code**: Memory levels vs wikis desatualizados
28
-
29
- ## 12-Month Vision
30
-
31
- | Trimestre | Objetivo | Métricas |
32
- |-----------|----------|---------|
33
- | Q1 (Agora) | MVP multi-tenant com auth + subscriptions | 3 módulos, 80+ E2E tests |
34
- | Q2 | Billing real (Stripe), webhooks | 0 payment fails, <1% churn |
35
- | Q3 | Analytics & observability | Dashboards, <100ms p99 latency |
36
- | Q4 | Compliance (SOC2, GDPR) | Audit trails, data export |
37
-
38
- ## Limites Declarados
39
-
40
- **Este boilerplate NÃO inclui:**
41
- - Frontend (React/Vue/etc — você escolhe)
42
- - Email delivery (apenas templates)
43
- - SMS (integração Twilio você faz)
44
- - Storage (S3, apenas clients)
45
- - Mobile SDK
46
-
47
- **Por quê?** Manter scaffold enxuto, focado em backend SaaS core.
48
-
49
- ## Sucesso =
50
-
51
- Um novo SaaS pode:
52
- 1. ✅ Clonar repo
53
- 2. ✅ `npm install && docker-compose up`
54
- 3. ✅ `npm run seed` (data de teste)
55
- 4. ✅ `npm test` (verde)
56
- 5. ✅ `npm run start:dev`
57
- 6. ✅ Fazer POST /api/auth/signup
58
- 7. ✅ Upgrade plan em /api/subscriptions
59
- 8. ✅ Ver mock payment em /api/billing
60
- 9. ✅ Deploy em staging
61
- 10. ✅ Customizar conforme necessário
62
-
63
- Tudo em **< 2 horas**.
@@ -1,232 +0,0 @@
1
- # Visão Geral da Arquitetura
2
-
3
- ## Diagrama da Arquitetura
4
-
5
- ```
6
- ┌─────────────────────────────────────────────────────────────────┐
7
- │ Cliente Web/Mobile │
8
- └─────────────────────────────────────────────────────────────────┘
9
- │
10
- ↓
11
- ┌─────────────────────────────────────────────────────────────────┐
12
- │ API Gateway │
13
- │ (Rate Limiter, CORS, Request Logging) │
14
- └─────────────────────────────────────────────────────────────────┘
15
- │
16
- ↓
17
- ┌─────────────────────────────────────────────────────────────────┐
18
- │ NestJS Application │
19
- │ ┌──────────────────────────────────────────────────────────┐ │
20
- │ │ Controllers │ Services │ Middleware │ Guards │ │
21
- │ ├──────────────┴────────────┴──────────────┴──────────────┤ │
22
- │ │ Modules: │ │
23
- │ │ • Auth (JWT, Local strategy) │ │
24
- │ │ • Users (RBAC, invites) │ │
25
- │ │ • Organizations (Multi-tenant) │ │
26
- │ │ • Subscriptions (Plans, upgrades) │ │
27
- │ │ • Billing (Payments, invoices) │ │
28
- │ └──────────────────────────────────────────────────────────┘ │
29
- └─────────────────────────────────────────────────────────────────┘
30
- │ │
31
- ┌──────┴──────┬──────────────┬┴────────┐
32
- ↓ ↓ ↓ ↓
33
- ┌──────────┐ ┌─────────┐ ┌──────────┐ ┌────────┐
34
- │PostgreSQL│ │ Redis │ │ Payment │ │ Email │
35
- │ Database │ │ Cache │ │ Gateway │ │Service │
36
- │ │ │ │ │ (Mock) │ │(Hooks) │
37
- └──────────┘ └─────────┘ └──────────┘ └────────┘
38
- ```
39
-
40
- ## Stack Técnico
41
-
42
- | Camada | Tecnologia | Versão |
43
- |--------|-----------|--------|
44
- | **Backend** | NestJS | 10+ |
45
- | **Language** | TypeScript | 5.0+ |
46
- | **Database** | PostgreSQL | 15+ |
47
- | **Cache** | Redis | 7.0+ |
48
- | **ORM** | TypeORM | 0.3+ |
49
- | **Auth** | JWT | HS256 |
50
- | **Testing** | Jest | 29+ |
51
- | **API Docs** | Swagger/OpenAPI | 3.0 |
52
- | **Runtime** | Node.js | 18+ LTS |
53
-
54
- ## Módulos Principais
55
-
56
- ### 1. Auth Module
57
- - JWT strategy (access + refresh)
58
- - Local strategy (username/password)
59
- - Password hashing (bcrypt)
60
- - Token validation & expiry
61
-
62
- ### 2. Users Module
63
- - User CRUD (create, read, update, delete)
64
- - RBAC (role assignment, permission checking)
65
- - User invites (email link)
66
- - Profile management
67
-
68
- ### 3. Organizations Module
69
- - Org CRUD (create, read, update, delete)
70
- - Org settings
71
- - Multi-tenant isolation
72
- - Org-level permissions
73
-
74
- ### 4. Subscriptions Module
75
- - Subscription CRUD
76
- - Plan management (free, pro, enterprise)
77
- - Upgrade/downgrade logic
78
- - Billing integration
79
-
80
- ### 5. Billing Module
81
- - Payment processing (mock)
82
- - Invoice generation
83
- - Webhook handling
84
- - Transaction history
85
-
86
- ## Fluxos Principais
87
-
88
- ### Signup Flow
89
- ```
90
- 1. POST /api/auth/signup { email, password, org_name }
91
- 2. Validar email único + força de senha
92
- 3. Hash password com bcrypt
93
- 4. Criar org + user (owner role)
94
- 5. Gerar JWT access token
95
- 6. Enviar email de confirmação (async)
96
- 7. Retornar token + user data
97
- ```
98
-
99
- ### Subscription Upgrade Flow
100
- ```
101
- 1. GET /api/subscriptions (validar tenant, auth)
102
- 2. POST /api/subscriptions/:id/upgrade { plan_id }
103
- 3. Validar transição de plano
104
- 4. Charge payment (mock)
105
- 5. Atualizar subscription
106
- 6. Gerar invoice
107
- 7. Registrar audit log
108
- 8. Enviar email de confirmação
109
- ```
110
-
111
- ### Billing Flow
112
- ```
113
- 1. POST /api/billing/charge { amount, currency }
114
- 2. Chamar payment gateway (Stripe mock)
115
- 3. Registrar transação
116
- 4. Gerar invoice
117
- 5. Enviar email de receipt
118
- 6. Webhook callback (async)
119
- 7. Atualizar subscription status se necessário
120
- ```
121
-
122
- ## Padrões Arquiteturais
123
-
124
- ### 1. Dependency Injection
125
- - NestJS @Injectable()
126
- - Constructor injection (explícito, type-safe)
127
- - Service-to-service via providers
128
-
129
- ### 2. Middleware Pattern
130
- - Tenant context middleware (set tenantId no request)
131
- - Logging middleware
132
- - Error handling middleware
133
-
134
- ### 3. Guard Pattern
135
- - JwtAuthGuard (validar token)
136
- - RolesGuard (verificar RBAC)
137
- - TenantGuard (isolar tenant)
138
-
139
- ### 4. Service Pattern
140
- - Business logic separado de HTTP
141
- - Reutilizável por controllers/jobs
142
- - Testável isoladamente
143
-
144
- ### 5. Repository Pattern
145
- - Typeorm repositories para data access
146
- - Abstração de queries
147
- - Facilitado testes (mock repositories)
148
-
149
- ## Camadas
150
-
151
- ```
152
- ┌───────────────────────────────┐
153
- │ HTTP Controllers │ (Request/Response)
154
- ├───────────────────────────────┤
155
- │ Services │ (Business Logic)
156
- ├───────────────────────────────┤
157
- │ Repositories │ (Data Access)
158
- ├───────────────────────────────┤
159
- │ Database / Cache │ (Persistence)
160
- └───────────────────────────────┘
161
- ```
162
-
163
- ## Decisões Arquiteturais
164
-
165
- ### Por que PostgreSQL, não MongoDB?
166
- - Relational: Users ↔ Organizations ↔ Subscriptions ↔ Invoices
167
- - Transactions: ACID para billing (crítico)
168
- - Compliance: Melhor para GDPR + audit trails
169
- - Cost: Managed PostgreSQL (RDS, Heroku) é mais barato
170
-
171
- ### Por que Redis, não memcache?
172
- - Data structures: Listas, sets (cache invalidation mais fácil)
173
- - Persistence: Opcional, mas disponível
174
- - Pub/Sub: Para notificações em tempo real (futura)
175
- - Cost: Comparable, Redis tem mais features
176
-
177
- ### Por que TypeScript?
178
- - Type safety: Detectar bugs em compile-time
179
- - DX: Melhor IDE support, autocompletion
180
- - Refactoring: Renomear símbolos com confiança
181
- - Migration: JavaScript é subset de TypeScript
182
-
183
- ### Por que NestJS?
184
- - Convention over configuration: Setup rápido
185
- - Dependency injection: Integrado desde início
186
- - Modular: Escalável conforme projeto cresce
187
- - Testing: Built-in testing utilities
188
- - Community: Stack MEAN maduro em produção
189
-
190
- ## Próximas Fases
191
-
192
- ### Phase 2: Internacionalização
193
- - Multi-currency (USD, EUR, GBP, etc)
194
- - Stripe real integration
195
- - Webhooks para payment events
196
-
197
- ### Phase 3: Observability
198
- - Prometheus metrics
199
- - Grafana dashboards
200
- - OpenTelemetry tracing
201
- - Distributed logging (ELK stack)
202
-
203
- ### Phase 4: Compliance
204
- - SOC2 audit trail
205
- - GDPR data export
206
- - User audit logs
207
- - Rate limiting per endpoint
208
-
209
- ### Phase 5: Performance
210
- - Database indexes optimization
211
- - Query result caching
212
- - Bulk operations
213
- - Webhook batch processing
214
-
215
- ## Deployment Strategy
216
-
217
- ### Development Environment
218
- - docker-compose com PostgreSQL + Redis
219
- - Hot-reload NestJS
220
- - Seed data automático
221
-
222
- ### Staging Environment
223
- - AWS RDS PostgreSQL
224
- - AWS ElastiCache Redis
225
- - Docker containers em ECS
226
- - Blue-green deployment
227
-
228
- ### Production Environment
229
- - Multi-AZ RDS PostgreSQL
230
- - Read replicas para scaling
231
- - CloudFront para static assets (future)
232
- - Auto-scaling groups
@@ -1,186 +0,0 @@
1
- # Auth API Specification
2
-
3
- ## Endpoints
4
-
5
- ### 1. Signup
6
-
7
- **POST** `/api/auth/signup`
8
-
9
- ```json
10
- {
11
- "email": "founder@example.com",
12
- "password": "SecureP@ss123",
13
- "organizationName": "My Startup"
14
- }
15
- ```
16
-
17
- **Response 201**:
18
- ```json
19
- {
20
- "data": {
21
- "id": "user-uuid",
22
- "email": "founder@example.com",
23
- "organization": {
24
- "id": "org-uuid",
25
- "name": "My Startup",
26
- "plan": "free"
27
- },
28
- "accessToken": "eyJhbGc...",
29
- "refreshToken": "eyJhbGc..."
30
- }
31
- }
32
- ```
33
-
34
- **Error 400**: Email já existe
35
- **Error 422**: Senha fraca
36
-
37
- ---
38
-
39
- ### 2. Login
40
-
41
- **POST** `/api/auth/login`
42
-
43
- ```json
44
- {
45
- "email": "founder@example.com",
46
- "password": "SecureP@ss123"
47
- }
48
- ```
49
-
50
- **Response 200**:
51
- ```json
52
- {
53
- "data": {
54
- "user": { "id", "email", "roles": ["owner"] },
55
- "organization": { "id", "name", "plan" },
56
- "accessToken": "eyJhbGc...",
57
- "refreshToken": "eyJhbGc..."
58
- }
59
- }
60
- ```
61
-
62
- **Error 401**: Email ou senha inválida
63
- **Error 429**: Too many attempts (rate limited)
64
-
65
- ---
66
-
67
- ### 3. Refresh Token
68
-
69
- **POST** `/api/auth/refresh`
70
-
71
- ```json
72
- {
73
- "refreshToken": "eyJhbGc..."
74
- }
75
- ```
76
-
77
- **Response 200**:
78
- ```json
79
- {
80
- "data": {
81
- "accessToken": "eyJhbGc...",
82
- "refreshToken": "eyJhbGc..." // new if rotated
83
- }
84
- }
85
- ```
86
-
87
- **Error 401**: Refresh token inválido ou expirado
88
-
89
- ---
90
-
91
- ### 4. Logout
92
-
93
- **POST** `/api/auth/logout`
94
-
95
- Headers: `Authorization: Bearer {accessToken}`
96
-
97
- **Response 200**:
98
- ```json
99
- {
100
- "message": "Logged out successfully"
101
- }
102
- ```
103
-
104
- ---
105
-
106
- ### 5. Get Current User
107
-
108
- **GET** `/api/auth/me`
109
-
110
- Headers: `Authorization: Bearer {accessToken}`
111
-
112
- **Response 200**:
113
- ```json
114
- {
115
- "data": {
116
- "id": "user-uuid",
117
- "email": "founder@example.com",
118
- "roles": ["owner"],
119
- "organization": {
120
- "id": "org-uuid",
121
- "name": "My Startup",
122
- "plan": "free"
123
- }
124
- }
125
- }
126
- ```
127
-
128
- ---
129
-
130
- ## Error Codes
131
-
132
- | Code | Message | Meaning |
133
- |------|---------|---------|
134
- | AUTH_001 | Invalid credentials | Email ou senha incorreta |
135
- | AUTH_002 | Email already exists | Email já cadastrado neste tenant |
136
- | AUTH_003 | Weak password | Senha não atende requisitos |
137
- | AUTH_004 | Invalid token | JWT inválido ou expirado |
138
- | AUTH_005 | Token expired | Usar refresh endpoint |
139
- | AUTH_006 | Account locked | 5 failed attempts, tente em 15 min |
140
- | AUTH_007 | Email not verified | Confirmar email primeiro |
141
-
142
- ## Flow Examples
143
-
144
- ### Scenario: User Signup
145
- ```bash
146
- curl -X POST http://localhost:3000/api/auth/signup \
147
- -H "Content-Type: application/json" \
148
- -d '{
149
- "email": "founder@example.com",
150
- "password": "SecureP@ss123",
151
- "organizationName": "My Startup"
152
- }'
153
- ```
154
-
155
- ### Scenario: User Login
156
- ```bash
157
- curl -X POST http://localhost:3000/api/auth/login \
158
- -H "Content-Type: application/json" \
159
- -d '{
160
- "email": "founder@example.com",
161
- "password": "SecureP@ss123"
162
- }'
163
- ```
164
-
165
- ### Scenario: Access Protected Route
166
- ```bash
167
- curl -X GET http://localhost:3000/api/auth/me \
168
- -H "Authorization: Bearer eyJhbGc..."
169
- ```
170
-
171
- ### Scenario: Refresh Expired Token
172
- ```bash
173
- curl -X POST http://localhost:3000/api/auth/refresh \
174
- -H "Content-Type: application/json" \
175
- -d '{
176
- "refreshToken": "eyJhbGc..."
177
- }'
178
- ```
179
-
180
- ## Implementation Notes
181
-
182
- - Todos endpoints retornam `tenantId` no JWT payload
183
- - Todas operações são isoladas por tenant
184
- - Email é único por tenant, não globalmente
185
- - Passwords são hashed com bcrypt (cost=12)
186
- - Tokens são signed com HS256