Skip to main content

Designing a Developer Portfolio That Scales

· 4 min read
Carlos Carvajal Vázquez
Carlos Carvajal Vázquez
Full Stack | Senior Engineer

When building a developer portfolio, it’s tempting to think of it as a simple static website, a place to list projects, add a short bio, and include a contact section.

But over time I started thinking about my portfolio differently.

Instead of a static page, I wanted to design something closer to a small engineering platform: a site that could grow with new projects, deeper technical documentation, and ongoing writing about engineering.

That shift in perspective influenced how I structured the site and the tools I chose.

Thinking Beyond a Landing Page​

A portfolio should do more than just show what you’ve built. It should help visitors understand:

  • How you think about engineering problems
  • The systems you’ve designed
  • The technologies you work with
  • The impact of the projects you’ve contributed to

For that reason, I wanted the site to support multiple layers of depth.

The landing page provides a quick overview:

  • Experience
  • Areas of expertise
  • Selected projects
  • Education
  • Contact

But each project can expand into its own documentation page, where I can describe things like:

  • Architectural decisions
  • System design trade-offs
  • Technical challenges
  • Lessons learned during implementation

This approach allows the portfolio to stay clean and concise on the surface, while still offering deeper technical context for readers who want to explore further.

Structuring the Content​

To keep things organized and maintainable, I structured the site into three main areas:

Portfolio​

The homepage acts as a curated overview of my work and experience.

It’s designed to be easily scannable for recruiters, engineers, or anyone interested in quickly understanding my background.

Project Documentation​

Each significant project can have its own documentation page.

This makes it possible to describe not just what was built, but also how and why it was built that way.

For engineers reviewing the site, this often provides far more insight than a simple project description.

Engineering Notes (Blog)​

The blog section serves as an engineering notebook.

Here I plan to write about:

  • architectural ideas
  • lessons learned while building systems
  • interesting technical challenges
  • experiments and prototypes

Over time, this section will become a collection of thoughts and experiences from day-to-day engineering work.

Small Details That Improve the Experience​

Beyond structure, I also wanted the site to feel modern and enjoyable to explore.

Some of the small improvements I’ve been experimenting with include:

  • subtle scroll animations when sections enter the viewport
  • consistent visual hierarchy across sections
  • lightweight styling and glow effects for interactive elements
  • a layout that keeps the focus on content rather than decoration

These details might seem small individually, but together they make the experience smoother and more engaging.

Designing for Long-Term Growth​

Another goal for this site is long-term maintainability.

By separating content into documentation pages and blog posts, the portfolio becomes easier to extend over time. New projects can be added with their own documentation, and new ideas can be shared through blog entries without needing to redesign the entire site.

This approach turns the portfolio into something closer to a living engineering record rather than a static snapshot.

Future Improvements​

There are still several improvements I plan to add in future iterations of the site.

One of the most interesting next steps is implementing a lightweight monitoring and analytics system.

The idea is to gain better insight into things like:

  • how much traffic the site receives
  • which pages attract the most attention
  • how visitors navigate between sections
  • which technical articles resonate most with readers

This kind of data can help guide future improvements and content decisions.

From an engineering perspective, it’s also an opportunity to experiment with monitoring and observability patterns in a small, controlled environment.

Final Thoughts​

A developer portfolio doesn’t have to be just a resume on the web.

With the right structure, it can evolve into a place to document projects, share ideas, and explore engineering topics over time.

This site is my attempt at building exactly that, a portfolio that grows alongside the work and experiences behind it.

If you’re curious, feel free to explore the projects, read through the documentation, or check out the other posts in this blog.