forjajs 5.0.0 → 5.1.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 (171) hide show
  1. package/CHANGELOG.md +68 -2
  2. package/README.md +4 -2
  3. package/README.pt-BR.md +4 -1
  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/bin/create-memory-nest-kit.js +0 -0
  50. package/dist/bin/forja.js +0 -0
  51. package/dist/bin/init-project.js +1 -0
  52. package/dist/lib/core/journey.js +10 -0
  53. package/dist/lib/generators/memory-generator.d.ts +0 -11
  54. package/dist/lib/generators/memory-generator.js +5 -161
  55. package/dist/lib/generators/readme-generator.js +1 -1
  56. package/dist/lib/llm/json-output.d.ts +14 -0
  57. package/dist/lib/llm/json-output.js +77 -0
  58. package/dist/lib/project-upgrade.d.ts +0 -4
  59. package/dist/lib/project-upgrade.js +19 -1
  60. package/dist/lib/project-wiring.d.ts +8 -0
  61. package/dist/lib/project-wiring.js +74 -2
  62. package/dist/lib/validators/structure-validator.js +0 -1
  63. package/dist/packages/llm/src/index.js +12 -2
  64. package/dist/scripts/llm-fit.js +23 -1
  65. package/dist/scripts/project-upgrade.js +9 -6
  66. package/docs/init-project.md +1 -1
  67. package/docs/llm-fit-loop.md +16 -0
  68. package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +1 -1
  69. package/memory/90-decisions/0088-templates-validados.md +3 -0
  70. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  71. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  72. package/package.json +2 -2
  73. package/specs/skills-do-projeto/plan.md +40 -0
  74. package/specs/skills-do-projeto/spec.md +63 -0
  75. package/specs/skills-do-projeto/tasks.md +27 -0
  76. package/templates/project/AGENTS.md +9 -0
  77. package/templates/project/agents/context-engineer.md +3 -0
  78. package/templates/project/agents/governance.md +3 -0
  79. package/templates/project/agents/marketing.md +3 -0
  80. package/templates/project/agents/orchestrator.md +3 -0
  81. package/templates/project/agents/product.md +3 -0
  82. package/templates/project/agents/sdd-architect.md +3 -0
  83. package/templates/project/skills/README.md +14 -0
  84. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  85. package/templates/project/skills/api-design/SKILL.md +77 -0
  86. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  87. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  88. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  89. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  90. package/templates/project/skills/commit-message/SKILL.md +143 -0
  91. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  92. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  93. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  94. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  95. package/templates/project/skills/event-storming/SKILL.md +95 -0
  96. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  97. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  98. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  99. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  100. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  101. package/templates/project/skills/observability/SKILL.md +93 -0
  102. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  103. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  104. package/templates/project/skills/pull-request/SKILL.md +101 -0
  105. package/templates/project/skills/query-performance/SKILL.md +83 -0
  106. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  107. package/templates/project/skills/release-notes/SKILL.md +87 -0
  108. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  109. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  110. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  111. package/templates/project/skills/testing/SKILL.md +109 -0
  112. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  113. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  114. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  115. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  116. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  117. package/templates/project/skills/web-performance/SKILL.md +72 -0
  118. package/boilerplates/02-saas-starter/.env.example +0 -25
  119. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  120. package/boilerplates/02-saas-starter/INFO.md +0 -252
  121. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  122. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  123. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  124. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  125. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  126. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  127. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  128. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  129. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  130. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  131. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  132. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  133. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  134. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  135. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  136. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  137. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  138. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  139. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  140. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  141. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  142. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  143. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  144. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  145. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  146. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  147. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  148. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  149. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  150. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  151. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  152. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  153. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  154. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  155. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  156. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  157. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  158. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  159. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  160. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  161. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  162. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  163. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  164. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  165. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  166. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  167. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  168. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  169. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  170. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  171. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -1,57 +0,0 @@
