# hamishmw/portfolio architecture

> Architecture diagram of the GitHub repository hamishmw/portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hamishmw/portfolio
- Repository: https://github.com/hamishmw/portfolio

## Overview

1. This repository is a personal portfolio site built as a Remix application, deployed to Cloudflare Pages/Functions. The architecture is split between route-driven app code under `app/`, serverless edge handlers in `functions/`, and static/public assets in `public/` and `app/assets/`.

2. The primary application boundary is Remix routing. Each page or page section lives in a route module under `app/routes/`, with matching UI files and optional `route.js`/`route.jsx` modules for loaders, actions, and route-level metadata. `app/root.jsx` and `app/root.module.css` define the global shell, document structure, and top-level styling.

3. The site content is organized into a few major sections: home, articles, projects, contact, and uses. The home route is the landing page with multiple visually rich subsections. The articles area renders blog posts from MDX content. The projects area contains separate showcase routes for individual projects. The contact route handles form submission, and the uses page is a curated gear/software list.

4. Articles are content-driven rather than database-driven. The repo includes MDX files directly in `app/routes/` for individual posts and a `posts.server.js` module under `app/routes/articles_._index/` that likely aggregates and sorts them for the index page. `app/layouts/post/` provides the shared article rendering layout and markdown presentation.

5. The project showcase subsystem is highly visual and asset-heavy. Individual project routes such as `projects.smart-sparrow` and `projects.volkihar-knight` have their own route modules plus dedicated components. These pages use GLB models, HDR environment maps, video textures, and custom shaders from `app/assets/` and route-local shader files, indicating a strong Three.js/WebGL rendering boundary inside otherwise standard React pages.

6. Shared UI is centralized in `app/components/`. This functions as a design system and includes text, headings, buttons, links, image wrappers, lists, tables, form inputs, loaders, progress indicators, segmented controls, icons, and layout primitives like `section`, `divider`, and `footer`. Many of these components have Storybook stories, which makes the component library independently reviewable from the full app.

7. Interactive behavior is encapsulated in custom hooks under `app/hooks/`. These include browser-aware and viewport-dependent utilities such as hydration detection, mounted-state checks, viewport observation, parallax, interval timing, scroll-to-hash behavior, window-size tracking, and form input management. This keeps route components focused on composition while isolating client-only logic.

8. Theming and navigation are first-class subsystems. `app/components/theme-provider/` manages the site theme, `app/routes/api.set-theme.js` is the route boundary for updating theme preference, and the navbar layout includes theme toggle and nav toggle components. This suggests a client/server split where UI state is persisted through a route action or API call.

9. Several reusable layout wrappers organize page structure and responsiveness: `app/layouts/navbar/`, `app/layouts/post/`, `app/layouts/project/`, and `app/layouts/error/`. These are not generic page components; they represent higher-level shells that enforce consistent spacing, navigation, and error presentation across route groups.

10. Utility modules under `app/utils/` handle cross-cutting concerns such as MDX processing, metadata generation, image helpers, style helpers, timing, throttling, date formatting, and Three.js-related helpers. These are the glue between content, rendering, and route metadata.

11. Static media is a major architectural input, not just decoration. The repo stores fonts, videos, 3D models, and HDR environment assets locally, and the app consumes them directly. The `app/components/model/` and route-specific 3D components indicate that large portions of the experience are built from local media assets rather than remote services.

12. Storybook is a parallel development surface. The `.storybook/` configuration plus per-component stories let the UI system be developed and validated without running the full Remix app. This is especially important here because many components have visual states, animations, and media-dependent rendering.

13. Build and deployment tooling reinforce the app’s separation of concerns. Vite is used for local bundling and Storybook integration, Cloudflare Wrangler is used for deployment, and `scripts/` contains supporting tasks such as Draco-related model processing. The presence of `public/_headers`, `manifest.json`, `robots.txt`, and `sitemap.xml` shows that the deployment output is meant to be a production static/edge site with SEO and PWA-style metadata.

14. Overall, the architecture is a content-rich portfolio shell with three main axes: route-based pages, a shared component system, and specialized visual/media features. For an architecture diagram, the clearest boundaries are Remix routes at the top, shared UI/layout/hooks/utils in the middle, and external/static media plus Cloudflare edge deployment at the bottom.

