Proof beats polish
A good final submission is not just a nice demo. It shows that your app works, and that your system design matches the code you shipped.
Judges and recruiters should be able to open your repo, read one design section, run or view the app, and understand your choices in five minutes.
Submission checklist
Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.
0 of 5 done
What to include
Your system design section should connect to real files in your repo. If you say you use Redis caching, show the cache code or explain that it is planned and not implemented.
For a hackathon project, simple is fine. A React client, Node API, PostgreSQL database, and a background queue is enough if you explain the boundaries clearly.
README structure
Use a structure like this in your README. Replace the sample text with your actual stack and decisions.
# Project name
## Demo
Live app: https://your-demo-link
Video: https://your-video-link
## What it does
Short description of the user problem and main flow.
## System design
Client: React app used by students to create and track requests.
Server: Express API handles auth, request creation, and status updates.
Database: PostgreSQL stores users, requests, and audit logs.
APIs: REST endpoints under /api for auth, requests, and admin actions.
Cache or queue: BullMQ queue sends slow email/WhatsApp notifications outside the request path.
Scaling: API can run behind a load balancer. Database remains the main bottleneck.
## Key APIs
POST /api/requests - create a request
GET /api/requests/:id - view request status
PATCH /api/requests/:id/status - update status
## Trade-offs
1. Chose PostgreSQL over MongoDB because request data is relational and needs clean status history. This is less flexible for changing fields quickly.
2. Used a queue for notifications so the API responds faster. This adds worker setup and retry handling.
## Run locally
npm install
cp .env.example .env
npm run devUse AI carefully
You can ask ChatGPT, Gemini, or Claude to review your README before submission. Paste your design section and ask: “What claims are not backed by the repo?”
Check every suggestion. Remove fake features, fake scale numbers, and tools you did not use. Your submission should be honest.
Avoid design theatre
Do not add Kafka, Kubernetes, microservices, or Redis just to sound serious. If your app does not need them, say what you would add later and why.
A defendable design is clear about limits. For example: “This version handles one API server. To scale, I would add a load balancer and move file uploads to object storage.”
Before you submit
Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.
0 of 5 done
Do this now
Do each one yourself, then tap it to tick it off. The ticks are only a checklist for you: they are not marked or scored.
0 of 5 done