Design Decisions

Overview

Every technical project involves trade-offs. Rather than selecting technologies simply because they are popular, this portfolio has been built around a series of deliberate engineering decisions.

The following sections describe some of the more significant choices made throughout the project, the alternatives that were considered and the reasoning behind the final implementation.

---

Why AWS?

A portfolio website can be deployed using platforms such as Vercel or Netlify with very little operational overhead. While those platforms are excellent for hosting modern web applications, they intentionally abstract away much of the infrastructure that I wanted to understand.

AWS was chosen because it allowed me to work directly with networking, DNS, IAM, container orchestration, infrastructure as code and deployment automation. The objective wasn't simply to host a website, but to gain practical experience building and operating the surrounding platform.

Alternatives considered

• Vercel
• Azure
• DigitalOcean

Trade-offs

Using AWS introduces significantly more complexity than a managed hosting platform, but it also provides hands-on experience with cloud services and operational practices commonly found in production environments.

---

Why ECS Fargate?

After deciding to use AWS, the next decision was how the application should be deployed.

I considered running the application on an EC2 instance, using AWS App Runner or deploying to ECS Fargate. ECS ultimately provided the best balance between learning modern container deployment practices while avoiding the operational overhead of maintaining virtual machines.

Alternatives considered

• EC2
• AWS App Runner
• Vercel

Trade-offs

ECS requires more supporting infrastructure than a managed hosting platform, but it also exposes concepts such as container orchestration, load balancing, IAM integration and rolling deployments that would otherwise remain hidden.

---

Why Terraform?

One of the goals of this project was to treat infrastructure with the same discipline as application code.

Managing AWS resources through Terraform means networking, IAM roles, ECS services and supporting infrastructure all exist as version-controlled configuration. Changes become reviewable, environments are reproducible and the entire platform can be recreated when required.

Alternatives considered

• Manual AWS Console configuration
• AWS CloudFormation
• AWS CDK

Trade-offs

Infrastructure as code introduces additional tooling and a steeper learning curve during development, but it creates a much stronger foundation for maintaining and evolving the platform over time.

---

Why Separate CI and Deployment?

The deployment pipeline originally evolved as a single GitHub Actions workflow. As the project grew, validation and deployment began serving different responsibilities.

Separating Continuous Integration from deployment resulted in smaller workflows that are easier to understand, maintain and troubleshoot. The CI workflow now focuses solely on validating changes, while the deployment workflow is responsible for publishing container images and updating the running infrastructure.

Alternatives considered

• A single GitHub Actions workflow

Trade-offs

Maintaining two workflows introduces a small amount of duplication, but results in clearer responsibilities and makes future expansion of both pipelines considerably simpler.

---

Why Portable Markdown?

The original documentation system used MDX components to build interactive documentation pages.

As the documentation expanded, I found that embedding React components directly into the documents tightly coupled the content to the application itself. The documentation could no longer be viewed naturally on GitHub or in standard Markdown editors.

The documentation was eventually refactored to use standard Markdown, allowing the portfolio to progressively enhance the content with navigation, Mermaid diagrams, syntax highlighting and custom styling while keeping the underlying documents portable.

Alternatives considered

• MDX component composition
• Nextra
• Docusaurus

Trade-offs

Standard Markdown is intentionally less expressive than MDX. The application now performs more work when rendering the documentation, but the content remains portable, easier to maintain and usable outside of the portfolio itself.

---

Why Build Incrementally?

It would have been possible to build the intended end-state architecture from the outset.

Instead, I chose to introduce infrastructure and application features as they became necessary. This keeps the project approachable while ensuring every addition solves a real problem rather than existing simply because it is considered best practice.

Many aspects of the platform, including private application networking, backend services and monitoring, have been planned from the beginning but are only introduced when they provide genuine value to the project.

Trade-offs

Some parts of the platform are intentionally incomplete today. However, each stage reflects the current needs of the project while leaving a clear path for future expansion without requiring significant architectural changes.