Standardized Tech Stack — Public Web Portals
This document defines the mandatory technology stack for all governmental body web portals in this repository. Every portal (DBIS, XOM, OMNL, ICCC, and any future additions) must align with this stack.
1. Runtime & Language
| Area |
Choice |
Version / Notes |
| Runtime |
Node.js |
LTS (currently 20.x). Use .nvmrc or engines in package.json. |
| Language |
TypeScript |
Strict mode enabled. All application code in .ts / .tsx. |
| Package manager |
pnpm |
Use pnpm-workspace.yaml if sharing packages; otherwise pnpm per portal. |
2. Frontend
| Area |
Choice |
Notes |
| Framework |
Next.js |
App Router. Enables SSR, static export, or hybrid as required. |
| UI library |
React |
With React 18+ patterns (e.g. Suspense where appropriate). |
| Styling |
Tailwind CSS |
With shared design tokens (colors, spacing, typography) from a common config. |
| Component library |
Shared design system or Radix/shadcn-style primitives |
Headless components preferred for accessibility and branding consistency. |
| State |
React state + URL + (if needed) Zustand or TanStack Query |
Avoid Redux unless explicitly justified. |
| Forms & validation |
React Hook Form + Zod |
Same schema patterns across portals for API and forms. |
| Data fetching |
TanStack Query (React Query) + fetch or agreed HTTP client |
Caching and loading/error states standardized. |
3. API & Backend
| Area |
Choice |
Notes |
| API style |
REST (JSON) or tRPC |
One chosen standard for the whole project; document in each portal. |
| Auth |
OIDC / OAuth 2.0 |
Same identity provider and flow across portals where possible. |
| API client |
Typed (OpenAPI/TRPC) |
No untyped any for API responses. |
4. Testing
| Area |
Choice |
Notes |
| Unit / component |
Vitest + React Testing Library |
Same patterns and helpers across portals. |
| E2E |
Playwright |
Same browser matrix and base config. |
| Coverage |
Enforced minimum (e.g. 80% for critical paths) |
Defined in TECH_POLICIES.md and CI. |
5. Quality & Tooling
| Area |
Choice |
Notes |
| Linting |
ESLint |
Shared config at repo root; extends per portal if needed. |
| Formatting |
Prettier |
Single shared config. No conflicting formatters. |
| Git hooks |
lint-staged + Husky (or equivalent) |
Pre-commit: lint + format + typecheck. |
| Type checking |
tsc --noEmit |
Required in CI; no skipLibCheck for library code unless justified. |
6. DevOps & Hosting
| Area |
Choice |
Notes |
| CI |
GitHub Actions (or org-standard CI) |
Same workflow structure: lint, test, build, (deploy). |
| Containers |
Docker |
Single Dockerfile pattern; multi-stage builds. |
| Environments |
dev / staging / production |
Same naming and promotion rules. |
| Secrets |
Env vars from secure store (e.g. vault / CI secrets) |
No secrets in repo or client bundles. |
7. Accessibility & Compliance
| Area |
Standard |
Notes |
| Accessibility |
WCAG 2.1 Level AA |
Required; automated checks in CI where possible. |
| Semantic HTML |
Required |
Use correct landmarks, headings, and ARIA only when necessary. |
| Browser support |
Per TECH_POLICIES.md |
Same supported browsers and versions. |
8. Portal layout (per directory)
Each portal directory (e.g. DBIS/, XOM/, OMNL/, ICCC/) must contain:
- A Next.js application that uses the stack above.
- A README with: purpose, how to run, env vars, and link to this TECH_STACK.
- Shared config usage: extend root ESLint/Prettier/TypeScript where provided.
- Design tokens aligned with the shared design system (e.g. from
shared/ or root config).
9. Adding a new portal
- Create a new directory with the governmental body’s initials.
- Bootstrap a Next.js app (TypeScript, Tailwind, App Router) that matches this stack.
- Copy or extend root configs (ESLint, Prettier, TS).
- Add a README and ensure TECH_STACK.md and TECH_POLICIES.md are linked and followed.
- Add the portal to any root-level scripts or docs that list portals.
Last updated: 2025-02. Review periodically and update version numbers and tool choices in one place to keep all portals in sync.
