sdg-agents 1.0.5

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 (130) hide show
  1. package/LICENSE +15 -0
  2. package/README.md +161 -0
  3. package/package.json +88 -0
  4. package/src/assets/dev-guides/agent-deep-flow.md +139 -0
  5. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/01-project-scope-and-mvp.md +45 -0
  6. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/02-stack-and-data-model.md +56 -0
  7. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/03-external-integrations.md +44 -0
  8. package/src/assets/dev-guides/prompt-tracks/00-lite-mode/04-launch-checklist.md +26 -0
  9. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/01-project-vision.md +77 -0
  10. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/02-problem-definition.md +63 -0
  11. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/03-success-metrics.md +48 -0
  12. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/05-engineering-culture-and-silos.md +41 -0
  13. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/00-foundation/06-foundation-approval.md +57 -0
  14. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/01-tech-stack.md +62 -0
  15. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/02-local-environment.md +50 -0
  16. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/03-version-control-and-tracking.md +65 -0
  17. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/04-hello-world-validation.md +37 -0
  18. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/01-setup/05-setup-approval.md +61 -0
  19. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/01-folder-structure.md +49 -0
  20. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/02-design-patterns.md +59 -0
  21. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/03-apis-and-communication.md +55 -0
  22. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/04-security-and-access.md +63 -0
  23. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/05-security-audit.md +64 -0
  24. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/06-design-system-ux.md +72 -0
  25. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/07-ai-strategy.md +72 -0
  26. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/08-observability.md +65 -0
  27. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/09-technical-documentation.md +64 -0
  28. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/10-infrastructure-and-costs.md +40 -0
  29. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/11-data-privacy-compliance.md +41 -0
  30. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/12-performance-and-scale.md +46 -0
  31. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/13-disaster-recovery.md +39 -0
  32. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/02-architecture/14-architecture-approval.md +81 -0
  33. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/03-delivery/01-ci-cd-pipeline.md +49 -0
  34. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/03-delivery/02-quality-standards.md +46 -0
  35. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/03-delivery/03-delivery-approval.md +58 -0
  36. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/00-feature-template.md +30 -0
  37. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/01-context-and-scope.md +46 -0
  38. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/02-business-rules.md +39 -0
  39. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/03-architecture-and-design.md +50 -0
  40. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/04-testing-strategy.md +48 -0
  41. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/05-implementation-plan.md +45 -0
  42. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/04-features/06-feature-approval.md +46 -0
  43. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/05-evolution/01-rfcs-and-changes.md +63 -0
  44. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/05-evolution/02-incident-postmortems.md +64 -0
  45. package/src/assets/dev-guides/prompt-tracks/01-new-evolution/05-evolution/03-adr-template.md +66 -0
  46. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/00-foundation/01-legacy-vision.md +73 -0
  47. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/00-foundation/02-foundation-approval.md +53 -0
  48. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/01-tech-debt-inventory.md +55 -0
  49. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/02-security-audit.md +63 -0
  50. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/03-regression-baseline.md +49 -0
  51. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/01-analysis/04-analysis-approval.md +65 -0
  52. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/01-modernization-approach.md +60 -0
  53. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/02-versioning-and-coexistence.md +57 -0
  54. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/03-new-demands-triage.md +41 -0
  55. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/02-strategy/04-strategy-approval.md +56 -0
  56. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/03-refactor/01-cleanup-backlog.md +45 -0
  57. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/03-refactor/02-refactor-approval.md +53 -0
  58. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/04-migration/01-migration-roadmap.md +47 -0
  59. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/04-migration/02-data-sync-strategy.md +56 -0
  60. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/04-migration/03-migration-approval.md +55 -0
  61. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/05-sunset/01-decommission-plan.md +47 -0
  62. package/src/assets/dev-guides/prompt-tracks/02-legacy-modernization/05-sunset/02-sunset-approval.md +60 -0
  63. package/src/assets/dev-guides/prompt-tracks/README.md +144 -0
  64. package/src/assets/dev-guides/software-development-lifecycle-sdlc.md +147 -0
  65. package/src/assets/dev-guides/spec-driven-dev-guide.md +81 -0
  66. package/src/assets/dev-guides/ui-prompt-guide.md +181 -0
  67. package/src/assets/img/sdg-agents-icon-dark.svg +55 -0
  68. package/src/assets/img/sdg-agents-icon-light.svg +55 -0
  69. package/src/assets/img/sdg-agents-menu-v1.png +0 -0
  70. package/src/assets/img/sdg-icon.svg +110 -0
  71. package/src/assets/instructions/commands/sdg-docs.md +69 -0
  72. package/src/assets/instructions/commands/sdg-feat.md +45 -0
  73. package/src/assets/instructions/commands/sdg-fix.md +41 -0
  74. package/src/assets/instructions/commands/sdg-land.md +128 -0
  75. package/src/assets/instructions/competencies/backend.md +353 -0
  76. package/src/assets/instructions/competencies/frontend.md +439 -0
  77. package/src/assets/instructions/core/agent-roles.md +104 -0
  78. package/src/assets/instructions/core/api-design.md +65 -0
  79. package/src/assets/instructions/core/ci-cd.md +144 -0
  80. package/src/assets/instructions/core/cloud.md +63 -0
  81. package/src/assets/instructions/core/code-style.md +144 -0
  82. package/src/assets/instructions/core/containers.md +115 -0
  83. package/src/assets/instructions/core/data-access.md +119 -0
  84. package/src/assets/instructions/core/engineering-standards.md +502 -0
  85. package/src/assets/instructions/core/naming.md +136 -0
  86. package/src/assets/instructions/core/observability.md +73 -0
  87. package/src/assets/instructions/core/security-pipeline.md +209 -0
  88. package/src/assets/instructions/core/security.md +45 -0
  89. package/src/assets/instructions/core/sql-style.md +138 -0
  90. package/src/assets/instructions/core/staff-dna.md +72 -0
  91. package/src/assets/instructions/core/testing-principles.md +212 -0
  92. package/src/assets/instructions/core/ui/architecture.md +171 -0
  93. package/src/assets/instructions/core/ui/design-thinking.md +319 -0
  94. package/src/assets/instructions/core/ui/presets.md +200 -0
  95. package/src/assets/instructions/core/ui/standards.md +144 -0
  96. package/src/assets/instructions/core/writing-soul.md +82 -0
  97. package/src/assets/instructions/flavors/legacy/principles.md +64 -0
  98. package/src/assets/instructions/flavors/lite/principles.md +39 -0
  99. package/src/assets/instructions/flavors/mvc/principles.md +124 -0
  100. package/src/assets/instructions/flavors/vertical-slice/principles.md +178 -0
  101. package/src/assets/instructions/idioms/csharp/patterns.md +367 -0
  102. package/src/assets/instructions/idioms/flutter/patterns.md +97 -0
  103. package/src/assets/instructions/idioms/go/patterns.md +193 -0
  104. package/src/assets/instructions/idioms/java/patterns.md +233 -0
  105. package/src/assets/instructions/idioms/javascript/patterns.md +223 -0
  106. package/src/assets/instructions/idioms/kotlin/patterns.md +94 -0
  107. package/src/assets/instructions/idioms/python/patterns.md +185 -0
  108. package/src/assets/instructions/idioms/rust/patterns.md +189 -0
  109. package/src/assets/instructions/idioms/scripts/patterns.md +81 -0
  110. package/src/assets/instructions/idioms/sql/patterns.md +109 -0
  111. package/src/assets/instructions/idioms/swift/patterns.md +97 -0
  112. package/src/assets/instructions/idioms/typescript/patterns.md +304 -0
  113. package/src/assets/instructions/idioms/vbnet/patterns.md +96 -0
  114. package/src/assets/instructions/idioms/vbnet-legacy/patterns.md +104 -0
  115. package/src/assets/instructions/templates/workflow.md +244 -0
  116. package/src/assets/instructions/workflows/governance.md +162 -0
  117. package/src/engine/bin/add-idiom.mjs +186 -0
  118. package/src/engine/bin/index.mjs +226 -0
  119. package/src/engine/config/stack-display.mjs +75 -0
  120. package/src/engine/config/stack-versions.mjs +76 -0
  121. package/src/engine/lib/cli-parser.mjs +80 -0
  122. package/src/engine/lib/display-utils.mjs +20 -0
  123. package/src/engine/lib/fs-utils.mjs +99 -0
  124. package/src/engine/lib/instruction-assembler.mjs +487 -0
  125. package/src/engine/lib/manifest-utils.mjs +128 -0
  126. package/src/engine/lib/prompt-utils.mjs +137 -0
  127. package/src/engine/lib/result-utils.mjs +14 -0
  128. package/src/engine/lib/ruleset-injector.mjs +183 -0
  129. package/src/engine/lib/ui-utils.mjs +216 -0
  130. package/src/engine/lib/wizard.mjs +472 -0
