gov-portals-monorepo/TECH_POLICIES.md

Tech Policies — Public Web Portals

These policies apply to all governmental body web portals in this repository. They define security, accessibility, quality, and operational standards.

---

1. Security

• No secrets in repository
  No API keys, passwords, or tokens in source code, config files, or history. Use environment variables or a secure secrets store.

• Dependency hygiene

  • Dependencies must be from trusted registries (npm/pnpm).
  • Run vulnerability scanning (e.g. pnpm audit, Snyk) in CI; fix or document accepted risks.
  • Prefer minimal dependency set; justify new dependencies in PRs.

• Content Security Policy (CSP)
  Each portal must ship with a strict CSP (e.g. via Next.js headers). Nonces or hashes for inline scripts if required; avoid unsafe-inline where possible.

• HTTPS only
  All environments (dev/staging/production) must use HTTPS. No mixed content.

• Authentication
  Use the standardized OIDC/OAuth 2.0 flow. Session handling (e.g. httpOnly cookies, token storage) must follow the same security guidelines across portals.

---

2. Accessibility (WCAG 2.1 AA)

• Compliance
  All user-facing content and flows must meet WCAG 2.1 Level AA unless a formal exception is documented.

• Testing

  • Use automated tools (e.g. axe-core, Pa11y) in CI.
  • Manual checks for keyboard navigation, screen reader, and zoom.
  • Critical user journeys must have an accessibility sign-off before release.

• Design
  Color contrast, focus indicators, and touch targets must meet WCAG. Use the shared design system’s accessible components.

---

3. Browser & Device Support

• Browsers
  Support the current and previous major versions of:
  Chrome, Firefox, Safari, Edge.
  Exact versions and “current” definition are set in CI (e.g. browserslist).

• Devices
  Responsive design required; mobile and tablet are first-class. Test on real or emulated devices for critical flows.

• Progressive enhancement
  Core content and actions must work without JavaScript where feasible; enhance with JS for better UX.

---

4. Code Quality & Consistency

• TypeScript
  Strict mode. No any except where explicitly typed and commented. Public APIs must be fully typed.

• Lint & format

  • ESLint and Prettier configs are shared at repo root.
  • CI fails on lint or format errors.
  • No disabling rules without a documented exception.

• Naming & structure

  • Same folder conventions across portals (e.g. app/, components/, lib/).
  • Shared glossary for common terms (e.g. “user”, “session”, “portal”) to keep copy and code consistent.

---

5. Testing

• Unit / component
  Vitest + React Testing Library. Critical business logic and shared components must have tests.

• E2E
  Playwright. Critical user journeys (e.g. login, main flows) must have E2E tests. Same browser matrix as production support.

• Coverage
  Minimum coverage thresholds (e.g. 80% for critical paths) enforced in CI. New code should not lower coverage without approval.

---

6. Documentation & Onboarding

• Per-portal README
  Each portal must have a README with: purpose, how to run locally, required env vars, and links to TECH_STACK.md and TECH_POLICIES.md.

• API contracts
  Document public APIs (OpenAPI or tRPC schema). Keep docs in sync with code.

• Changelog / releases
  Document breaking changes and notable updates. Use a consistent format (e.g. keep a CHANGELOG or use release notes).

---

7. Performance & Reliability

• Performance budgets
  Set and enforce budgets (e.g. LCP, FID, CLS) in CI where possible. No regression without approval.

• Error handling
  User-facing errors must be handled gracefully; no raw stack traces or internal details exposed.

• Logging & monitoring
  Use the same approach (e.g. structured logs, same log levels). No PII in logs.

---

8. Governance

• Changes to TECH_STACK.md and TECH_POLICIES.md
  Changes apply to all portals. Update stack/policies via a process that includes impact review (e.g. ADR or tech lead sign-off).

• Exceptions
  Any exception to these policies must be documented (what, why, expiry, owner) and reviewed periodically.

• Review cycle
  Stack and policies should be reviewed at least annually and after major incidents or audits.

---

These policies sit alongside TECH_STACK.md. Portals must comply with both.