How to Write a Cloud Portfolio Case Study

Why the write-up matters as much as the build

Most hiring managers reviewing cloud portfolios spend 2–3 minutes per project. They will not run your Terraform. They will not deploy your Lambda function. They will read your README and skim your code structure.

In those 2–3 minutes they are trying to answer:

• Does this person understand what they built?
• Did they make deliberate decisions or follow a tutorial?
• Can they explain technical choices clearly?
• Would I trust this person to explain architecture decisions to the rest of the team?

Your README is your answer to all four questions. Code alone does not answer them.

The README as a case study

Your project README is the case study. Write it with the same intention you would bring to a professional write-up — clearly, specifically, and without jargon that obscures rather than explains.

Before and after: what a weak README looks like vs a strong one

Weak README (what most beginners write):

This project deploys a serverless API using AWS Lambda and DynamoDB. It uses Terraform to provision the infrastructure. The API allows you to create and retrieve URL mappings.

This tells the hiring manager nothing useful. It describes what the project is, not why any decision was made.

Strong README (what gets you noticed):

A URL shortener API built with AWS Lambda and DynamoDB, provisioned entirely with Terraform.

Why DynamoDB: The access pattern is a simple key-value lookup (short code → original URL) with no joins and no complex queries. DynamoDB’s single-digit millisecond latency at any scale and its built-in TTL feature (used here for link expiry) made it the right choice over RDS, which would have added unnecessary relational complexity and connection management overhead.

IAM design: The Lambda execution role is scoped to dynamodb:GetItem and dynamodb:PutItem on the specific table ARN — not dynamodb:* on all tables. A CloudWatch logging policy is attached separately. The IAM policies are defined using aws_iam_policy_document data sources in Terraform rather than inline JSON.

What I would add in production: API Gateway throttling limits, DynamoDB auto-scaling, a WAF rule to block malformed requests, CloudWatch alarms on error rates and latency, and caching popular short codes at the Lambda layer to reduce DynamoDB reads.

The second version demonstrates thinking. The first demonstrates typing.

Which decisions are worth documenting

Not every line of code needs an explanation. Focus on decisions that had real alternatives — places where you could have done something differently and made a conscious choice.

Good decisions to document:

• Service selection: Why Lambda rather than EC2? Why DynamoDB rather than RDS? Why GitHub Actions rather than Jenkins?
• IAM design: What permissions does the compute layer have? Why that scope? What would a broader permission have allowed and why did you restrict it?
• Network design: Why public versus private subnets? What traffic is allowed between which components?
• Storage decisions: How is data encrypted? What is the retention policy? Why that bucket policy?
• Failure handling: What happens when the database is unavailable? What is the retry strategy? What data could be lost?
• Deployment strategy: Why this deployment approach? What is the rollback mechanism?

You do not need to document all of these for every project. Pick the two or three decisions that were most interesting or most deliberate and explain them well.

Architecture diagrams

A good architecture diagram adds real value to a README. It does not need to be professional-quality design — a clear diagram drawn with any tool is better than no diagram.

Tools for making diagrams:

• draw.io (diagrams.net) — free, browser-based, exports to PNG or SVG, good for cloud architecture with AWS and GCP icon packs
• Excalidraw — free, hand-drawn aesthetic, good for quick architecture sketches
• Mermaid — diagram-as-code in Markdown, rendered natively in GitHub READMEs
• Lucidchart — polished but has a free tier limit

A Mermaid diagram embedded in your README is particularly convenient because it renders directly on GitHub without exporting an image file. A simple flow diagram showing the components and their connections takes 10–15 minutes to write.

Include the diagram source file in the repository (.drawio file or the Mermaid code block) so anyone can modify it if they fork your project.

Documenting the production gap

Every portfolio project has gaps — things you would add in a real production system that are impractical for a portfolio. Documenting these gaps explicitly is a positive signal, not a negative one. It shows you understand the difference between a portfolio project and production-grade infrastructure.

Examples of what to include in this section:

• “In production I would add API Gateway throttling and WAF rules — omitted here to keep the Terraform focused on the core architecture"
• "The database uses a single Availability Zone — production would use Multi-AZ for failover at increased cost"
• "Secret rotation is not implemented — production would use Secrets Manager with an automated rotation Lambda"
• "State is stored locally — a team environment would use remote state in S3 with DynamoDB locking”

This section also gives you material for the “what would you change?” interview question, which you will almost certainly be asked.

Adapting the case study for your CV

The README is too long for a CV. For your CV’s projects section, distill each project to three to five bullet points:

• One sentence describing the project — what it is and what it does
• The key technologies — Terraform, AWS Lambda, DynamoDB, GitHub Actions
• One specific decision or outcome — “scoped Lambda execution role to specific DynamoDB table ARN using least-privilege IAM policy”
• A link to the repository — directly to the project, not to your GitHub homepage

The specific decision bullet is the most important. “Built a serverless API” is generic. “Designed IAM execution roles with least-privilege permissions and documented the scoping decisions in the README” is specific and shows engineering thinking.

Preparing your case study for the interview room

Your README is also your interview preparation. For each project, prepare verbal answers to:

• “Tell me about this project.” — Describe it in 90 seconds: what it does, the key design decisions, and what you learned.
• ”Why did you choose [service X]?” — Reference the decision section of your README. Have a clear one-sentence answer and a one-sentence explanation of the alternative you considered.
• ”What would you do differently in production?” — Reference the production gap section. These are already written down — you just need to be able to say them clearly.
• ”What was the hardest part?” — A genuine answer to this question builds trust. “Setting up OIDC federation between GitHub Actions and AWS took longer than expected because…” is far more compelling than “it all went smoothly.”

Practice saying these out loud before the interview. Reading from the README in your head and saying the answers to a real person in real time feel very different until you have done it a few times.