Initial monorepo: shared package and DBIS, ICCC, OMNL, XOM portals
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
126
TECH_POLICIES.md
Normal file
126
TECH_POLICIES.md
Normal file
@@ -0,0 +1,126 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user