Architecture Overview — How This Portfolio Is Built

This post walks through the technical architecture of this portfolio — the frameworks, the content pipeline, and the build process that generates fully-typed, statically-rendered pages.

High-Level Overview

The content pipeline flows like this:

MDX Files → Contentlayer parses → Type Definitions + JSON Data
Types + Data → Next.js consumes → React Pages
Pages → Build process → Static HTML
Static HTML → Deploy → Vercel Edge Network

Key principles:

Content as data — MDX files are parsed into typed JSON at build time
Type-safety everywhere — TypeScript strict mode, no any types
Static by default — Every route pre-rendered, zero server runtime
Progressive enhancement — HTML first, JavaScript for interactivity

Tech Stack Breakdown

Next.js 15 (App Router)

Using the latest App Router for:

// app/(site)/layout.tsx
export default function SiteLayout({ children }) {
  return (
    <div className="flex min-h-screen">
      <Sidebar />
      <main className="flex-1">{children}</main>
      <RightRail />
    </div>
  );
}
 
// app/(site)/work/page.tsx
import { allProjects } from '@/.contentlayer/generated';
 
export default function WorkIndex() {
  const projects = allProjects
    .filter(p => p.status === 'shipped')
    .sort((a, b) => b.date - a.date);
 
  return <ProjectGrid projects={projects} />;
}

Why App Router over Pages?

Better layouts with nested routes
Server Components by default (less JS)
Streaming SSR ready (future-proofing)
Improved data fetching patterns

Contentlayer — Type-Safe MDX

The magic behind type-safe content:

// contentlayer.config.ts
import { defineDocumentType, makeSource } from 'contentlayer/source-files';
import readingTime from 'reading-time';
 
