SITE ARCHITECTURE
How this Portfolio was Made
This site serves as a live case study demonstrating how modern AI pair-programming workflows can collaborate with a developer to build highly performant, accessible, and robust web applications.
The Creative Workflow
The site was built using a hybrid AI and human-led engineering model, dividing responsibility between visual specification and structural implementation.
Designed with Google Stitch
The visual layout, user interactions, and tokenized design system (including custom fonts, vibrant secondary states, and grid layouts) were designed using Google Labs' AI-native UI tool, Stitch. Design tokens were exported directly as pure CSS variables, ensuring visual design intent mapped perfectly to code.
Created with Antigravity
Antigravity, a powerful agentic AI coding assistant from Google DeepMind, acted as the primary implementation agent. It bootstrapped the React Router 7 framework, integrated the Google Stitch design system, refactored pages, conducted automated accessibility (a11y) passes, and ran local compilers and bundlers to ensure production readiness.
Test-Driven Development (TDD) Workflow
To guarantee stability, accessibility, and zero-regression updates, the entire application was constructed under a strict Test-Driven Development (TDD) red/green cycle.
Red Phase (Write Tests)
Before a single line of feature code was written, companion test files were defined using Vitest and React Testing Library. Tests asserted the existence of accessible header landmarks, semantic markup tags, keyboard focus targets, and routing boundaries.
Green Phase (Implement)
The minimal React code necessary to satisfy the test assertions was written. Focus was kept purely on implementing correct routing hooks, importing components, and using appropriate semantic HTML structures to transition the suite from failing (Red) to passing (Green).
Refactor (Clean & Optimize)
With the safety net of passing tests, the code was refactored. We extracted components, optimized Tailwind utilities, streamlined layout parameters, and completed accessibility sweeps confident that all previously defined specifications remained green.
The Technology Stack
The architecture uses lightweight, modern web frameworks chosen to minimize bundle size, maximize rendering speed, and ensure absolute development predictability:
- React Router 7:Combines client-side hydration, declarative routing, and meta headers configuration to eliminate page-load lag.
- Tailwind CSS v4:Configured via the new compiler engine. Styles are declared using native `@theme` directives in standard CSS variables, completely removing JS config setup overhead.
- Vitest & React Testing Library:Provides quick-feedback testing in a browser-like JSDOM context. Running on top of Vite's fast transformation engine, it runs tests on code change in milliseconds.
Dependency Overview
Hosting & Deployment Pipeline
The application is compiled into a lightweight Docker image using a multi-stage production builder targeting AMD64 architecture. Deployments are orchestrated via Kamal 2, enabling zero-downtime container updates on the server.
DigitalOcean Target Environment
- Droplet IP:
xx.xxx.xx.xxx - Domain Name:
portfolio.jonathanclarke.dev - Traffic Proxy: Automated SSL auto-certification via Let's Encrypt managed by Kamal Proxy routing requests to port 3000.
Kamal 2 Config Summary
The config in config/deploy.yml declares:
service: portfolio
image: jonclarke84/portfolio
servers:
web:
- xx.xxx.xx.xxx
proxy:
ssl: true
hosts:
- portfolio.jonathanclarke.dev
app_port: 3000