105 lines
4.4 KiB
Markdown
105 lines
4.4 KiB
Markdown
# 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.*
|