Technical Documentation: Architecture & Rationale

6 July 2025

Last updated: 6 July 2025

Project Overview

HeyShrey.com is a modern, content-rich, personal website and blog built with Next.js and deployed on Netlify. It features articles, photography, timepiece guides, and more, with a focus on performance, SEO, and a great mobile experience.

Directory Structure

/
├── public/                # Static assets (images, icons, manifest, etc.)
├── src/
│   ├── app/               # Next.js app directory (routes, pages, layouts)
│   ├── components/        # React components (UI, layout, widgets)
│   ├── data/              # Data files (e.g., timepieces.ts)
│   ├── lib/               # Utility libraries (e.g., utils.ts)
│   ├── content/           # Markdown or static content (if any)
├── json/                  # JSON data for articles, photographs, etc.
├── static/                # Legacy static files (if any)
├── node_modules/          # Dependencies
├── .next/                 # Next.js build output
├── netlify.toml           # Netlify deployment/configuration
├── package.json           # Project metadata and scripts
├── next.config.js         # Next.js configuration
├── manifest.json          # PWA manifest
├── robots.txt             # SEO: robots rules
├── sitemap.xml            # SEO: sitemap
├── rss.xml                # SEO: RSS feed
└── ... (other config files)

What is `netlify.toml`?

netlify.toml is the primary configuration file for sites deployed on Netlify. It allows you to define build settings, environment variables, custom HTTP headers, caching rules, and redirect logic. This file is read by Netlify during every build and deploy, making it essential for customizing your deployment pipeline and site behavior.

Why is `netlify.toml` important?

It centralizes all Netlify-specific configuration, ensuring your site builds and behaves consistently across environments. It is especially useful for:

Defining build commands and output directories
Setting custom HTTP headers for security (CSP, X-Frame-Options, etc.)
Controlling browser and CDN caching for static assets
Creating redirect and rewrite rules for SPA routing, clean URLs, and static file serving
Integrating plugins (e.g., sitemap generation)

Example `netlify.toml` snippet

[build]
  command = "npm run build"
  publish = ".next"

[[headers]]
  for = "/static/*"
  [headers.values]
    Cache-Control = "public, max-age=31536000, immutable"

[[redirects]]
  from = "/work"
  to = "/work.html"
  status = 200

Troubleshooting `netlify.toml`

Incorrect build directory? Make sure publish matches your framework's output (e.g., .next for Next.js SSR, out for static export).
Redirects not working? Place specific redirects above catch-all rules.
Headers not applied? Double-check the for path and header syntax.

manifest.json: The PWA Identity Card

What is it?
manifest.json is your website's digital business card for browsers and devices. It tells Chrome, Safari, and others how your site should look and behave when "installed" on a phone or tablet. It's what makes your site feel like an app, not just a web page.

Why is it important?
Without a manifest, you can't be a true PWA. You'll miss out on "Add to Home Screen" prompts, splash screens, and a branded experience. It also helps with SEO—Google loves sites that act like apps.

How does it work here?
Our manifest.json lives in /public and is linked in the site's <head>. It defines the app name, theme color, and icons. We use high-res PNGs for best device support. The start_url is set to "/" so users always land on the homepage when launching from their home screen.

{
  "name": "HeyShrey.com",
  "short_name": "HeyShrey",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#7161ef",
  "icons": [
    { "src": "/assets/icons/sj.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/assets/icons/sj.png", "sizes": "512x512", "type": "image/png" }
  ]
}

Best practices:
- Use unique, high-res icons (at least 192x192 and 512x512).
- Match theme_color to your brand for a seamless browser UI.
- Test with Chrome DevTools' Lighthouse to catch missing fields.

Troubleshooting:
- If the "Add to Home Screen" prompt doesn't show, check your manifest link and icon paths.
- Make sure the file is served with Content-Type: application/json.

next.config.js: The Next.js Control Center

What is it?
next.config.js is the master switchboard for your Next.js app. It controls everything from image optimization to custom headers, rewrites, and experimental features.

