Skip to content
Documentation

ADR-027: Default Tech Stack

Decision

Adopt one binding default stack across every P3 project — frontend, backend (TypeScript and Go), data, observability, testing, and infrastructure. Any deviation requires a project-scoped ADR that references this record; undocumented deviations are non-conformant and treated as bugs.

Key rules

  • Frontend: React 19 + TypeScript, Tailwind via @dmwd-io/design-system, TanStack Router + Query + Table + Form, Zod for validation, Zustand for client state.
  • Backend (TypeScript): Astro 5 (SSR) endpoints or Hono, an api-client.ts wrapper, Zod response schemas, Better-Auth or OIDC for auth.
  • Backend (Go): Go 1.25+ with Fiber v2, GORM over PostgreSQL, Viper for config, zerolog for logging, Taskfile for tasks.
  • Data: PostgreSQL for services; SQLite for local and embedded use.
  • Testing: Vitest + React Testing Library (unit), Playwright (E2E), Lost Pixel (visual regression) — never Chromatic.
  • Infrastructure: Kubernetes with ArgoCD + Helm, GitHub Actions for CI/CD, 1Password Connect surfaced through External Secrets, Taskfile for repeatable tasks.
  • Override protocol: a project-scoped ADR referencing ADR-027 is mandatory before deviating; silent deviations are non-conformant.

Why

A single, documented default stack keeps every P3 project legible, reviewable, and portable between teams, and forces deviations to be explicit and auditable rather than incidental. The toolchain is chosen for type-safety end to end (TypeScript + Zod + GORM-backed Postgres), GitOps-native delivery (ArgoCD + Helm), and secret hygiene (1Password Connect via External Secrets).

This record reconciles the original Vite/React Hook Form draft with current dmwd-io practice: TanStack Form (not React Hook Form) is the form library, Astro 5 SSR is the canonical TypeScript app/runtime, Go is pinned to 1.25+ with Fiber v2, and SQLite is named alongside PostgreSQL as the local/embedded default. Kubernetes CRDs are installed as a separate kubectl apply step before Helm releases, never owned by Helm CRD hooks or app-of-apps sync.

Applies when

You are starting a new project, choosing a library or framework, or evaluating any technology choice that could deviate from the standard stack.

  • ADR-023 — wide-events logging.
  • ADR-024 — engineering standards.
  • ADR-025 — auth JWT standard.
  • ADR-028 — platform foundations.