Why it exists
Lead with the problem, not the technology. What was annoying enough that you built something? This is the section people actually read, and it’s the one that makes a project sound worth looking at.
How it works
A short tour. Enough that a reader could sketch the architecture on a napkin, and no more. Link out to the repo for anyone who wants detail.
- The interesting decision, and what you traded away for it.
- The bit that turned out harder than expected.
- The bit you’d do differently.
What I’d change
Optional, but this is the section that makes a portfolio page read like a developer rather than a brochure. Being specific about a weakness is more convincing than any claim of strength.