Platform NFR & Architectural Governance
Status: Draft, 2026-03-31 Version: 1.1 Source:
docs/Smackz-Phase2/Platform-NFR-Governance.mdCompanion: Security Scanning FRD
Problem
Audit of 15+ SMACKZ repos identified gaps in functionality integrity (API contracts, schema governance, multi-tenancy boundaries) and security (secrets, rate limiting, audit logs) that are not enforced by any existing CLAUDE.md guardrail, pre-commit hook, or review agent. v1.1 adds 4 new vulnerability scanning NFRs following the platform-wide audit.
Recommendation
Implement 27 governance rules across 9 categories with a prioritized backlog:
- Tier 1 — ship this quarter (8 stories).
- Tier 2 — next quarter (9 stories).
- Tier 3 — backlog.
Key early wins: GitHub org 2FA + branch protection, dependency scanning in all CI pipelines, secrets scanning pre-commit, rate limiting middleware, PII governance policy.
NFR Categories
| Category | Count | Key NFRs | Enforcement |
|---|---|---|---|
| Functionality Integrity | 9 | API contract stability, Redis Streams schema, shared package versioning, multi-tenancy boundary, test coverage, env var completeness, feature flags, MCP/yum sync, lakehouse schema evolution | CI gates + PR checklists |
| Security (traditional) | 11 | Secrets scanning, webhook signature verification, PII masking, rate limiting, dependency scanning, CORS policy, LLM output sanitization, MCP tool permissions, audit logging, Firebase Security Rules, SSRF protection | Pre-commit + CI gates |
| Vulnerability Scanning | 4 | SCA (npm/pip audit), container image CVE (Trivy), SAST (CodeQL/Bandit/gitleaks), GitHub org baseline | CI gates + org settings |
Backlog
26 stories (S-00a through S-22) with effort estimates: S = 1–3 days, M = 3–7 days, L = 7–15 days. Tier 1 covers 8 stories with ~10 dev-days total. Org-level settings (2FA, branch protection, GitHub Advanced Security) have zero dev effort.
Scope
In: All 15+ repos, yum/shared-core/lakehouse APIs, Stripe/POS webhooks, rate limiting, SAST tooling, GitHub org settings.
Out: Runtime RASP, penetration testing, DAST on live, Terraform/K8s scanning.
Sample NFR
NFR-INT-01 — Cross-Service API Contract Stability
Priority: Critical Applies to: yum, shared-core, Smackz-MCP, Smackz-Admin, Smackz-Websites, Restaurant-Websites, SMACKZ-MOBILE
Requirement: Any change to a yum API endpoint or shared-core exported type must not silently break downstream consumers. A breaking change must be identified at the time of authoring, not at runtime.
Resolution: OpenAPI spec diff in CI on every qa push, fail the build if breaking changes are detected without a corresponding version bump. Add a BREAKING CHANGE checklist item to PR templates.