How this website was built: The Bulletproof Architecture
Building a personal website is often seen as a simple task, but for me, it was an opportunity to implement the engineering standards I value most. For this project, I adopted the Bulletproof React architecture—a comprehensive guide to building scalable and maintainable React applications.
In this post, I'll explain how I applied these principles to create a foundation that isn't just a digital card, but a professional-grade codebase.
The Core Philosophy: Feature-Based Organization
The most significant shift in a Bulletproof architecture is moving away from grouping files by technical type (e.g., components/, hooks/) and instead grouping them by feature.
Why Feature-Based?
In a standard React project, files related to a single piece of functionality are often scattered. If you want to change how the "Resume" works, you might have to touch:
src/components/Resume.tsxsrc/hooks/useResumeData.tssrc/types/resume.ts
As the project grows, these folders become unmanageable. Bulletproof solves this by centralizing everything related to a feature in one place.
In this project, my src/features/resume folder contains:
- components/: UI specific to the resume (e.g.,
resume-timeline.tsx). - types.ts: Domain-specific TypeScript interfaces.
- resume-data.ts: The data source for the resume.
This ensures high cohesion and loose coupling. The Resume feature is a self-contained module that doesn't leak its complexity into the rest of the app.
The Tech Stack: Intentional Choices
Bulletproof React emphasizes choosing tools that solve real-world problems.
Next.js 16 & Server Components
I chose Next.js for its built-in performance optimizations. By using React Server Components, I've minimized the amount of JavaScript sent to the client. Most of this site is rendered on the server, resulting in a near-instant experience for the visitor.
OKLCH: Accessible, Perceptual Color
I've moved beyond HEX colors to OKLCH. This allows for a more consistent and accessible color palette. For example, my new blue theme remains legible across both light and dark modes because the colors are defined by their perceptual lightness, rather than arbitrary numbers.
Scaling with Precision
By following the Bulletproof patterns, I've created a site that is incredibly easy to extend. Adding a new section (like a portfolio of projects) is as simple as creating a new folder in features/ and following the established patterns.
In the next post, I'll dive into the specific CLI tools and development workflows that make managing this architecture seamless.