Why is it important?
This file lets you lock down security (CSP, X-Frame-Options), allow images from trusted domains, and tweak how Next.js builds and serves your site. It's where you make your app production-ready.

How does it work here?
We use next.config.js to allow images from WordPress (for photography), set strict security headers, and control trailing slashes. The headers() function returns custom headers for different routes, so each section (timepieces, socials, etc.) gets the right CSP.

module.exports = {
  images: {
    domains: ["thebrowniris.files.wordpress.com"],
    unoptimized: true,
  },
  async headers() {
    return [
      {
        source: "/(.*)",
        headers: [
          { key: "X-Content-Type-Options", value: "nosniff" },
          { key: "X-Frame-Options", value: "DENY" },
        ],
      },
    ];
  },
};

Best practices:
- Only allow image domains you trust.
- Set security headers for all routes.
- Use unoptimized: true only if you handle image optimization elsewhere.

Troubleshooting:
- If images don't load, check the domains array.
- For header issues, make sure your source path matches your routes.

Service Worker: The Offline Powerhouse

What is it?
A service worker is a background script that can intercept network requests, cache files, and enable offline access. It's the secret sauce behind fast, reliable PWAs.

Why is it important?
With a service worker, your site can load instantly—even with no internet. It also enables push notifications and background sync.

How does it work here?
The codebase includes a commented-out service worker registration in public/scripts/main.js. To enable offline support, uncomment the code and add a sw.js file. This will cache assets and serve them when offline.

if ('serviceWorker' in navigator) {
  navigator.serviceWorker.register('/sw.js')
    .then(reg => console.log('Service Worker registered'))
    .catch(err => console.error('Service Worker registration failed', err));
}

Best practices:
- Always test in incognito to avoid stale caches.
- Use self.skipWaiting() and clients.claim() for instant updates.

Troubleshooting:
- If updates don't show, unregister the service worker in dev tools.
- Check the browser console for errors.

robots.txt: The Search Engine Gatekeeper

What is it?
robots.txt tells search engines what they can and can't crawl. It's your site's "doorman" for Google, Bing, and others.

Why is it important?
It helps you control what gets indexed, keeps private pages out of search, and points crawlers to your sitemap.

How does it work here?
Our robots.txt is in /public and allows all bots to crawl everything. It also links to sitemap.xml for better discovery.

User-agent: *
Allow: /
Sitemap: https://heyshrey.com/sitemap.xml

Best practices:
- Always include a sitemap link.
- Only block pages you truly want hidden.

Troubleshooting:
- If pages aren't indexed, check for Disallow rules or typos.

sitemap.xml: The SEO Roadmap

What is it?
sitemap.xml is a list of all your site's important URLs. It helps search engines find and index your content quickly.

Why is it important?
Without a sitemap, Google might miss new or deep pages. A good sitemap boosts SEO and ensures your latest articles are found fast.

How does it work here?
We update sitemap.xml whenever new articles or guides are added. It's referenced in robots.txt and submitted to Google Search Console for best results.

<url>
  <loc>https://heyshrey.com/article/technical-documentation</loc>
</url>

Best practices:
- Update your sitemap with every new page.
- Validate your sitemap with online tools.

Troubleshooting:
- If new pages aren't indexed, check your sitemap for errors.

rss.xml: The Content Syndicator

What is it?
rss.xml is a feed that lets users and apps subscribe to your site's updates. It's the backbone of blog syndication and podcasting.

Why is it important?
RSS feeds keep your audience engaged and help your content reach more people via feed readers and aggregators.

How does it work here?
Every new article or guide is added to rss.xml. Each <item> includes a title, link, and description for discoverability.

<item>
  <guid>https://heyshrey.com/article/technical-documentation</guid>
  <title>📚 Technical Documentation: Architecture & Rationale</title>
  <link>https://heyshrey.com/article/technical-documentation</link>
  <description>Comprehensive technical documentation for heyshrey.com, including architecture, configuration, and rationale for all major decisions.</description>
