Your GitHub repo is your project’s first impression. Judges, recruiters, and collaborators will look at it — and they’ll form an opinion within 10 seconds. A messy repo with an empty README screams “we ran out of time.” A clean repo with screenshots, a live demo link, and clear setup instructions says “we’re professionals.” This section covers how to make your repo work as hard as your code does.
You don’t need a complex branching strategy for a 24-hour project. But you do need some structure, or you’ll end up with merge conflicts at 4 AM that nobody can fix.
main ← always working, always deployable
├── feat/auth ← feature branches for major pieces
├── feat/ui
└── fix/api
Merge back to main whenever:
Don’t merge when:
Keep it simple and consistent:
feat: add user authentication with JWT
fix: resolve login redirect loop
ui: polish landing page responsive design
docs: add setup instructions to README
refactor: simplify API route structure
chore: update dependencies
The prefix tells your teammates what kind of change it is at a glance. At a hackathon, this is more useful than detailed descriptions because people are scanning, not reading.
The golden rule: Commit often. Small, frequent commits are infinitely better than one massive commit at the end. If something breaks, you can roll back to the last working state instead of losing everything.
.env files, API keys, or secrets. Use .env.example with placeholders.node_modules/, __pycache__/, or build artifacts. Use .gitignore from the start.A winning hackathon README isn’t a novel — it’s a sales page. Here’s what each section should contain, annotated with exactly what judges and recruiters are looking for.
# 🧠 MindMap AI
**Turn your messy notes into visual mind maps using AI**
What this does: Immediately tells the reader what the project is. No jargon, no buzzwords. The subtitle explains the value in plain English.
🔗 **[Live Demo](https://mindmap-ai.vercel.app)** | 🎥 **[Video Demo](https://youtube.com/...)**
What this does: Judges want to see it working in under 5 seconds. Put the live link at the very top. The screenshot should show the most impressive screen — not the landing page, not the login screen. Show the thing that makes your project special.
## The Problem
Students and professionals take hundreds of notes but never organize them.
Existing mind map tools require manual input, defeating the purpose of quick note-taking.
What this does: Frames the project in terms of real human need. Judges score “problem relevance” separately from “technical execution.” Don’t skip this.
## What We Built
MindMap AI is a web app that:
- 📸 Accepts photo uploads of handwritten or typed notes
- 🤖 Uses GPT-4 to extract key concepts and relationships
- 🗺️ Generates interactive mind maps automatically
- 📤 Exports to PDF, PNG, or Markdown
What this does: Bullet points are scannable. Judges review 20–40 projects. They’re not reading paragraphs. Each bullet should describe a feature that’s visible in the demo.
## Tech Stack
- **Frontend:** React, Tailwind CSS, D3.js (for mind map visualization)
- **Backend:** Node.js, Express
- **AI:** OpenAI GPT-4 API
- **Database:** PostgreSQL (via Supabase)
- **Deployment:** Vercel, Railway
What this does: Shows technical breadth without overwhelming. If you used a sponsor’s API, mention it here — sponsors notice.
## Architecture
What this does: A simple diagram (even hand-drawn and photographed) shows that you understand how your pieces fit together. Use Mermaid, Excalidraw, or draw.io. It doesn’t need to be fancy — it needs to exist.
## Getting Started
```bash
git clone https://github.com/yourteam/mindmap-ai.git
cd mindmap-ai
cp .env.example .env # Add your API keys
npm install
npm run dev
What this does: If a judge or recruiter wants to run your project locally, they should be able to in under 2 minutes. Three commands max. If your setup requires more than that, you’ve overcomplicated it.
## Screenshots
| Upload Notes | AI Processing | Generated Mind Map |
|---|---|---|
|  |  |  |
What this does: Visual proof that the project works. GIFs of the core interaction are worth more than any description. Use tools like Loom, OBS, or Kap to record short clips.
## What's Next
- [ ] Mobile app with camera capture
- [ ] Collaborative mind maps (real-time editing)
- [ ] Integration with Notion and Obsidian
What this does: Shows judges that you’ve thought beyond the hackathon. This signals product thinking, not just coding ability.
## Team
- **Alice Chen** — Backend & AI integration ([@alice](https://github.com/alice))
- **Bob Kumar** — Frontend & UI/UX ([@bob](https://github.com/bob))
- **Carol Smith** — Pitch & presentation ([@carol](https://github.com/carol))
What this does: Gives credit and shows who did what. Recruiters browsing repos will check individual contributions.
## License
MIT License — see [LICENSE](./LICENSE) for details.
What this does: Signals that this is a real project, not a throwaway hack.
| License | When to Use | Key Feature |
|---|---|---|
| MIT | Default for hackathons. Simple, permissive, everyone can use it. | Maximum freedom — anyone can use, modify, and distribute |
| Apache 2.0 | Projects that might have patent implications or you want patent protection. | Includes explicit patent grant — good for AI/ML projects with potential IP |
| GPL v3 | You want derivatives to also be open source. | Copyleft — if someone uses your code, their project must also be GPL |
| BSD 2-Clause | Similar to MIT but slightly different language. | Minimal restrictions, very permissive |
| Creative Commons | For non-code assets (designs, documentation, datasets). | Not for software — for creative works |
| No License | Technically means “all rights reserved.” Don’t do this. | Your code can’t be legally used by anyone |
The hackathon default: MIT. It’s what judges expect, it’s what recruiters recognize, and it doesn’t create legal complications. If you’re building something with AI models or patents, consider Apache 2.0. Don’t overthink this — just pick one and include a LICENSE file.
GitHub Actions can automate your deployment so that every push to main automatically deploys your project. This is easier than it sounds.
Create .github/workflows/deploy.yml:
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm test
- run: npm run build
- uses: amondnet/vercel-action@v25
with:
vercel-token: $
vercel-org-id: $
vercel-project-id: $
What this does: Every time you push to main, GitHub automatically runs your tests, builds your project, and deploys it to Vercel. No manual deploy commands. No “oh wait, I forgot to deploy.”
Add a deploy badge to your README:
[](https://vercel.com/new/clone?repository-url=https://github.com/yourteam/mindmap-ai)
This lets anyone deploy a copy of your project with one click. Judges love this because it means your project is reproducible.
The biggest shift in thinking: your repo is not a code dump — it’s a product landing page.
Think about what a product landing page does:
Your repo should do the same:
Value proposition → The README title and subtitle Product in action → Screenshots, GIFs, and video demo Easy to get started → Setup instructions Trust signals → Architecture diagram, tech stack, contribution guidelines
When you view your repo this way, you stop thinking about it as “where I store my code” and start thinking about it as “the first thing a judge sees.” That shift changes everything about how you organize and present it.
You don’t need Jira. You don’t even need a complex system. But you do need something more structured than “I’ll remember what I was working on.”
Use GitHub Issues with labels:
| Label | Color | Meaning |
|---|---|---|
urgent |
Red | Must be done before demo |
backend |
Blue | Backend work |
frontend |
Green | Frontend work |
design |
Purple | UI/UX work |
pitch |
Yellow | Presentation work |
blocked |
Orange | Can’t proceed without something |
blocked label and describe what you needThe rule: If it’s not an issue, it doesn’t exist. Verbal agreements disappear. Written issues persist.
Judges don’t have time to read every line of code. Here’s what they actually do:
.gitignore that works.The 10-second test: Open your repo in an incognito window. Can you figure out what the project does, see it working, and understand the tech stack within 10 seconds? If not, your README needs work.
Your GitHub profile is your technical resume. Recruiters check it. Judges check it. Here’s how to make it work for you.
GitHub lets you create a special repository with the same name as your username. The README in that repo appears on your profile page. Use it.
What to include:
The green squares on your profile matter more than you think. Consistent contributions signal that you code regularly — not just during hackathons. If your contribution graph is empty except for one week in March (when a hackathon happened), it looks like you only code under pressure.
The fix: Even 15 minutes of daily coding will keep your graph active. Side projects, open source contributions, or even just committing small improvements to existing projects.
Pin your best 6 repositories. For hackathon participants, this should include:
Include shields.io badges in your profile README to show your tech stack visually. They’re free, they look professional, and they help recruiters quickly identify your skills.
.env.example.The repo itself should help a judge understand the project faster. Think of it as a self-service demo — someone should be able to read the README, click the live link, and understand everything without talking to you. That’s the mark of a well-organized hackathon project.