# 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

1. Create a new directory with the governmental body’s initials.
2. Bootstrap a Next.js app (TypeScript, Tailwind, App Router) that matches this stack.
3. Copy or extend root configs (ESLint, Prettier, TS).
4. Add a README and ensure TECH_STACK.md and TECH_POLICIES.md are linked and followed.
5. 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.*