</item>

Best practices:
- Include all major articles and updates.
- Keep descriptions clear and concise.

Troubleshooting:
- If feed readers don't update, check for valid XML and correct URLs.

package.json: The Dependency Blueprint

What is it?
package.json is the master list of your project's dependencies, scripts, and metadata. It's what makes npm install work.

Why is it important?
Without package.json, you can't install, build, or deploy your app. It also defines scripts for dev, build, and deploy workflows.

How does it work here?
Ours lists all dependencies (React, Next.js, Tailwind, etc.), scripts for building and deploying, and project metadata. Netlify and local dev both rely on it.

{
  "name": "heyshrey",
  "version": "1.0.0",
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  },
  "dependencies": {
    "next": "^13.0.0",
    "react": "^18.0.0",
    "tailwindcss": "^3.0.0"
  }
}

Best practices:
- Keep dependencies up to date.
- Use scripts for common tasks.

Troubleshooting:
- If builds fail, check for missing or incompatible dependencies.

tsconfig.json: The TypeScript Enforcer

What is it?
tsconfig.json configures TypeScript for your project. It controls compiler options, file inclusion/exclusion, and strictness settings.

Why is it important?
It enforces type safety, improves code quality, and enables advanced TypeScript features.

How does it work here?
We use strict mode for maximum type safety, and include all src/ files. This keeps the codebase robust and maintainable.

{
  "compilerOptions": {
    "target": "esnext",
    "module": "esnext",
    "strict": true,
    "jsx": "preserve"
  },
  "include": ["src/**/*"]
}

Best practices:
- Enable strict mode.
- Keep include and exclude lists up to date.

Troubleshooting:
- If you see type errors, check your compilerOptions and file paths.

tailwind.config.js: The Design System Engine

What is it?
tailwind.config.js customizes Tailwind CSS for your project. It lets you define your design system, colors, spacing, breakpoints, and plugins.

Why is it important?
It enables a consistent, scalable design system and allows you to extend Tailwind with custom utilities and themes.

How does it work here?
We define custom colors, font families, and responsive breakpoints to match the site's branding and layout needs.

module.exports = {
  theme: {
    extend: {
      colors: {
        accent: '#7161ef',
      },
      fontFamily: {
        virgil: ['Virgil', 'sans-serif'],
      },
    },
  },
  plugins: [],
}

Best practices:
- Keep your design tokens (colors, fonts, spacing) in sync with your brand.
- Use plugins for advanced utilities (typography, forms, etc.).

Troubleshooting:
- If custom classes don't work, check your purge/content paths.

globals.css: The Universal Style Sheet

What is it?
globals.css contains global CSS styles for your project. It sets base styles, resets, and utility classes that apply site-wide.

Why is it important?
It ensures a consistent look and feel across all pages and components, and is the foundation for your design system.

How does it work here?
We include Tailwind's base styles, custom resets, and global utility classes for typography, layout, and accessibility.

@tailwind base;
@tailwind components;
@tailwind utilities;

body {
  font-family: 'Virgil', sans-serif;
  background: #fff;
}

Best practices:
- Keep global styles minimal and use utility classes for most styling.
- Reset browser defaults for consistency.

Troubleshooting:
- If styles don't apply, check your import order and file paths.

Development Methodology

The site is built with a component-based approach, using modern tooling (Next.js, Tailwind CSS, PostCSS, TypeScript). Automated workflows handle development, build, and optimization. SEO and accessibility are considered from the start, and performance is a top priority.

Why These Choices?

Next.js provides hybrid static/SSR, fast builds, and a great developer experience. Netlify offers seamless CI/CD, instant rollbacks, and a global CDN. Tailwind CSS enables rapid, consistent, and responsive UI development. PWA features provide a native-app-like experience and offline support. Strict security is enforced with custom headers and CSP for each section. SEO is maximized for discoverability and reach.

Article