forjajs 5.0.1 → 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.
- package/CHANGELOG.md +38 -2
- package/README.md +4 -2
- package/README.pt-BR.md +4 -1
- package/boilerplates/02-saas-starter/README.md +58 -293
- package/boilerplates/02-saas-starter/backend/.env.example +13 -0
- package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
- package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
- package/boilerplates/02-saas-starter/backend/package.json +32 -73
- package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
- package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
- package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
- package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
- package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
- package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
- package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
- package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
- package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
- package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
- package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
- package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
- package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
- package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
- package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
- package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
- package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
- package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
- package/boilerplates/README.md +9 -10
- package/dist/bin/init-project.js +1 -0
- package/dist/lib/core/journey.js +10 -0
- package/dist/lib/generators/memory-generator.d.ts +0 -11
- package/dist/lib/generators/memory-generator.js +5 -161
- package/dist/lib/generators/readme-generator.js +1 -1
- package/dist/lib/llm/json-output.d.ts +14 -0
- package/dist/lib/llm/json-output.js +77 -0
- package/dist/lib/project-wiring.d.ts +8 -0
- package/dist/lib/project-wiring.js +74 -2
- package/dist/lib/validators/structure-validator.js +0 -1
- package/dist/packages/llm/src/index.js +12 -2
- package/dist/scripts/llm-fit.js +23 -1
- package/docs/llm-fit-loop.md +16 -0
- package/memory/90-decisions/0088-templates-validados.md +3 -0
- package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
- package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
- package/package.json +1 -1
- package/specs/skills-do-projeto/plan.md +40 -0
- package/specs/skills-do-projeto/spec.md +63 -0
- package/specs/skills-do-projeto/tasks.md +27 -0
- package/templates/project/AGENTS.md +9 -0
- package/templates/project/agents/context-engineer.md +3 -0
- package/templates/project/agents/governance.md +3 -0
- package/templates/project/agents/marketing.md +3 -0
- package/templates/project/agents/orchestrator.md +3 -0
- package/templates/project/agents/product.md +3 -0
- package/templates/project/agents/sdd-architect.md +3 -0
- package/templates/project/skills/README.md +14 -0
- package/templates/project/skills/accessibility-review/SKILL.md +89 -0
- package/templates/project/skills/api-design/SKILL.md +77 -0
- package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
- package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
- package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
- package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
- package/templates/project/skills/commit-message/SKILL.md +143 -0
- package/templates/project/skills/data-migrations/SKILL.md +88 -0
- package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
- package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
- package/templates/project/skills/domain-modeling/SKILL.md +120 -0
- package/templates/project/skills/event-storming/SKILL.md +95 -0
- package/templates/project/skills/executive-writing/SKILL.md +99 -0
- package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
- package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
- package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
- package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
- package/templates/project/skills/observability/SKILL.md +93 -0
- package/templates/project/skills/product-evaluation/SKILL.md +130 -0
- package/templates/project/skills/prompt-spec/SKILL.md +83 -0
- package/templates/project/skills/pull-request/SKILL.md +101 -0
- package/templates/project/skills/query-performance/SKILL.md +83 -0
- package/templates/project/skills/release-checklist/SKILL.md +106 -0
- package/templates/project/skills/release-notes/SKILL.md +87 -0
- package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
- package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
- package/templates/project/skills/technical-spike/SKILL.md +101 -0
- package/templates/project/skills/testing/SKILL.md +109 -0
- package/templates/project/skills/threat-modeling/SKILL.md +87 -0
- package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
- package/templates/project/skills/ts-code-review/SKILL.md +121 -0
- package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
- package/templates/project/skills/ts-testing/SKILL.md +89 -0
- package/templates/project/skills/web-performance/SKILL.md +72 -0
- package/boilerplates/02-saas-starter/.env.example +0 -25
- package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
- package/boilerplates/02-saas-starter/INFO.md +0 -252
- package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
- package/boilerplates/02-saas-starter/START-HERE.md +0 -259
- package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
- package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
- package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
- package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
- package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
- package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
- package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
- package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
- package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
- package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
- package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
- package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
- package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
- package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
- package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
- package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
- package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
- package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
- package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
- package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
- package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
- package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
- package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
- package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
- package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
- package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
- package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
- package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
- package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
- package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
- package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
- 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
|