# asmattic/matthewoldfield-com architecture

> Architecture diagram of the GitHub repository asmattic/matthewoldfield-com, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asmattic/matthewoldfield-com
- Repository: https://github.com/asmattic/matthewoldfield-com

## Overview

##### Project Type and Purpose
- This is a full-stack static+dynamic Next.js application serving as a personal portfolio and blog.
- It uses file-based content (MDX), Tailwind CSS for styling, Contentlayer for content ingestion, and serverless API routes for newsletter and authentication integrations.

##### File-Structure Analysis
- pages/ : Next.js page routes (static pages, MDX-based blog, API endpoints under pages/api).
- layouts/ : page templates (AuthorLayout, PostLayout, ListLayout, etc.).
- data/ : site metadata, authors, blog posts, project data, nav links.
- lib/ & scripts/ : content-processing utilities (Remark plugins, contentlayer config, RSS & sitemap generators).
- public/static/ : static assets (images, favicons, downloads).
- next.config.js, middleware.ts, Contentlayer config: build and runtime configuration.

##### Key Technologies & Patterns
- Next.js SSG/SSR and Incremental Static Regeneration for page rendering.
- Contentlayer to transform MDX content into JSON data at build time.
- File-based routing and API routes (newsletter subscribe endpoints, auth via NextAuth).
- Tailwind CSS/PostCSS for styling, PrismCSS for code blocks.
- Serverless functions (Vercel) for dynamic features.
- External integrations: Google Analytics, Disqus (comments), Buttondown/ConvertKit/Mailchimp (newsletter), NextAuth (auth).

##### Main Components
a. Browser / Client
- Renders HTML/CSS/JS bundle, initiates API calls, executes GA scripts.
b. CDN / Static Hosting (Vercel)
- Serves static assets (JS bundles, CSS, images, fonts) and pre-rendered HTML.
c. Next.js Application
- SSG Build Pipeline:
- Contentlayer reads MDX & data files → generates GraphQL-style data nodes
- Next.js build generates static pages (HTML + JSON)
- Scripts generate RSS & sitemap
- Runtime Serverless Functions:
- pages/api/auth/[...nextauth] → NextAuth handlers
- pages/api/buttondown.js, convertkit.js, mailchimp.js → newsletter endpoints
- Middleware.ts for any edge logic/CSP enforcement.
d. Data Layer
- Local file system: MDX blog posts, JSON/JS data files (siteMetadata, projectsData, authors).
- contentlayer.config.ts orchestrates file ingestion.
e. Styling Pipeline
- tailwind.config.js + PostCSS + css/tailwind.css → compiled CSS
- css/prism.css → code block styling
f. External Services
- Google Analytics (analytics/GoogleAnalytics.tsx)
- Disqus (comments/Disqus.tsx)
- Newsletter providers: Buttondown, ConvertKit, Mailchimp
- Authentication providers via NextAuth

##### Relationships & Data Flows
- At build time: File system → Contentlayer → Next.js build → Static HTML + JSON → CDN
- At runtime (Client):
- Client requests page from CDN → HTML + hydration JS → React SPA
- Client fires GA events → Google Analytics
- Client submits newsletter form → Next.js API route → external newsletter API → confirmation
- Client loads Disqus script → Disqus comment threads
- Client may trigger NextAuth flows → external auth provider → NextAuth API route
- All static assets (CSS, images) fetched from CDN/public/static.

##### Architectural Patterns & Principles
- Jamstack hybrid: static generation + dynamic serverless endpoints
- Component-driven UI (React), layout composability
- Clear separation: presentation (components/layouts), content (data/MDX), logic (lib, scripts, API)
- Convention-over-configuration: Next.js file routing, Contentlayer ingestion

