From 2c78a21169178e7a5609f81067a6dfb6fe42742e Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 19 Sep 2026 07:54:26 +0000 Subject: [PATCH] docs(architecture): establish tech radar, adr index, and zod validation adr - Add docs/tech-radar.md covering 4 quadrants across 4 rings - Add docs/adr/README.md master index for ADRs - Update docs/adr/0001-cloudflare-production-render-jules.md with AI directives - Add docs/adr/0002-strict-zod-schema-validation-and-feature-flags.md - Record architectural journal entry in .Jules/archie.md Co-authored-by: alehar9320 <5390430+alehar9320@users.noreply.github.com> --- .Jules/archie.md | 5 ++ ...0001-cloudflare-production-render-jules.md | 35 ++++++--- ...zod-schema-validation-and-feature-flags.md | 35 +++++++++ docs/adr/README.md | 26 +++++++ docs/tech-radar.md | 76 +++++++++++++++++++ 5 files changed, 168 insertions(+), 9 deletions(-) create mode 100644 .Jules/archie.md create mode 100644 docs/adr/0002-strict-zod-schema-validation-and-feature-flags.md create mode 100644 docs/adr/README.md create mode 100644 docs/tech-radar.md diff --git a/.Jules/archie.md b/.Jules/archie.md new file mode 100644 index 00000000..3a7b74ec --- /dev/null +++ b/.Jules/archie.md @@ -0,0 +1,5 @@ +# Archie Architectural Journal + +## 2026-08-24 - Codifying Tech Radar Ground Truth & Zod Validation Governance +Learning: The repository lacked a central Tech Radar and master ADR index, causing potential AI context drift around Workers vs Node dual adapters and unwritten content validation conventions. +Action: Maintain `docs/tech-radar.md` and `docs/adr/README.md` as mandatory ground-truth artifacts, enforcing explicit AI Agent Directives in every ADR to guarantee deterministic agent execution. diff --git a/docs/adr/0001-cloudflare-production-render-jules.md b/docs/adr/0001-cloudflare-production-render-jules.md index 1070a827..915cc067 100644 --- a/docs/adr/0001-cloudflare-production-render-jules.md +++ b/docs/adr/0001-cloudflare-production-render-jules.md @@ -1,18 +1,35 @@ -# ADR 0001: Cloudflare as production, Render as Jules test env +# 0001. Cloudflare Workers Production Architecture with Node.js Render Test Sandbox -- Status: Accepted -- Date: 2026-08-24 +- **Status:** Accepted +- **Date:** 2026-08-24 +- **Deciders:** Autonomous Architect (Archie) / Repository Analysis ## Context -The site can build two ways: Cloudflare Workers (static + `@astrojs/cloudflare`) or a Node standalone server when `RENDER=true` (`@astrojs/node`). Prod already runs at https://me.alehar.workers.dev/. We need a clear split so Google Jules can debug against a Node environment without treating that path as a second production or failover. +The repository supports dual build modes: Cloudflare Workers (static SSG + `@astrojs/cloudflare` SSR) and a Node standalone server (`@astrojs/node`) enabled when `RENDER=true`. Production runs on Cloudflare Workers (`https://me.alehar.workers.dev/`). A clear architectural separation is required so AI developer agents (such as Google Jules) can test and debug in a Node environment without misinterpreting the Node target as a secondary production environment, failover, or multi-cloud deployment. ## Decision -Production is Cloudflare Workers only. Render is a test environment for Google Jules (Node server via `render.yaml`). It is not a second prod and not a failover. +Production is strictly deployed on **Cloudflare Workers**. The Render Node web service (`render.yaml`) is designated exclusively as a **testing and debugging environment** for Google Jules and automated agent execution. It is not a secondary production cluster and must not be treated as a failover route. -## Consequences +## Consequences & Tradeoffs -- Ship and operate prod on the Cloudflare Worker (`wrangler.jsonc`, `src/cloudflare-worker.ts`). -- Keep the Render Node path for Jules debugging only; expect AI/KV and other Workers bindings to be absent or stubbed there (`src/env/cloudflare-workers.node.ts`). -- Docs and ops language should call Cloudflare production and Render the Jules test env. +- **Positive:** + - Clear architectural boundaries eliminate ambiguity for human developers and AI agents. + - Ensures Cloudflare Workers edge bindings (`wrangler.jsonc`, `src/cloudflare-worker.ts`) remain the single source of production runtime truth. + - Allows isolated local/agent Node debugging without polluting production edge environment configurations. +- **Negative / Risks:** + - Workers-specific bindings (e.g., KV, AI, HTMLRewriter) are absent or mocked in the Node standalone test environment (`src/env/cloudflare-workers.node.ts`). + - Dual-adapter Astro configuration (`astro.config.mjs`) must maintain branching logic (`isRender`). +- **Adoption Readiness:** Already active and production-proven across Cloudflare and Render setups. + +## Directives for AI Agents + +- **Do:** + - Treat Cloudflare Workers (`@astrojs/cloudflare`) as the sole production target. + - Use the Node adapter path (`RENDER=true`) strictly for agent debugging, isolated smoke tests, or local Node preview testing. + - Keep `src/env/cloudflare-workers.node.ts` up to date with proper mocks whenever new Cloudflare Workers bindings are added. +- **Don't:** + - **NEVER** modify `wrangler.jsonc` or Cloudflare deployment configs to route production traffic to Render. + - **NEVER** assume Workers bindings (KV, AI) are natively present when running under `RENDER=true`. + - **NEVER** treat Render as a production failover or multi-cloud target in architecture documentation or operational scripts. diff --git a/docs/adr/0002-strict-zod-schema-validation-and-feature-flags.md b/docs/adr/0002-strict-zod-schema-validation-and-feature-flags.md new file mode 100644 index 00000000..8f4a3c15 --- /dev/null +++ b/docs/adr/0002-strict-zod-schema-validation-and-feature-flags.md @@ -0,0 +1,35 @@ +# 0002. Strict Zod Schema Validation for Content Collections and Feature Flags + +- **Status:** Accepted +- **Date:** 2026-08-24 +- **Deciders:** Autonomous Architect (Archie) / Repository Analysis + +## Context + +The repository relies on Astro Content Collections (`src/content.config.ts`) to manage portfolio content (e.g. work experience, publications) and runtime feature flags (`src/content/flags/config.json`). To prevent runtime errors, maintain strict TypeScript safety, and ensure autonomous AI agents do not introduce invalid or untyped content structures, all data schemas must be strictly defined and validated at build time. + +## Decision + +All content collections and feature flags **MUST** be defined using Astro Content Collections (`defineCollection`) and validated strictly with Zod schemas (`import { z } from 'astro/zod'`) inside `src/content.config.ts`. Unchecked, dynamically-typed, or raw unvalidated JSON imports are strictly prohibited across all application routes and components. + +## Consequences & Tradeoffs + +- **Positive:** + - Build-time static validation catches invalid content structures, missing fields, and type mismatches before deployment. + - Provides auto-generated TypeScript type definitions for all content entries and feature flags across the codebase. + - Guarantees zero-dependency runtime overhead since Zod schemas are evaluated during Astro's content compilation build step. +- **Negative / Risks:** + - Adding new feature flags or content properties requires updating `src/content.config.ts` in addition to JSON/Markdown source files. + - Schema shifts require `npx astro sync` or build verification to update generated types. +- **Adoption Readiness:** Fully implemented and active in `src/content.config.ts` across `work` and `flags` collections. + +## Directives for AI Agents + +- **Do:** + - Pass all new content collection types or feature flags through Zod schemas in `src/content.config.ts`. + - Use Astro's `getCollection` or `getEntry` APIs to query content collections and feature flags safely. + - Enforce default fallback values in Zod schemas for optional boolean feature flags (e.g., `z.boolean().default(false)`). +- **Don't:** + - **NEVER** import JSON files directly using raw `import data from '...'` when representing content or feature flags. + - **NEVER** use `any` or `@ts-ignore` to bypass Zod schema validation errors. + - **NEVER** bypass schema definitions by creating unvalidated dynamic content loaders outside `src/content.config.ts`. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..44a4c274 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,26 @@ +# Architecture Decision Records (ADRs) + +This directory contains the sequential Architecture Decision Records (ADRs) for the Alexander Härenstam Personal Website repository (`astro-cloudflare-personal-website`). + +ADRs document significant architectural decisions, codebase conventions, runtime trade-offs, and strategic technology shifts. Every ADR contains explicit **Directives for AI Agents** to ensure consistent agent execution and prevent architectural drift. + +--- + +## Index of Architecture Decision Records + +| Number | Title | Status | Date | +| :--------------------------------------------------------------: | :-------------------------------------------------------------------------- | :--------: | :--------: | +| [0001](./0001-cloudflare-production-render-jules.md) | Cloudflare Workers Production Architecture with Node.js Render Test Sandbox | `Accepted` | 2026-08-24 | +| [0002](./0002-strict-zod-schema-validation-and-feature-flags.md) | Strict Zod Schema Validation for Content Collections and Feature Flags | `Accepted` | 2026-08-24 | + +--- + +## ADR Template Guidelines + +When proposing or codifying new decisions, follow the standard template structure: + +1. **Header:** Title formatted as `# NNNN. [Title]`, Status (`Accepted` | `Proposed` | `Superseded` | `Deprecated`), Date, Deciders. +2. **Context:** Problem statement and driving constraints. +3. **Decision:** Explicit rule, architecture, or pattern established. +4. **Consequences & Tradeoffs:** Positive outcomes, negative trade-offs, adoption readiness. +5. **Directives for AI Agents:** Binary **Do** and **Don't** rules enforceable by static analysis or automated tools. diff --git a/docs/tech-radar.md b/docs/tech-radar.md new file mode 100644 index 00000000..fd1da8d1 --- /dev/null +++ b/docs/tech-radar.md @@ -0,0 +1,76 @@ +# Repository Tech Radar + +Welcome to the Tech Radar for the Alexander Härenstam Personal Website repository (`astro-cloudflare-personal-website`). This document tracks technology choices, architectural patterns, and engineering workflows evaluated and adopted across the codebase. + +--- + +## Structure & Definitions + +### Quadrants + +1. **Frameworks & Runtimes:** Core application frameworks, language runtimes, and adapter environments. +2. **Infrastructure & Cloud:** Edge hosting, hosting environments, CI/CD pipelines, and runtime storage. +3. **Tooling & AI Workflows:** Developer tooling, linter/formatter configurations, test runners, and autonomous AI agent workflows. +4. **Patterns & Architecture:** Structural conventions, CSS design systems, data validation rules, and runtime patterns. + +### Rings + +- **Adopt:** High confidence, production-proven in this repository. Default choice for all new features and updates. +- **Trial:** High potential with low risk. Proven in isolated test environments, experimental routes, or specific helper utilities. +- **Assess:** Under evaluation for architectural fit, trade-offs, and maintenance cost. Not recommended for active production code without prior ADR. +- **Hold:** Phased out, anti-patterns, or explicitly banned in this setup. Do not use for new work. + +--- + +## 1. Frameworks & Runtimes + +| Ring | Technology / Tool | Context & Usage | +| :--------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------- | +| **Adopt** | **Astro 5.x** | Primary web framework for fast SSG/SSR content delivery and island component rendering. | +| **Adopt** | **Cloudflare Workers (`@astrojs/cloudflare`)** | Production runtime adapter for edge serverless execution and static asset serving. | +| **Adopt** | **TypeScript (Strict Mode)** | Primary development language; full type safety enforced across all components and utilities. | +| **Trial** | **Node.js Standalone Adapter (`@astrojs/node`)** | Secondary test runtime environment on Render (`RENDER=true`) for AI agent (Jules) debugging. | +| **Assess** | **Cloudflare Workflows / Durable Objects** | Potential stateful edge services if dynamic interactive backends expand. | +| **Hold** | **Heavy JS UI Frameworks (React, Vue, Svelte)** | Banned for core pages to preserve minimalist bundle size and zero-JS client default. | + +--- + +## 2. Infrastructure & Cloud + +| Ring | Technology / Tool | Context & Usage | +| :--------- | :--------------------------------------- | :----------------------------------------------------------------------------------------------------- | +| **Adopt** | **Cloudflare Workers + Assets** | Primary production hosting environment deployed via `wrangler.jsonc` and Git integration. | +| **Adopt** | **GitHub Actions** | Automated CI pipeline (`ci.yml`) enforcing format checks, linting, unit tests, and build verification. | +| **Trial** | **Render Blueprint (`render.yaml`)** | Secondary Node web service Blueprint used specifically as a test sandbox for Jules agent debugging. | +| **Assess** | **Cloudflare KV / D1** | Edge storage bindings available for future dynamic persistence needs. | +| **Hold** | **Traditional Monolithic / VPS Hosting** | Anti-goal; repository is architected exclusively for edge serverless and static asset delivery. | + +--- + +## 3. Tooling & AI Workflows + +| Ring | Technology / Tool | Context & Usage | +| :--------- | :----------------------------------- | :------------------------------------------------------------------------------------------------------- | +| **Adopt** | **Vitest (`vitest`)** | Fast unit testing runner used for all utility, component, and route tests. | +| **Adopt** | **Prettier & ESLint** | Standardized code formatting (`prettier-plugin-astro`) and linting (`eslint-plugin-astro`). | +| **Adopt** | **Husky & Lint-Staged** | Pre-commit Git hooks ensuring code style compliance before committing. | +| **Adopt** | **Autonomous AI Agent Fleet** | Structured AI roles (Archie, Sentinel, Vantage, Bolt, Jules, etc.) governing repo quality and evolution. | +| **Trial** | **Sentry Astro / Cloudflare SDKs** | Error tracking and telemetry integration (`@sentry/astro`, `@sentry/cloudflare`). | +| **Trial** | **Codecov (`@codecov/vite-plugin`)** | Automated coverage analysis and reporting integrated with CI pipeline. | +| **Assess** | **Model Context Protocol (MCP)** | Tooling protocol for enhancing AI agent context awareness and external integrations. | +| **Hold** | **pnpm / yarn** | Repository strictly mandates `npm` as the sole package manager to ensure lockfile deterministic builds. | + +--- + +## 4. Patterns & Architecture + +| Ring | Technology / Tool | Context & Usage | +| :--------- | :------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- | +| **Adopt** | **Static-First Hybrid Rendering** | Default to pre-rendered HTML pages with opt-in edge SSR handlers where dynamic response is required. | +| **Adopt** | **Vanilla CSS "Northern Lights" Theme** | Micro-designed glassmorphic UI using marine blue & cyan gradients without external CSS libraries. | +| **Adopt** | **Strict Schema Validation via Zod** | All content collections and static feature flag definitions MUST pass strict Zod schemas (`src/content.config.ts`). | +| **Adopt** | **Feature Flag Isolation** | Experimental features and UI enhancements must be gated behind feature flags (`src/content/flags/config.json`). | +| **Trial** | **Canvas / WebGL Micro-Interactions** | Self-contained, teardown-managed canvas elements in `/lab/` or interactive islands with `astro:before-swap` cleanup. | +| **Assess** | **Single-Pass Array Traversal for Edge SSR** | Micro-optimization pattern replacing array chain allocations with single `for...of` or indexed loops on Workers. | +| **Hold** | **Tailwind CSS / CSS Frameworks** | Anti-goal; external utility CSS frameworks are prohibited in favor of scoped Vanilla CSS. | +| **Hold** | **Raw `set:html` Directives** | Banned unless input content is 100% trusted or sanitized to eliminate XSS risks. |