# 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.*