This post outlines the technical architecture and design decisions behind my personal portfolio website. The project started after I saw a Reddit comment suggesting, "For a startup, get a landing page with Magic UI."
While researching that for my own startup, I came across dillionverma/portfolio. I liked the clean, Apple-inspired design and precise UI interactions, so I decided to adapt it first as my personal site. Over time, it evolved into a technical playground to showcase my experiments, projects, and ideas.
1. Core Technology Stack & Configuration
The stack was chosen to balance performance, scalability, and long-term maintainability.
Framework: The portfolio is built with Next.js 14, using the new App Router for file-based routing and built-in server-side rendering capabilities. I configured next.config.mjs with output: 'export' to generate a fully static export, making it easy to host on GitHub Pages.
Language: TypeScript is used throughout, providing strict type safety and reducing runtime errors. The tsconfig.json enforces strict mode and defines path aliases (e.g., @/*) to simplify and clarify imports.
Styling: Tailwind CSS is the primary styling framework, with custom configurations defined in tailwind.config.ts. The setup integrates tailwindcss-animate for fine-tuned keyframe animations and supports both light and dark modes via a ThemeProvider.
UI Components: The UI layer combines shadcn/ui and Magic UI. Unlike external black-box libraries, these components live directly in src/components/ui/, making them fully customizable.
3D Graphics & Animations: Three.js, rendered via React Three Fiber, is used for interactive 3D visualizations. Helper components from @react-three/drei simplify common tasks such as camera controls and geometry setup. Framer Motion powers animations throughout the UI, from dock hover interactions to scroll-triggered reveals.
Deployment: Automated deployment is set up using GitHub Actions. Each push triggers a build (via pnpm), generates the static site, and deploys directly to GitHub Pages, providing a predictable and reproducible release process.
2. Component Architecture
The frontend is designed around modular, reusable components, with a strong emphasis on composability and clarity.
Navigation and Dock
Navbar & Dock (src/components/navbar.tsx, src/components/magicui/dock.tsx):
The main navigation includes a macOS-style dock that scales icons dynamically based on cursor proximity, implemented with framer-motion. The Navbar also includes a dark/light mode toggle and a button to activate an Aquarium overlay for additional visual detail.
Cards
ResumeCard & ProjectCard (src/components/resume-card.tsx, src/components/project-card.tsx):
Cards are used extensively across "Work," "Education," and "Projects" sections. These components can expand and collapse with animated transitions, and support dynamic content like tech stacks, video previews, and links.
Table of Contents
Table of Contents (src/components/table-of-contents.tsx):
A floating, scroll-synced navigation element uses IntersectionObserver to track which page section is currently in view. This improves user orientation and overall navigation on longer pages.
Interactive Visualizations
Rubik's Cube (src/components/rubiks-cube.tsx):
A fully animated 3D Rubik's Cube built with React Three Fiber. The solver class implements the CFOP method and executes each stage in real time using requestAnimationFrame for smooth, incremental rotations.
Maps (src/components/world-map.tsx, src/components/hong-kong-map.tsx):
The world map uses react-simple-maps and d3-geo to highlight visited countries. The Hong Kong map uses react-leaflet with categorized custom markers to show local points of interest.
GitHub Contributions (src/components/github-contributions.tsx):
Fetches contribution data from GitHub's GraphQL API and renders it as a heatmap, similar to the official GitHub profile view. Includes responsive layout and loading states for smooth performance.
Showcase Visualizations
Protein Folding (src/components/protein-folding.tsx):
Visualizes the folding of a polypeptide backbone using TubeGeometry, with color coding based on predicted confidence (inspired by pLDDT). Includes a 2D PAE plot rendered on <canvas>, providing additional structural uncertainty insight.
Torus-Mug Morph (src/components/torus-mug-morph.tsx):
A demonstration of topological equivalence between a torus and a coffee mug. Vertex positions and normals are interpolated using custom lerpArray and lerpColor utilities, allowing real-time shape morphing controlled by a slider.
UI Effects and Additional Features
BlurFade Components (src/components/magicui/blur-fade.tsx, src/components/magicui/blur-fade-text.tsx):
Implements staggered fade-in animations for text and UI elements as they scroll into view, using framer-motion hooks.
Aquarium Overlay (src/components/aquarium.tsx):
A toggleable, animated overlay with fish and shrimp that move dynamically across the screen. Motion is handled via requestAnimationFrame, with boundary collision logic to simulate natural movement.
Commonplace Book
The "Commonplace Book" section functions as a living record of books and essays that influence my thinking. Rather than simply listing titles, it serves as a curated, transparent window into what shapes my ideas and approaches.
3. Conclusion
This portfolio is designed as both a personal website and a technical sandbox by combining Next.js, TypeScript, Tailwind CSS, shadcn/ui, Magic UI, and advanced visualization libraries like React Three Fiber.