From 569a3799bcfdc7d46c0140642272815fca5f8257 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 7 Sep 2026 07:59:25 +0000 Subject: [PATCH] docs(adr): establish baseline ADR index, zero-dependency ADR, and Tech Radar Standardize ADR 0001 format with Directives for AI Agents. Codify Accepted ADR 0002 for Edge-First Zero-Dependency Architecture. Create master index table in docs/adr/README.md. Create docs/tech-radar.md across 4 quadrants and 4 rings. Record architectural learnings in .Jules/archie.md. Co-authored-by: alehar9320 <5390430+alehar9320@users.noreply.github.com> --- .Jules/archie.md | 3 + ...0001-cloudflare-production-render-jules.md | 26 +++++--- ...edge-first-zero-dependency-architecture.md | 29 ++++++++ docs/adr/README.md | 14 ++++ docs/tech-radar.md | 66 +++++++++++++++++++ 5 files changed, 129 insertions(+), 9 deletions(-) create mode 100644 .Jules/archie.md create mode 100644 docs/adr/0002-edge-first-zero-dependency-architecture.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..ab533df5 --- /dev/null +++ b/.Jules/archie.md @@ -0,0 +1,3 @@ +2026-03-30 - Architecture Governance Baseline & Edge-First Directives +Learning: Standardizing ADR formats with explicit 'Directives for AI Agents' and establishing a Repository Tech Radar prevents AI agent drift across edge runtime constraints (Cloudflare Workers vs Render Node test env) and eliminates redundant dependencies. +Action: Require all future ADRs to define actionable 'Do' and 'Don't' directives for AI agents and maintain the master index in docs/adr/README.md. diff --git a/docs/adr/0001-cloudflare-production-render-jules.md b/docs/adr/0001-cloudflare-production-render-jules.md index 1070a827..d5c291d8 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, Render as Jules Test Environment -- 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 personal portfolio site supports two build paths: Cloudflare Workers (static SSG/SSR via `@astrojs/cloudflare`) and a standalone Node.js server (`@astrojs/node`) triggered when `RENDER=true`. Production runs on Cloudflare Workers (https://me.alehar.workers.dev/). A clear operational separation is required so AI agents (such as Google Jules) can run integration and health checks against a Node environment without treating Render as a production failover or active secondary 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. +Cloudflare Workers is strictly designated as the sole Production target. Render is strictly an isolated testing and preview environment for AI agent verification (`render.yaml`). Render is neither a production failover nor a secondary hosting target. -## 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:** Eliminates operational confusion regarding dual deployment targets; guarantees Cloudflare Edge environment bindings (`wrangler.jsonc`, KV, AI) remain production authoritative. +- **Negative / Risks:** Node standalone compatibility stubs (`src/env/cloudflare-workers.node.ts`) must be maintained to ensure agent verification passes on Render without Workers native bindings. +- **Adoption Readiness:** Already implemented across `astro.config.mjs`, `render.yaml`, and `wrangler.jsonc`. + +## Directives for AI Agents + +- **Do:** Ensure production deployment features and Worker bindings target `@astrojs/cloudflare` and `wrangler.jsonc`. +- **Do:** Keep Render node mocks/stubs in `src/env/cloudflare-workers.node.ts` updated if Worker binding contracts change. +- **Don't:** Modify production routing or architectural assumptions to treat Render as a secondary production environment. +- **Don't:** Remove the `isRender` branching in `astro.config.mjs`. diff --git a/docs/adr/0002-edge-first-zero-dependency-architecture.md b/docs/adr/0002-edge-first-zero-dependency-architecture.md new file mode 100644 index 00000000..7293043b --- /dev/null +++ b/docs/adr/0002-edge-first-zero-dependency-architecture.md @@ -0,0 +1,29 @@ +# 0002. Edge-First Zero-Dependency Architecture & Single-Pass Data Transforms + +- **Status:** Accepted +- **Date:** 2026-03-30 +- **Deciders:** Autonomous Architect (Archie) / Repository Analysis + +## Context + +The personal portfolio operates on Cloudflare Workers edge runtime isolates where memory overhead, GC pauses, subrequest latency, and bundle sizes are critical performance factors. Relying on heavy external runtime utility libraries or executing multi-pass array operations (`.map()`, `.filter()`, `.slice()`, `.flatMap()`) in Edge SSR handlers creates unnecessary dynamic intermediate allocations and increases cold start latency. + +## Decision + +1. **Zero-Dependency Utilities:** All backend, math, data transformation, and UI helper functions must be implemented natively in pure TypeScript without adding third-party runtime dependencies. +2. **Single-Pass Edge Transforms:** Array processing in Edge SSR helpers (such as visitor changelogs, release summaries, and chat utilities) must utilize single-pass `for...of` loops or reverse-indexed `for` loops rather than chaining dynamic intermediate array allocations. +3. **Strict Schema Boundaries:** All untrusted external inputs (Markdown frontmatter, API endpoints, feature flag JSON, user payloads) must be validated using Zod schemas at system boundaries. + +## Consequences & Tradeoffs + +- **Positive:** Drastically minimizes Cloudflare Worker bundle size, eliminates memory allocation spikes during Edge requests, ensures sub-millisecond SSR execution, and maintains total type safety. +- **Negative / Risks:** Developers and AI agents must author bespoke native TypeScript helpers instead of pulling in utility packages (e.g., Lodash, Ramda). +- **Adoption Readiness:** Fully active across all utilities in `src/utils/` and content loaders in `src/content.config.ts`. + +## Directives for AI Agents + +- **Do:** Write math, string parsing, and array utilities natively in pure TypeScript. +- **Do:** Refactor multi-step array chains (`.map().filter().slice()`) in Edge SSR routines into single-pass `for...of` or indexed loops. +- **Do:** Strictly validate all external inputs with Zod schemas using `z.infer` for derived types. +- **Don't:** Introduce third-party npm runtime dependencies for utility or data processing needs. +- **Don't:** Use `@ts-ignore`, `any`, or unvalidated type assertions on external boundaries. diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 00000000..bca06441 --- /dev/null +++ b/docs/adr/README.md @@ -0,0 +1,14 @@ +# Architecture Decision Records (ADRs) + +This directory contains the sequential Architecture Decision Records for Alexander Härenstam's personal portfolio repository. These records govern the strategic architecture, framework choices, edge runtime constraints, and AI agent boundaries. + +## ADR Index + +| ID | Title | Status | Date | +| :-------------------------------------------------------- | :-------------------------------------------------------------------- | :------- | :--------- | +| [0001](./0001-cloudflare-production-render-jules.md) | Cloudflare Workers as Production, Render as Jules Test Environment | Accepted | 2026-08-24 | +| [0002](./0002-edge-first-zero-dependency-architecture.md) | Edge-First Zero-Dependency Architecture & Single-Pass Data Transforms | Accepted | 2026-03-30 | + +## Structure & Directives + +Each ADR defines explicit **Directives for AI Agents** to ensure human developers and autonomous AI agents maintain repository architectural standards without agent drift or regression. diff --git a/docs/tech-radar.md b/docs/tech-radar.md new file mode 100644 index 00000000..583f0fdc --- /dev/null +++ b/docs/tech-radar.md @@ -0,0 +1,66 @@ +# Repository Tech Radar + +This document maintains ground-truth technology status across four standard rings and four operational quadrants for Alexander Härenstam's personal portfolio repository. + +## Quadrants & Technology Status + +### 1. Frameworks & Runtimes + +- **Adopt:** + - **Astro (v7):** Core web framework using static SSG & Edge SSR adapters (`@astrojs/cloudflare`). + - **Cloudflare Workers:** Production Edge SSR runtime for zero-cold-start delivery. + - **TypeScript:** Strict type checking across the entire codebase. +- **Trial:** + - **Node.js (v22+):** Used exclusively for Jules test runner / standalone Render preview environment via `@astrojs/node`. +- **Assess:** + - **Workers AI:** Cloudflare edge LLM inference for release summarization (`@cf/meta/llama-3.1-8b-instruct-fast`). +- **Hold:** + - **React / Vue / Svelte Heavy Hydration:** Avoid introducing framework islands when vanilla JS or Astro components suffice. + +### 2. Infrastructure & Cloud + +- **Adopt:** + - **Cloudflare Workers Builds:** Production deployment pipeline (`wrangler.jsonc`). + - **Cloudflare KV:** Edge key-value caching for release summaries and visit stats. +- **Trial:** + - **Render:** Isolated test environment for automated AI agent preview verification (`render.yaml`). +- **Assess:** + - **Cloudflare Vectorize:** High-dimensional vector storage for semantic portfolio search. +- **Hold:** + - **Traditional VPS / Dedicated Servers:** Production MUST run on Cloudflare Workers edge runtime. + +### 3. Tooling & AI Workflows + +- **Adopt:** + - **Vitest:** Native TypeScript test runner for zero-dependency utility and API unit tests. + - **Prettier & ESLint:** Enforced code formatting and linting pipelines. + - **Husky & lint-staged:** Git pre-commit hooks for format check enforcement. + - **PostHog:** Deferred dynamic-import analytics integration (`posthog-js`). +- **Trial:** + - **Sentry (@sentry/astro & @sentry/cloudflare):** Application monitoring and error boundary tracing. +- **Assess:** + - **Codecov Vite Plugin:** Automated bundle size and test coverage analysis in CI. +- **Hold:** + - **Jest / Mocha:** Legacy test runners. Use Vitest exclusively. + +### 4. Patterns & Architecture + +- **Adopt:** + - **Vanilla CSS Glassmorphism:** Lightweight, hardware-accelerated 'Northern Lights' aesthetic using Vanilla CSS variables. + - **Zod Schema Boundaries:** Strict runtime validation for API payloads, frontmatter, and feature flags (`src/content.config.ts`). + - **Single-Pass Array Traversals:** Zero-allocation `for...of` loops and reverse-indexed loops in Edge SSR functions. + - **Feature Flags via Content Collections:** Isolated feature toggles (`src/content/flags/config.json`). +- **Trial:** + - **DOM MutationObserver State Guarding:** Synchronizing state with `localStorage` while preventing redundant disk write I/O. +- **Assess:** + - **Canvas DPR Capping:** Hardware-accelerated canvas micro-interactions capped at DPR <= 2. +- **Hold:** + - **Tailwind CSS & Utility Frameworks:** Strictly forbidden. All layout and interactive styling uses Vanilla CSS. + - **Unvalidated Inputs & `@ts-ignore`:** Banned across all files. + +## Ring Definitions + +- **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 test environments. +- **Assess:** Worth tracking and evaluating trade-offs; not yet recommended for active production standard. +- **Hold:** Phasing out, banned, or proven problematic in our setup. Do not use for new work.