export const Blog = defineDocumentType(() => ({
  name: 'Blog',
  filePathPattern: `blog/**/*.mdx`,
  contentType: 'mdx',
  fields: {
    title: { type: 'string', required: true },
    date: { type: 'date', required: true },
    tags: { type: 'list', of: { type: 'string' } },
    excerpt: { type: 'string' },
    author: { type: 'string' },
    cover: { type: 'string' },
    series: { type: 'string' },
    seo: { type: 'json' },
  },
  computedFields: {
    slug: {
      type: 'string',
      resolve: (doc) => doc._raw.flattenedPath.replace(/^blog\//, ''),
    },
    url: {
      type: 'string',
      resolve: (doc) => `/blog/${doc._raw.flattenedPath.replace(/^blog\//, '')}`,
    },
    readingTime: {
      type: 'json',
      resolve: (doc) => readingTime(doc.body.raw),
    },
  },
}));

What Contentlayer does:

Parses MDX — Reads all .mdx files in content/
Validates frontmatter — Required fields must exist, types must match
Generates TypeScript — Creates .contentlayer/generated/types.d.ts
Outputs JSON — Each file becomes structured data
Computes fields — Derived values like slug, reading time

The result:

import { allBlogs } from '@/.contentlayer/generated';
 
// ✅ Fully typed!
allBlogs[0].title;       // string
allBlogs[0].date;        // string (IsoDateTimeString)
allBlogs[0].tags;        // string[] | undefined
allBlogs[0].readingTime; // { text: string, minutes: number, ... }
allBlogs[0].slug;        // string (computed)

Build-time validation:

$ npm run build
 
Error: Found 1 problem in 3 documents.
 
└── "blog/broken-post.mdx" of type "Blog" has incompatible fields:
    • title: Required field missing
    • date: Expected date, got string "yesterday"

Build fails, not production. 🎉

MDX Configuration

Rich content with React components:

// contentlayer.config.ts
export default makeSource({
  contentDirPath: 'content',
  documentTypes: [Blog, Project],
  mdx: {
    remarkPlugins: [
      remarkGfm,              // GitHub Flavored Markdown (tables, task lists)
    ],
    rehypePlugins: [
      rehypeSlug,             // Add IDs to headings
      [rehypeAutolinkHeadings, { behavior: 'wrap' }],  // Link headings
      [rehypePrettyCode, { theme: 'github-dark' }],    // Syntax highlighting
    ],
  },
});

Features enabled:

Tables — GitHub-style markdown tables
Code blocks — Syntax highlighting with line numbers
Heading anchors — Clickable heading links
Custom components — Import React components in MDX

Example MDX features:

Regular markdown formatting (bold, italic, lists)
Custom React components embedded in content
Syntax-highlighted code blocks
GitHub Flavored Markdown extensions

Tailwind CSS 4

Utility-first styling with design tokens:

/* app/globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;
 
@layer base {
  :root {
    --bg: 255 255 255;
    --fg: 0 0 0;
    --border: 229 231 235;
    --accent: 59 130 246;
  }
 
  .dark {
    --bg: 0 0 0;
    --fg: 255 255 255;
    --border: 38 38 38;
    --accent: 96 165 250;
  }
}

Usage in components:

<div className="bg-[--bg] text-[--fg] border-[--border]">
  <h1 className="text-4xl font-semibold">Hello</h1>
  <p className="text-[--fg]/80 mt-2">Supporting text</p>
</div>

Why Tailwind over CSS-in-JS?

Zero runtime overhead
Better tree-shaking (unused classes removed)
Fast development with autocomplete
Easy theming with CSS variables

Project Structure

/calvin-dev
├── app/
│   ├── (site)/
│   │   ├── layout.tsx          # Shared layout (Sidebar, RightRail)
│   │   ├── page.tsx             # Home
│   │   ├── work/
│   │   │   ├── page.tsx         # Work index
│   │   │   └── [slug]/page.tsx  # Project detail
│   │   ├── blog/
│   │   │   ├── page.tsx         # Blog index
│   │   │   └── [slug]/page.tsx  # Blog post
│   │   └── about/page.tsx       # About page
│   ├── api/og/route.tsx         # Dynamic OG images
│   └── globals.css              # Tailwind + theme variables
│
├── content/
│   ├── blog/*.mdx               # Blog posts
│   └── work/*.mdx               # Project case studies
│
├── components/
│   ├── layout/                  # Sidebar, RightRail
│   ├── cards/                   # ProjectCard, BlogCard
│   └── ui/                      # Button, Dialog primitives
│
├── types/
│   └── content.ts               # Extended types (Project, BlogPost)
│
├── .contentlayer/
│   └── generated/               # Auto-generated types & JSON
│
├── contentlayer.config.ts       # Content schema
└── next.config.ts               # Next.js config

Build Pipeline

1. Content Generation

$ npm run build
 
> contentlayer build
 
Generated 12 documents in .contentlayer/
  • 10 Blog posts
  • 2 Projects

Contentlayer runs before Next.js build, generating:

.contentlayer/generated/types.d.ts — TypeScript definitions
.contentlayer/generated/Blog/*.json — Post data
.contentlayer/generated/Project/*.json — Project data

2. Next.js Build

> next build
 
Route (app)                              Size     First Load JS
┌ ○ /                                 5.44 kB         107 kB
├ ○ /work                             3.21 kB         105 kB
├ ○ /work/memfuse-v1                  8.92 kB         112 kB
├ ○ /blog                             3.45 kB         105 kB
├ ○ /blog/launch-notes                7.81 kB         111 kB
└ ○ /about                            2.34 kB         104 kB
 
○  (Static)  prerendered as static content

All routes are static HTML. No server runtime needed.

3. Deployment

$ git push origin main
 
→ Vercel detects push
→ Runs build
→ Deploys to Edge network
→ Lighthouse CI checks performance

Preview deployments: Every PR gets a unique preview URL. Lighthouse scores posted as comment.

Performance Optimizations

Image Optimization

import Image from 'next/image';
import coverImage from '@/public/images/work/memfuse/cover.png';
 
<Image
  src={coverImage}
  alt="MemFuse architecture diagram"
  placeholder="blur"
  className="rounded-lg"
/>

Next.js automatically:

Generates WebP/AVIF versions
Creates responsive srcsets
Extracts blur placeholder
Lazy loads below fold

Font Optimization

// app/layout.tsx
import { Inter } from 'next/font/google';
 
const inter = Inter({
  subsets: ['latin'],
  display: 'swap',
  variable: '--font-inter',
});
 
export default function RootLayout({ children }) {
  return (
    <html lang="en" className={inter.variable}>
      <body>{children}</body>
    </html>
  );
}

Next.js:

Self-hosts fonts (no external requests)
Subsets to only used glyphs
Preloads font files
Zero layout shift

Code Splitting

Every page gets its own bundle. Shared code extracted to chunks:

chunks/255-4efeec91c7871d79.js    45.7 kB  (React core)
chunks/4bd1b696-c023c6e3521b1417.js 54.2 kB  (React DOM)
chunks/app-pages-internals.js      1.9 kB  (Next.js internals)

Result: Landing page loads only what it needs.

Type Safety in Practice

Before Contentlayer

// Fragile, runtime errors
const posts = fs.readdirSync('content/blog')
  .map(file => {
    const content = fs.readFileSync(file);
    const parsed = matter(content);
    return {
      title: parsed.data.title,      // ❌ Could be undefined
      date: new Date(parsed.data.date), // ❌ Could be invalid
      slug: file.replace('.mdx', ''), // ❌ Manual logic
    };
  });

After Contentlayer

import { allBlogs } from '@/.contentlayer/generated';
 
// ✅ Type-safe, build-time validated
const posts = allBlogs.map(post => ({
  title: post.title,       // ✅ Guaranteed string
  date: post.date,         // ✅ Valid ISO date
  slug: post.slug,         // ✅ Computed correctly
  readingTime: post.readingTime.text, // ✅ Auto-calculated
}));

Errors caught at build time, not runtime.

Lessons Learned

1. Contentlayer Is a Game-Changer

Type-safe content transforms how you build content sites. Refactoring is safe, templates are simpler, and bugs vanish.

2. App Router Pays Off Long-Term

Learning curve is steeper than Pages Router, but layouts, loading states, and Server Components are worth it.

3. Static Generation Scales

12 pages? 1200 pages? Doesn't matter. Build time scales linearly, runtime performance stays perfect.

4. CSS Variables > Hardcoded Colors

Theming becomes trivial when colors are variables. Dark mode is a CSS class toggle.

Resources

Source Code

Full source available: github.com/calvinku/calvin-dev

Check out:

contentlayer.config.ts — Schema definitions
app/(site)/ — Page structure
types/content.ts — Extended type helpers
.github/workflows/ — CI/CD pipeline

Questions? Find me on Twitter or email.