forjajs 2.0.4 → 4.0.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 (825) hide show
  1. package/.claude/agents/context-engineer.md +19 -25
  2. package/.claude/agents/governance.md +19 -55
  3. package/.claude/agents/marketing.md +19 -24
  4. package/.claude/agents/orchestrator.md +19 -31
  5. package/.claude/agents/product.md +19 -26
  6. package/.claude/agents/release-auditor.md +50 -50
  7. package/.claude/agents/sdd-architect.md +19 -34
  8. package/.claude/settings.json +76 -76
  9. package/.claude/skills/new-adr/SKILL.md +61 -61
  10. package/.claude/skills/new-command/SKILL.md +67 -67
  11. package/.gemini-instructions.md +93 -87
  12. package/.github/copilot-instructions.md +93 -87
  13. package/.memoryrc.json +104 -104
  14. package/.openai-instructions.md +93 -87
  15. package/AGENTS.md +137 -134
  16. package/CHANGELOG.md +656 -555
  17. package/CONTRIBUTING.md +32 -32
  18. package/DOC-MAP.md +68 -60
  19. package/LICENSE +21 -21
  20. package/README.md +404 -343
  21. package/README.pt-BR.md +374 -345
  22. package/boilerplates/01-api-rest/README.md +336 -336
  23. package/boilerplates/01-api-rest/boilerplate.manifest.json +41 -41
  24. package/boilerplates/02-saas-starter/.env.example +25 -25
  25. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +190 -190
  26. package/boilerplates/02-saas-starter/INFO.md +252 -252
  27. package/boilerplates/02-saas-starter/QUICK_START.md +194 -194
  28. package/boilerplates/02-saas-starter/README.md +305 -305
  29. package/boilerplates/02-saas-starter/START-HERE.md +259 -259
  30. package/boilerplates/02-saas-starter/backend/package.json +87 -87
  31. package/boilerplates/02-saas-starter/backend/src/app.module.ts +27 -27
  32. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +3 -3
  33. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +6 -6
  34. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +23 -23
  35. package/boilerplates/02-saas-starter/backend/src/config/database.ts +26 -26
  36. package/boilerplates/02-saas-starter/backend/src/main.ts +26 -26
  37. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +46 -46
  38. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +25 -25
  39. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +145 -145
  40. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +30 -30
  41. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +24 -24
  42. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +19 -19
  43. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +42 -42
  44. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +13 -13
  45. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +67 -67
  46. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +52 -52
  47. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +36 -36
  48. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +16 -16
  49. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +13 -13
  50. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +34 -34
  51. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +40 -40
  52. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +36 -36
  53. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +13 -13
  54. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +91 -91
  55. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +42 -42
  56. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +14 -14
  57. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +13 -13
  58. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +48 -48
  59. package/boilerplates/02-saas-starter/backend/tsconfig.json +28 -28
  60. package/boilerplates/02-saas-starter/boilerplate.manifest.json +42 -42
  61. package/boilerplates/02-saas-starter/docker-compose.yml +34 -34
  62. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +227 -227
  63. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +141 -141
  64. package/boilerplates/02-saas-starter/memory/00-global/index.md +133 -133
  65. package/boilerplates/02-saas-starter/memory/00-global/mission.md +45 -45
  66. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +223 -223
  67. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +240 -240
  68. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +239 -239
  69. package/boilerplates/02-saas-starter/memory/10-product/personas.md +195 -195
  70. package/boilerplates/02-saas-starter/memory/10-product/vision.md +63 -63
  71. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +232 -232
  72. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +186 -186
  73. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +85 -85
  74. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +262 -262
  75. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +137 -137
  76. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +176 -176
  77. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +100 -100
  78. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +81 -81
  79. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +97 -97
  80. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +57 -57
  81. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +90 -90
  82. package/boilerplates/02-saas-starter/memory/60-runs/index.md +54 -54
  83. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +50 -50
  84. package/boilerplates/02-saas-starter/memory/80-data/schema.md +185 -185
  85. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +75 -75
  86. package/boilerplates/03-ecommerce-starter/FLOW_EXEMPLOS.md +599 -599
  87. package/boilerplates/03-ecommerce-starter/GUIA_RAPIDO.md +322 -322
  88. package/boilerplates/03-ecommerce-starter/MANIFEST.md +463 -463
  89. package/boilerplates/03-ecommerce-starter/README.md +465 -465
  90. package/boilerplates/03-ecommerce-starter/backend/.env.example +121 -121
  91. package/boilerplates/03-ecommerce-starter/backend/Dockerfile +15 -15
  92. package/boilerplates/03-ecommerce-starter/backend/docker-compose.yml +56 -56
  93. package/boilerplates/03-ecommerce-starter/backend/jest.config.js +16 -16
  94. package/boilerplates/03-ecommerce-starter/backend/package.json +71 -71
  95. package/boilerplates/03-ecommerce-starter/backend/src/app.controller.ts +12 -12
  96. package/boilerplates/03-ecommerce-starter/backend/src/app.module.ts +48 -48
  97. package/boilerplates/03-ecommerce-starter/backend/src/app.service.ts +12 -12
  98. package/boilerplates/03-ecommerce-starter/backend/src/main.ts +51 -51
  99. package/boilerplates/03-ecommerce-starter/backend/src/modules/auth/auth.module.ts +8 -8
  100. package/boilerplates/03-ecommerce-starter/backend/src/modules/cart/cart.module.ts +8 -8
  101. package/boilerplates/03-ecommerce-starter/backend/src/modules/coupons/coupons.module.ts +8 -8
  102. package/boilerplates/03-ecommerce-starter/backend/src/modules/inventory/inventory.module.ts +8 -8
  103. package/boilerplates/03-ecommerce-starter/backend/src/modules/orders/orders.module.ts +10 -10
  104. package/boilerplates/03-ecommerce-starter/backend/src/modules/payments/payments.module.ts +8 -8
  105. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/dto/create-product.dto.ts +34 -34
  106. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/category.entity.ts +47 -47
  107. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/entities/product.entity.ts +66 -66
  108. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.controller.ts +78 -78
  109. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.module.ts +14 -14
  110. package/boilerplates/03-ecommerce-starter/backend/src/modules/products/products.service.ts +112 -112
  111. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/entities/review.entity.ts +32 -32
  112. package/boilerplates/03-ecommerce-starter/backend/src/modules/reviews/reviews.module.ts +11 -11
  113. package/boilerplates/03-ecommerce-starter/backend/test/health.e2e-spec.ts +31 -31
  114. package/boilerplates/03-ecommerce-starter/backend/test/jest-e2e.json +12 -12
  115. package/boilerplates/03-ecommerce-starter/backend/tsconfig.json +23 -23
  116. package/boilerplates/03-ecommerce-starter/boilerplate.manifest.json +42 -42
  117. package/boilerplates/03-ecommerce-starter/boilerplate.md +128 -128
  118. package/boilerplates/03-ecommerce-starter/memory/00-global/agent-contract.md +53 -53
  119. package/boilerplates/03-ecommerce-starter/memory/00-global/context-index.md +55 -55
  120. package/boilerplates/03-ecommerce-starter/memory/00-global/context-policy.md +31 -31
  121. package/boilerplates/03-ecommerce-starter/memory/00-global/mission.md +25 -25
  122. package/boilerplates/03-ecommerce-starter/memory/00-global/standards.md +45 -45
  123. package/boilerplates/03-ecommerce-starter/memory/10-product/business-rules.md +62 -62
  124. package/boilerplates/03-ecommerce-starter/memory/10-product/nfrs.md +62 -62
  125. package/boilerplates/03-ecommerce-starter/memory/10-product/vision.md +124 -124
  126. package/boilerplates/03-ecommerce-starter/memory/20-architecture/backend.md +253 -253
  127. package/boilerplates/03-ecommerce-starter/memory/20-architecture/observability.md +319 -319
  128. package/boilerplates/03-ecommerce-starter/memory/20-architecture/overview.md +133 -133
  129. package/boilerplates/03-ecommerce-starter/memory/20-architecture/security.md +227 -227
  130. package/boilerplates/03-ecommerce-starter/memory/30-domains/catalog/context.md +210 -210
  131. package/boilerplates/03-ecommerce-starter/memory/30-domains/inventory/context.md +233 -233
  132. package/boilerplates/03-ecommerce-starter/memory/30-domains/orders/context.md +210 -210
  133. package/boilerplates/03-ecommerce-starter/memory/30-domains/payments/context.md +168 -168
  134. package/boilerplates/03-ecommerce-starter/memory/80-data/sqlite.md +260 -260
  135. package/boilerplates/03-ecommerce-starter/memory/90-decisions/ADR-TEMPLATE.md +223 -223
  136. package/boilerplates/04-microservices-starter/.env.example +43 -43
  137. package/boilerplates/04-microservices-starter/API-EXAMPLES.md +609 -609
  138. package/boilerplates/04-microservices-starter/ARCHITECTURE.md +512 -512
  139. package/boilerplates/04-microservices-starter/GETTING-STARTED.md +246 -246
  140. package/boilerplates/04-microservices-starter/INDEX.md +377 -377
  141. package/boilerplates/04-microservices-starter/MANIFEST.md +456 -456
  142. package/boilerplates/04-microservices-starter/README.md +466 -466
  143. package/boilerplates/04-microservices-starter/SUMMARY.md +386 -386
  144. package/boilerplates/04-microservices-starter/backend/api-gateway/Dockerfile +14 -14
  145. package/boilerplates/04-microservices-starter/backend/api-gateway/package.json +29 -29
  146. package/boilerplates/04-microservices-starter/backend/api-gateway/src/app.module.ts +9 -9
  147. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.controller.ts +45 -45
  148. package/boilerplates/04-microservices-starter/backend/api-gateway/src/gateway.service.ts +114 -114
  149. package/boilerplates/04-microservices-starter/backend/api-gateway/src/main.ts +9 -9
  150. package/boilerplates/04-microservices-starter/backend/api-gateway/tsconfig.json +20 -20
  151. package/boilerplates/04-microservices-starter/backend/services/auth-service/Dockerfile +14 -14
  152. package/boilerplates/04-microservices-starter/backend/services/auth-service/package.json +42 -42
  153. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/app.module.ts +7 -7
  154. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/main.ts +9 -9
  155. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.controller.ts +130 -130
  156. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.module.ts +21 -21
  157. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/auth.service.ts +159 -159
  158. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/jwt.strategy.ts +19 -19
  159. package/boilerplates/04-microservices-starter/backend/services/auth-service/src/modules/auth/local.strategy.ts +18 -18
  160. package/boilerplates/04-microservices-starter/backend/services/auth-service/tsconfig.json +21 -21
  161. package/boilerplates/04-microservices-starter/backend/services/notification-service/Dockerfile +14 -14
  162. package/boilerplates/04-microservices-starter/backend/services/notification-service/package.json +25 -25
  163. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/app.module.ts +7 -7
  164. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/main.ts +9 -9
  165. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.controller.ts +160 -160
  166. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.module.ts +10 -10
  167. package/boilerplates/04-microservices-starter/backend/services/notification-service/src/modules/notification/notification.service.ts +92 -92
  168. package/boilerplates/04-microservices-starter/backend/services/notification-service/tsconfig.json +20 -20
  169. package/boilerplates/04-microservices-starter/backend/services/user-service/Dockerfile +14 -14
  170. package/boilerplates/04-microservices-starter/backend/services/user-service/package.json +25 -25
  171. package/boilerplates/04-microservices-starter/backend/services/user-service/src/app.module.ts +7 -7
  172. package/boilerplates/04-microservices-starter/backend/services/user-service/src/main.ts +9 -9
  173. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.controller.ts +122 -122
  174. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.module.ts +10 -10
  175. package/boilerplates/04-microservices-starter/backend/services/user-service/src/modules/user/user.service.ts +161 -161
  176. package/boilerplates/04-microservices-starter/backend/services/user-service/tsconfig.json +20 -20
  177. package/boilerplates/04-microservices-starter/backend/shared/package.json +15 -15
  178. package/boilerplates/04-microservices-starter/backend/shared/src/constants/index.ts +84 -84
  179. package/boilerplates/04-microservices-starter/backend/shared/src/decorators/index.ts +12 -12
  180. package/boilerplates/04-microservices-starter/backend/shared/src/index.ts +4 -4
  181. package/boilerplates/04-microservices-starter/backend/shared/src/interfaces/index.ts +152 -152
  182. package/boilerplates/04-microservices-starter/backend/shared/src/utils/index.ts +54 -54
  183. package/boilerplates/04-microservices-starter/backend/shared/tsconfig.json +20 -20
  184. package/boilerplates/04-microservices-starter/boilerplate.manifest.json +41 -41
  185. package/boilerplates/04-microservices-starter/docker-compose.yml +164 -164
  186. package/boilerplates/04-microservices-starter/memory/00-global/agent-contract.md +171 -171
  187. package/boilerplates/04-microservices-starter/memory/00-global/context-policy.md +89 -89
  188. package/boilerplates/04-microservices-starter/memory/00-global/index.md +102 -102
  189. package/boilerplates/04-microservices-starter/memory/00-global/mission.md +44 -44
  190. package/boilerplates/04-microservices-starter/memory/00-global/patterns.md +106 -106
  191. package/boilerplates/04-microservices-starter/memory/10-product/vision.md +76 -76
  192. package/boilerplates/04-microservices-starter/memory/20-architecture/overview.md +247 -247
  193. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/api.md +293 -293
  194. package/boilerplates/04-microservices-starter/memory/30-domains/auth-service/context.md +108 -108
  195. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/api.md +333 -333
  196. package/boilerplates/04-microservices-starter/memory/30-domains/notification-service/context.md +121 -121
  197. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/api.md +308 -308
  198. package/boilerplates/04-microservices-starter/memory/30-domains/user-service/context.md +120 -120
  199. package/boilerplates/04-microservices-starter/memory/50-orchestration/topology.md +216 -216
  200. package/boilerplates/04-microservices-starter/package.json +21 -21
  201. package/boilerplates/05-monorepo-starter/.env.example +1 -1
  202. package/boilerplates/05-monorepo-starter/BOILERPLATE_SUMMARY.md +193 -193
  203. package/boilerplates/05-monorepo-starter/DEVELOPMENT.md +481 -481
  204. package/boilerplates/05-monorepo-starter/Dockerfile +35 -35
  205. package/boilerplates/05-monorepo-starter/README.md +318 -318
  206. package/boilerplates/05-monorepo-starter/boilerplate.manifest.json +43 -43
  207. package/boilerplates/05-monorepo-starter/docker-compose.yml +36 -36
  208. package/boilerplates/05-monorepo-starter/memory/00-global/agent-contract.md +28 -28
  209. package/boilerplates/05-monorepo-starter/memory/00-global/context-policy.md +21 -21
  210. package/boilerplates/05-monorepo-starter/memory/00-global/index.md +44 -44
  211. package/boilerplates/05-monorepo-starter/memory/00-global/mission.md +17 -17
  212. package/boilerplates/05-monorepo-starter/memory/00-global/patterns.md +48 -48
  213. package/boilerplates/05-monorepo-starter/memory/10-product/business-rules.md +24 -24
  214. package/boilerplates/05-monorepo-starter/memory/10-product/nfrs.md +39 -39
  215. package/boilerplates/05-monorepo-starter/memory/10-product/personas.md +25 -25
  216. package/boilerplates/05-monorepo-starter/memory/10-product/vision.md +22 -22
  217. package/boilerplates/05-monorepo-starter/memory/20-architecture/backend.md +85 -85
  218. package/boilerplates/05-monorepo-starter/memory/20-architecture/data.md +66 -66
  219. package/boilerplates/05-monorepo-starter/memory/20-architecture/frontend.md +58 -58
  220. package/boilerplates/05-monorepo-starter/memory/20-architecture/overview.md +86 -86
  221. package/boilerplates/05-monorepo-starter/memory/20-architecture/security.md +58 -58
  222. package/boilerplates/05-monorepo-starter/memory/30-domains/order/api.md +81 -81
  223. package/boilerplates/05-monorepo-starter/memory/30-domains/order/context.md +63 -63
  224. package/boilerplates/05-monorepo-starter/memory/30-domains/product/api.md +81 -81
  225. package/boilerplates/05-monorepo-starter/memory/30-domains/product/context.md +56 -56
  226. package/boilerplates/05-monorepo-starter/memory/30-domains/user/api.md +99 -99
  227. package/boilerplates/05-monorepo-starter/memory/30-domains/user/context.md +58 -58
  228. package/boilerplates/05-monorepo-starter/package.json +30 -30
  229. package/boilerplates/05-monorepo-starter/packages/apps/backend/.env.example +15 -15
  230. package/boilerplates/05-monorepo-starter/packages/apps/backend/README.md +28 -28
  231. package/boilerplates/05-monorepo-starter/packages/apps/backend/package.json +53 -53
  232. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/app.module.ts +40 -40
  233. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/exceptions/global.exception.ts +32 -32
  234. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.guard.ts +5 -5
  235. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/jwt.strategy.ts +11 -11
  236. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/guards/roles.guard.ts +17 -17
  237. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/common/health.controller.ts +13 -13
  238. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/main.ts +28 -28
  239. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/dto/index.ts +23 -23
  240. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/entities/order.entity.ts +48 -48
  241. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.controller.ts +51 -51
  242. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.module.ts +13 -13
  243. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/orders/orders.service.ts +123 -123
  244. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/dto/index.ts +35 -35
  245. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/entities/product.entity.ts +28 -28
  246. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.controller.ts +49 -49
  247. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.module.ts +12 -12
  248. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/products/products.service.ts +79 -79
  249. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/dto/index.ts +24 -24
  250. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/entities/user.entity.ts +28 -28
  251. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.controller.ts +29 -29
  252. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.module.ts +15 -15
  253. package/boilerplates/05-monorepo-starter/packages/apps/backend/src/modules/users/users.service.ts +78 -78
  254. package/boilerplates/05-monorepo-starter/packages/apps/backend/tsconfig.json +25 -25
  255. package/boilerplates/05-monorepo-starter/packages/apps/frontend/.env.example +1 -1
  256. package/boilerplates/05-monorepo-starter/packages/apps/frontend/README.md +30 -30
  257. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/dashboard/page.tsx +39 -39
  258. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/layout.tsx +15 -15
  259. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/page.tsx +47 -47
  260. package/boilerplates/05-monorepo-starter/packages/apps/frontend/app/products/page.tsx +51 -51
  261. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/features/product-card.tsx +19 -19
  262. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/footer.tsx +10 -10
  263. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/header.tsx +24 -24
  264. package/boilerplates/05-monorepo-starter/packages/apps/frontend/components/layout/layout.tsx +13 -13
  265. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/api-client.ts +34 -34
  266. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/auth.ts +35 -35
  267. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/orders.ts +28 -28
  268. package/boilerplates/05-monorepo-starter/packages/apps/frontend/lib/products.ts +28 -28
  269. package/boilerplates/05-monorepo-starter/packages/apps/frontend/next.config.js +15 -15
  270. package/boilerplates/05-monorepo-starter/packages/apps/frontend/package.json +31 -31
  271. package/boilerplates/05-monorepo-starter/packages/apps/frontend/postcss.config.js +3 -3
  272. package/boilerplates/05-monorepo-starter/packages/apps/frontend/styles/globals.css +7 -7
  273. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tailwind.config.js +7 -7
  274. package/boilerplates/05-monorepo-starter/packages/apps/frontend/tsconfig.json +14 -14
  275. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/README.md +35 -35
  276. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/package.json +17 -17
  277. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/common.ts +18 -18
  278. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/order.ts +38 -38
  279. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/product.ts +33 -33
  280. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/api/user.ts +32 -32
  281. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/domain/index.ts +41 -41
  282. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/errors/index.ts +46 -46
  283. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/src/index.ts +7 -7
  284. package/boilerplates/05-monorepo-starter/packages/packages/shared-types/tsconfig.json +8 -8
  285. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/README.md +30 -30
  286. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/package.json +17 -17
  287. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/constants/index.ts +45 -45
  288. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/index.ts +4 -4
  289. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/index.ts +3 -3
  290. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/math.ts +30 -30
  291. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/utils/string.ts +48 -48
  292. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/src/validators/index.ts +44 -44
  293. package/boilerplates/05-monorepo-starter/packages/packages/shared-utils/tsconfig.json +8 -8
  294. package/boilerplates/05-monorepo-starter/tsconfig.json +23 -23
  295. package/boilerplates/05-monorepo-starter/turbo.json +35 -35
  296. package/boilerplates/06-clean-arch/README.md +48 -48
  297. package/boilerplates/06-clean-arch/WHEN-CLEAN-WHEN-LEAN.md +71 -71
  298. package/boilerplates/06-clean-arch/backend/package.json +43 -43
  299. package/boilerplates/06-clean-arch/backend/src/app.module.ts +20 -20
  300. package/boilerplates/06-clean-arch/backend/src/main.ts +10 -10
  301. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/place-order.usecase.ts +47 -47
  302. package/boilerplates/06-clean-arch/backend/src/modules/orders/application/ship-order.usecase.ts +28 -28
  303. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/money.vo.ts +30 -30
  304. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order-status.vo.ts +36 -36
  305. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.entity.ts +85 -85
  306. package/boilerplates/06-clean-arch/backend/src/modules/orders/domain/order.repository.ts +17 -17
  307. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/order.orm-entity.ts +24 -24
  308. package/boilerplates/06-clean-arch/backend/src/modules/orders/infrastructure/typeorm-order.repository.ts +57 -57
  309. package/boilerplates/06-clean-arch/backend/src/modules/orders/orders.module.ts +28 -28
  310. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.controller.ts +31 -31
  311. package/boilerplates/06-clean-arch/backend/src/modules/orders/presentation/orders.http.dto.ts +30 -30
  312. package/boilerplates/06-clean-arch/backend/src/modules/products/product.entity.ts +20 -20
  313. package/boilerplates/06-clean-arch/backend/src/modules/products/products.controller.ts +43 -43
  314. package/boilerplates/06-clean-arch/backend/src/modules/products/products.module.ts +11 -11
  315. package/boilerplates/06-clean-arch/backend/src/shared/result.ts +32 -32
  316. package/boilerplates/06-clean-arch/backend/test/orders/place-order.spec.ts +46 -46
  317. package/boilerplates/06-clean-arch/backend/tsconfig.json +16 -16
  318. package/boilerplates/06-clean-arch/boilerplate.manifest.json +43 -43
  319. package/boilerplates/06-clean-arch/memory/30-domains/orders/context.md +39 -39
  320. package/boilerplates/06-clean-arch/memory/30-domains/products/context.md +23 -23
  321. package/boilerplates/README.md +427 -427
  322. package/design-md/BRIEF-TEMPLATE.md +47 -47
  323. package/design-md/INDEX.md +35 -35
  324. package/design-md/MATRIX.md +24 -24
  325. package/design-md/PLAYBOOK.md +35 -35
  326. package/design-md/examples/agent-console-brief.md +48 -48
  327. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +8 -1
  328. package/dist/apps/dashboard/app/api/forja/guard.d.ts +24 -0
  329. package/dist/apps/dashboard/app/api/forja/guard.js +63 -0
  330. package/dist/apps/dashboard/app/dashboard-client.jsx +10 -10
  331. package/dist/apps/server/src/forja-nest.module.js +9 -4
  332. package/dist/apps/server/src/main.js +10 -1
  333. package/dist/bin/create-memory-nest-kit.js +17 -17
  334. package/dist/bin/init-project.js +38 -38
  335. package/dist/lib/audit.js +7 -7
  336. package/dist/lib/code-context.js +6 -0
  337. package/dist/lib/context-builder.js +32 -32
  338. package/dist/lib/core/architecture-gate.d.ts +20 -0
  339. package/dist/lib/core/architecture-gate.js +60 -0
  340. package/dist/lib/core/drift-gate.d.ts +18 -0
  341. package/dist/lib/core/drift-gate.js +55 -0
  342. package/dist/lib/core/gates.d.ts +9 -2
  343. package/dist/lib/core/gates.js +13 -2
  344. package/dist/lib/core/health.js +17 -1
  345. package/dist/lib/core/incident-search.d.ts +19 -0
  346. package/dist/lib/core/incident-search.js +32 -0
  347. package/dist/lib/core/model-pricing.d.ts +31 -0
  348. package/dist/lib/core/model-pricing.js +74 -0
  349. package/dist/lib/core/registry.d.ts +194 -0
  350. package/dist/lib/core/registry.js +194 -0
  351. package/dist/lib/core/release.d.ts +194 -0
  352. package/dist/lib/core/release.js +3 -0
  353. package/dist/lib/core/risk-collect.d.ts +19 -0
  354. package/dist/lib/core/risk-collect.js +173 -0
  355. package/dist/lib/drift-sentinel.d.ts +59 -0
  356. package/dist/lib/drift-sentinel.js +126 -0
  357. package/dist/lib/generators/memory-generator.js +691 -691
  358. package/dist/lib/generators/nest-generator.js +412 -398
  359. package/dist/lib/generators/readme-generator.js +180 -180
  360. package/dist/lib/governance-report.js +39 -39
  361. package/dist/lib/llm/codex-output.d.ts +12 -0
  362. package/dist/lib/llm/codex-output.js +56 -0
  363. package/dist/lib/llm/context.d.ts +5 -0
  364. package/dist/lib/llm/context.js +17 -0
  365. package/dist/lib/llm/session.d.ts +18 -0
  366. package/dist/lib/llm/session.js +34 -0
  367. package/dist/lib/llm/validation.d.ts +37 -0
  368. package/dist/lib/llm/validation.js +88 -0
  369. package/dist/lib/workspace.js +29 -29
  370. package/dist/packages/adapter-git/src/index.d.ts +1 -1
  371. package/dist/packages/adapter-git/src/index.js +11 -6
  372. package/dist/packages/adapter-nest/src/index.d.ts +19 -0
  373. package/dist/packages/adapter-nest/src/index.js +26 -1
  374. package/dist/packages/adapter-sqlite/src/index.d.ts +27 -1
  375. package/dist/packages/adapter-sqlite/src/index.js +61 -12
  376. package/dist/packages/contracts/src/index.d.ts +33 -0
  377. package/dist/packages/contracts/src/index.js +13 -0
  378. package/dist/packages/core/src/index.d.ts +12 -0
  379. package/dist/packages/core/src/index.js +29 -0
  380. package/dist/packages/engineering/architecture/src/index.d.ts +76 -0
  381. package/dist/packages/engineering/architecture/src/index.js +131 -0
  382. package/dist/packages/engineering/evidence/src/index.d.ts +41 -0
  383. package/dist/packages/engineering/evidence/src/index.js +31 -0
  384. package/dist/packages/engineering/identity/src/index.d.ts +57 -0
  385. package/dist/packages/engineering/identity/src/index.js +88 -0
  386. package/dist/packages/engineering/monitoring/src/index.d.ts +37 -0
  387. package/dist/packages/engineering/monitoring/src/index.js +40 -0
  388. package/dist/packages/engineering/provenance/src/index.d.ts +25 -0
  389. package/dist/packages/engineering/provenance/src/index.js +21 -0
  390. package/dist/packages/engineering/risk/src/index.d.ts +89 -0
  391. package/dist/packages/engineering/risk/src/index.js +120 -0
  392. package/dist/packages/evals/src/index.js +6 -0
  393. package/dist/packages/graph/src/index.d.ts +23 -1
  394. package/dist/packages/graph/src/index.js +88 -15
  395. package/dist/packages/llm/src/index.d.ts +8 -1
  396. package/dist/packages/llm/src/index.js +64 -7
  397. package/dist/packages/mcp/src/index.js +27 -8
  398. package/dist/packages/orchestration/src/index.d.ts +11 -1
  399. package/dist/packages/orchestration/src/index.js +34 -7
  400. package/dist/packages/policy/src/index.d.ts +40 -0
  401. package/dist/packages/policy/src/index.js +39 -4
  402. package/dist/packages/runtime/src/index.js +3 -0
  403. package/dist/packages/sandbox/src/index.d.ts +47 -0
  404. package/dist/packages/sandbox/src/index.js +59 -0
  405. package/dist/packages/validator/src/index.d.ts +8 -0
  406. package/dist/packages/validator/src/index.js +21 -6
  407. package/dist/scripts/adr.d.ts +17 -0
  408. package/dist/scripts/adr.js +152 -0
  409. package/dist/scripts/agent-harness.js +72 -64
  410. package/dist/scripts/agent-router.js +20 -20
  411. package/dist/scripts/agent.d.ts +27 -0
  412. package/dist/scripts/agent.js +249 -0
  413. package/dist/scripts/architecture.d.ts +16 -0
  414. package/dist/scripts/architecture.js +186 -0
  415. package/dist/scripts/build-smart-context.js +22 -22
  416. package/dist/scripts/compress-memory.js +8 -8
  417. package/dist/scripts/context-ops.js +29 -29
  418. package/dist/scripts/cost-economy.d.ts +2 -0
  419. package/dist/scripts/cost-economy.js +79 -0
  420. package/dist/scripts/demo-autonomy.js +13 -6
  421. package/dist/scripts/dev.js +13 -13
  422. package/dist/scripts/drift-check.d.ts +17 -0
  423. package/dist/scripts/drift-check.js +63 -0
  424. package/dist/scripts/engineer.d.ts +20 -0
  425. package/dist/scripts/engineer.js +208 -0
  426. package/dist/scripts/evidence.d.ts +12 -0
  427. package/dist/scripts/evidence.js +55 -0
  428. package/dist/scripts/extract-global-knowledge.js +5 -5
  429. package/dist/scripts/gates.d.ts +6 -2
  430. package/dist/scripts/gates.js +14 -4
  431. package/dist/scripts/generate-dashboard.js +11 -11
  432. package/dist/scripts/incident.d.ts +19 -0
  433. package/dist/scripts/incident.js +103 -0
  434. package/dist/scripts/llm-fit.js +85 -9
  435. package/dist/scripts/memory-schema.js +48 -48
  436. package/dist/scripts/provenance.d.ts +14 -0
  437. package/dist/scripts/provenance.js +114 -0
  438. package/dist/scripts/query-universal-memory.js +13 -13
  439. package/dist/scripts/risk.d.ts +15 -0
  440. package/dist/scripts/risk.js +81 -0
  441. package/dist/scripts/simulate.d.ts +20 -0
  442. package/dist/scripts/simulate.js +150 -0
  443. package/dist/scripts/sprint-manager.js +39 -39
  444. package/dist/scripts/sync-universal-memory.js +44 -44
  445. package/docs/2x/CLI-CAPABILITIES.md +35 -35
  446. package/docs/2x/IMPLEMENTATION-AUDIT.md +40 -40
  447. package/docs/2x/SPRINT-1-CLI-CAPABILITY-PLAN.md +53 -53
  448. package/docs/2x/SPRINT-10-GRAPH-SYNC-PLAN.md +54 -54
  449. package/docs/2x/SPRINT-11-GRAPH-SYNC-CLI-MCP-PLAN.md +38 -38
  450. package/docs/2x/SPRINT-12-REAL-AUTONOMY-PLAN.md +40 -40
  451. package/docs/2x/SPRINT-13-MCP-STDIO-PLAN.md +26 -26
  452. package/docs/2x/SPRINT-14-SERVER-RESTART-PLAN.md +28 -28
  453. package/docs/2x/SPRINT-15-CHAOS-SECURITY-PLAN.md +22 -22
  454. package/docs/2x/SPRINT-16-LAST-MILE-PLAN.md +25 -25
  455. package/docs/2x/SPRINT-2-CLI-CAPABILITY-PLAN.md +39 -39
  456. package/docs/2x/SPRINT-3-RUNTIME-PERSISTENCE-PLAN.md +42 -42
  457. package/docs/2x/SPRINT-4-MCP-REGISTRY-PLAN.md +35 -35
  458. package/docs/2x/SPRINT-5-SERVER-APPROVALS-AUDIT-PLAN.md +31 -31
  459. package/docs/2x/SPRINT-6-EVENTS-E2E-PLAN.md +55 -55
  460. package/docs/2x/SPRINT-7-GRAPHLOOP-PERSISTENCE-PLAN.md +60 -60
  461. package/docs/2x/SPRINT-8-CONTEXT-GRAPH-PLAN.md +64 -64
  462. package/docs/2x/SPRINT-9-DETERMINISTIC-EXTRACTORS-PLAN.md +51 -51
  463. package/docs/GUIA-ONBOARDING-EXECUTIVO.md +63 -63
  464. package/docs/GUIA-ONBOARDING-OPERACIONAL-PAPEIS.md +136 -136
  465. package/docs/GUIA-ONBOARDING-PROJETO.md +279 -279
  466. package/docs/agent-harnesses.md +149 -149
  467. package/docs/agent-operating-contract.md +26 -0
  468. package/docs/architecture/FORJA-2.0-ARCHITECTURE.md +109 -109
  469. package/docs/architecture/FORJA-2.0-IMPACT-FOUNDATION.md +273 -273
  470. package/docs/architecture/FORJA-3-ENGINEERING-INTELLIGENCE-ARCHITECTURE.md +442 -0
  471. package/docs/archive/CHECKLIST-FINAL.md +295 -295
  472. package/docs/archive/FASE2-SUMMARY.md +263 -263
  473. package/docs/archive/FASE3-PROGRESS.md +355 -355
  474. package/docs/archive/IMPLEMENTACAO-FASE1.md +476 -476
  475. package/docs/archive/INDICE-MASTER.md +282 -282
  476. package/docs/archive/PROJETO-COMPLETO.md +363 -363
  477. package/docs/archive/README-REFINAMENTO.md +293 -293
  478. package/docs/archive/REFERENCIA-RAPIDA.md +324 -324
  479. package/docs/archive/REFINAMENTO-v1.0.md +565 -565
  480. package/docs/archive/RELATORIO-TESTES-INTEGRACAO.md +223 -223
  481. package/docs/archive/START-HERE.md +319 -319
  482. package/docs/archive/SUMARIO-EXECUTIVO.md +268 -268
  483. package/docs/archive/examples/v1/AGENTS.md +10 -10
  484. package/docs/archive/examples/v1/README.md +36 -36
  485. package/docs/archive/examples/v1/backend/jest-e2e.json +9 -9
  486. package/docs/archive/examples/v1/backend/nest-cli.json +4 -4
  487. package/docs/archive/examples/v1/backend/package.json +42 -42
  488. package/docs/archive/examples/v1/backend/src/app.controller.ts +12 -12
  489. package/docs/archive/examples/v1/backend/src/app.module.ts +10 -10
  490. package/docs/archive/examples/v1/backend/src/app.service.ts +8 -8
  491. package/docs/archive/examples/v1/backend/src/main.ts +10 -10
  492. package/docs/archive/examples/v1/backend/test/app.e2e-spec.ts +24 -24
  493. package/docs/archive/examples/v1/backend/tsconfig.build.json +4 -4
  494. package/docs/archive/examples/v1/backend/tsconfig.json +17 -17
  495. package/docs/archive/examples/v1/memory/00-global/glossary.md +5 -5
  496. package/docs/archive/examples/v1/memory/00-global/mission.md +9 -9
  497. package/docs/archive/examples/v1/memory/00-global/standards.md +12 -12
  498. package/docs/archive/examples/v1/memory/00-global/tooling.md +10 -10
  499. package/docs/archive/examples/v1/memory/10-product/business-rules.md +3 -3
  500. package/docs/archive/examples/v1/memory/10-product/nfrs.md +6 -6
  501. package/docs/archive/examples/v1/memory/10-product/personas.md +3 -3
  502. package/docs/archive/examples/v1/memory/10-product/vision.md +3 -3
  503. package/docs/archive/examples/v1/memory/20-architecture/backend.md +10 -10
  504. package/docs/archive/examples/v1/memory/20-architecture/data.md +3 -3
  505. package/docs/archive/examples/v1/memory/20-architecture/frontend.md +3 -3
  506. package/docs/archive/examples/v1/memory/20-architecture/observability.md +5 -5
  507. package/docs/archive/examples/v1/memory/20-architecture/security.md +6 -6
  508. package/docs/archive/examples/v1/memory/20-architecture/system-overview.md +3 -3
  509. package/docs/archive/examples/v1/memory/30-domains/auth/api.md +3 -3
  510. package/docs/archive/examples/v1/memory/30-domains/auth/context.md +3 -3
  511. package/docs/archive/examples/v1/memory/30-domains/auth/rules.md +3 -3
  512. package/docs/archive/examples/v1/memory/30-domains/billing/api.md +3 -3
  513. package/docs/archive/examples/v1/memory/30-domains/billing/context.md +3 -3
  514. package/docs/archive/examples/v1/memory/30-domains/billing/rules.md +3 -3
  515. package/docs/archive/examples/v1/memory/40-delivery/backlog.md +3 -3
  516. package/docs/archive/examples/v1/memory/40-delivery/current-sprint.md +10 -10
  517. package/docs/archive/examples/v1/memory/40-delivery/roadmap.md +3 -3
  518. package/docs/archive/examples/v1/memory/90-decisions/ADR-0001-template.md +9 -9
  519. package/docs/archive/examples/v1/prompts/project-prompt-base.md +19 -19
  520. package/docs/archive/examples/v2/.memoryrc.json +8 -8
  521. package/docs/archive/examples/v2/AGENTS.md +16 -16
  522. package/docs/archive/examples/v2/README.md +35 -35
  523. package/docs/archive/examples/v2/agents/README.md +3 -3
  524. package/docs/archive/examples/v2/agents/backend-nest.md +9 -9
  525. package/docs/archive/examples/v2/agents/dba.md +4 -4
  526. package/docs/archive/examples/v2/agents/frontend.md +4 -4
  527. package/docs/archive/examples/v2/agents/orchestrator.md +9 -9
  528. package/docs/archive/examples/v2/agents/reviewer.md +6 -6
  529. package/docs/archive/examples/v2/agents/security.md +4 -4
  530. package/docs/archive/examples/v2/backend/jest-e2e.json +9 -9
  531. package/docs/archive/examples/v2/backend/nest-cli.json +4 -4
  532. package/docs/archive/examples/v2/backend/package.json +42 -42
  533. package/docs/archive/examples/v2/backend/src/app.controller.ts +12 -12
  534. package/docs/archive/examples/v2/backend/src/app.module.ts +10 -10
  535. package/docs/archive/examples/v2/backend/src/app.service.ts +8 -8
  536. package/docs/archive/examples/v2/backend/src/main.ts +10 -10
  537. package/docs/archive/examples/v2/backend/test/app.e2e-spec.ts +24 -24
  538. package/docs/archive/examples/v2/backend/tsconfig.build.json +4 -4
  539. package/docs/archive/examples/v2/backend/tsconfig.json +17 -17
  540. package/docs/archive/examples/v2/memory/00-global/agent-contract.md +15 -15
  541. package/docs/archive/examples/v2/memory/00-global/context-index.md +12 -12
  542. package/docs/archive/examples/v2/memory/00-global/context-policy.md +14 -14
  543. package/docs/archive/examples/v2/memory/00-global/mission.md +9 -9
  544. package/docs/archive/examples/v2/memory/00-global/standards.md +12 -12
  545. package/docs/archive/examples/v2/memory/10-product/business-rules.md +3 -3
  546. package/docs/archive/examples/v2/memory/10-product/nfrs.md +6 -6
  547. package/docs/archive/examples/v2/memory/10-product/personas.md +3 -3
  548. package/docs/archive/examples/v2/memory/10-product/vision.md +3 -3
  549. package/docs/archive/examples/v2/memory/20-architecture/backend.md +10 -10
  550. package/docs/archive/examples/v2/memory/20-architecture/data.md +3 -3
  551. package/docs/archive/examples/v2/memory/20-architecture/frontend.md +3 -3
  552. package/docs/archive/examples/v2/memory/20-architecture/observability.md +5 -5
  553. package/docs/archive/examples/v2/memory/20-architecture/security.md +6 -6
  554. package/docs/archive/examples/v2/memory/20-architecture/system-overview.md +3 -3
  555. package/docs/archive/examples/v2/memory/30-domains/auth/api.md +3 -3
  556. package/docs/archive/examples/v2/memory/30-domains/auth/context.md +3 -3
  557. package/docs/archive/examples/v2/memory/30-domains/auth/rules.md +3 -3
  558. package/docs/archive/examples/v2/memory/30-domains/billing/api.md +3 -3
  559. package/docs/archive/examples/v2/memory/30-domains/billing/context.md +3 -3
  560. package/docs/archive/examples/v2/memory/30-domains/billing/rules.md +3 -3
  561. package/docs/archive/examples/v2/memory/40-delivery/backlog.md +3 -3
  562. package/docs/archive/examples/v2/memory/40-delivery/current-sprint.md +10 -10
  563. package/docs/archive/examples/v2/memory/40-delivery/roadmap.md +3 -3
  564. package/docs/archive/examples/v2/memory/50-orchestration/handoff-protocol.md +8 -8
  565. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/2026-04-18T18-40-10.517Z_orchestrator_para_backend-nest.md +19 -19
  566. package/docs/archive/examples/v2/memory/50-orchestration/handoffs/README.md +4 -4
  567. package/docs/archive/examples/v2/memory/50-orchestration/parallel-playbook.md +9 -9
  568. package/docs/archive/examples/v2/memory/50-orchestration/routing.md +10 -10
  569. package/docs/archive/examples/v2/memory/50-orchestration/topology.md +15 -15
  570. package/docs/archive/examples/v2/memory/60-runs/README.md +3 -3
  571. package/docs/archive/examples/v2/memory/70-summaries/domain-summary.md +3 -3
  572. package/docs/archive/examples/v2/memory/70-summaries/global-summary.md +6 -6
  573. package/docs/archive/examples/v2/memory/90-decisions/ADR-0001-template.md +9 -9
  574. package/docs/archive/examples/v2/memory/README.md +8 -8
  575. package/docs/archive/examples/v2/prompts/multi-agent-orchestrator.md +12 -12
  576. package/docs/archive/examples/v2/prompts/project-prompt-base.md +21 -21
  577. package/docs/archive/examples/v2/prompts/worker-task-template.md +10 -10
  578. package/docs/archive/examples/v2/scripts/append-handoff.mjs +25 -25
  579. package/docs/archive/examples/v2/scripts/build-context-pack.mjs +31 -31
  580. package/docs/archive/examples/v2/skills/context-compaction/SKILL.md +9 -9
  581. package/docs/archive/examples/v2/skills/handoff/SKILL.md +8 -8
  582. package/docs/archive/examples/v2/skills/nest-api/SKILL.md +7 -7
  583. package/docs/archive/examples/v2/skills/triage-task/SKILL.md +10 -10
  584. package/docs/archive/legacy-bin/create-memory-nest-kit-monolith.js +1486 -1486
  585. package/docs/capacidades-externas.md +86 -86
  586. package/docs/cli-first-operacao.md +74 -74
  587. package/docs/dev-workflow.md +421 -421
  588. package/docs/examples.md +546 -546
  589. package/docs/fluxo.md +103 -103
  590. package/docs/glossary.md +453 -453
  591. package/docs/init-project.md +457 -457
  592. package/docs/llm-evolution.md +51 -0
  593. package/docs/llm-fit-loop.md +134 -5
  594. package/docs/manual-operacional-cli-sdd-gsd.md +1014 -1014
  595. package/docs/personas/architect/README.md +333 -333
  596. package/docs/personas/developer/README.md +371 -371
  597. package/docs/personas/executive/README.md +172 -172
  598. package/docs/personas/qa/README.md +350 -350
  599. package/docs/processo-projeto.md +138 -138
  600. package/docs/publishing.md +49 -377
  601. package/docs/quick-reference.md +409 -409
  602. package/docs/security/FORJA-2.0-RELEASE-AUDIT-2026-08-01.md +95 -95
  603. package/docs/structure.md +360 -360
  604. package/docs/token-optimization.md +502 -502
  605. package/docs/vision/FORJA-2.0-VISION.md +72 -72
  606. package/memory/00-global/mission.md +15 -15
  607. package/memory/00-global/shared-knowledge.md +8 -8
  608. package/memory/00-global/standards.md +47 -47
  609. package/memory/10-product/personas.md +21 -21
  610. package/memory/10-product/vision.md +27 -27
  611. package/memory/30-projects/README.md +15 -15
  612. package/memory/40-delivery/backlog.md +15 -15
  613. package/memory/40-delivery/current-sprint.md +20 -20
  614. package/memory/50-orchestration/gsd-harness.md +55 -55
  615. package/memory/50-orchestration/handoffs/2026-07-31_architect_foundation-contracts.md +15 -15
  616. package/memory/50-orchestration/handoffs/2026-07-31_backend-nest.md +22 -22
  617. package/memory/50-orchestration/handoffs/2026-07-31_context-engine.md +16 -16
  618. package/memory/50-orchestration/handoffs/2026-07-31_control-plane.md +28 -28
  619. package/memory/50-orchestration/handoffs/2026-07-31_core-capability-registry.md +15 -15
  620. package/memory/50-orchestration/handoffs/2026-07-31_evals-plugin-sdk.md +22 -22
  621. package/memory/50-orchestration/handoffs/2026-07-31_events-scheduler.md +16 -16
  622. package/memory/50-orchestration/handoffs/2026-07-31_graphloop.md +16 -16
  623. package/memory/50-orchestration/handoffs/2026-07-31_mcp.md +21 -21
  624. package/memory/50-orchestration/handoffs/2026-07-31_nest-bootstrap.md +28 -28
  625. package/memory/50-orchestration/handoffs/2026-07-31_next-dashboard.md +22 -22
  626. package/memory/50-orchestration/handoffs/2026-07-31_observability.md +27 -27
  627. package/memory/50-orchestration/handoffs/2026-07-31_orchestration.md +21 -21
  628. package/memory/50-orchestration/handoffs/2026-07-31_planner-validator.md +16 -16
  629. package/memory/50-orchestration/handoffs/2026-07-31_policy-engine.md +14 -14
  630. package/memory/50-orchestration/handoffs/2026-07-31_runtime-control-plane.md +23 -23
  631. package/memory/50-orchestration/handoffs/2026-07-31_runtime-controlado.md +15 -15
  632. package/memory/50-orchestration/handoffs/2026-07-31_sandbox.md +21 -21
  633. package/memory/50-orchestration/handoffs/2026-07-31_sdk.md +27 -27
  634. package/memory/50-orchestration/handoffs/2026-07-31_sqlite-adapter.md +21 -21
  635. package/memory/50-orchestration/handoffs/2026-07-31_worker-dashboard-boundary.md +23 -23
  636. package/memory/50-orchestration/handoffs/2026-08-01_approval-server-identity.md +23 -23
  637. package/memory/50-orchestration/handoffs/2026-08-01_dashboard-auth-query.md +24 -24
  638. package/memory/50-orchestration/handoffs/2026-08-01_graphloop-approvals.md +23 -23
  639. package/memory/50-orchestration/handoffs/2026-08-01_sprint-1-cli-capabilities.md +41 -41
  640. package/memory/50-orchestration/handoffs/2026-08-01_sprint-10-graph-sync.md +23 -23
  641. package/memory/50-orchestration/handoffs/2026-08-01_sprint-11-graph-sync-cli-mcp.md +22 -22
  642. package/memory/50-orchestration/handoffs/2026-08-01_sprint-12-real-autonomy.md +16 -16
  643. package/memory/50-orchestration/handoffs/2026-08-01_sprint-2-cli-capabilities.md +30 -30
  644. package/memory/50-orchestration/handoffs/2026-08-01_sprint-3-runtime-persistence.md +29 -29
  645. package/memory/50-orchestration/handoffs/2026-08-01_sprint-4-mcp.md +29 -29
  646. package/memory/50-orchestration/handoffs/2026-08-01_sprint-5-server-approvals-audit.md +22 -22
  647. package/memory/50-orchestration/handoffs/2026-08-01_sprint-6-events-e2e.md +25 -25
  648. package/memory/50-orchestration/handoffs/2026-08-01_sprint-7-graphloop.md +23 -23
  649. package/memory/50-orchestration/handoffs/2026-08-01_sprint-8-context-graph.md +23 -23
  650. package/memory/50-orchestration/handoffs/2026-08-01_sprint-9-extractors.md +21 -21
  651. package/memory/50-orchestration/handoffs/2026-08-02_sprint-13-mcp-stdio.md +14 -14
  652. package/memory/50-orchestration/handoffs/2026-08-02_sprint-14-server-restart.md +15 -15
  653. package/memory/50-orchestration/handoffs/2026-08-02_sprint-15-chaos-security.md +13 -13
  654. package/memory/50-orchestration/handoffs/2026-08-02_sprint-16-last-mile.md +11 -11
  655. package/memory/90-decisions/0001-memoria-hierarquica.md +38 -38
  656. package/memory/90-decisions/0002-sqlite-fts5-busca.md +25 -25
  657. package/memory/90-decisions/0003-smart-context-3-modos.md +31 -31
  658. package/memory/90-decisions/0004-validacao-obrigatoria-nest.md +27 -27
  659. package/memory/90-decisions/0005-handoff-7-campos.md +32 -32
  660. package/memory/90-decisions/0006-docs-por-persona.md +23 -23
  661. package/memory/90-decisions/0007-sdd-pipeline.md +33 -33
  662. package/memory/90-decisions/0008-sub-agents-claude-handoff-sqlite.md +36 -36
  663. package/memory/90-decisions/0009-claude-hooks-token-economy.md +43 -43
  664. package/memory/90-decisions/0010-banco-postgres.md +30 -30
  665. package/memory/90-decisions/0011-adrs-de-produto-realocadas.md +19 -19
  666. package/memory/90-decisions/0016-integracao-capacidades-externas.md +64 -64
  667. package/memory/90-decisions/0017-codegraph-no-harness-gsd.md +40 -40
  668. package/memory/90-decisions/0018-ferramentas-de-processo.md +46 -46
  669. package/memory/90-decisions/0019-workspace-separado.md +45 -45
  670. package/memory/90-decisions/0020-forja-core-cli-unica.md +45 -45
  671. package/memory/90-decisions/0021-guardrails-de-harness.md +111 -111
  672. package/memory/90-decisions/0022-congelar-dashboard-web.md +101 -101
  673. package/memory/90-decisions/0023-doctor-como-gate-do-nucleo.md +114 -114
  674. package/memory/90-decisions/0024-gate-do-tarball.md +103 -103
  675. package/memory/90-decisions/0025-coerencia-da-documentacao.md +105 -105
  676. package/memory/90-decisions/0026-migracao-typescript-runtime-duplo.md +66 -66
  677. package/memory/90-decisions/0027-clean-arch-calibrada.md +127 -127
  678. package/memory/90-decisions/0028-governanca-visivel.md +84 -84
  679. package/memory/90-decisions/0029-gate-do-projeto-gerado.md +59 -59
  680. package/memory/90-decisions/0030-projeto-gerado-herda-os-gates.md +53 -53
  681. package/memory/90-decisions/0031-motor-de-orquestracao.md +55 -55
  682. package/memory/90-decisions/0032-superficies-do-projeto-usam-cwd.md +63 -63
  683. package/memory/90-decisions/0033-doctor-distingue-permissao-de-corrupcao.md +64 -64
  684. package/memory/90-decisions/0034-forja-2-core-e-contratos.md +29 -29
  685. package/memory/90-decisions/0035-forja-2-local-first-e-autonomia.md +23 -23
  686. package/memory/90-decisions/0036-forja-2-capability-registry.md +30 -30
  687. package/memory/90-decisions/0037-forja-2-policy-engine-obrigatorio.md +28 -28
  688. package/memory/90-decisions/0038-forja-2-runtime-controlado.md +28 -28
  689. package/memory/90-decisions/0039-forja-2-event-bus-scheduler-local-first.md +31 -31
  690. package/memory/90-decisions/0040-forja-2-context-engine-budget-cache.md +32 -32
  691. package/memory/90-decisions/0041-forja-2-graphloop-separado-codegraph.md +32 -32
  692. package/memory/90-decisions/0042-forja-2-planner-validator-independentes.md +29 -29
  693. package/memory/90-decisions/0043-forja-2-orchestration-entities.md +16 -16
  694. package/memory/90-decisions/0044-forja-2-sandbox-worktree.md +19 -19
  695. package/memory/90-decisions/0045-forja-2-sqlite-adapter.md +19 -19
  696. package/memory/90-decisions/0046-forja-2-mcp-adapter.md +18 -18
  697. package/memory/90-decisions/0047-forja-2-backend-nest-adapter.md +19 -19
  698. package/memory/90-decisions/0048-forja-2-sdk-transport.md +18 -18
  699. package/memory/90-decisions/0049-forja-2-observability-control-plane.md +18 -18
  700. package/memory/90-decisions/0050-forja-2-control-plane-application-ports.md +18 -18
  701. package/memory/90-decisions/0051-forja-2-runtime-control-plane-composition.md +18 -18
  702. package/memory/90-decisions/0052-forja-2-deterministic-evaluation.md +15 -15
  703. package/memory/90-decisions/0053-forja-2-plugin-sdk-permissionado.md +16 -16
  704. package/memory/90-decisions/0054-forja-2-worker-dashboard-boundary.md +15 -15
  705. package/memory/90-decisions/0055-forja-2-next-dashboard-distribution.md +16 -16
  706. package/memory/90-decisions/0056-forja-2-dashboard-proxy-auth-query.md +16 -16
  707. package/memory/90-decisions/0057-forja-2-graphloop-approvals-dashboard.md +15 -15
  708. package/memory/90-decisions/0058-forja-2-approval-server-identity.md +15 -15
  709. package/memory/90-decisions/0059-cli-adapter-capability-registry.md +17 -17
  710. package/memory/90-decisions/0060-runtime-persistence-port.md +17 -17
  711. package/memory/90-decisions/0061-mcp-dynamic-registry-stdio.md +16 -16
  712. package/memory/90-decisions/0062-server-catalog-approval-audit.md +17 -17
  713. package/memory/90-decisions/0063-events-persistent-e2e.md +19 -19
  714. package/memory/90-decisions/0064-graphloop-sqlite-store.md +20 -20
  715. package/memory/90-decisions/0065-context-graph-source-cache.md +20 -20
  716. package/memory/90-decisions/0066-graph-deterministic-extractors.md +16 -16
  717. package/memory/90-decisions/0067-graph-sync-capability.md +17 -17
  718. package/memory/90-decisions/0068-graph-sync-cli-mcp.md +17 -17
  719. package/memory/90-decisions/0069-real-autonomy-demo.md +16 -16
  720. package/memory/90-decisions/0070-mcp-stdio-real.md +11 -11
  721. package/memory/90-decisions/0071-server-persistence-composition.md +12 -12
  722. package/memory/90-decisions/0072-sandbox-security-boundaries.md +9 -9
  723. package/memory/90-decisions/0073-last-mile-rollback-benchmark-plugins.md +17 -17
  724. package/memory/90-decisions/0077-cost-aware-autonomy-budget.md +95 -0
  725. package/memory/90-decisions/0078-forjajs-3-engineering-control-plane.md +116 -0
  726. package/memory/90-decisions/0079-autonomous-maintenance-readiness.md +102 -0
  727. package/memory/90-decisions/0080-llm-execution-evidence.md +42 -0
  728. package/memory/90-decisions/0081-llm-resume-validation.md +42 -0
  729. package/memory/90-decisions/_template.md +28 -28
  730. package/package.json +159 -157
  731. package/prompts/context-engineer-agent.md +13 -19
  732. package/prompts/governance-agent.md +13 -16
  733. package/prompts/marketing-agent.md +13 -13
  734. package/prompts/orchestrator-agent.md +13 -18
  735. package/prompts/product-agent.md +13 -13
  736. package/prompts/sdd-architect-agent.md +13 -20
  737. package/skills/MANIFEST.json +10 -0
  738. package/skills/llm-provider-routing/SKILL.md +18 -0
  739. package/specs/README.md +70 -70
  740. package/specs/_templates/plan.md +50 -43
  741. package/specs/_templates/spec.md +50 -43
  742. package/specs/_templates/tasks.md +39 -32
  743. package/specs/agent-identity-reputation/plan.md +133 -0
  744. package/specs/agent-identity-reputation/spec.md +125 -0
  745. package/specs/agent-identity-reputation/tasks.md +51 -0
  746. package/specs/agent-instructions-v4/plan.md +8 -0
  747. package/specs/agent-instructions-v4/spec.md +21 -0
  748. package/specs/agent-instructions-v4/tasks.md +12 -0
  749. package/specs/agent-runtime-monitoring/plan.md +78 -0
  750. package/specs/agent-runtime-monitoring/spec.md +92 -0
  751. package/specs/agent-runtime-monitoring/tasks.md +39 -0
  752. package/specs/ai-code-provenance/plan.md +71 -0
  753. package/specs/ai-code-provenance/spec.md +97 -0
  754. package/specs/ai-code-provenance/tasks.md +39 -0
  755. package/specs/architecture-constitution/plan.md +110 -0
  756. package/specs/architecture-constitution/spec.md +114 -0
  757. package/specs/architecture-constitution/tasks.md +58 -0
  758. package/specs/change-risk-engine/plan.md +130 -0
  759. package/specs/change-risk-engine/spec.md +119 -0
  760. package/specs/change-risk-engine/tasks.md +72 -0
  761. package/specs/clean-arch-boilerplate/plan.md +137 -137
  762. package/specs/clean-arch-boilerplate/spec.md +121 -121
  763. package/specs/clean-arch-boilerplate/tasks.md +70 -70
  764. package/specs/cli-first-operacao/plan.md +53 -53
  765. package/specs/cli-first-operacao/spec.md +53 -53
  766. package/specs/cli-first-operacao/tasks.md +53 -53
  767. package/specs/code-context/spec.md +56 -56
  768. package/specs/coerencia-do-sistema/plan.md +155 -155
  769. package/specs/coerencia-do-sistema/spec.md +123 -123
  770. package/specs/coerencia-do-sistema/tasks.md +115 -115
  771. package/specs/cost-aware-autonomy-budget/spec.md +102 -0
  772. package/specs/dev-token-assets-db/plan.md +71 -71
  773. package/specs/dev-token-assets-db/spec.md +58 -58
  774. package/specs/dev-token-assets-db/tasks.md +58 -58
  775. package/specs/doctor-do-nucleo/plan.md +165 -165
  776. package/specs/doctor-do-nucleo/spec.md +139 -139
  777. package/specs/doctor-do-nucleo/tasks.md +172 -172
  778. package/specs/drift-sentinel/spec.md +117 -0
  779. package/specs/engineer-facade-extension/plan.md +71 -0
  780. package/specs/engineer-facade-extension/spec.md +98 -0
  781. package/specs/engineer-facade-extension/tasks.md +36 -0
  782. package/specs/engineering-evidence-ledger/plan.md +121 -0
  783. package/specs/engineering-evidence-ledger/spec.md +90 -0
  784. package/specs/engineering-evidence-ledger/tasks.md +54 -0
  785. package/specs/engineering-graph-extensions/plan.md +92 -0
  786. package/specs/engineering-graph-extensions/spec.md +101 -0
  787. package/specs/engineering-graph-extensions/tasks.md +60 -0
  788. package/specs/engineering-intelligence/spec.md +177 -0
  789. package/specs/forja-core/spec.md +71 -71
  790. package/specs/gates/spec.md +63 -63
  791. package/specs/governanca-visivel/plan.md +122 -122
  792. package/specs/governanca-visivel/spec.md +112 -112
  793. package/specs/governanca-visivel/tasks.md +60 -60
  794. package/specs/harness-codegraph/spec.md +71 -71
  795. package/specs/learning-loop-incidents/plan.md +59 -0
  796. package/specs/learning-loop-incidents/spec.md +93 -0
  797. package/specs/learning-loop-incidents/tasks.md +36 -0
  798. package/specs/llm-integration-v2/plan.md +55 -0
  799. package/specs/llm-integration-v2/spec.md +61 -0
  800. package/specs/llm-integration-v2/tasks.md +28 -0
  801. package/specs/llm-resume-validation/plan.md +50 -0
  802. package/specs/llm-resume-validation/spec.md +35 -0
  803. package/specs/llm-resume-validation/tasks.md +19 -0
  804. package/specs/memory-audit/spec.md +54 -54
  805. package/specs/orchestrate/spec.md +108 -108
  806. package/specs/orchestration-coherent/spec.md +95 -95
  807. package/specs/pipeline-sdd-e-orquestracao/spec.md +61 -61
  808. package/specs/predictive-change-simulation/plan.md +109 -0
  809. package/specs/predictive-change-simulation/spec.md +107 -0
  810. package/specs/predictive-change-simulation/tasks.md +41 -0
  811. package/specs/project-smoke/spec.md +96 -96
  812. package/specs/project-upgrade/spec.md +58 -58
  813. package/specs/reestruturacao-forja-v2/plan.md +95 -95
  814. package/specs/reestruturacao-forja-v2/spec.md +74 -74
  815. package/specs/reestruturacao-forja-v2/tasks.md +113 -113
  816. package/specs/release-auditor-health/spec.md +23 -23
  817. package/specs/release-gate/plan.md +174 -174
  818. package/specs/release-gate/spec.md +122 -122
  819. package/specs/release-gate/tasks.md +183 -183
  820. package/specs/smart-agent-routing/plan.md +55 -0
  821. package/specs/smart-agent-routing/spec.md +85 -0
  822. package/specs/smart-agent-routing/tasks.md +26 -0
  823. package/specs/ts-migration/plan.md +200 -200
  824. package/specs/ts-migration/spec.md +119 -119
  825. package/specs/ts-migration/tasks.md +110 -110