1
- # Sprint Atual - Sprint 1
2
-
3
- **Duration**: 2024-01-15 to 2024-01-26
4
- **Goal**: Foundation complete, all modules created and tested
5
-
6
- ## Tasks
7
-
8
- ### Setup Agent
9
- - [ ] PostgreSQL container running (docker-compose)
10
- - [ ] Migrations created
11
- - [ ] Seed data generated
12
- - [ ] Redis cache ready
13
- - [ ] Environment variables documented (.env.example)
14
-
15
- ### Auth Agent
16
- - [ ] User entity with password hash
17
- - [ ] JWT strategy implemented
18
- - [ ] Local strategy implemented
19
- - [ ] Login endpoint working
20
- - [ ] Signup endpoint with org creation
21
- - [ ] Refresh token endpoint
22
- - [ ] E2E tests passing
23
-
24
- ### Organizations Agent
25
- - [ ] Organization entity
26
- - [ ] Multi-tenant context middleware
27
- - [ ] Tenant isolation verified
28
- - [ ] Organization CRUD endpoints
29
- - [ ] Tests for tenant isolation
30
-
31
- ### Users Agent
32
- - [ ] User entity with roles
33
- - [ ] RBAC matrix implemented
34
- - [ ] Invite user endpoint
35
- - [ ] Remove user endpoint
36
- - [ ] Tests for RBAC
37
-
38
- ### Documentation
39
- - [ ] README.md with quick start
40
- - [ ] QUICK_START.md guide
41
- - [ ] .env.example configured
42
- - [ ] Patterns documented (copy from memory/00-global/patterns.md)
43
-
44
- ## Blockers
45
-
46
- None currently.
47
-
48
- ## Velocity
49
-
50
- Target: 8 story points
51
- Completed: 0 (sprint just started)
52
-
53
- ## Decisions Made
54
-
55
- - JWT expiry: 15 min access, 7 days refresh (see ADR if created)
56
- - Password hash: bcrypt cost=12
57
- - Database: PostgreSQL (see ADR in 90-decisions/)
@@ -1,90 +0,0 @@
1
- # Topologia de Agentes
2
-
3
- ## Sequência de Execução
4
-
5
- ```
6
- Setup Agent (0 deps)
7
- ↓
8
- ├→ Auth Agent
9
- │ ↓
10
- │ ├→ Subscriptions Agent
11
- │ │ ↓
12
- │ │ └→ Billing Agent
13
- │ │
14
- │ └→ Users Agent (RBAC)
15
- │
16
- ├→ Organizations Agent (Multi-tenant)
17
- │
18
- └→ Analytics Agent (não-blocking, last)
19
- ```
20
-
21
- ## Agentes & Timeline
22
-
23
- | # | Agent | Deps | Duration | Output |
24
- |---|-------|------|----------|--------|
25
- | 1 | Setup | - | 2h | ENV + DB ready |
26
- | 2 | Auth | Setup | 4h | JWT auth working |
27
- | 3 | Organizations | Setup | 2h | Multi-tenant isolation |
28
- | 4 | Users | Auth + Orgs | 3h | RBAC matrix |
29
- | 5 | Subscriptions | Auth + Users | 3h | Plans + CRUD |
30
- | 6 | Billing | Subscriptions | 3h | Mock Stripe |
31
- | 7 | Analytics | All (optional) | 2h | Event tracking |
32
-
33
- **Total sequential**: 19 hours
34
- **With parallelization**: 11 hours (Auth + Orgs parallel, then rest)
35
-
36
- ## Parallelização Possível
37
-
38
- ### Wave 1 (Start)
39
- - Setup Agent (blocking, must complete first)
40
-
41
- ### Wave 2 (After Setup)
42
- - Auth Agent (parallel)
43
- - Organizations Agent (parallel)
44
-
45
- ### Wave 3 (After Wave 2)
46
- - Users Agent (depends on Auth + Orgs)
47
- - Subscriptions Agent (depends on Auth)
48
-
49
- ### Wave 4 (After Wave 3)
50
- - Billing Agent (depends on Subscriptions)
51
-
52
- ### Wave 5 (Optional)
53
- - Analytics Agent (optional, non-blocking)
54
-
55
- ## Decisões & Handoffs
56
-
57
- Cada agente cria handoff document (`memory/50-orchestration/handoffs/`) após completar:
58
-
59
- ```
60
- handoffs/
61
- ├── 2024-01-15-setup-auth.md (Setup → Auth)
62
- ├── 2024-01-15-auth-subscriptions.md (Auth → Subscriptions)
63
- ├── 2024-01-15-subscriptions-billing.md (Subscriptions → Billing)
64
- └── ...
65
- ```
66
-
67
- ## Critérios de Sucesso
68
-
69
- Agente completa quando:
70
- 1. ✅ Todos endpoints implementados
71
- 2. ✅ Testes E2E passando
72
- 3. ✅ Zero breaking changes
73
- 4. ✅ Documentação atualizada (memory/30-domains/)
74
- 5. ✅ Run log criado (memory/60-runs/)
75
- 6. ✅ Handoff document criado
76
-
77
- ## Escalation Path
78
-
79
- Se agente falha:
80
- 1. Registrar em memory/60-runs/{date}-ERROR.md
81
- 2. Criar issue no backlog como bloqueador
82
- 3. Revisar com tech lead
83
- 4. Retry com contexto de erro (ADR)
84
- 5. Se persiste: manual investigation
85
-
86
- ## Monitoring
87
-
88
- - Agentes com timeout: >4 horas sem handoff
89
- - Quality gate: Coverage <60% ou testes falhando
90
- - Performance: E2E tests >30s = investigate
@@ -1,54 +0,0 @@
1
- # Índice de Execuções (Runs)
2
-
3
- Histórico de execuções de agentes, testes e deployments.
4
-
5
- ## Runs Completas
6
-
7
- - TBD (nenhuma execução ainda)
8
-
9
- ## Runs em Andamento
10
-
11
- - TBD
12
-
13
- ## Runs Falhadas
14
-
15
- - TBD
16
-
17
- ## Como Adicionar Run
18
-
19
- Cada agente, após completar tarefa, cria arquivo: `YYYY-MM-DD-agent-task.md`
20
-
21
- ```markdown
22
- # Auth Setup - 2024-01-15 14:30:00
23
-
24
- ## Agente
25
- Auth Agent
26
-
27
- ## Tarefa
28
- Implementar JWT + login/signup
29
-
30
- ## Status
31
- ✅ COMPLETA
32
-
33
- ## Saída
34
- - POST /api/auth/signup
35
- - POST /api/auth/login
36
- - POST /api/auth/refresh
37
- - GET /api/auth/me
38
- - E2E tests: 12 passing
39
-
40
- ## Issues Encontrados
41
- - None
42
-
43
- ## Próximo Agente
44
- Subscriptions Agent
45
- ```
46
-
47
- ## Métricas de Execução
48
-
49
- | Métrica | Q1 Target |
50
- |---------|-----------|
51
- | Sprint velocity | 5-8 pts/sprint |
52
- | Test coverage | >60% |
53
- | Deployment time | <30 min |
54
- | Failed runs | 0 |
@@ -1,50 +0,0 @@
1
- # Sumário Executivo Global
2
-
3
- **Data**: 2024-01-15
4
- **Status**: 🚀 Scaffold criado, pronto para desenvolvimento
5
-
6
- ## Funcionalidades Implementadas
7
-
8
- - ✅ Estrutura de memória (10 níveis)
9
- - ✅ Padrões & convenções documentados
10
- - ✅ Contrato de agentes definido
11
- - ✅ Roadmap 12 meses
12
- - ✅ Domain contexts (auth, subscriptions, billing)
13
- - ✅ API specifications documentadas
14
-
15
- ## Funcionalidades Pendentes
16
-
17
- - 🚧 Backend NestJS (módulos)
18
- - 🚧 Testes E2E
19
- - 🚧 Docker-compose funcional
20
- - 🚧 Implementação de agents
21
-
22
- ## Métricas
23
-
24
- | Métrica | Alvo | Atual | Status |
25
- |---------|------|-------|--------|
26
- | Memory docs | 100% | 100% | ✅ |
27
- | API endpoints spec | 18 | 0 | 🚧 |
28
- | Test coverage | 60% | - | 🚧 |
29
- | E2E tests | 15+ | 0 | 🚧 |
30
- | Deployment | <30min | - | 🚧 |
31
-
32
- ## Bloqueadores
33
-
34
- - None (all items on track)
35
-
36
- ## Próximos Steps
37
-
38
- 1. **Próximo Agente**: Setup Agent
39
- 2. **Próxima Tarefa**: PostgreSQL + Redis docker-compose
40
- 3. **Próximo Milestone**: Sprint 1 (1-2 semanas)
41
-
42
- ## Time & Recursos
43
-
44
- - **Dedicação**: 1-3 engineers
45
- - **Stack**: TypeScript, NestJS, PostgreSQL, Redis
46
- - **Infrastructure**: Docker-compose (dev), AWS RDS (prod)
47
-
48
- ## Risk Assessment
49
-
50
- 🟢 **BAIXO RISCO** - Arquitetura clara, padrões bem definidos, dependências resolvidas.
@@ -1,185 +0,0 @@
1
- # Database Schema
2
-
3
- ## Entities & Relationships
4
-
5
- ```
6
- Organization (1) ──→ (Many) User
7
- Organization (1) ──→ (1) Subscription
8
- Organization (1) ──→ (Many) Invoice
9
- Subscription (1) ──→ (Many) Invoice
10
- User (1) ──→ (Many) Audit Log
11
- ```
12
-
13
- ## Entity: Organization
14
-
15
- ```sql
16
- CREATE TABLE organizations (
17
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
18
- tenantId UUID NOT NULL UNIQUE,
19
- name VARCHAR(255) NOT NULL,
20
- slug VARCHAR(255) NOT NULL UNIQUE,
21
- ownerUserId UUID NOT NULL REFERENCES users(id),
22
- plan VARCHAR(50) NOT NULL DEFAULT 'free',
23
- stripeCustomerId VARCHAR(255),
24
- createdAt TIMESTAMP NOT NULL DEFAULT NOW(),
25
- updatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
26
- deletedAt TIMESTAMP
27
- );
28
-
29
- CREATE INDEX idx_org_tenant ON organizations(tenantId);
30
- CREATE INDEX idx_org_owner ON organizations(ownerUserId);
31
- ```
32
-
33
- ## Entity: User
34
-
35
- ```sql
36
- CREATE TABLE users (
37
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
38
- tenantId UUID NOT NULL,
39
- email VARCHAR(255) NOT NULL,
40
- passwordHash VARCHAR(255),
41
- firstName VARCHAR(100),
42
- lastName VARCHAR(100),
43
- roles VARCHAR(50)[] DEFAULT ARRAY['member'],
44
- status VARCHAR(50) NOT NULL DEFAULT 'active',
45
- emailVerifiedAt TIMESTAMP,
46
- createdAt TIMESTAMP NOT NULL DEFAULT NOW(),
47
- updatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
48
- deletedAt TIMESTAMP,
49
- CONSTRAINT fk_user_tenant FOREIGN KEY (tenantId) REFERENCES organizations(tenantId)
50
- );
51
-
52
- CREATE INDEX idx_user_tenant_email ON users(tenantId, email);
53
- CREATE INDEX idx_user_tenant_status ON users(tenantId, status);
54
- CREATE UNIQUE INDEX idx_user_unique_email ON users(tenantId, email) WHERE deletedAt IS NULL;
55
- ```
56
-
57
- ## Entity: Subscription
58
-
59
- ```sql
60
- CREATE TABLE subscriptions (
61
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
62
- organizationId UUID NOT NULL REFERENCES organizations(id),
63
- tenantId UUID NOT NULL,
64
- plan VARCHAR(50) NOT NULL,
65
- status VARCHAR(50) NOT NULL DEFAULT 'active',
66
- currentPeriodStart TIMESTAMP NOT NULL,
67
- currentPeriodEnd TIMESTAMP NOT NULL,
68
- cancelAtPeriodEnd BOOLEAN DEFAULT FALSE,
69
- cancelledAt TIMESTAMP,
70
- createdAt TIMESTAMP NOT NULL DEFAULT NOW(),
71
- updatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
72
- CONSTRAINT fk_sub_tenant FOREIGN KEY (tenantId) REFERENCES organizations(tenantId)
73
- );
74
-
75
- CREATE INDEX idx_sub_org ON subscriptions(organizationId);
76
- CREATE INDEX idx_sub_tenant ON subscriptions(tenantId);
77
- CREATE INDEX idx_sub_status ON subscriptions(tenantId, status);
78
- ```
79
-
80
- ## Entity: Invoice
81
-
82
- ```sql
83
- CREATE TABLE invoices (
84
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
85
- organizationId UUID NOT NULL REFERENCES organizations(id),
86
- tenantId UUID NOT NULL,
87
- invoiceNumber VARCHAR(50) NOT NULL UNIQUE,
88
- subscriptionId UUID REFERENCES subscriptions(id),
89
- amount DECIMAL(10, 2) NOT NULL,
90
- currency VARCHAR(3) NOT NULL DEFAULT 'USD',
91
- status VARCHAR(50) NOT NULL DEFAULT 'pending',
92
- description TEXT,
93
- items JSONB,
94
- issuedAt TIMESTAMP NOT NULL,
95
- dueDate TIMESTAMP,
96
- paidAt TIMESTAMP,
97
- createdAt TIMESTAMP NOT NULL DEFAULT NOW(),
98
- updatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
99
- CONSTRAINT fk_invoice_tenant FOREIGN KEY (tenantId) REFERENCES organizations(tenantId)
100
- );
101
-
102
- CREATE INDEX idx_inv_org ON invoices(organizationId);
103
- CREATE INDEX idx_inv_tenant ON invoices(tenantId);
104
- CREATE INDEX idx_inv_status ON invoices(tenantId, status);
105
- ```
106
-
107
- ## Entity: Payment Transaction
108
-
109
- ```sql
110
- CREATE TABLE transactions (
111
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
112
- organizationId UUID NOT NULL REFERENCES organizations(id),
113
- tenantId UUID NOT NULL,
114
- invoiceId UUID REFERENCES invoices(id),
115
- amount DECIMAL(10, 2) NOT NULL,
116
- currency VARCHAR(3) NOT NULL,
117
- type VARCHAR(50) NOT NULL,
118
- status VARCHAR(50) NOT NULL DEFAULT 'pending',
119
- paymentMethodId VARCHAR(255),
120
- stripePaymentIntentId VARCHAR(255),
121
- description TEXT,
122
- failureReason TEXT,
123
- retryCount INT DEFAULT 0,
124
- nextRetryAt TIMESTAMP,
125
- createdAt TIMESTAMP NOT NULL DEFAULT NOW(),
126
- updatedAt TIMESTAMP NOT NULL DEFAULT NOW(),
127
- CONSTRAINT fk_txn_tenant FOREIGN KEY (tenantId) REFERENCES organizations(tenantId)
128
- );
129
-
130
- CREATE INDEX idx_txn_org ON transactions(organizationId);
131
- CREATE INDEX idx_txn_tenant ON transactions(tenantId);
132
- CREATE INDEX idx_txn_invoice ON transactions(invoiceId);
133
- CREATE INDEX idx_txn_status ON transactions(tenantId, status);
134
- ```
135
-
136
- ## Entity: Audit Log
137
-
138
- ```sql
139
- CREATE TABLE audit_logs (
140
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
141
- tenantId UUID NOT NULL,
142
- userId UUID REFERENCES users(id),
143
- action VARCHAR(100) NOT NULL,
144
- entity VARCHAR(100) NOT NULL,
145
- entityId UUID,
146
- changes JSONB,
147
- ipAddress INET,
148
- userAgent TEXT,
149
- createdAt TIMESTAMP NOT NULL DEFAULT NOW(),
150
- CONSTRAINT fk_audit_tenant FOREIGN KEY (tenantId) REFERENCES organizations(tenantId)
151
- );
152
-
153
- CREATE INDEX idx_audit_tenant ON audit_logs(tenantId);
154
- CREATE INDEX idx_audit_user ON audit_logs(userId);
155
- CREATE INDEX idx_audit_action ON audit_logs(action);
156
- ```
157
-
158
- ## Entity: API Key (Future)
159
-
160
- ```sql
161
- CREATE TABLE api_keys (
162
- id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
163
- organizationId UUID NOT NULL REFERENCES organizations(id),
164
- tenantId UUID NOT NULL,
165
- keyHash VARCHAR(255) NOT NULL UNIQUE,
166
- name VARCHAR(255) NOT NULL,
167
- lastUsedAt TIMESTAMP,
168
- expiresAt TIMESTAMP,
169
- createdAt TIMESTAMP NOT NULL DEFAULT NOW(),
170
- revokedAt TIMESTAMP,
171
- CONSTRAINT fk_apikey_tenant FOREIGN KEY (tenantId) REFERENCES organizations(tenantId)
172
- );
173
-
174
- CREATE INDEX idx_apikey_org ON api_keys(organizationId);
175
- CREATE INDEX idx_apikey_hash ON api_keys(keyHash);
176
- ```
177
-
178
- ## Constraints & Rules
179
-
180
- - Every table has `tenantId` for isolation
181
- - Foreign keys enforce referential integrity
182
- - Soft deletes with `deletedAt`
183
- - Timestamps: `createdAt`, `updatedAt` on every table
184
- - Indexes on every foreign key + filtering column
185
- - Unique constraints on business keys (email, invoiceNumber, etc)
@@ -1,75 +0,0 @@
1
- # ADR Template - Architecture Decision Records
2
-
3
- Use este template para documentar decisões arquiteturais importantes.
4
-
5
- ## ADR-YYYYMMDD-XXX: {Título da Decisão}
6
-
7
- **Date**: YYYY-MM-DD
8
- **Status**: Proposed | Accepted | Deprecated | Superseded by ADR-...
9
- **Deciders**: [names]
10
-
11
- ## Context
12
-
13
- Descreva o problema ou situação que motivou esta decisão.
14
-
15
- **Background**:
16
- - What is the issue?
17
- - Why now?
18
- - What constraints exist?
19
-
20
- **Options Considered**:
21
- 1. Option A
22
- 2. Option B
23
- 3. Option C
24
-
25
- ## Decision
26
-
27
- Declare qual opção foi escolhida e por quê.
28
-
29
- ## Consequences
30
-
31
- ### Positive
32
- - Benefit 1
33
- - Benefit 2
34
-
35
- ### Negative
36
- - Risk 1
37
- - Risk 2
38
-
39
- ### Neutral
40
- - Other impact 1
41
-
42
- ## Rationale
43
-
44
- Explique o raciocínio por trás dessa decisão em detalhes.
45
-
46
- ## Related ADRs
47
-
48
- - ADR-YYYYMMDD-XXX (related decision)
49
- - ADR-YYYYMMDD-YYY (conflicting/complementary decision)
50
-
51
- ## Examples
52
-
53
- ### Exemplo: Por que PostgreSQL?
54
-
55
- **ADR-20240115-001: Database Choice**
56
-
57
- **Context**
58
- - Need relational data (users, orgs, subscriptions, invoices)
59
- - Transactions required (ACID) for billing
60
- - Multi-tenant architecture demands row-level security
61
- - Cost considerations
62
-
63
- **Decision**
64
- PostgreSQL with row-level tenant isolation (tenantId column)
65
-
66
- **Consequences**
67
- - ✅ Strong ACID guarantees for billing
68
- - ✅ Mature ecosystem, lots of examples
69
- - ✅ Managed options (RDS, Heroku)
70
- - ✅ Full-text search (future feature)
71
- - ❌ Slightly higher latency vs NoSQL (acceptable)
72
- - ❌ Vertical scaling limits (acceptable for MVP)
73
-
74
- **Rationale**
75
- Banking/billing requires ACID compliance. MongoDB would introduce risks for money operations. PostgreSQL is battle-tested in production SaaS platforms.