Building This Blog

architecture dev-tools

Introduction

Welcome to a look under the hood of dsj.blog. As an engineering leader and builder, I wanted a platform that wasn’t just a place to write, but a showcase of modern web architecture and developer experience, and one that I could continue to use to experiment with technologies and AI development practices.

This post details how the blog was built, the technology choices driving its performance, and how it leverages agentic development workflows to maintain high quality standards.

Key Concepts

Building a platform that is both highly performant and easy to maintain requires splitting our focus between efficient architectural patterns and carefully selected technical tooling.

Architectural Overview

The primary goal of our architecture is to maintain absolute minimal client-side overhead while retaining highly dynamic edge-computing capabilities for interactive features:

  • Hybrid Rendering & Islands Architecture: The core pages are statically rendered on the server to deliver zero JavaScript by default. We use React Islands (with an Astro client:visible directive) to only hydrate engagement areas—like comments and likes—when they actually scroll into view, maintaining lightning-fast initial page loads.
  • Real-Time Edge Processing: To provide a mini-app experience without bringing down static page speed, user interactions are handled securely at the edge via Cloudflare Workers and safely persisted in a globally distributed edge database.
  • Event-Driven Workflows: Features like adding comments trigger asynchronous API events via custom Make.com webhooks, which open up flexible notification workflows over channels like Email or Slack.
  • Silent Bot Protection: We offload spam bot filtering to a background service that verifies legitimacy without interrupting users with friction-heavy CAPTCHAs.

Tooling & Libraries

Bringing this architectural vision to life required a strict curation of tools and libraries oriented around absolute speed, robust type safety, and edge compatibility:

  • Astro: The hybrid framework orchestrating our content-first build format.
  • React v19: Renders the complex UI and manages state within our interactive islands.
  • Tailwind CSS v4 & MDX: Utility-first styling injected perfectly into rich markdown via @tailwindcss/typography.
  • Turso (SQLite at the Edge): Distributed SQLite databases providing incredibly fast, globally replicated persistence.
  • Drizzle ORM: Exceptionally performant, type-safe database queries against Turso.
  • Cloudflare Turnstile: Enterprise-grade infrastructure driving the silent bot protection.
  • Biome: Extensively adopted to perform all of our code linting and formatting in milliseconds.
  • Vitest: Used as the Vite-native test runner for our unit tests.
  • Husky: Framework for enforcing git pre-commit hooks so validations are never inadvertently bypassed.

Agentic Development Workflow

One of the most unique aspects of this repository is the use of the .agents protocol for structured AI assistance. Rather than relying on simple ad-hoc chat prompts, the architecture includes an explicit Antigravity Agent Protocol that defines system guardrails, personas, and workflows.

  • Central Instruction Set: A .agents/instructions.md file acts as the primary system prompt, securely enforcing rules like accessibility compliance and security best practices before an agent writes any code.
  • Validation Workflows: Automations like validate-blog.ts check every new MDX post prior to committing to ensure correct frontmatter keys, required headings (like this one), and allowed tags (e.g., ["architecture", "dev-tools"]).
  • Slash Commands: AI-assisted tasks are executed predictably. For instance, the /create-blog-post workflow systematically converts raw notes into a fully formatted MDX article, ensuring boilerplate and metadata consistency across all content.

Conclusion

Building this blog was an exercise in aligning a modern web stack with advanced agentic development workflows. By combining the raw edge performance of Astro and Turso with the structured rigor of the .agents protocol, I now have a fast, scalable, and beautifully automated platform to share my technical journey. I hope this architectural overview provides inspiration for your own projects!

Table of Contents