##### Final Recommendations
- Above components and flows without over-splitting trivial files.
- Custom middleware or special CSP considerations from next.config.js & middleware.ts.
- Keep it high-level yet detailed enough to show static vs dynamic boundaries and external integrations.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Build Phase
  subgraph "Build Phase"
    FS[(File System: MDX & Data Files)]:::data
    subgraph "Remark Plugins"
      CODETITLE["Code Titles Plugin"]:::build
      FRONTMATTER["Frontmatter Extraction Plugin"]:::build
      IMGTOJSX["Image to JSX Plugin"]:::build
      TOCHEAD["TOC Headings Plugin"]:::build
    end
    CL["Contentlayer"]:::build
    CLCFG["contentlayer.config.ts"]:::build
    CLUTIL["lib/utils/contentlayer.ts"]:::build
    NXBUILD["Next.js Build (SSG)"]:::build
    RSS["RSS Generator"]:::build
    SMAP["Sitemap Generator"]:::build
    subgraph "Styling Pipeline"
      TAILWCFG["tailwind.config.js"]:::build
      POSTCSS["postcss.config.js"]:::build
      TAILWENT["css/tailwind.css"]:::build
      PRISMCSS["css/prism.css"]:::build
    end
    subgraph "Config"
      NXCONF["next.config.js"]:::build
      MIDDLE["middleware.ts"]:::build
    end

    FS -->|"MDX → JSON"| CL
    CL -->|"GraphQL nodes"| NXBUILD
    NXCONF --> NXBUILD
    FS --> RSS
    FS --> SMAP
    RSS -->|"rss.xml"| CDN
    SMAP -->|"sitemap.xml"| CDN
    FS --> TAILWCFG
    FS --> POSTCSS
    POSTCSS --> TAILWENT
    TAILWENT --> CDN
    PRISMCSS --> CDN
    MIDDLE --> CDN

    FS --> CODETITLE
    FS --> FRONTMATTER
    FS --> IMGTOJSX
    FS --> TOCHEAD
  end

  %% CDN / Hosting
  subgraph "CDN / Hosting"
    CDN["Vercel CDN\n- HTML, JS, CSS\n- Static Assets\n- Serverless"]:::serverless
  end

  %% Runtime / Client
  subgraph "Runtime / Client"
    BROWSER["Browser / Client"]:::frontend

    subgraph "Serverless API Routes"
      AUTH["NextAuth API"]:::serverless
      BTNAPI["Buttondown API"]:::serverless
      CVTAPI["ConvertKit API"]:::serverless
      MAILAPI["Mailchimp API"]:::serverless
    end

    subgraph "External Services"
      GA["Google Analytics"]:::external
      DISQUS["Disqus"]:::external
      BUTTON["Buttondown"]:::external
      CONV["ConvertKit"]:::external
      MAIL["Mailchimp"]:::external
      AUTHPROV["Auth Providers"]:::external
    end

    BROWSER -->|"page request"| CDN
    BROWSER -->|"GA events"| GA
    BROWSER -->|"load comments"| DISQUS
    BROWSER -->|"subscribe"| BTNAPI
    BROWSER -->|"subscribe"| CVTAPI
    BROWSER -->|"subscribe"| MAILAPI
    BROWSER -->|"auth flow"| AUTH

    BTNAPI -->|"calls"| BUTTON
    CVTAPI -->|"calls"| CONV
    MAILAPI -->|"calls"| MAIL
    AUTH -->|"auth flow"| AUTHPROV
  end

  %% Click Events
  click AUTH "https://github.com/asmattic/matthewoldfield-com/blob/main/pages/api/auth/[...nextauth].ts"
  click BTNAPI "https://github.com/asmattic/matthewoldfield-com/blob/main/pages/api/buttondown.ts"
  click CVTAPI "https://github.com/asmattic/matthewoldfield-com/blob/main/pages/api/convertkit.ts"
  click MAILAPI "https://github.com/asmattic/matthewoldfield-com/blob/main/pages/api/mailchimp.ts"
  click CLCFG "https://github.com/asmattic/matthewoldfield-com/blob/main/contentlayer.config.ts"
  click CLUTIL "https://github.com/asmattic/matthewoldfield-com/blob/main/lib/utils/contentlayer.ts"
  click CODETITLE "https://github.com/asmattic/matthewoldfield-com/blob/main/lib/remark-code-title.ts"
  click FRONTMATTER "https://github.com/asmattic/matthewoldfield-com/blob/main/lib/remark-extract-frontmatter.ts"
  click IMGTOJSX "https://github.com/asmattic/matthewoldfield-com/blob/main/lib/remark-img-to-jsx.ts"
  click TOCHEAD "https://github.com/asmattic/matthewoldfield-com/blob/main/lib/remark-toc-headings.ts"
  click RSS "https://github.com/asmattic/matthewoldfield-com/blob/main/scripts/generate-rss.mjs"
  click SMAP "https://github.com/asmattic/matthewoldfield-com/blob/main/scripts/generate-sitemap.mjs"
  click TAILWCFG "https://github.com/asmattic/matthewoldfield-com/blob/main/tailwind.config.js"
  click POSTCSS "https://github.com/asmattic/matthewoldfield-com/blob/main/postcss.config.js"
  click TAILWENT "https://github.com/asmattic/matthewoldfield-com/blob/main/css/tailwind.css"
  click PRISMCSS "https://github.com/asmattic/matthewoldfield-com/blob/main/css/prism.css"
  click NXCONF "https://github.com/asmattic/matthewoldfield-com/blob/main/next.config.js"
  click MIDDLE "https://github.com/asmattic/matthewoldfield-com/blob/main/middleware.ts"

  %% Styles
  classDef frontend fill:#cce5ff,stroke:#1f78b4,color:#1f78b4
  classDef build fill:#d4edda,stroke:#31a354,color:#31a354
  classDef serverless fill:#fff3cd,stroke:#e08e1e,color:#e08e1e
  classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d
  classDef external fill:#e5d4f4,stroke:#6f42c1,color:#6f42c1
```