@@ -0,0 +1,63 @@
1
+ # 03 - Security and Access
2
+
3
+ ## Authentication and Authorization
4
+
5
+ - How does the user identify themselves (OAuth2, JWT, SAML)?
6
+ - How do we control permissions (RBAC, ABAC)?
7
+
8
+ ## Data Protection
9
+
10
+ - How do we protect data at rest (Encryption at rest)?
11
+ - How do we protect data in transit (TLS/SSL)?
12
+ - How do we manage secrets (HashiCorp Vault, AWS Secrets Manager)?
13
+
14
+ ## Audit and Logs
15
+
16
+ - Which actions are recorded in audit logs?
17
+ - Where are these logs securely stored?
18
+
19
+ ---
20
+
21
+ ## Learn by Examples
22
+
23
+ ### ❌ Bad Example
24
+
25
+ ```markdown
26
+ # 03 - Security and Access
27
+
28
+ ## Authentication and Authorization
29
+
30
+ User and password in the database.
31
+
32
+ ## Data Protection
33
+
34
+ We will use HTTPS.
35
+
36
+ ## Audit
37
+
38
+ Record to the server console.
39
+ ```
40
+
41
+ > **Rationale**: Plain text passwords are unacceptable. HTTPS only solves transit, not rest. Console logs disappear on reboot.
42
+
43
+ ### ✅ Good Example
44
+
45
+ ```markdown
46
+ # 03 - Security and Access
47
+
48
+ ## Authentication and Authorization
49
+
50
+ - **Authn**: JWT with RSA-256 and 15min expiration time.
51
+ - **Authz**: Platform-native RBAC (Role-Based Access Control).
52
+
53
+ ## Data Protection
54
+
55
+ - **Rest**: AES-256 for the Tax ID (CPF) field in the database.
56
+ - **Secrets**: Injected via AWS Secrets Manager at runtime.
57
+
58
+ ## Audit
59
+
60
+ Mutation logs sent to CloudWatch Logs with 2-year retention for compliance.
61
+ ```
62
+
63
+ > **Rationale**: Defines algorithms (RSA-256, AES-256), specific tools, and compliance policies (2-year log retention).
@@ -0,0 +1,64 @@
1
+ # 04 - Audit and Threat Modeling
2
+
3
+ ## Threat Modeling
4
+
5
+ - What are the main attack vectors identified (e.g., OWASP Top 10)?
6
+ - How do we mitigate "Supply Chain" and dependency attacks?
7
+
8
+ ## Audit Plan
9
+
10
+ - Who will perform the audit (Internal team, Pentest company)?
11
+ - How often (Every major release, annually)?
12
+ - Which automated security tools (SAST/DAST) will be integrated?
13
+
14
+ ## Resilience and Response
15
+
16
+ - How does the system behave under attack (Fail-safe)?
17
+ - What is the response plan for security incidents?
18
+
19
+ ---
20
+
21
+ ## Learn by Examples
22
+
23
+ ### ❌ Bad Example
24
+
25
+ ```markdown
26
+ # 04 - Audit and Threat Modeling
27
+
28
+ ## Threat Modeling
29
+
30
+ The system will be secure against hackers.
31
+
32
+ ## Audit Plan
33
+
34
+ We'll do a test before launching.
35
+
36
+ ## Resilience
37
+
38
+ If it goes down, we'll bring it back up.
39
+ ```
40
+
41
+ > **Rationale**: "Secure against hackers" is an aspiration, not a specification. It doesn't define tools or concrete plans.
42
+
43
+ ### ✅ Good Example
44
+
45
+ ```markdown
46
+ # 04 - Audit and Threat Modeling
47
+
48
+ ## Threat Modeling
49
+
50
+ - Focus on avoiding Broken Access Control (OWASP #1) through forced auditing in API interceptors.
51
+ - Supply Chain mitigation via dependency scanner (Snyk) blocking the CI in case of critical failures.
52
+
53
+ ## Audit Plan
54
+
55
+ - Bi-weekly DAST scan via OWASP ZAP in Staging environment.
56
+ - Annual external Pentest performed by a CREST-certified company.
57
+
58
+ ## Resilience
59
+
60
+ - Aggressive Rate Limit (100 req/min/IP) to prevent Brute Force.
61
+ - Transparent Circuit Breaker: if the Authentication service fails, all accesses are denied (Fail-closed).
62
+ ```
63
+
64
+ > **Rationale**: Defines specific attacks (Broken Access Control), tools (Snyk, OWASP ZAP), frequency, and failure behaviors (`Fail-closed`).
@@ -0,0 +1,72 @@
1
+ # 05 - Design System and UX
2
+
3
+ ## Platforms and Devices
4
+
5
+ - Which devices will be supported (Web, Desktop, Mobile)?
6
+ - Is there a need for a PWA (Progressive Web App)?
7
+
8
+ ## Design System (Tokens)
9
+
10
+ - **Colors**: 60/30/10 Rule definition (Primary, Secondary, and Contrast).
11
+ - **Typography**: Chosen fonts for readability (e.g., Inter, Roboto).
12
+
13
+ ## Accessibility (A11y)
14
+
15
+ - Does the system meet WCAG compliance (Level AA)?
16
+ - How do we ensure contrast and keyboard navigation?
17
+
18
+ ## Micro-interactions
19
+
20
+ - What animations and visual feedbacks will be standard (Hover, Loading)?
21
+
22
+ ---
23
+
24
+ ## Learn by Examples
25
+
26
+ ### ❌ Bad Example
27
+
28
+ ```markdown
29
+ # 05 - Design System and UX
30
+
31
+ ## Platforms
32
+
33
+ Web only for now.
34
+
35
+ ## Design System
36
+
37
+ Nice colors (Orange and Blue).
38
+
39
+ ## Accessibility
40
+
41
+ We'll look into it later.
42
+ ```
43
+
44
+ > **Rationale**: Vague and neglects accessibility, which is a compliance requirement. "Nice colors" is not a technical definition of tokens.
45
+
46
+ ### ✅ Good Example
47
+
48
+ ```markdown
49
+ # 05 - Design System and UX
50
+
51
+ ## Platforms and Devices
52
+
53
+ PWA for mobile devices and Web Desktop (Responsive First).
54
+
55
+ ## Design System (Tokens)
56
+
57
+ - **60%**: Neutral Gray (#F8F9FA) - Main background.
58
+ - **30%**: Brand Blue (#0056B3) - Buttons and headers.
59
+ - **10%**: Contrast Amber (#FFC107) - CTAs and alerts.
60
+ - **Font**: Inter (Sans-serif) for body, Montserrat for headings.
61
+
62
+ ## Accessibility (A11y)
63
+
64
+ - Minimum contrast of 4.5:1 on all text (WCAG AA).
65
+ - Full keyboard (Tab) navigation and labels for Screen Readers on all inputs.
66
+
67
+ ## Micro-interactions
68
+
69
+ Glassmorphism effect on modals with a smooth 0.2s transition (`ease-in-out`).
70
+ ```
71
+
72
+ > **Rationale**: Defines specific color tokens (HEX), robust typography, technical accessibility criteria, and interface states.
@@ -0,0 +1,72 @@
1
+ # 06 - AI Strategy
2
+
3
+ ## AI Engine
4
+
5
+ - Which models (OpenAI, Claude, Llama 3) and what execution infrastructure?
6
+ - Local Model (Ollama) or Cloud (Vertex AI)?
7
+
8
+ ## Integration and Tools
9
+
10
+ - Will we use the MCP (Model Context Protocol) to connect tools?
11
+ - How will RAG (Retrieval Augmented Generation) access external data?
12
+ - Agents (LangChain, CrewAI) or pure LLM?
13
+
14
+ ## AI Privacy and Governance
15
+
16
+ - How do we prevent PII (Personally Identifiable Information) leakage in prompts?
17
+ - Is there an audit of AI inputs and outputs?
18
+
19
+ ## Costs and Limits
20
+
21
+ - Monthly budget per million tokens (Input/Output).
22
+ - Rate limits per user.
23
+
24
+ ---
25
+
26
+ ## Learn by Examples
27
+
28
+ ### ❌ Bad Example
29
+
30
+ ```markdown
31
+ # 06 - AI Strategy
32
+
33
+ ## AI Engine
34
+
35
+ Use ChatGPT for everything.
36
+
37
+ ## Integration
38
+
39
+ Chat on the interface.
40
+
41
+ ## Privacy
42
+
43
+ AI is smart and knows what it's doing.
44
+ ```
45
+
46
+ > **Rationale**: Ignores token costs, privacy risks, and infrastructure (API SLA).
47
+
48
+ ### ✅ Good Example
49
+
50
+ ```markdown
51
+ # 06 - AI Strategy
52
+
53
+ ## AI Engine
54
+
55
+ GPT-4o via Azure OpenAI (Ensures data does not train the model).
56
+
57
+ ## Integration and Tools
58
+
59
+ - MCP (Model Context Protocol) to allow the AI to execute internal audit scripts.
60
+ - RAG via Pinecone (Vector DB) with 1000-token semantic chunking.
61
+
62
+ ## Privacy
63
+
64
+ PII Preservation: Regex intercepting Tax IDs (CPFs) and names before sending to the API.
65
+
66
+ ## Costs
67
+
68
+ - Budget: $5,000/month.
69
+ - Limit: 50 requests/hour per user.
70
+ ```
71
+
72
+ > **Rationale**: Defines robust technological choices (Azure OpenAI, Pinecone, MCP), data governance (PII Regex), and financial control (tokens/requests).
@@ -0,0 +1,65 @@
1
+ # 07 - Observability (Logs, Metrics, and Traces)
2
+
3
+ ## System and Business Metrics
4
+
5
+ - Which critical systemic metrics will be monitored (CPU, RAM usage, RPS, P99 Latency)?
6
+ - Which business metrics (KPIs) will be extracted from the transactional system (Sales Balance, Registration Errors)?
7
+
8
+ ## Centralization and Log Standard
9
+
10
+ - What log aggregation and search tool will be used (e.g., Grafana Loki, ELK Stack, Datadog)?
11
+ - What structured format will be used for log ingestion (e.g., JSON)?
12
+ - What will NEVER be logged (Sensitive Data/PII, Passwords)?
13
+
14
+ ## Distributed Tracing
15
+
16
+ - Will the project adopt multi-service request tracking (OpenTelemetry, Jaeger)?
17
+ - How will the `CorrelationID` or `TraceID` be propagated in HTTP Headers and Messaging Queues?
18
+
19
+ ---
20
+
21
+ ## Learn by Examples
22
+
23
+ ### ❌ Bad Example
24
+
25
+ ```markdown
26
+ # 07 - Observability
27
+
28
+ ## Metrics
29
+
30
+ We'll check the server to see if it doesn't go down.
31
+
32
+ ## Logs
33
+
34
+ Send `console.log()` to the terminal and we'll read the server file if there's an error.
35
+
36
+ ## Tracing
37
+
38
+ Create a random ID there.
39
+ ```
40
+
41
+ > **Rationale**: Absence of proactive metrics. Waiting for it to "go down" to check the server is unacceptable at a professional level. Loose logs in the terminal are not searchable and violate compliance.
42
+
43
+ ### ✅ Good Example
44
+
45
+ ```markdown
46
+ # 07 - Observability
47
+
48
+ ## System and Business Metrics
49
+
50
+ - **Infra**: P95 Latency < 200ms and Memory Usage on the Grafana dashboard.
51
+ - **Business**: Monitoring `OrderCreated` volume in the sales module via Prometheus.
52
+
53
+ ## Logs
54
+
55
+ - **Standard**: Structured JSON in `Standard Output`.
56
+ - **Aggregation**: Datadog (with 15-day retention).
57
+ - **Security**: Tax IDs (CPFs) and Credit Cards will be masked at the source (Logger Library).
58
+
59
+ ## Distributed Tracing
60
+
61
+ - **Propagation**: W3C Trace Context headers throughout the stack.
62
+ - **Tool**: OpenTelemetry Collector exporting to Datadog APM.
63
+ ```
64
+
65
+ > **Rationale**: Unambiguous definitions that allow for creating real-time alerts. The team will know about the error before the customer opens a ticket. Sensitive data protected by design.
@@ -0,0 +1,64 @@
1
+ # 08 - Technical Documentation and Contracts
2
+
3
+ ## API Contracts (Public Specs)
4
+
5
+ - How will endpoints and integrations be documented (Swagger, OpenAPI 3.0, GraphQL Schema)?
6
+ - Will the documentation be generated dynamically via code (Annotations) or manually (separate YAML files)?
7
+
8
+ ## Architectural Decision Records (ADRs)
9
+
10
+ - Does the project use Architectural Decision Records (ADRs) to record the "why" behind each technological choice that should not be altered (Immutable)?
11
+ - In which directory will the ADRs live (e.g., `docs/adrs/`)?
12
+
13
+ ## Operation Guides and Runbooks
14
+
15
+ - Where will the _Runbook_ on how to start the project live (Initial setup for new Devs)?
16
+ - Are there _Playbooks_ on what to do if the main database goes down or if an external service is offline (Operational Resilience)?
17
+
18
+ ---
19
+
20
+ ## Learn by Examples
21
+
22
+ ### ❌ Bad Example
23
+
24
+ ```markdown
25
+ # 08 - Technical Documentation
26
+
27
+ ## Contracts
28
+
29
+ The backend API will have a Postman collection that we'll share on Slack.
30
+
31
+ ## Decisions
32
+
33
+ We always decide orally in the Daily.
34
+
35
+ ## Guides
36
+
37
+ Just read the code; it's "self-documenting".
38
+ ```
39
+
40
+ > **Rationale**: Code does not document obsolete business rules or external contracts. Relying on temporary Slack messages is anti-architecture.
41
+
42
+ ### ✅ Good Example
43
+
44
+ ```markdown
45
+ # 08 - Technical Documentation
46
+
47
+ ## API Contracts
48
+
49
+ - **Standard**: OpenAPI 3.1
50
+ - **Generation Engine**: Swaggo (Go annotations) auto-generated in the build pipeline and served at `/swagger/index.html`.
51
+ - **Automatic Validation**: _Spectral Linter_ will run in the CI ensuring the use of HTTPS and error payload description.
52
+
53
+ ## Architectural Decision Records (ADRs)
54
+
55
+ - **Location**: Dedicated folder `docs/decisions/`.
56
+ - **Workflow**: No central library (ORM, Gateway) or new database should be added without a PR completing the corresponding ADR.
57
+
58
+ ## Operational Guides (Runbooks)
59
+
60
+ - **Main Document**: `/README.md` with local script (`docker compose up`) and documented environment variables.
61
+ - **Troubleshooting**: `docs/runbooks/db-failover.md` describing database restoration and health check commands.
62
+ ```
63
+
64
+ > **Rationale**: Prepares the project for team scalability, smooth _Onboarding_, and is forget-proof. The auto-generated Swagger engine does not suffer from synchronization issues with commits.
@@ -0,0 +1,40 @@
1
+ # 09 - Infrastructure and Costs (FinOps)
2
+
3
+ Staff-level architecture understands that code costs money to run. Designing a cloud microservices system without understanding the underlying economics and its _Unit Economics_ is a serious architectural failure.
4
+
5
+ ## Unit Economics and Sizing
6
+
7
+ - **Cost per Transaction:** How much does it cost, in terms of infrastructure, for the company to process 1 new Order/Customer in this module?
8
+ - **Scale Estimation:** Given the expected traffic for the next 12 months, what is the estimated monthly _TCO (Total Cost of Ownership)_ in BRL/USD?
9
+ - **Managed Dependencies:** Will we use an expensive managed database (e.g., RDS Aurora) or something fixed (e.g., EC2 + Docker)? Does the SLA justify the premium price paid?
10
+
11
+ ## Budget Protection
12
+
13
+ - **Billing Alarms:** What are the upper thresholds defined in the cloud? (e.g., If the queue bottlenecks and climbs to $1,000 in a day of uncontrolled lambdas, who is notified via Slack?)
14
+ - **Hidden Costs:** Was there an accounting for Network Outbound Traffic (Data Transfer Out), storage of giant Logs, and daily Database Snapshots?
15
+
16
+ ---
17
+
18
+ ## Learn by Examples
19
+
20
+ ### ❌ Bad Example
21
+
22
+ ```markdown
23
+ # Infrastructure
24
+
25
+ We'll use AWS K8S (EKS) because the team is already familiar with it and it's the current industry standard. It handles everything we need to send.
26
+ ```
27
+
28
+ > **Rationale**: Wasteful. They don't even mention what "Everything we need" is. An EKS cluster costs > $70/month just for the _Control Plane_ while empty. Building on it to process 10 requests per day is financial amateurism disguised as scalability.
29
+
30
+ ### ✅ Good Example
31
+
32
+ ```markdown
33
+ # Infrastructure: Invoice Generation Module (FinOps)
34
+
35
+ - **Calculated Unit Cost:** We will use AWS Lambda. Each invoice (1 req + 2 database connections + s3) will last 800ms at 512MB RAM. Estimated at $0.0005 per invoice.
36
+ - **Estimated Monthly TCO:** For 1 million expected invoices/month in Q4, the bill for this feature will be approx. $15 USD (Serverless).
37
+ - **Budget Protection:** A $50/month Billing Alarm created on the `feature:invoice` tag. If it exceeds this, it's a sign of a bug in the infinite retry code. It will notify `#dev-alerts`.
38
+ ```
39
+
40
+ > **Rationale**: Executive perfection. The developer proved they sized things, understood the demand-based Serverless payment model, and already prepared the safeguard against billing anomalies before spending a single cent of the company's money.
@@ -0,0 +1,41 @@
1
+ # 10 - Data Privacy and Compliance (LGPD/GDPR)
2
+
3
+ Data protection laws are not just bureaucratic requirements; they require native architectures to support them. If a system is designed in an intertwined way, meeting a user's Right-to-be-Forgotten securely is almost impossible.
4
+
5
+ ## PII (Personally Identifiable Information) Mapping
6
+
7
+ - Which columns in the new database store sensitive data (Name, Tax ID/CPF, Email, Card)?
8
+ - What is the **Masking** strategy for this data when mirrored to Quality environments (Staging/QA) or sent to application logs (e.g., Datadog)?
9
+
10
+ ## Deletion and Retention
11
+
12
+ - **Right to be Forgotten:** Can the system destroy `UserId=123` and maintain relational consistency? (e.g., order records become anonymous and linked to a `deleted_user` UUID).
13
+ - **Retention Time:** What data _cannot_ be deleted at the user's request due to tax compliance, and for how long (e.g., invoices in Glacier)?
14
+
15
+ ---
16
+
17
+ ## Learn by Examples
18
+
19
+ ### ❌ Bad Example
20
+
21
+ ```markdown
22
+ # LGPD Security
23
+
24
+ We use TLS 1.2 on the site for LGPD. The database uses disk encryption, so LGPD is covered against hackers.
25
+ ```
26
+
27
+ > **Rationale**: Naive. Encrypting the disk and using SSL prevents hacker breaches and unauthorized listening, but it doesn't solve real internal compliance (LGPD/GDPR) regarding the use and deletion of information by the data subject themselves if they request it tomorrow.
28
+
29
+ ### ✅ Good Example
30
+
31
+ ```markdown
32
+ # Privacy By Design: Profile Module V2
33
+
34
+ - **PII Mapped (`Users` table):** The `cpf`, `phone`, and `email` columns are classified as level A PII.
35
+ - **Log Masking:** Our `pino-logger` library has been natively configured to obfuscate these keys (replacing the string with `***`). They will NEVER appear in the clear in Datadog.
36
+ - **Deletion (GDPR/LGPD):** If the `DELETE /account` route is triggered:
37
+ 1. Real PII data in the `Users` table undergoes a _Hard Delete_.
38
+ 2. History in `Sales` remains (Legal/Tax Requirement), but its Foreign Key is mapped to an internal `anon-ledger` system, blocking primary identification.
39
+ ```
40
+
41
+ > **Rationale**: The architecture is born legally shielded from million-dollar fines. Database IDs are designed anticipating the loss of parent data without crashing the Frontend in the future.
@@ -0,0 +1,46 @@
1
+ # 11 - Performance and Scale SLAs (Operations)
2
+
3
+ Distributed systems that do not anticipate traffic contention will suffer "Cascading" unavailability (Timeout Avalanche). The architect needs to define the pain thresholds of their system in the contract.
4
+
5
+ ## Resilience Levers
6
+
7
+ - **Rate Limiting:** Will the API block clients that call more than `100 req/min`? (Protect your database).
8
+ - **Circuit Breakers:** If the partner microservice goes down (e.g., Payment Gateway), how long will our service continue waiting for a response before opening the circuit (e.g., fail-fast < 500ms)?
9
+ - **Target Latency (SLOs - Service Level Objectives):** The strict p95 percentile must be `< 250ms`.
10
+
11
+ ## Structural Tactics (Cache vs Sync)
12
+
13
+ - Will the reading be heavy? What goes to Cache (`Redis/Memcached`) and what will seek Primary Storage directly? Will we use asynchronous queues (Kafka/SQS) for the write model (CQRS)?
14
+
15
+ ---
16
+
17
+ ## Learn by Examples
18
+
19
+ ### ❌ Bad Example
20
+
21
+ ```markdown
22
+ # Scalability
23
+
24
+ It will hold up during Black Friday because our cloud is elastic (Autoscaling).
25
+ ```
26
+
27
+ > **Rationale**: Failed promise. Scaling up 1,000 Frontend instances to hit a single stressed database will only exhaust the database's connection pool faster (Internal DDoS).
28
+
29
+ ### ✅ Good Example
30
+
31
+ ```markdown
32
+ # Performance: Cart Module V2
33
+
34
+ ## P95 Latency (Target)
35
+
36
+ - List Cart (GET): `< 150ms`.
37
+ - Pay Cart (POST): `< 850ms` (Due to external acquirer latency).
38
+
39
+ ## Anti-Avalanche Measures
40
+
41
+ - Redis Cache for the top 50 best-selling items (10m TTL).
42
+ - Stripe HTTP connection will have a **strict 3-second timeout**. If Stripe does not return, the code throws a `PaymentGatewayTimeoutException` saving it to the database as Pending.
43
+ - **Rate Limit (API Gateway):** 30 Requests per IP per Minute.
44
+ ```
45
+
46
+ > **Rationale**: Defines strict rules and thresholds. The Sysadmin only needs to read this document to correctly configure the Nginx `Rate Limiting` firewall; the back-end developer won't forget to configure the Timeout in their HTTP Client!
@@ -0,0 +1,39 @@
1
+ # 12 - Disaster Recovery Plan (DR / BCP)
2
+
3
+ Critical failures in cloud providers occur annually. "DROP TABLE" and _Ransomware_ incidents occur every hour. Designing from an SRE perspective requires us to document how the _software comes back to life_ after losing an entire region.
4
+
5
+ ## Critical Rescue Objectives
6
+
7
+ - **RTO (Recovery Time Objective):** Promised time to C-Level to bring Core systems back online (e.g., < 4 hours)?
8
+ - **RPO (Recovery Point Objective):** How many minutes or hours of sales data the company is willing to "lose" if the Main DB goes down? (Optimal Backup Point).
9
+
10
+ ## Multi-Zone and Cold Redundancy
11
+
12
+ - How does your infrastructure respond to the failure of an entire _Availability Zone (AZ)_?
13
+ - Do the "Terraform Infrastructure as Code (IaC)" have the state to bring up another datacenter in the _US-East-2_ Zone if _US-East-1_ fails permanently (Cold Architecture / Standby)?
14
+
15
+ ---
16
+
17
+ ## Learn by Examples
18
+
19
+ ### ❌ Bad Example
20
+
21
+ ```markdown
22
+ # Disaster Recovery (DR)
23
+
24
+ Our MySQL database takes a snapshot on AWS every day at midnight. And we have Terraform done for the K8S Cluster.
25
+ ```
26
+
27
+ > **Rationale**: If the region goes down at noon, you've just thrown _12 hours of morning revenue in the trash_ (Unacceptable to the CEO). You're covering the minimum, but how does the team bring up this Terraform when the alert goes off?
28
+
29
+ ### ✅ Good Example
30
+
31
+ ```markdown
32
+ # "Transactions V2" Module Recovery
33
+
34
+ - **RTO (Recovery Target):** `Max 2 Hours` – Aurora database uses Auto-Failover (< 60 seconds). The ECS cluster has Multi-Zonal Autoscaling and will bring up containers in _eu-west-1b_ if _1a_ goes down.
35
+ - **RPO (Data Acceptance):** `Max 5 Minutes` – Database has Continuous Backup (AWS PITR - Point-in-Time Recovery). Worst-case scenario, we lose only the transactional logs from the last 4.9 minutes.
36
+ - **Chaos Simulations:** Performed annually through "Game Day" by the SRE and documented in `Incident Postmortems`.
37
+ ```
38
+
39
+ > **Rationale**: The document reassures investors and C-Level leadership that corporate SLA laws and short RPOs were properly incorporated into the software before it was built and priced.
@@ -0,0 +1,81 @@
1
+ # 14 - Architecture Approval
2
+
3
+ ## Artifacts Checklist
4
+
5
+ - [ ] 01-folder-structure.md (Defined)
6
+ - [ ] 02-design-patterns.md (Written)
7
+ - [ ] 03-apis-and-communication.md (Gateways, gRPC, RabbitMQ defined)
8
+ - [ ] 04-security-and-access.md (Approved)
9
+ - [ ] 05-security-audit.md (Mapped)
10
+ - [ ] 06-design-system-ux.md (Premium UX)
11
+ - [ ] 07-ai-strategy.md (Intelligent)
12
+ - [ ] 08-observability.md (Mandatory Logs/Metrics)
13
+ - [ ] 09-technical-documentation.md (ADRs/Runbooks defined)
14
+ - [ ] 10-infrastructure-and-costs.md (FinOps / Unit Economics calculated)
15
+ - [ ] 11-data-privacy-compliance.md (LGPD Masking/Deletion mapped)
16
+ - [ ] 12-performance-and-scale.md (SLAs and Rate Limits established)
17
+ - [ ] 13-disaster-recovery.md (RTO/RPO targets assured)
18
+
19
+ ## Expert Approval
20
+
21
+ - **Principal Architect**: [Signature/Date]
22
+ - **UI/UX Designer**: [Signature/Date]
23
+ - **Security (SecOps)**: [Signature/Date]
24
+ - **DPO / SRE Lead**: [Signature/Date]
25
+
26
+ ## Definition of Readiness (Ready for Delivery)
27
+
28
+ - [ ] Architecture diagrams, API contracts, and Message Brokers reviewed.
29
+ - [ ] AI infrastructure choice (Local vs Cloud) approved.
30
+ - [ ] Accessibility plan (A11y) validated.
31
+ - [ ] Centralized Logging model configured (won't go to `stdout` in vain).
32
+ - [ ] Estimated Cloud budget and Privacy Policies (Right to be Forgotten) outlined.
33
+
34
+ ---
35
+
36
+ ## Learn by Examples
37
+
38
+ ### ❌ Bad Example
39
+
40
+ ```markdown
41
+ # 14 - Architecture Approval
42
+
43
+ ## Checklist
44
+
45
+ - [x] Folder structure done.
46
+
47
+ ## Definition of Readiness
48
+
49
+ - [x] The team knows what to do.
50
+ ```
51
+
52
+ > **Rationale**: How do you prove that the team "knows what to do"? Is there an API design document? What about observability and documentation artifacts?
53
+
54
+ ### ✅ Good Example
55
+
56
+ ```markdown
57
+ # 14 - Architecture Approval
58
+
59
+ ## Checklist
60
+
61
+ - [x] 01-folder-structure.md (Hexagonal)
62
+ - [x] 03-apis-and-communication.md (GraphQL, gRPC, RabbitMQ, and API Gateway validated)
63
+ - [x] 06-design-system-ux.md (WCAG AA)
64
+ - [x] 07-ai-strategy.md (MCP + Ollama)
65
+ - [x] 08-observability.md (Datadog + Tracer)
66
+ - [x] 09-technical-documentation.md (Auto-generated OpenAPI)
67
+ - [x] 10-infrastructure-and-costs.md (AWS Lambda Serverless < $15/month target)
68
+ - [x] 13-disaster-recovery.md (5-minute PITR RPO mapped)
69
+
70
+ ## Expert Approval
71
+
72
+ - **UI/UX Designer**: Julia Silver (Approved on 2026-05-20)
73
+
74
+ ## Definition of Readiness
75
+
76
+ - [x] Color palette (60/30/10 Rule) exported to CSS Variables.
77
+ - [x] 1,000-token limit per AI request configured in the Proxy.
78
+ - [x] Base Grafana dashboards imported (CPU/RPS Dashboards).
79
+ ```
80
+
81
+ > **Rationale**: Ensures that technical (Interfaces/Events), visual (UX), intelligent (AI), as well as SRE (Costs, Performance, Disaster, and Privacy) pillars were formally validated before the first line of code is written.