A software engineer portfolio gets interviews when a reviewer can see, within a few minutes, what you built, why you built it that way, and that it actually works. In practice that means two to four focused projects, each with a short case study, a README that explains your decisions, and a live demo or video, plus a GitHub profile that points to all of it. Everything else is decoration.
This guide covers what to include and what to leave out, how to write each piece, and how to present mobile apps, which are harder to show than websites. There’s a checklist at the end. If you’re self-taught, your portfolio carries even more weight; see how to get hired as a developer without a CS degree for the rest of that picture.
What reviewers check first
Two kinds of people will look at your portfolio, and they look for different things.
- Recruiters and non-technical screeners read the project name, the one-line summary, and the tech stack, then click the live link. They’re matching you against the job description.
- Engineers and hiring managers open the repository. They read the README, skim the folder structure, open a few files, check for tests, and scan the commit history. They’re asking whether they’d be comfortable reviewing your pull requests every day.
Your portfolio has to work for both. A quick test: show one project to a non-developer friend for sixty seconds and ask what it does and who it’s for. Then ask a developer friend what they’d criticize in the code. Fix whatever trips up either of them.
Choosing projects: what to include
Pick projects for the signal they send to the role you want, not for how impressive the technology sounds.
| Project type | What it proves | Best for |
|---|---|---|
| A small product with real users, even a handful | You can ship, handle feedback, and keep something running | Any role, especially at startups |
| A tool that solves a real problem for you or someone you know | Product sense and practical judgment | Full-stack, internal tools, automation |
| Merged open source pull requests | You can work in an unfamiliar codebase and respond to review | Any role; especially backend and infrastructure |
| Freelance or client work you have permission to show | You deliver against someone else’s requirements and deadlines | Agencies, product companies, future clients |
| A focused technical build, such as a rate limiter, a job queue, or an offline sync layer | Depth on one hard problem | Backend, mobile, infrastructure |
| A published or beta mobile app | You can handle the full release process, not just the code | Mobile roles |
Two to four featured projects is enough. A reviewer who sees three strong projects assumes you have more. A reviewer who sees twelve average ones assumes you can’t tell which of your work is good.
Match the mix to the job. For frontend roles, at least one project should have a polished, accessible, responsive interface. For backend roles, show an API with authentication, validation, a sensible database schema, background jobs, and tests. For mobile roles, show an app that deals with what phones make hard: offline use, unreliable networks, permissions, and store releases.
What to leave out
- Unchanged tutorial projects. If thousands of people built the same to-do or weather app from the same course, it tells a reviewer nothing about you. Keep one only if you extended it substantially, and say exactly what you added.
- Unfinished repositories with a placeholder README and no way to run them.
- Forks with no commits of your own.
- Anything with secrets in its history. If an API key was ever committed, rotate it. Deleting the file doesn’t remove it from Git history.
- Projects you can’t explain. If large parts came from a tutorial or an AI assistant and you can’t defend the design in an interview, the project is a liability.
- Client work you don’t have permission to share. Describe it in a case study without code or screenshots instead.
Writing a project case study: problem, decisions, result
A case study is a short write-up, 300 to 600 words is plenty, that sits on your portfolio site or at the top of the README. Most portfolios skip it, and it’s the part that gives an interviewer something to ask you about.
Use this structure:
- One-line summary. What it is and who it’s for. For example: “A booking app for small barbershops that works on low-end Android phones.”
- The problem. Who had it, what they did before, and why that was painful. Two or three sentences.
- Constraints. Budget, time, devices, team size, data limits. Constraints explain your decisions.
- Your role. Solo, or exactly what you owned in a team. Be precise; interviewers will ask.
- Key decisions. Two or three choices, each with the options you considered and why you picked one.
- The hardest part. One technical problem, how you diagnosed it, and how you fixed it.
- Result. What’s true now: who uses it, what improved, what you measured. Real numbers only.
- What’s next. Known limitations and the improvements you’d make. This reads as maturity, not weakness.
The key decisions section is where most write-ups fall flat. Compare these two:
Weak: “Built with React Native and Firebase.”
Strong: “Chose Firestore over a self-hosted PostgreSQL server because the app needed offline support on cheap phones and there was no budget for running a server. The trade-off is that reporting queries are awkward, so a scheduled export copies bookings into a spreadsheet for the owner.”
The strong version shows you weighed options, understood a cost, and dealt with it. That’s what working engineers do every week, and it’s the conversation you want to have in an interview.
On results: don’t invent metrics. “Improved performance by 40%” with no baseline invites a question you can’t answer. Measure something real instead: a Lighthouse score before and after a change, API response times from a simple load test, weekly active users from your analytics, or the number of people actually using it. If you have no numbers, describe the observable change, such as “the owner stopped taking bookings through chat messages”.
A README template that does the work
For an engineer opening your repository, the README is the case study. Here’s a template you can copy and adapt:
# Project Name
One sentence: what it does and who it's for.
Live demo: https://... Video walkthrough (2 min): https://...
Demo account: demo@example.com / demo-password (read-only, resets nightly)
## Why it exists
The problem in two or three sentences.
## Features
- The 3-5 things a user can actually do
## Tech stack and why
- Frontend: ... (one-line reason)
- Backend: ... (one-line reason)
- Database: ... (one-line reason)
## Architecture
A short paragraph or a simple diagram: main components and how data flows.
## Running it locally
1. Prerequisites (language version, database)
2. Copy .env.example to .env and fill in the values
3. One command to install, one command to run
## Tests
How to run them and what they cover.
## Decisions and trade-offs
Two or three decisions, with the alternatives you rejected.
## Known limitations and next steps
What doesn't work yet and what you'd build next.
## License
A few details matter more than they look:
- Put the live link and a screenshot or GIF in the first screenful. Many reviewers never scroll.
- Commit an .env.example file that names every variable, with no real values.
- Keep setup to one or two commands. If the project needs a database, include a Docker Compose file.
- Write commits as if a teammate will read them: small changes, with messages that explain why, not “fix” and “update”.
Live demos that don’t break
A broken demo link is worse than no link, because it’s the first thing a recruiter clicks.
- Static frontends: GitHub Pages hosts static HTML, CSS, and JavaScript directly from a repository, which is enough for most frontend projects and for a portfolio site.
- Apps with a backend: many hosting providers have free or low-cost tiers, but free tiers often put idle apps to sleep, so the first request can be slow. Mention it in the README, or pay for a small instance for the project you feature most. Free-tier terms change often, so check the provider’s current limits.
- Give reviewers a way in. Nobody will create an account to look at your project. Add a demo account with realistic seeded data or a “try as guest” option, and reset the data on a schedule.
- Record a walkthrough. A two-to-three-minute screen recording covers the cases where the demo is down, the reviewer is on a phone, or the work is under NDA.
- Check every link before each round of applications. Domains expire, third-party APIs change, and demo databases fill up.
Showing mobile apps: store links, TestFlight, and Play testing
Mobile apps are harder to show than websites because a reviewer can’t just click and look. Use the strongest option you have:
- A published app. Link the App Store and Google Play listings. If it was a team app, state exactly what you built, for example “built the offline queue and the payment flow”.
- A public beta on iOS. Apple’s TestFlight lets you invite external testers through a public link, without collecting their email addresses. The first build must be approved by App Review for TestFlight before external testers can install it, so set this up well before you start applying.
- A testing track on Android. Google Play offers internal, closed, and open testing. Open tests can be joined by anyone; internal and closed tests use an opt-in link you share, and that link only becomes available once the app’s status shows as Published in Play Console.
- A video and screenshots. Include these even when you have store links. Many reviewers won’t install an app, and few will sideload an APK from a stranger.
In the case study, focus on what makes mobile work different: offline behavior, slow networks, background tasks, push notifications, permissions, device fragmentation, and release management, such as staged rollouts, crash monitoring, and handling a store review rejection. Those are the topics mobile interviewers tend to ask about, and they’re hard to fake.
GitHub profile hygiene
Your GitHub profile is often the second link a reviewer opens. Ten minutes of cleanup goes a long way.
- Add a profile README. GitHub displays a profile README when you create a public repository with the same name as your username and put a README.md in its root. Keep it short: who you are, what you build, and links to your two or three best projects.
- Pin your best work. You can pin up to six repositories or gists. Pin your portfolio projects, not your dotfiles or course exercises.
- Fill in each repository’s description and website field, so the pinned cards explain themselves.
- Archive or make private old tutorial repositories and experiments you don’t want judged.
- Add a license to projects you’re happy for others to reuse.
- Use the same name and photo on GitHub, LinkedIn, your resume, and your portfolio site, so reviewers know they’ve found the right person.
- Don’t game the contribution graph. Experienced reviewers know a solid green grid is easy to fake and that plenty of good engineers work mostly in private repositories. The substance of your pinned projects matters far more.
Do you need a portfolio website?
Not strictly. A tidy GitHub profile with strong READMEs is enough for many backend roles. A simple site helps when:
- You’re applying for frontend or design-heavy roles, where the site itself is a work sample.
- You want to present case studies with screenshots and video in a cleaner format than a README.
- You have client work or private code that you can only describe, not link.
Keep it to a short introduction, your featured projects with case studies, a link to your resume, and contact details. It should load quickly and work well on a phone. A fancy animated site with thin content does more harm than a plain one with strong case studies. If you want the site to build your reputation over time, writing about what you build is the natural next step; see building a personal brand as a software engineer.
Portfolio checklist
Run through this before you send your portfolio link anywhere:
- Two to four featured projects, each relevant to the role you’re applying for
- A one-line summary per project that a non-developer understands
- A case study per project covering problem, decisions, and result
- Every live demo works on desktop and on a phone
- A demo account or guest mode, so nobody has to sign up
- A short video walkthrough for each featured project
- READMEs with setup steps that work on a fresh machine
- No secrets in any repository’s history, and an .env.example instead
- Tests for the core logic of at least your main project
- A readable commit history with descriptive messages
- Mobile apps linked to a store listing, TestFlight, or a Play testing track, plus a video
- A GitHub profile README, pinned repositories, and filled-in descriptions
- The same name, photo, and links on your portfolio, GitHub, LinkedIn, and resume
- Every metric you mention is real, and you can explain how you measured it
- You could talk about any file in a featured project for five minutes
Where to start this week
Pick your single strongest project and bring it all the way up to this standard before touching the others: a working demo, a case study, a README based on the template above, and a walkthrough video. One project done properly is enough to start applying. Then put it near the top of your resume; our resume guide for remote software engineering jobs shows where it fits.