@@ -1,512 +1,512 @@
1
- # 🏗️ ARCHITECTURE.md
2
-
3
- ## System Architecture
4
-
5
- ### High-Level Overview
6
-
7
- ```
8
- ┌─────────────────────────────────────────────────────────────────────┐
9
- │ EXTERNAL CLIENTS │
10
- │ (Web Browser, Mobile App, Desktop CLI) │
11
- └──────────────────────────────────┬──────────────────────────────────┘
12
- │
13
- ┌──────────────▼──────────────┐
14
- │ API GATEWAY (Port 3000) │
15
- │ ┌────────────────────────┐ │
16
- │ │ - Route Dispatcher │ │
17
- │ │ - CORS Enabled │ │
18
- │ │ - Request Logging │ │
19
- │ │ - Error Aggregation │ │
20
- │ └────────────────────────┘ │
21
- └────┬─────────────────┬─────┘
22
- │ │
23
- ┌────────────────▼────┐ ┌────────▼──────────┐
24
- │ AUTH SERVICE │ │ USER SERVICE │
25
- │ (Port 3001) │ │ (Port 3002) │
26
- │ ┌─────────────────┐ │ │ ┌────────────────┐│
27
- │ │ Controllers │ │ │ │ Controllers ││
28
- │ │ - register │ │ │ │ - getProfile ││
29
- │ │ - login │ │ │ │ - updateProfile││
30
- │ │ - refresh │ │ │ │ - deleteUser ││
31
- │ │ - logout │ │ │ │ - listUsers ││
32
- │ └─────────────────┘ │ │ └────────────────┘│
33
- │ ┌─────────────────┐ │ │ ┌────────────────┐│
34
- │ │ Services │ │ │ │ Services ││
35
- │ │ - Auth Logic │ │ │ │ - Profile Mgmt ││
36
- │ │ - JWT Tokens │ │ │ │ - Email Verify ││
37
- │ │ - Password Hash │ │ │ │ - Settings ││
38
- │ └─────────────────┘ │ │ └────────────────┘│
39
- │ ┌─────────────────┐ │ │ ┌────────────────┐│
40
- │ │ Persistence │ │ │ │ Persistence ││
41
- │ │ - In-memory map │ │ │ │ - In-memory map││
42
- │ │ (can be DB) │ │ │ │ (can be DB) ││
43
- │ └─────────────────┘ │ │ └────────────────┘│
44
- └────────┬──────────┘ └────────┬───────────┘
45
- │ │
46
- ┌────────▼──────────┐ ┌────────▼──────────┐
47
- │ PostgreSQL (Auth) │ │PostgreSQL (Users) │
48
- │ Port: 5432 │ │ Port: 5433 │
49
- │ DB: auth_db │ │ DB: users_db │
50
- └───────────────────┘ └───────────────────┘
51
- │ │
52
- ┌────────▼────────────────────┐
53
- │ NOTIFICATION SERVICE │
54
- │ (Port 3003) │
55
- │ ┌──────────────────────────┐│
56
- │ │ Controllers ││
57
- │ │ - sendEmail ││
58
- │ │ - sendPush ││
59
- │ │ - getStatus ││
60
- │ │ - listNotifications ││
61
- │ └──────────────────────────┘│
62
- │ ┌──────────────────────────┐│
63
- │ │ Services ││
64
- │ │ - Email Sending ││
65
- │ │ - Push Notifications ││
66
- │ │ - Event Consumption ││
67
- │ │ - Retry Logic ││
68
- │ └──────────────────────────┘│
69
- └────┬──────────────┬──────────┘
70
- │ │
71
- ┌────────▼──────┐ ┌────▼───────────┐
72
- │ RabbitMQ │ │ Redis Cache │
73
- │ (Port 5672) │ │ (Port 6379) │
74
- │ - user.events │ │ - Sessions │
75
- │ - auth.events │ │ - Token cache │
76
- │ - sys.events │ │ - Rate limits │
77
- └───────────────┘ └────────────────┘
78
- ```
79
-
80
- ---
81
-
82
- ## Service Boundaries
83
-
84
- ### Auth Service (Bounded Context)
85
- **Responsibility:** Authentication and authorization
86
-
87
- - ✅ User registration & login
88
- - ✅ Password hashing (bcrypt)
89
- - ✅ JWT token generation
90
- - ✅ Token refresh
91
- - ✅ Token validation
92
- - ✅ Session management
93
- - ❌ User profile data
94
- - ❌ Notification sending
95
-
96
- **Database:** PostgreSQL (auth_db)
97
- - Users table
98
- - Refresh tokens table
99
- - Sessions table
100
-
101
- **External Dependencies:**
102
- - Redis for token blacklist
103
- - RabbitMQ for event publishing
104
-
105
- ---
106
-
107
- ### User Service (Bounded Context)
108
- **Responsibility:** User profiles and settings
109
-
110
- - ✅ User profile CRUD
111
- - ✅ Profile settings management
112
- - ✅ Email verification
113
- - ✅ User search/listing
114
- - ❌ Authentication
115
- - ❌ Sending notifications directly
116
-
117
- **Database:** PostgreSQL (users_db)
118
- - User profiles table
119
- - User settings table
120
- - Email verification table
121
-
122
- **External Dependencies:**
123
- - Auth Service (via API Gateway)
124
- - RabbitMQ for events
125
-
126
- ---
127
-
128
- ### Notification Service (Bounded Context)
129
- **Responsibility:** Multi-channel notifications
130
-
131
- - ✅ Email sending
132
- - ✅ Push notifications
133
- - ✅ Event-driven processing
134
- - ✅ Retry logic
135
- - ✅ Status tracking
136
- - ❌ User authentication
137
- - ❌ Storing user data
138
-
139
- **Storage:** Redis only (no database)
140
- - Notification cache
141
- - Retry counters
142
- - Delivery tracking
143
-
144
- **External Dependencies:**
145
- - RabbitMQ for event consumption
146
- - Redis for caching
147
- - Email/Push providers
148
-
149
- ---
150
-
151
- ## Communication Patterns
152
-
153
- ### Synchronous (HTTP REST)
154
-
155
- ```
156
- Client
157
- │
158
- ├─ POST /auth/login
159
- │ └─► API Gateway
160
- │ └─► Auth Service
161
- │
162
- ├─ GET /users/:id
163
- │ └─► API Gateway
164
- │ └─► User Service
165
- │
166
- └─ POST /notifications/email
167
- └─► API Gateway
168
- └─► Notification Service
169
- ```
170
-
171
- **Characteristics:**
172
- - Request-response model
173
- - Immediate feedback
174
- - Timeout: 5 seconds (default)
175
- - Retry: Circuit breaker protected
176
-
177
- ### Asynchronous (Message Queue)
178
-
179
- ```
180
- Auth Service publishes:
181
- user.registered
182
- │
183
- ├─► User Service consumer
184
- │ └─ Create profile
185
- │
186
- └─► Notification consumer
187
- └─ Send welcome email
188
- ```
189
-
190
- **Characteristics:**
191
- - Fire-and-forget
192
- - Loose coupling
193
- - Guaranteed delivery
194
- - Retry on failure
195
- - Event ordering per stream
196
-
197
- ---
198
-
199
- ## Data Architecture
200
-
201
- ### Database Per Service
202
-
203
- ```
204
- Auth DB (auth_db):
205
- ├── users
206
- │ ├─ id (PK)
207
- │ ├─ email (UNIQUE)
208
- │ ├─ password_hash (bcrypt)
209
- │ ├─ status (active/disabled)
210
- │ └─ created_at, updated_at
211
- │
212
- └── refresh_tokens
213
- ├─ id (PK)
214
- ├─ user_id (FK)
215
- ├─ token
216
- ├─ expires_at
217
- └─ device_id (optional)
218
-
219
- User DB (users_db):
220
- ├── user_profiles
221
- │ ├─ user_id (PK, FK → auth_db)
222
- │ ├─ email
223
- │ ├─ full_name
224
- │ ├─ avatar_url
225
- │ ├─ bio
226
- │ ├─ email_verified
227
- │ └─ created_at, updated_at
228
- │
229
- └── user_settings
230
- ├─ user_id (PK, FK)
231
- ├─ theme
232
- ├─ notifications_enabled
233
- ├─ language
234
- └─ timezone
235
-
236
- Notification Service (Redis):
237
- └── (Stateless - reads from RabbitMQ events)
238
- ├─ notification:{id} → JSON
239
- ├─ notification:pending → Queue
240
- └─ notification:retry_count → Counter
241
- ```
242
-
243
- **Rationale:**
244
- - Independent scaling
245
- - Technology flexibility
246
- - Deployment isolation
247
- - Eventual consistency
248
-
249
- ### Caching Strategy
250
-
251
- ```
252
- Redis:
253
- ├── sessions:{sessionId} (TTL: 24h)
254
- ├── user_profile:{userId} (TTL: 1h)
255
- ├── auth_token_blacklist: (TTL: token expiry)
256
- ├── rate_limit:{ip} (TTL: 1m)
257
- └── notification:pending (TTL: varies)
258
- ```
259
-
260
- ---
261
-
262
- ## Request Flow Example
263
-
264
- ### Example: User Login & Profile Update
265
-
266
- ```
267
- 1. Client POST /auth/login
268
- │
269
- ├─► API Gateway receives request
270
- │ ├─ Generate request ID
271
- │ ├─ Extract headers
272
- │ └─ Route to /auth/login
273
- │
274
- ├─► Auth Service:
275
- │ ├─ Validate email/password
276
- │ ├─ Hash comparison
277
- │ ├─ Generate JWT tokens
278
- │ ├─ Store refresh token in Redis
279
- │ └─ Return tokens
280
- │
281
- ├─► API Gateway aggregates response
282
- │ └─ Return to client
283
- │
284
- ├─ Client stores tokens
285
- │
286
- └─► Client GET /users/:userId
287
- ├─► API Gateway
288
- │ ├─ Extract authorization header
289
- │ ├─ Pass JWT to User Service
290
- │ │
291
- │ ├─► User Service:
292
- │ │ ├─ Verify JWT (via Auth Service or JWT library)
293
- │ │ ├─ Query user_profiles table
294
- │ │ ├─ Check Redis cache
295
- │ │ └─ Return profile
296
- │ │
297
- │ └─ Aggregate response
298
- │
299
- └─ Return profile to client
300
- ```
301
-
302
- ---
303
-
304
- ## Error Handling Architecture
305
-
306
- ### Error Response Flow
307
-
308
- ```
309
- Service receives invalid request
310
- │
311
- ├─ Validate input
312
- │
313
- ├─ If invalid:
314
- │ ├─ Return 400 Bad Request
315
- │ └─ Include error code & message
316
- │
317
- ├─ Check authorization
318
- │ ├─ If unauthorized:
319
- │ │ ├─ Return 401/403
320
- │ │ └─ Include error details
321
- │
322
- ├─ Call downstream service
323
- │ ├─ If service unavailable:
324
- │ │ ├─ Circuit breaker opens
325
- │ │ ├─ Return 503 Service Unavailable
326
- │ │ └─ Retry after timeout
327
- │
328
- └─ If server error:
329
- ├─ Log error
330
- ├─ Return 500
331
- └─ Include request ID for tracking
332
- ```
333
-
334
- ### Error Codes
335
-
336
- ```
337
- Authentication:
338
- - INVALID_CREDENTIALS (401)
339
- - INVALID_TOKEN (401)
340
- - EMAIL_ALREADY_EXISTS (409)
341
-
342
- Authorization:
343
- - UNAUTHORIZED_UPDATE (403)
344
- - INSUFFICIENT_PERMISSIONS (403)
345
-
346
- Resource:
347
- - USER_NOT_FOUND (404)
348
- - NOTIFICATION_NOT_FOUND (404)
349
-
350
- Validation:
351
- - INVALID_EMAIL (400)
352
- - INVALID_PASSWORD (400)
353
-
354
- Rate Limiting:
355
- - TOO_MANY_ATTEMPTS (429)
356
- - RATE_LIMIT_EXCEEDED (429)
357
-
358
- Server:
359
- - SERVICE_UNAVAILABLE (503)
360
- - INTERNAL_ERROR (500)
361
- ```
362
-
363
- ---
364
-
365
- ## Scalability Considerations
366
-
367
- ### Horizontal Scaling
368
-
369
- ```
370
- Production Setup:
371
- ┌──────────────────────────────────┐
372
- │ Load Balancer │
373
- └────┬──────────────────────────┬──┘
374
- │ │
375
- ┌────▼──────────┐ ┌────────▼────┐
376
- │ API GW (pod1) │ │ API GW (pod2)│
377
- └────┬─────┬────┘ └────┬─────┬───┘
378
- │ │ │ │
379
- ┌──▼──┐ ┌──▼──┐ ┌─────▼─┐ ┌───▼──┐
380
- │Auth1│ │Auth2│ ... │User1 │ │User2 │ ...
381
- └─────┘ └─────┘ └───────┘ └──────┘
382
- ```
383
-
384
- **Scaling Rules:**
385
- - API Gateway: 1-3 replicas
386
- - Auth Service: 1-2 replicas
387
- - User Service: 1-2 replicas
388
- - Notification Service: 1 replica (or N for throughput)
389
-
390
- **Database Scaling:**
391
- - Read replicas for User DB
392
- - Connection pooling (PgBouncer)
393
- - Vertical scaling for Auth DB
394
-
395
- **Message Queue:**
396
- - RabbitMQ in cluster mode
397
- - Multiple consumer instances
398
-
399
- ---
400
-
401
- ## Deployment Topology
402
-
403
- ### Local Development
404
- ```
405
- Docker Compose:
406
- - Single Docker network
407
- - All services connected
408
- - Shared databases
409
- - Health checks enabled
410
- ```
411
-
412
- ### Production (Kubernetes)
413
- ```
414
- Namespace: microservices
415
- ├── api-gateway deployment (1-3 replicas)
416
- ├── auth-service statefulset (1-3 replicas)
417
- ├── user-service statefulset (1-3 replicas)
418
- ├── notification-service deployment (1-N replicas)
419
- ├── postgres-auth statefulset
420
- ├── postgres-user statefulset
421
- ├── rabbitmq statefulset (cluster)
422
- └── redis deployment (with persistence)
423
- ```
424
-
425
- ---
426
-
427
- ## Monitoring & Observability
428
-
429
- ### Logging
430
- ```
431
- Each service logs:
432
- - Request entry/exit
433
- - Service calls
434
- - Database queries
435
- - Errors with stack traces
436
- - Performance metrics
437
-
438
- Format: JSON for easy parsing
439
- {"timestamp": "...", "level": "INFO", "service": "auth-service", ...}
440
- ```
441
-
442
- ### Tracing
443
- ```
444
- X-Trace-Id: Generated at API Gateway
445
- X-Span-Id: Generated per service
446
- X-Parent-Span-Id: Propagated through calls
447
-
448
- Example flow:
449
- API Gateway → Auth Service
450
- X-Trace-Id: trace-001
451
- ├─ X-Span-Id: span-gateway-001
452
- └─ X-Span-Id: span-auth-001 (parent: span-gateway-001)
453
- ```
454
-
455
- ### Metrics
456
- ```
457
- Prometheus targets:
458
- - HTTP request count
459
- - HTTP request duration
460
- - Database query duration
461
- - Message queue depth
462
- - Cache hit/miss ratio
463
- ```
464
-
465
- ---
466
-
467
- ## Security Architecture
468
-
469
- ### Authentication & Authorization
470
- ```
471
- 1. Client sends credentials → Auth Service
472
- 2. Auth Service validates → Issues JWT
473
- 3. JWT stored in headers (Authorization: Bearer ...)
474
- 4. API Gateway verifies JWT signature
475
- 5. Each service validates token expiry
476
-
477
- Token Structure:
478
- {
479
- "userId": "...",
480
- "email": "...",
481
- "iat": 1234567890,
482
- "exp": 1234568790,
483
- "type": "access"
484
- }
485
- ```
486
-
487
- ### Data Protection
488
- ```
489
- - Passwords: bcrypt (cost: 12)
490
- - In-transit: HTTPS (TLS 1.3)
491
- - Tokens: JWT with RS256 signature
492
- - Sensitive data: Encrypted at rest
493
- ```
494
-
495
- ### Network Security
496
- ```
497
- - Services isolated to private network
498
- - API Gateway only public endpoint
499
- - Rate limiting per IP/user
500
- - Request validation on all endpoints
501
- ```
502
-
503
- ---
504
-
505
- ## Conclusion
506
-
507
- This architecture provides:
508
- - **Scalability**: Services scale independently
509
- - **Resilience**: Failures isolated per service
510
- - **Flexibility**: Different tech stacks per service
511
- - **Maintainability**: Clear service boundaries
512
- - **Observability**: Tracing and logging built-in
1
+ # 🏗️ ARCHITECTURE.md
2
+
3
+ ## System Architecture
4
+
5
+ ### High-Level Overview
6
+
7
+ ```
8
+ ┌─────────────────────────────────────────────────────────────────────┐
9
+ │ EXTERNAL CLIENTS │
10
+ │ (Web Browser, Mobile App, Desktop CLI) │
11
+ └──────────────────────────────────┬──────────────────────────────────┘
12
+ │
13
+ ┌──────────────▼──────────────┐
14
+ │ API GATEWAY (Port 3000) │
15
+ │ ┌────────────────────────┐ │
16
+ │ │ - Route Dispatcher │ │
17
+ │ │ - CORS Enabled │ │
18
+ │ │ - Request Logging │ │
19
+ │ │ - Error Aggregation │ │
20
+ │ └────────────────────────┘ │
21
+ └────┬─────────────────┬─────┘
22
+ │ │
23
+ ┌────────────────▼────┐ ┌────────▼──────────┐
24
+ │ AUTH SERVICE │ │ USER SERVICE │
25
+ │ (Port 3001) │ │ (Port 3002) │
26
+ │ ┌─────────────────┐ │ │ ┌────────────────┐│
27
+ │ │ Controllers │ │ │ │ Controllers ││
28
+ │ │ - register │ │ │ │ - getProfile ││
29
+ │ │ - login │ │ │ │ - updateProfile││
30
+ │ │ - refresh │ │ │ │ - deleteUser ││
31
+ │ │ - logout │ │ │ │ - listUsers ││
32
+ │ └─────────────────┘ │ │ └────────────────┘│
33
+ │ ┌─────────────────┐ │ │ ┌────────────────┐│
34
+ │ │ Services │ │ │ │ Services ││
35
+ │ │ - Auth Logic │ │ │ │ - Profile Mgmt ││
36
+ │ │ - JWT Tokens │ │ │ │ - Email Verify ││
37
+ │ │ - Password Hash │ │ │ │ - Settings ││
38
+ │ └─────────────────┘ │ │ └────────────────┘│
39
+ │ ┌─────────────────┐ │ │ ┌────────────────┐│
40
+ │ │ Persistence │ │ │ │ Persistence ││
41
+ │ │ - In-memory map │ │ │ │ - In-memory map││
42
+ │ │ (can be DB) │ │ │ │ (can be DB) ││
43
+ │ └─────────────────┘ │ │ └────────────────┘│
44
+ └────────┬──────────┘ └────────┬───────────┘
45
+ │ │
46
+ ┌────────▼──────────┐ ┌────────▼──────────┐
47
+ │ PostgreSQL (Auth) │ │PostgreSQL (Users) │
48
+ │ Port: 5432 │ │ Port: 5433 │
49
+ │ DB: auth_db │ │ DB: users_db │
50
+ └───────────────────┘ └───────────────────┘
51
+ │ │
52
+ ┌────────▼────────────────────┐
53
+ │ NOTIFICATION SERVICE │
54
+ │ (Port 3003) │
55
+ │ ┌──────────────────────────┐│
56
+ │ │ Controllers ││
57
+ │ │ - sendEmail ││
58
+ │ │ - sendPush ││
59
+ │ │ - getStatus ││
60
+ │ │ - listNotifications ││
61
+ │ └──────────────────────────┘│
62
+ │ ┌──────────────────────────┐│
63
+ │ │ Services ││
64
+ │ │ - Email Sending ││
65
+ │ │ - Push Notifications ││
66
+ │ │ - Event Consumption ││
67
+ │ │ - Retry Logic ││
68
+ │ └──────────────────────────┘│
69
+ └────┬──────────────┬──────────┘
70
+ │ │
71
+ ┌────────▼──────┐ ┌────▼───────────┐
72
+ │ RabbitMQ │ │ Redis Cache │
73
+ │ (Port 5672) │ │ (Port 6379) │
74
+ │ - user.events │ │ - Sessions │
75
+ │ - auth.events │ │ - Token cache │
76
+ │ - sys.events │ │ - Rate limits │
77
+ └───────────────┘ └────────────────┘
78
+ ```
79
+
80
+ ---
81
+
82
+ ## Service Boundaries
83
+
84
+ ### Auth Service (Bounded Context)
85
+ **Responsibility:** Authentication and authorization
86
+
87
+ - ✅ User registration & login
88
+ - ✅ Password hashing (bcrypt)
89
+ - ✅ JWT token generation
90
+ - ✅ Token refresh
91
+ - ✅ Token validation
92
+ - ✅ Session management
93
+ - ❌ User profile data
94
+ - ❌ Notification sending
95
+
96
+ **Database:** PostgreSQL (auth_db)
97
+ - Users table
98
+ - Refresh tokens table
99
+ - Sessions table
100
+
101
+ **External Dependencies:**
102
+ - Redis for token blacklist
103
+ - RabbitMQ for event publishing
104
+
105
+ ---
106
+
107
+ ### User Service (Bounded Context)
108
+ **Responsibility:** User profiles and settings
109
+
110
+ - ✅ User profile CRUD
111
+ - ✅ Profile settings management
112
+ - ✅ Email verification
113
+ - ✅ User search/listing
114
+ - ❌ Authentication
115
+ - ❌ Sending notifications directly
116
+
117
+ **Database:** PostgreSQL (users_db)
118
+ - User profiles table
119
+ - User settings table
120
+ - Email verification table
121
+
122
+ **External Dependencies:**
123
+ - Auth Service (via API Gateway)
124
+ - RabbitMQ for events
125
+
126
+ ---
127
+
128
+ ### Notification Service (Bounded Context)
129
+ **Responsibility:** Multi-channel notifications
130
+
131
+ - ✅ Email sending
132
+ - ✅ Push notifications
133
+ - ✅ Event-driven processing
134
+ - ✅ Retry logic
135
+ - ✅ Status tracking
136
+ - ❌ User authentication
137
+ - ❌ Storing user data
138
+
139
+ **Storage:** Redis only (no database)
140
+ - Notification cache
141
+ - Retry counters
142
+ - Delivery tracking
143
+
144
+ **External Dependencies:**
145
+ - RabbitMQ for event consumption
146
+ - Redis for caching
147
+ - Email/Push providers
148
+
149
+ ---
150
+
151
+ ## Communication Patterns
152
+
153
+ ### Synchronous (HTTP REST)
154
+
155
+ ```
156
+ Client
157
+ │
158
+ ├─ POST /auth/login
159
+ │ └─► API Gateway
160
+ │ └─► Auth Service
161
+ │
162
+ ├─ GET /users/:id
163
+ │ └─► API Gateway
164
+ │ └─► User Service
165
+ │
166
+ └─ POST /notifications/email
167
+ └─► API Gateway
168
+ └─► Notification Service
169
+ ```
170
+
171
+ **Characteristics:**
172
+ - Request-response model
173
+ - Immediate feedback
174
+ - Timeout: 5 seconds (default)
175
+ - Retry: Circuit breaker protected
176
+
177
+ ### Asynchronous (Message Queue)
178
+
179
+ ```
180
+ Auth Service publishes:
181
+ user.registered
182
+ │
183
+ ├─► User Service consumer
184
+ │ └─ Create profile
185
+ │
186
+ └─► Notification consumer
187
+ └─ Send welcome email
188
+ ```
189
+
190
+ **Characteristics:**
191
+ - Fire-and-forget
192
+ - Loose coupling
193
+ - Guaranteed delivery
194
+ - Retry on failure
195
+ - Event ordering per stream
196
+
197
+ ---
198
+
199
+ ## Data Architecture
200
+
201
+ ### Database Per Service
202
+
203
+ ```
204
+ Auth DB (auth_db):
205
+ ├── users
206
+ │ ├─ id (PK)
207
+ │ ├─ email (UNIQUE)
208
+ │ ├─ password_hash (bcrypt)
209
+ │ ├─ status (active/disabled)
210
+ │ └─ created_at, updated_at
211
+ │
212
+ └── refresh_tokens
213
+ ├─ id (PK)
214
+ ├─ user_id (FK)
215
+ ├─ token
216
+ ├─ expires_at
217
+ └─ device_id (optional)
218
+
219
+ User DB (users_db):
220
+ ├── user_profiles
221
+ │ ├─ user_id (PK, FK → auth_db)
222
+ │ ├─ email
223
+ │ ├─ full_name
224
+ │ ├─ avatar_url
225
+ │ ├─ bio
226
+ │ ├─ email_verified
227
+ │ └─ created_at, updated_at
228
+ │
229
+ └── user_settings
230
+ ├─ user_id (PK, FK)
231
+ ├─ theme
232
+ ├─ notifications_enabled
233
+ ├─ language
234
+ └─ timezone
235
+
236
+ Notification Service (Redis):
237
+ └── (Stateless - reads from RabbitMQ events)
238
+ ├─ notification:{id} → JSON
239
+ ├─ notification:pending → Queue
240
+ └─ notification:retry_count → Counter
241
+ ```
242
+
243
+ **Rationale:**
244
+ - Independent scaling
245
+ - Technology flexibility
246
+ - Deployment isolation
247
+ - Eventual consistency
248
+
249
+ ### Caching Strategy
250
+
251
+ ```
252
+ Redis:
253
+ ├── sessions:{sessionId} (TTL: 24h)
254
+ ├── user_profile:{userId} (TTL: 1h)
255
+ ├── auth_token_blacklist: (TTL: token expiry)
256
+ ├── rate_limit:{ip} (TTL: 1m)
257
+ └── notification:pending (TTL: varies)
258
+ ```
259
+
260
+ ---
261
+
262
+ ## Request Flow Example
263
+
264
+ ### Example: User Login & Profile Update
265
+
266
+ ```
267
+ 1. Client POST /auth/login
268
+ │
269
+ ├─► API Gateway receives request
270
+ │ ├─ Generate request ID
271
+ │ ├─ Extract headers
272
+ │ └─ Route to /auth/login
273
+ │
274
+ ├─► Auth Service:
275
+ │ ├─ Validate email/password
276
+ │ ├─ Hash comparison
277
+ │ ├─ Generate JWT tokens
278
+ │ ├─ Store refresh token in Redis
279
+ │ └─ Return tokens
280
+ │
281
+ ├─► API Gateway aggregates response
282
+ │ └─ Return to client
283
+ │
284
+ ├─ Client stores tokens
285
+ │
286
+ └─► Client GET /users/:userId
287
+ ├─► API Gateway
288
+ │ ├─ Extract authorization header
289
+ │ ├─ Pass JWT to User Service
290
+ │ │
291
+ │ ├─► User Service:
292
+ │ │ ├─ Verify JWT (via Auth Service or JWT library)
293
+ │ │ ├─ Query user_profiles table
294
+ │ │ ├─ Check Redis cache
295
+ │ │ └─ Return profile
296
+ │ │
297
+ │ └─ Aggregate response
298
+ │
299
+ └─ Return profile to client
300
+ ```
301
+
302
+ ---
303
+
304
+ ## Error Handling Architecture
305
+
306
+ ### Error Response Flow
307
+
308
+ ```
309
+ Service receives invalid request
310
+ │
311
+ ├─ Validate input
312
+ │
313
+ ├─ If invalid:
314
+ │ ├─ Return 400 Bad Request
315
+ │ └─ Include error code & message
316
+ │
317
+ ├─ Check authorization
318
+ │ ├─ If unauthorized:
319
+ │ │ ├─ Return 401/403
320
+ │ │ └─ Include error details
321
+ │
322
+ ├─ Call downstream service
323
+ │ ├─ If service unavailable:
324
+ │ │ ├─ Circuit breaker opens
325
+ │ │ ├─ Return 503 Service Unavailable
326
+ │ │ └─ Retry after timeout
327
+ │
328
+ └─ If server error:
329
+ ├─ Log error
330
+ ├─ Return 500
331
+ └─ Include request ID for tracking
332
+ ```
333
+
334
+ ### Error Codes
335
+
336
+ ```
337
+ Authentication:
338
+ - INVALID_CREDENTIALS (401)
339
+ - INVALID_TOKEN (401)
340
+ - EMAIL_ALREADY_EXISTS (409)
341
+
342
+ Authorization:
343
+ - UNAUTHORIZED_UPDATE (403)
344
+ - INSUFFICIENT_PERMISSIONS (403)
345
+
346
+ Resource:
347
+ - USER_NOT_FOUND (404)
348
+ - NOTIFICATION_NOT_FOUND (404)
349
+
350
+ Validation:
351
+ - INVALID_EMAIL (400)
352
+ - INVALID_PASSWORD (400)
353
+
354
+ Rate Limiting:
355
+ - TOO_MANY_ATTEMPTS (429)
356
+ - RATE_LIMIT_EXCEEDED (429)
357
+
358
+ Server:
359
+ - SERVICE_UNAVAILABLE (503)
360
+ - INTERNAL_ERROR (500)
361
+ ```
362
+
363
+ ---
364
+
365
+ ## Scalability Considerations
366
+
367
+ ### Horizontal Scaling
368
+
369
+ ```
370
+ Production Setup:
371
+ ┌──────────────────────────────────┐
372
+ │ Load Balancer │
373
+ └────┬──────────────────────────┬──┘
374
+ │ │
375
+ ┌────▼──────────┐ ┌────────▼────┐
376
+ │ API GW (pod1) │ │ API GW (pod2)│
377
+ └────┬─────┬────┘ └────┬─────┬───┘
378
+ │ │ │ │
379
+ ┌──▼──┐ ┌──▼──┐ ┌─────▼─┐ ┌───▼──┐
380
+ │Auth1│ │Auth2│ ... │User1 │ │User2 │ ...
381
+ └─────┘ └─────┘ └───────┘ └──────┘
382
+ ```
383
+
384
+ **Scaling Rules:**
385
+ - API Gateway: 1-3 replicas
386
+ - Auth Service: 1-2 replicas
387
+ - User Service: 1-2 replicas
388
+ - Notification Service: 1 replica (or N for throughput)
389
+
390
+ **Database Scaling:**
391
+ - Read replicas for User DB
392
+ - Connection pooling (PgBouncer)
393
+ - Vertical scaling for Auth DB
394
+
395
+ **Message Queue:**
396
+ - RabbitMQ in cluster mode
397
+ - Multiple consumer instances
398
+
399
+ ---
400
+
401
+ ## Deployment Topology
402
+
403
+ ### Local Development
404
+ ```
405
+ Docker Compose:
406
+ - Single Docker network
407
+ - All services connected
408
+ - Shared databases
409
+ - Health checks enabled
410
+ ```
411
+
412
+ ### Production (Kubernetes)
413
+ ```
414
+ Namespace: microservices
415
+ ├── api-gateway deployment (1-3 replicas)
416
+ ├── auth-service statefulset (1-3 replicas)
417
+ ├── user-service statefulset (1-3 replicas)
418
+ ├── notification-service deployment (1-N replicas)
419
+ ├── postgres-auth statefulset
420
+ ├── postgres-user statefulset
421
+ ├── rabbitmq statefulset (cluster)
422
+ └── redis deployment (with persistence)
423
+ ```
424
+
425
+ ---
426
+
427
+ ## Monitoring & Observability
428
+
429
+ ### Logging
430
+ ```
431
+ Each service logs:
432
+ - Request entry/exit
433
+ - Service calls
434
+ - Database queries
435
+ - Errors with stack traces
436
+ - Performance metrics
437
+
438
+ Format: JSON for easy parsing
439
+ {"timestamp": "...", "level": "INFO", "service": "auth-service", ...}
440
+ ```
441
+
442
+ ### Tracing
443
+ ```
444
+ X-Trace-Id: Generated at API Gateway
445
+ X-Span-Id: Generated per service
446
+ X-Parent-Span-Id: Propagated through calls
447
+
448
+ Example flow:
449
+ API Gateway → Auth Service
450
+ X-Trace-Id: trace-001
451
+ ├─ X-Span-Id: span-gateway-001
452
+ └─ X-Span-Id: span-auth-001 (parent: span-gateway-001)
453
+ ```
454
+
455
+ ### Metrics
456
+ ```
457
+ Prometheus targets:
458
+ - HTTP request count
459
+ - HTTP request duration
460
+ - Database query duration
461
+ - Message queue depth
462
+ - Cache hit/miss ratio
463
+ ```
464
+
465
+ ---
466
+
467
+ ## Security Architecture
468
+
469
+ ### Authentication & Authorization
470
+ ```
471
+ 1. Client sends credentials → Auth Service
472
+ 2. Auth Service validates → Issues JWT
473
+ 3. JWT stored in headers (Authorization: Bearer ...)
474
+ 4. API Gateway verifies JWT signature
475
+ 5. Each service validates token expiry
476
+
477
+ Token Structure:
478
+ {
479
+ "userId": "...",
480
+ "email": "...",
481
+ "iat": 1234567890,
482
+ "exp": 1234568790,
483
+ "type": "access"
484
+ }
485
+ ```
486
+
487
+ ### Data Protection
488
+ ```
489
+ - Passwords: bcrypt (cost: 12)
490
+ - In-transit: HTTPS (TLS 1.3)
491
+ - Tokens: JWT with RS256 signature
492
+ - Sensitive data: Encrypted at rest
493
+ ```
494
+
495
+ ### Network Security
496
+ ```
497
+ - Services isolated to private network
498
+ - API Gateway only public endpoint
499
+ - Rate limiting per IP/user
500
+ - Request validation on all endpoints
501
+ ```
502
+
503
+ ---
504
+
505
+ ## Conclusion
506
+
507
+ This architecture provides:
508
+ - **Scalability**: Services scale independently
509
+ - **Resilience**: Failures isolated per service
510
+ - **Flexibility**: Different tech stacks per service
511
+ - **Maintainability**: Clear service boundaries
512
+ - **Observability**: Tracing and logging built-in