System Architecture

How this portfolio is engineered

A live look at the architecture, system design and automated workflows behind bilalahamad.com — from the Vercel edge down to a single source of truth, the content pipelines, and the quality gates that ship every change.

8
Routes
5
API endpoints
7
MDX blog posts
9
Type tokens

The Stack

A layered, server-first architecture

Requests flow down from the visitor through the edge into server-rendered React, then back up as static HTML enriched with hydrated client islands. The data dots trace that path through every layer.

  • Client & Crawlers

    Recruiters, browsers, ATS bots and social scrapers

    Desktop & mobileGooglebot / ATSOG link previewsRSS · sitemap

  • Vercel Edge & CDN

    Global edge network with response caching

    Edge routings-maxage 1h cachenext/image optimizationSpeed Insights

  • Next.js 16 · App Router

    React Server Components render HTML on the server

    Server ComponentsMetadata APIJSON-LD: Person + Breadcrumbssitemap.xml · robots.txt

  • Client Islands

    Hydrated interactivity layered over static HTML

    NavbarV2BentoGridV2 · ssr:falseFramer MotionTheme + analytics

  • Data & Content

    A single, typed source of truth feeds every view

    portfolio.tsMDX blog · gray-matterai-metrics.json9 roles · 5 projects

  • API Routes

    Serverless endpoints for dynamic + form data

    /api/contact/api/repos/api/badges/api/ai-metrics/api/visitors

  • External Services

    Third-party integrations behind the API layer

    SMTP · nodemailerGitHub APIGA4 Data APIUpstash KVLinkedIn API

Request Lifecycle

From URL to interactive

What happens between a click and a fully interactive page — the packet follows a single request through the rendering pipeline.

  1. 1

    Request

    GET /experience hits the edge

  2. 2

    Edge & cache

    CDN serves or forwards

  3. 3

    RSC render

    HTML built on the server

  4. 4

    Stream HTML

    Static markup + JSON-LD

  5. 5

    Hydrate

    Client islands wake up

  6. 6

    Interactive

    Animations + analytics live

Workflows

Automated content & delivery pipelines

Three pipelines keep the site fresh and trustworthy — watch each one light up stage by stage as work moves through it.

Blog publishing

MDX in, static HTML out — no client JS to read a post

  1. MDX file
  2. gray-matter parse
  3. Server render
  4. Static HTML
  5. ATS-indexed route

Blog → LinkedIn (/post)

One command cross-publishes to the blog and LinkedIn

  1. Topic
  2. Draft + infographic
  3. MDX article
  4. npm run build
  5. LinkedIn API
  6. Backfill URL
  7. Commit + push

CI/CD quality gates

Every push is linted, tested and visually checked before deploy

  1. git push
  2. Lint
  3. Unit + e2e
  4. Visual regression
  5. Vercel build
  6. Production

System Design

The principles holding it together

Eight decisions that make the site fast, accessible, recruiter-ready and cheap to maintain.

SSR-first for ATS

Every job title, company and metric ships as static HTML — applicant-tracking crawlers read it without running a line of JS.

Single source of truth

All career data lives in one typed module, portfolio.ts. Components only read from it, so content never drifts out of sync.

Fluid type system

Nine semantic t-* tokens built on clamp() scale text smoothly from phone to desktop — no responsive class soup.

Glassmorphism system

A small set of glass utilities and design tokens keeps every surface visually consistent and on-brand.

Edge caching

GitHub-backed API routes cache at the CDN for an hour via s-maxage, so repeat visits feel instant.

Accessible by default

WCAG-AA contrast, visible focus rings, a skip-link and full prefers-reduced-motion support are baked in.

Type-safe & linted

TypeScript strict mode, zero any types, and a clean build + lint gate run on every single commit.

Automated publishing

A /post pipeline cross-publishes to the blog and LinkedIn — draft, build, API publish and commit in one flow.

Want to see it in action?

The same engineering rigor goes into every project. Explore the work or read the source on GitHub.

View projectsView source