From 0f50561949eeb410738328f4864a795a8f5010c5 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Tue, 15 Sep 2026 07:53:39 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=8F=9B=EF=B8=8F=20Archie:=20Codify=20ADR?= =?UTF-8?q?=200001/0002,=20Master=20Index,=20and=20Tech=20Radar?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: alehar9320 <5390430+alehar9320@users.noreply.github.com> --- .Jules/archie.md | 3 + ...0001-cloudflare-production-render-jules.md | 26 +++++--- .../0002-strict-zod-boundary-validation.md | 26 ++++++++ docs/adr/README.md | 16 +++++ docs/tech-radar.md | 64 +++++++++++++++++++ 5 files changed, 126 insertions(+), 9 deletions(-) create mode 100644 .Jules/archie.md create mode 100644 docs/adr/0002-strict-zod-boundary-validation.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..c872f6fe --- /dev/null +++ b/.Jules/archie.md @@ -0,0 +1,3 @@ +2026-08-24 - Initial Architectural Governance & Tech Radar Codification +Learning: Missing master ADR index (`docs/adr/README.md`) and Tech Radar (`docs/tech-radar.md`) allowed implicit architectural conventions (such as strict Zod boundary validation and Workers-First runtime models) to remain uncodified, risking AI agent context drift during feature development. +Action: Standardized ADR 0001, codified Zod boundary validation as Accepted ADR 0002, created master index `docs/adr/README.md`, and established `docs/tech-radar.md` with explicit Directives for AI Agents across four operational quadrants. diff --git a/docs/adr/0001-cloudflare-production-render-jules.md b/docs/adr/0001-cloudflare-production-render-jules.md index 1070a827..c5006e79 100644 --- a/docs/adr/0001-cloudflare-production-render-jules.md +++ b/docs/adr/0001-cloudflare-production-render-jules.md @@ -1,18 +1,26 @@ -# ADR 0001: Cloudflare as production, Render as Jules test env +# 0001. Cloudflare Workers as Production Environment and Render as Jules Testbed -- 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 site can build using two runtime paths: Cloudflare Workers (static + `@astrojs/cloudflare`) or a Node.js standalone server when `RENDER=true` (`@astrojs/node`). Production runs on Cloudflare Workers (`https://me.alehar.workers.dev/`). A clear architectural split is required so autonomous agents like Google Jules can execute and debug tests in a Node.js environment without treating that secondary path as production or a failover target. ## 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 Cloudflare Workers with Assets (`wrangler.jsonc`). The Render deployment is designated strictly as a test/debugging environment for autonomous agents (Google Jules) via `render.yaml`. Render is neither a production target nor a failover environment. -## 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 operational boundaries prevent accidental deployment of Node-specific artifacts to Cloudflare Workers and simplify Workers-first runtime optimizations. +- **Negative / Risks:** Node testbed requires stubbing Cloudflare Worker bindings (e.g., `src/env/cloudflare-workers.node.ts`). +- **Adoption Readiness:** Fully implemented and active in repository build pipelines (`astro.config.mjs`, `wrangler.jsonc`, `render.yaml`). + +## Directives for AI Agents + +- **Do:** Assume Cloudflare Workers + Assets (`wrangler.jsonc`) is the sole production runtime. +- **Do:** Keep `@astrojs/node` build logic isolated behind `process.env.RENDER === 'true'`. +- **Don't:** Add production features or cloud bindings that rely on Node.js runtime globals or server-side Node packages in production code paths. +- **Don't:** Treat Render as a production environment or failover target in documentation, CI, or deployment logic. diff --git a/docs/adr/0002-strict-zod-boundary-validation.md b/docs/adr/0002-strict-zod-boundary-validation.md new file mode 100644 index 00000000..4fcdf652 --- /dev/null +++ b/docs/adr/0002-strict-zod-boundary-validation.md @@ -0,0 +1,26 @@ +# 0002. Strict Zod Boundary Validation for External and Content Schemas + +- **Status:** Accepted +- **Date:** 2026-08-24 +- **Deciders:** Autonomous Architect (Archie) / Repository Analysis + +## Context + +The site processes structured data from multiple system boundaries, including Astro content collections, API endpoints, environment variables, and telemetry events. Unvalidated data entering runtime code risks runtime exceptions, type unsafety, and silent failures, especially when interacted with by automated AI agents. + +## Decision + +All external data boundaries—including content collection frontmatter, API request payloads, and environment configurations—must be strictly validated using Zod schemas. Compile-time types must be derived from Zod schemas using `z.infer` rather than hand-written interfaces. + +## Consequences & Tradeoffs + +- **Positive:** Guarantees runtime type safety, fast failures at boundaries, and self-documenting data structures across human and AI development. +- **Negative / Risks:** Slight build-time and runtime overhead for schema parsing; schema maintenance when external payloads evolve. +- **Adoption Readiness:** Fully active across content collections (`src/content.config.ts`), guidelines (`docs/zod-guidelines.md`), and API endpoints. + +## Directives for AI Agents + +- **Do:** Define Zod schemas for all new content collections, API request bodies, and external payload handlers. +- **Do:** Derive TypeScript types using `z.infer`. +- **Don't:** Use `any` or `@ts-ignore` to bypass schema validation. +- **Don't:** Write duplicate interface definitions alongside Zod schemas; maintain a single source of truth. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..5b379ef9 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,16 @@ +# Architecture Decision Records (ADRs) + +This directory records key architectural decisions made in the development, operation, and governance of Alexander Härenstam's personal portfolio website and Cloudflare Workers infrastructure. + +## Master Index + +| ID | Title | Status | Date | +| -------------------------------------------------- | ------------------------------------------------------------------------ | -------- | ---------- | +| [0001](0001-cloudflare-production-render-jules.md) | Cloudflare Workers as Production Environment and Render as Jules Testbed | Accepted | 2026-08-24 | +| [0002](0002-strict-zod-boundary-validation.md) | Strict Zod Boundary Validation for External and Content Schemas | Accepted | 2026-08-24 | + +## Governance Rules + +- All architectural changes, conventions, or strategic proposals must be documented as ADRs in this directory. +- ADRs must follow sequential numbering (`0001`, `0002`, `0003`, ...). +- Every ADR must include an explicit **Directives for AI Agents** section to prevent agent context drift across the codebase. diff --git a/docs/tech-radar.md b/docs/tech-radar.md new file mode 100644 index 00000000..9e32b970 --- /dev/null +++ b/docs/tech-radar.md @@ -0,0 +1,64 @@ +# Repository Tech Radar + +This Tech Radar tracks technologies, frameworks, libraries, tools, and architectural patterns used across this repository. It serves as ground truth context for human developers and autonomous AI agents. + +## Quadrants + +### 1. Frameworks & Runtimes + +- **Adopt:** + - **Astro (v7+)**: Static-first web framework providing zero-JS default output and component hydration islands. + - **Cloudflare Workers & Assets**: Production edge execution runtime (`wrangler.jsonc`). + - **TypeScript (Strict Mode)**: Mandatory static type safety across the entire codebase. +- **Trial:** + - **Node.js Standalone (`@astrojs/node`)**: Gated behind `RENDER=true` strictly for autonomous agent testbed execution. +- **Assess:** + - **Cloudflare D1 / KV**: Potential storage additions for dynamic features. +- **Hold:** + - **Classic Cloudflare Pages**: Deprecated in favor of modern Workers + Assets runtime. + +### 2. Infrastructure & Cloud + +- **Adopt:** + - **Cloudflare Workers + Assets (`wrangler.jsonc`)**: Production edge platform. + - **GitHub Actions**: CI pipeline for formatting, linting, testing, and releases. +- **Trial:** + - **Render (`render.yaml`)**: Jules autonomous testing environment. +- **Assess:** + - **Cloudflare Vectorize**: Vector embeddings for potential semantic search. +- **Hold:** + - **Manual Server Deployments**: All deployments must flow through git integration or automated workflows. + +### 3. Tooling & AI Workflows + +- **Adopt:** + - **Vitest**: Unit testing framework with native Vite integration. + - **ESLint & Prettier**: Static analysis and code style formatting enforcement. + - **Jules AI Agents**: Scheduled and PR-triggered autonomous maintenance and feature agents. +- **Trial:** + - **MCP (Model Context Protocol) Servers**: Local developer context integration via `mcp_config.json`. +- **Assess:** + - **Playwright**: End-to-end frontend verification testing. +- **Hold:** + - **Jest / Mocha**: Banned in favor of Vitest. + +### 4. Patterns & Architecture + +- **Adopt:** + - **Workers-First Architecture**: Single Worker runtime handling assets and edge routes. + - **Strict Zod Boundary Validation**: Schema-first runtime validation for API inputs, env vars, and content collections. + - **Vanilla CSS Styling**: Hardware-accelerated glassmorphism without framework bloat. +- **Trial:** + - **Dynamic Telemetry Imports**: Splitting heavy dynamic chunks for client-side analytics. +- **Assess:** + - **WebGPU / Advanced WebGL Canvases**: High-performance interactive visual art. +- **Hold:** + - **Tailwind CSS & Utility CSS Frameworks**: Strictly forbidden in favor of scoped Vanilla CSS. + - **Global State Managers (Redux, Zustand)**: Banned; rely on native Web APIs, URL state, or Astro island props. + +## Rings + +- **Adopt:** High confidence, production-proven in this repo. Default choice for new work. +- **Trial:** High potential with low risk. Ready for isolated usage in minor features or scripts. +- **Assess:** Worth tracking and evaluating trade-offs; not yet recommended for active production code. +- **Hold:** Phasing out or proven problematic in our setup. Do not use for new work.