CASE STUDY 03 / STATIC-FIRST WEB ARCHITECTURE

This portfolio, by design

An engineering portfolio that keeps content static and optional infrastructure independent.

AstroTypeScriptTailwind CSSGitHub Actions

Overview

The site you are reading uses pre-rendered HTML for its core experience. A small amount of JavaScript enhances theme selection and navigation. The optional Systems Lab is an isolated feature, not a requirement for reading the site.

Problem

A portfolio should communicate engineering work quickly, on a small screen or a slow connection. A content site does not need an application runtime to deliver its most important information.

Requirements

  • Readable, responsive content and dedicated project case studies.
  • Accessible dark and light themes with minimal browser scripting.
  • Centralized content and draft-aware Markdown notes.
  • Static hosting compatibility and graceful optional-service failure.

Architecture

  1. Typed content & Markdown
  2. Astro build
  3. Static HTML, CSS & JS
  4. CDN
  5. Browser
CI checksOptional Systems Lab API
Conceptual flow · supporting capabilities shown below the primary path

Important engineering decisions

Generate HTML at build time with Astro. This leaves navigation and content available even when JavaScript is disabled.

Use shared typed data for project summaries and detail pages to prevent content drift. Use Astro content collections for future Markdown articles.

Make the status endpoint opt-in. A configured request runs after page load, with a timeout and a bounded, validated response.

Data flow

Typed project data and local Markdown enter the Astro build. The output is a directory of static assets suitable for a CDN. The browser can independently request a public Systems Lab endpoint when one is configured.

Technology choices

  • Astro renders content without shipping a component runtime.
  • Strict TypeScript checks data and component interfaces.
  • Tailwind CSS and shared CSS tokens provide layout utilities and a consistent visual system.
  • Native HTML details provides the mobile navigation fallback.

Challenges

The main design challenge is showing technical depth without turning the portfolio into a dashboard. A restrained visual hierarchy, explicit architecture flows, and focused case studies keep the content approachable.

Testing strategy

The repository includes linting, Astro and TypeScript checks, a production build verifier, and tests for optional API failure handling. The verifier checks internal links, page metadata, draft exclusion, and a compressed JavaScript budget. Actual executed results belong in the delivery report.

Security considerations

There is no contact-form backend or user authentication surface. Local Markdown is trusted, repository-reviewed content. Security header guidance includes a Content Security Policy, and no frontend environment variable should contain a secret.

Performance considerations

System fonts eliminate a font download. Diagrams use CSS and SVG. There are no analytics, image libraries, animation libraries, or hydrated React components. A 15 KB compressed budget covers all shipped JavaScript, including optional code.

What I learned

A small architecture can still make deliberate decisions about accessibility, failure boundaries, content ownership, and deployment. Constraints are useful when they keep the reading experience fast and understandable.

Future improvements

  • Keep the résumé current.
  • Publish engineering notes after drafting and review.
  • Deploy static assets to S3 behind CloudFront; attach a separate read-only API only when it exists.