How hamishmw/portfolio works
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: components UI library · route.jsx Article index · root.jsx Root shell · project.jsx Project shell
Components 23
App Shell
Remix application entry, routing, layouts, and page composition.
- Root shell · Global document, providers, and app-wide styling.
app/root.jsx - Navbar · Site navigation, theme toggle, and nav state.
app/layouts/navbar/navbar.jsx - Project shell · Shared layout for project showcase pages.
app/layouts/project/project.jsx - Error shell · Consistent error presentation across routes.
app/layouts/error/error.jsx
Content Routes
Route-driven sections and content-heavy pages.
- Articles · Top-level articles section route.
app/routes/articles/route.jsx - Article index · Aggregates and renders the article listing.
app/routes/articles_._index/route.jsx - Post loader · Server-side post collection and sorting.
app/routes/articles_._index/posts.server.js - Post layout · Shared article rendering and markdown presentation.
app/layouts/post/post.jsx - Home · Landing page route with rich visual sections.
app/routes/home/route.js - Home sections · Intro, profile, project summary, and hero visuals.
app/routes/home/home.jsx - Smart Sparrow · Visual project showcase with heavy media and WebGL.
app/routes/projects.smart-sparrow/route.js - Volkihar Knight · Visual project showcase with custom 3D presentation.
app/routes/projects.volkihar-knight/route.js - Slice · Project showcase route with route-level composition.
app/routes/projects.slice/route.js - Contact · Contact page and submission boundary.
app/routes/contact/route.js - Uses · Tools, gear, and software list page.
app/routes/uses/route.js
Shared UI
Reusable components, hooks, and utilities used across routes.
- Theme provider · Manages and distributes site theme state.
app/components/theme-provider/theme-provider.jsx - UI library · Shared text, controls, media, and layout primitives.
app/components - Hooks · Browser-aware and interaction-focused reusable hooks.
app/hooks - Utilities · MDX, metadata, styling, timing, and Three.js helpers.
app/utils
Media
Local static assets consumed by pages and visual components.
- Assets · Local fonts, videos, HDRs, and 3D models used by the site.
app/assets - Public files · SEO, manifest, headers, and public static files.
public
Tooling
Storybook, build, deployment, and support scripts.
- Storybook · Parallel UI development and visual validation surface.
.storybook - Cloudflare · Functions entry points and Wrangler deployment config.
functions/[[path]].js
Connections 27
- 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.