Main entry points: [`app/components`](https://github.com/hamishmw/portfolio/tree/master/app/components) (UI library), [`app/routes/articles_._index/route.jsx`](https://github.com/hamishmw/portfolio/blob/master/app/routes/articles_._index/route.jsx) (Article index), [`app/root.jsx`](https://github.com/hamishmw/portfolio/blob/master/app/root.jsx) (Root shell), [`app/layouts/project/project.jsx`](https://github.com/hamishmw/portfolio/blob/master/app/layouts/project/project.jsx) (Project shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_root["Root shell<br/>Remix root<br/>[root.jsx]"]
  node_navbar["Navbar<br/>layout shell<br/>[navbar.jsx]"]
  node_project_layout["Project shell<br/>[project.jsx]"]
  node_error_layout["Error shell<br/>[error.jsx]"]
end

subgraph group_content["Content Routes"]
  node_route_articles["Articles<br/>route boundary<br/>[route.jsx]"]
  node_route_articles_index["Article index<br/>content index<br/>[route.jsx]"]
  node_posts_server["Post loader<br/>content source<br/>[posts.server.js]"]
  node_post_layout["Post layout<br/>article shell<br/>[post.jsx]"]
  node_route_home["Home<br/>landing page<br/>[route.js]"]
  node_home_parts["Home sections<br/>page sections<br/>[home.jsx]"]
  node_route_projects_spr["Smart Sparrow<br/>project route<br/>[route.js]"]
  node_route_projects_vk["Volkihar Knight<br/>project route<br/>[route.js]"]
  node_route_projects_slice["Slice<br/>project route<br/>[route.js]"]
  node_route_contact["Contact<br/>form route<br/>[route.js]"]
  node_route_uses["Uses<br/>curated list<br/>[route.js]"]
end

subgraph group_shared["Shared UI"]
  node_theme_provider["Theme provider<br/>state provider<br/>[theme-provider.jsx]"]
  node_ui_components["UI library<br/>design system"]
  node_hooks["Hooks"]
  node_utils["Utilities<br/>helpers"]
end

subgraph group_media["Media"]
  node_assets[("Assets<br/>static media")]
  node_public[("Public files<br/>static output")]
end

subgraph group_tooling["Tooling"]
  node_storybook["Storybook<br/>ui workspace<br/>[.storybook]"]
  node_deploy["Cloudflare<br/>edge deploy<br/>[[[path]].js]"]
end

node_root -->|"uses"| node_navbar
node_root -->|"wraps"| node_theme_provider
node_root -->|"routes to"| node_route_home
node_route_home -->|"renders"| node_home_parts
node_home_parts -->|"composes"| node_ui_components
node_route_articles -->|"contains"| node_route_articles_index
node_route_articles_index -->|"loads"| node_posts_server
node_route_articles_index -->|"formats"| node_post_layout
node_route_articles_index -->|"composes"| node_ui_components
node_route_projects_spr -->|"uses"| node_project_layout
node_route_projects_vk -->|"uses"| node_project_layout
node_route_projects_slice -->|"uses"| node_project_layout
node_route_projects_spr -->|"loads"| node_assets
node_route_projects_vk -->|"loads"| node_assets
node_route_projects_slice -->|"loads"| node_assets
node_project_layout -->|"composes"| node_ui_components
node_navbar -->|"composes"| node_ui_components
node_theme_provider -->|"supports"| node_ui_components
node_ui_components -->|"uses"| node_hooks
node_ui_components -->|"uses"| node_utils
node_route_contact -->|"composes"| node_ui_components
node_route_contact -->|"uses"| node_hooks
node_route_uses -->|"composes"| node_ui_components
node_route_articles_index -.->|"publishes"| node_public
node_storybook -->|"documents"| node_ui_components
node_deploy -->|"serves"| node_public
node_deploy -->|"runs app"| node_root

click node_root "https://github.com/hamishmw/portfolio/blob/master/app/root.jsx"
click node_route_articles "https://github.com/hamishmw/portfolio/blob/master/app/routes/articles/route.jsx"
click node_route_articles_index "https://github.com/hamishmw/portfolio/blob/master/app/routes/articles_._index/route.jsx"
click node_posts_server "https://github.com/hamishmw/portfolio/blob/master/app/routes/articles_._index/posts.server.js"
click node_post_layout "https://github.com/hamishmw/portfolio/blob/master/app/layouts/post/post.jsx"
click node_route_home "https://github.com/hamishmw/portfolio/blob/master/app/routes/home/route.js"
click node_home_parts "https://github.com/hamishmw/portfolio/blob/master/app/routes/home/home.jsx"
click node_route_projects_spr "https://github.com/hamishmw/portfolio/blob/master/app/routes/projects.smart-sparrow/route.js"
click node_route_projects_vk "https://github.com/hamishmw/portfolio/blob/master/app/routes/projects.volkihar-knight/route.js"
click node_route_projects_slice "https://github.com/hamishmw/portfolio/blob/master/app/routes/projects.slice/route.js"
click node_route_contact "https://github.com/hamishmw/portfolio/blob/master/app/routes/contact/route.js"
click node_route_uses "https://github.com/hamishmw/portfolio/blob/master/app/routes/uses/route.js"
click node_navbar "https://github.com/hamishmw/portfolio/blob/master/app/layouts/navbar/navbar.jsx"
click node_project_layout "https://github.com/hamishmw/portfolio/blob/master/app/layouts/project/project.jsx"
click node_error_layout "https://github.com/hamishmw/portfolio/blob/master/app/layouts/error/error.jsx"
click node_theme_provider "https://github.com/hamishmw/portfolio/blob/master/app/components/theme-provider/theme-provider.jsx"
click node_ui_components "https://github.com/hamishmw/portfolio/tree/master/app/components"
click node_hooks "https://github.com/hamishmw/portfolio/tree/master/app/hooks"
click node_utils "https://github.com/hamishmw/portfolio/tree/master/app/utils"
click node_assets "https://github.com/hamishmw/portfolio/tree/master/app/assets"
click node_public "https://github.com/hamishmw/portfolio/tree/master/public"
click node_storybook "https://github.com/hamishmw/portfolio/blob/master/.storybook"
click node_deploy "https://github.com/hamishmw/portfolio/blob/master/functions/[[path]].js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root,node_navbar,node_project_layout,node_error_layout toneBlue
class node_route_articles,node_route_articles_index,node_posts_server,node_post_layout,node_route_home,node_home_parts,node_route_projects_spr,node_route_projects_vk,node_route_projects_slice,node_route_contact,node_route_uses toneAmber
class node_theme_provider,node_ui_components,node_hooks,node_utils toneMint
class node_assets,node_public toneRose
class node_storybook,node_deploy toneIndigo
```

## Components

### App Shell

Remix application entry, routing, layouts, and page composition.

- [Root shell](https://github.com/hamishmw/portfolio/blob/master/app/root.jsx): Remix root · Global document, providers, and app-wide styling. · `app/root.jsx`
- [Navbar](https://github.com/hamishmw/portfolio/blob/master/app/layouts/navbar/navbar.jsx): layout shell · Site navigation, theme toggle, and nav state. · `app/layouts/navbar/navbar.jsx`
- [Project shell](https://github.com/hamishmw/portfolio/blob/master/app/layouts/project/project.jsx): project shell · Shared layout for project showcase pages. · `app/layouts/project/project.jsx`
- [Error shell](https://github.com/hamishmw/portfolio/blob/master/app/layouts/error/error.jsx): error shell · Consistent error presentation across routes. · `app/layouts/error/error.jsx`

### Content Routes

Route-driven sections and content-heavy pages.

- [Articles](https://github.com/hamishmw/portfolio/blob/master/app/routes/articles/route.jsx): route boundary · Top-level articles section route. · `app/routes/articles/route.jsx`
- [Article index](https://github.com/hamishmw/portfolio/blob/master/app/routes/articles_._index/route.jsx): content index · Aggregates and renders the article listing. · `app/routes/articles_._index/route.jsx`
- [Post loader](https://github.com/hamishmw/portfolio/blob/master/app/routes/articles_._index/posts.server.js): content source · Server-side post collection and sorting. · `app/routes/articles_._index/posts.server.js`
- [Post layout](https://github.com/hamishmw/portfolio/blob/master/app/layouts/post/post.jsx): article shell · Shared article rendering and markdown presentation. · `app/layouts/post/post.jsx`
- [Home](https://github.com/hamishmw/portfolio/blob/master/app/routes/home/route.js): landing page · Landing page route with rich visual sections. · `app/routes/home/route.js`
- [Home sections](https://github.com/hamishmw/portfolio/blob/master/app/routes/home/home.jsx): page sections · Intro, profile, project summary, and hero visuals. · `app/routes/home/home.jsx`
- [Smart Sparrow](https://github.com/hamishmw/portfolio/blob/master/app/routes/projects.smart-sparrow/route.js): project route · Visual project showcase with heavy media and WebGL. · `app/routes/projects.smart-sparrow/route.js`
- [Volkihar Knight](https://github.com/hamishmw/portfolio/blob/master/app/routes/projects.volkihar-knight/route.js): project route · Visual project showcase with custom 3D presentation. · `app/routes/projects.volkihar-knight/route.js`
- [Slice](https://github.com/hamishmw/portfolio/blob/master/app/routes/projects.slice/route.js): project route · Project showcase route with route-level composition. · `app/routes/projects.slice/route.js`
- [Contact](https://github.com/hamishmw/portfolio/blob/master/app/routes/contact/route.js): form route · Contact page and submission boundary. · `app/routes/contact/route.js`
- [Uses](https://github.com/hamishmw/portfolio/blob/master/app/routes/uses/route.js): curated list · Tools, gear, and software list page. · `app/routes/uses/route.js`

### Shared UI

Reusable components, hooks, and utilities used across routes.

- [Theme provider](https://github.com/hamishmw/portfolio/blob/master/app/components/theme-provider/theme-provider.jsx): state provider · Manages and distributes site theme state. · `app/components/theme-provider/theme-provider.jsx`
- [UI library](https://github.com/hamishmw/portfolio/tree/master/app/components): design system · Shared text, controls, media, and layout primitives. · `app/components`
- [Hooks](https://github.com/hamishmw/portfolio/tree/master/app/hooks): client hooks · Browser-aware and interaction-focused reusable hooks. · `app/hooks`
- [Utilities](https://github.com/hamishmw/portfolio/tree/master/app/utils): helpers · MDX, metadata, styling, timing, and Three.js helpers. · `app/utils`

### Media

Local static assets consumed by pages and visual components.

- [Assets](https://github.com/hamishmw/portfolio/tree/master/app/assets): static media · Local fonts, videos, HDRs, and 3D models used by the site. · `app/assets`
- [Public files](https://github.com/hamishmw/portfolio/tree/master/public): static output · SEO, manifest, headers, and public static files. · `public`

### Tooling

Storybook, build, deployment, and support scripts.

- [Storybook](https://github.com/hamishmw/portfolio/blob/master/.storybook): ui workspace · Parallel UI development and visual validation surface. · `.storybook`
- [Cloudflare](https://github.com/hamishmw/portfolio/blob/master/functions/[[path]].js): edge deploy · Functions entry points and Wrangler deployment config. · `functions/[[path]].js`

## Connections

- Root shell → Navbar: uses · Root composes the site chrome.
- Root shell → Theme provider: wraps · Theme context is provided at the app shell.
- Root shell → Home: routes to · Root app hosts the route tree.
- Home → Home sections: renders · Home route assembles sectional components.
- Home sections → UI library: composes · Home sections are built from shared UI primitives.
- Articles → Article index: contains · Articles section includes the index route.
- Article index → Post loader: loads · Index page uses server-side post aggregation.
- Article index → Post layout: formats · Article listing connects to shared post presentation.
- Article index → UI library: composes · List and article UI use shared primitives.
- Smart Sparrow → Project shell: uses · Project route is wrapped in the shared project shell.
- Volkihar Knight → Project shell: uses · Project route is wrapped in the shared project shell.
- Slice → Project shell: uses · Project route is wrapped in the shared project shell.
- Smart Sparrow → Assets: loads · Uses local 3D and media assets.
- Volkihar Knight → Assets: loads · Uses local 3D and media assets.
- Slice → Assets: loads · Uses local visual assets.
- Project shell → UI library: composes · Project shell reuses shared design system pieces.
- Navbar → UI library: composes · Navigation shell is built from shared primitives.
- Theme provider → UI library: supports · Theme state influences shared UI rendering.
- UI library → Hooks: uses · Interactive components rely on shared hooks.
- UI library → Utilities: uses · Components share formatting and helper logic.
- Contact → UI library: composes · Contact form uses shared controls and layout.
- Contact → Hooks: uses · Form and viewport behavior use custom hooks.
- Uses → UI library: composes · Uses page is assembled from shared UI pieces.
- Article index → Public files: publishes · Content pages align with public SEO and static assets.
- Storybook → UI library: documents · Storybook provides an isolated review surface for components.
- Cloudflare → Public files: serves · Cloudflare deployment serves public files and headers.
- Cloudflare → Root shell: runs app · Edge functions host the Remix application.
