A portfolio is a small application, but it still benefits from deliberate architecture.
My previous version used a headless CMS. It worked, but the operational cost was out of proportion to the problem. Every page load depended on a content model that lived outside the repository. Local development required another service. Content changes were harder to review alongside code, and the deployment pipeline carried complexity that produced little value for a site maintained by one person.
The rebuild started with a simple question: what does this website actually need?
The answer was not a database. It needed structured content, predictable builds, good performance, and a writing workflow I would continue using. That led me to Next.js, TypeScript, Tailwind CSS, and MDX.
Architecture should match the rate of change
The content on this site changes regularly, but it is not transactional. Blog posts, projects, and product pages do not need real-time database writes or complex editorial permissions. They need a clear schema, source control, and reliable rendering.
MDX provides that balance. Each entry is a plain file with structured frontmatter and a Markdown body:
This keeps content portable and reviewable. A title change appears in a diff. A deleted paragraph can be restored from Git. A content update travels through the same tested deployment process as the application.
Reading content at build time
The application reads MDX files from the repository, extracts their frontmatter, and converts them into typed records:
There is no content API in the request path. Pages can be generated from local source files, and invalid metadata can be caught before deployment rather than discovered by a visitor.
Why Next.js fits the delivery model
The App Router provides the pieces the site needs without forcing everything into one rendering strategy:
- Server components keep content loading on the server
- Static generation makes article and project pages fast to deliver
- Route-level metadata supports search and social previews
- Image optimization creates appropriately sized assets for each viewport
- Client components are limited to interactions such as filters, themes, and forms
That separation matters. A portfolio should not ship a large client-side application simply because a few sections are interactive.
Adding an editor without giving up file ownership
Plain files are excellent for developers, but a visual editor is useful for longer writing sessions. Keystatic adds that editor while preserving the repository as the source of truth.
The important architectural point is that the editor does not introduce a second content system. It reads and writes the same MDX files used by the application. Local editing remains simple, Git history remains complete, and the deployed site does not need a database connection.
What I would repeat
Three decisions have held up well:
- Keep content close to the code. The content model and the components that render it evolve together.
- Use client-side JavaScript selectively. Search and filtering need it; article rendering does not.
- Treat content validation as a build concern. A failed build is preferable to publishing a page with missing metadata or a broken route.
The broader lesson is not that every site should use MDX. It is that technical sophistication should be measured by fit, not by the number of services in the diagram.
For this portfolio, a file-based architecture is easier to understand, easier to operate, and more resilient. That is the kind of simplicity I value in larger systems as well.
