All the reading

System Design

8 lessons, about 38 minutes. The check's questions come from these.

Sketch the whole system

1. Sketch the whole system

4 min

Key point

One page first

Start with the whole system before you discuss tables, endpoints, cache, or scale.

A good sketch shows what talks to what. It lets a reviewer see your app in 30 seconds.

What to sketch

Use boxes for parts and arrows for calls. Keep it boring and clear.

Most hackathon apps need these boxes: user, client app, backend server, database, file storage, and any external service like UPI, WhatsApp, Maps, or an AI API.

Your to-do

Build the first diagram

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.

Write the main user action in one sentence.
List the screens or clients the user touches.
List the servers and services that do work.
Draw arrows for request flow and data flow.
Mark where data is stored permanently.

0 of 5 done

Example

Example repo note

Put this in a file named SYSTEM_DESIGN.md. You can draw the diagram later, but write the parts today.

This example is for a canteen pre-order app on a college campus.

# System design

## User action
A student orders food before lunch break and picks it up at the canteen.

## Parts
- Client: React web app used by students and canteen staff
- Server: Node.js Express API for login, menu, orders, and order status
- Database: PostgreSQL for users, menu items, orders, and payments
- External service: UPI payment link or payment gateway for collecting money
- Notification: Email or WhatsApp provider for order-ready alerts

## First request flow
1. Student opens the React app.
2. React calls the Express API to fetch today’s menu.
3. Student places an order.
4. Express saves the order in PostgreSQL.
5. Express creates a payment request using the payment service.
6. Staff dashboard reads pending orders from the API.
7. Staff marks an order ready.
8. Server sends a notification to the student.

## Open choices
- We still need to decide if payments are confirmed by webhook or manual status.
- We still need to decide if notifications are sent directly or through a queue.

8. Submit your system design project

5 min

Key point

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.

Your to-do

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.

Share a public GitHub repository with a clear README.
Add a live demo link or a short screen recording if deployment is not stable.
Include a system design section with client, server, database, APIs, cache or queue, and scaling notes.
List at least two trade-offs you made, not just the final choices.
Add setup steps so another builder can run the project locally.

0 of 5 done

What to include

Design APIs and choose storage

2. Design APIs between parts

5 min

Key point

Contract first

An API is a contract between two parts of your system. Write the contract before you code the route.

For a hackathon project, a good API contract says who calls it, what data goes in, what comes back, and what can fail.

Where APIs sit

In your system sketch, draw arrows between client, server, database, payment service, auth service, and any worker. Each arrow that crosses a boundary usually needs an API or a message format.

Do not list every internal function. Focus on the calls another part depends on. Your React app calling your Express server is an API. Your server calling Razorpay or a college ERP endpoint is also an API.

Your to-do

Define each endpoint

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.

Cache and balance traffic

4. Add cache and load balancing

5 min

Key point

Remember this

Cache reduces repeated work. Load balancing spreads live traffic across server copies.

Use them only where your design has a reason. In your submission, say what becomes faster, what can go stale, and what happens when one server fails.

Where cache fits

A cache stores a recent answer close to your app. It is useful when many users ask for the same data, like college event listings, product catalogues, leaderboard pages, or user profiles.

Do not cache everything. Cache reads that are common, slow, and safe to be slightly old for a short time.

Your to-do

Pick cache data

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.

Handle slow work and scale

5. Use queues for slow work

5 min

Key point

Remember this

A queue lets your API accept work now and finish it later. The user gets a fast response, while a worker handles the slow or unreliable task in the background.

When to use it

Use a queue when work takes longer than a normal request should, or when an external service can fail. Common hackathon examples are sending OTP emails, generating PDFs, resizing images, calling an AI model, syncing UPI payment status, or sending WhatsApp alerts.

Do not put everything in a queue. Reading a profile, creating a simple record, or checking login should usually stay in the API request.

Your to-do

Basic flow

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.

10 questions, 7 to pass.

Tip

Use AI carefully

Ask ChatGPT, Gemini, or Claude to turn your idea into a system sketch. Then check every box yourself.

Remove parts you will not build. If your hackathon app has one Express server, do not claim microservices. Reviewers prefer honest scope.

Prompt:
I am building a hackathon app for [users] to [main action].
Give me a simple system design with client, server, database, external services, request flow, and open choices.
Keep it realistic for a 2-day college hackathon.

Example

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 dev

Example

API contract example

Here is a small contract for a mess meal booking app. Keep this in your README or docs/api.md so judges can see your design without reading all code.

Endpoint: POST /api/bookings
Caller: Mobile or web client
Owner: Backend API
Purpose: Book a meal slot for a student

Headers:
Authorization: Bearer <token>
Content-Type: application/json

Request body:
{
  "mealDate": "2026-02-10",
  "slot": "lunch",
  "messId": "mess_a"
}

Success: 201 Created
{
  "bookingId": "bk_123",
  "status": "confirmed",
  "mealDate": "2026-02-10",
  "slot": "lunch"
}

Errors:
400 Bad Request: missing mealDate or invalid slot
401 Unauthorized: missing or invalid token
409 Conflict: slot already booked

Tip

Use AI carefully

Ask an AI tool to draft API contracts from your feature list. Then check every endpoint yourself.

Check that paths are consistent, errors are realistic, private data is not returned, and the response has enough data for the UI. AI often invents fields that are not in your database.

Prompt:
I am building a hackathon app for college mess meal booking.
Features: login, view meal slots, book a slot, cancel a booking, admin sees daily count.
Draft REST API contracts with method, path, request body, success response, and common errors.
Keep it simple for a Node.js backend and React client.

3. Choose SQL or NoSQL

5 min

Key point

Pick for access

Choose the database that matches how your app reads and writes data. Do not choose only because a tool is popular in your college group.

If your data has strong relationships and you need reliable transactions, start with SQL. If your data shape changes often and reads are mostly by document, consider NoSQL.

When SQL fits

SQL databases like PostgreSQL and MySQL store data in tables. They are good when your app has clear entities and relationships: users, orders, payments, bookings, teams, submissions.

Use SQL when you need joins, constraints, and transactions. For example, a UPI split app should not mark a payment as settled unless the related payment record is also saved correctly.

When NoSQL fits

NoSQL databases like MongoDB and Firebase Firestore store flexible documents or collections. They are useful when each item may have different fields, or when you want to move fast with changing screens.

Use NoSQL when your main read is usually one document or one collection query. For example, a campus notice app can store notices with optional fields like clubName, eventDate, imageUrl, and tags.

Your to-do

Decision steps

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.

List your main screens and the data each screen needs.
Write your top 3 read queries and top 3 write actions.
Check if your data needs joins across many tables.
Check if one write must update multiple records safely.
Pick SQL if relationships and transactions are central; pick NoSQL if flexible documents and simple reads are central.

0 of 5 done

Common mistake

Avoid vague reasons

Do not write, “We used MongoDB because it is scalable.” That does not defend your design. Almost any database can scale enough for a hackathon if used well.

Write the reason from your app’s access pattern. Mention what you gain and what you give up.

Example

Design note example

Add a short note like this in your README or system design section. Keep it specific to your project.

Database choice

We use PostgreSQL for this food pre-order app.

Main data:
- users
- canteens
- menu_items
- orders
- order_items
- payments

Why SQL:
- Orders have clear relationships with users, menu items, and payments.
- We need transactions so an order and its order items are saved together.
- We need queries like: show all orders for one user, show pending orders for one canteen, and calculate daily sales.

Trade-off:
- Schema changes take more planning than MongoDB.
- In return, we get safer relationships and easier reporting queries.

Tip

Use AI carefully

You can ask an AI tool to compare SQL and NoSQL for your app. Give it your screens, data, and queries. Do not accept a generic answer.

Check if it mentions your actual read and write patterns. If it only says “NoSQL is scalable” or “SQL is structured,” ask it to rewrite using your project details.

Prompt:
I am building a hackathon app for college mess pre-ordering.
Screens: menu list, cart, order status, admin order dashboard.
Data: users, menu items, orders, order items, payments.
Main queries: show menu by canteen, create order with items, show pending orders for admin.
Should I use PostgreSQL or MongoDB? Give a short design note with 2 trade-offs.

Your to-do

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.

Open your project README or design doc.
Write your main data objects as a short list.
Write 3 reads and 3 writes your app must support.
Choose SQL or NoSQL using the decision steps above.
Add a database choice note with one reason and one trade-off.

0 of 5 done

Example

Express cache example

This simple in-memory cache is fine for learning and a demo. It will reset when the server restarts, and each server instance has its own cache.

For a real multi-server app, use a shared cache like Redis, then mention Redis in your design. If you ask AI to generate this code, check TTL, user data leakage, and error handling.

// server.js
import express from "express";

const app = express();
const cache = new Map();
const TTL_MS = 60 * 1000;

async function getEventsFromDb() {
  return [
    { id: 1, name: "HackIndia campus demo", city: "Bengaluru" },
    { id: 2, name: "AI build night", city: "Pune" }
  ];
}

app.get("/api/events", async (req, res) => {
  const key = "events:list";
  const cached = cache.get(key);

  if (cached && Date.now() < cached.expiresAt) {
    return res.json({ source: "cache", data: cached.data });
  }

  const data = await getEventsFromDb();
  cache.set(key, { data, expiresAt: Date.now() + TTL_MS });
  res.json({ source: "db", data });
});

app.listen(3000, () => console.log("API on port 3000"));

Example

Node queue example

This uses BullMQ with Redis. Redis is the broker here. Your API adds the job. A separate worker file processes it.

Install with npm install bullmq ioredis. Run Redis locally with Docker if you already use Docker.

// queue.js
const { Queue } = require('bullmq');

const connection = { host: '127.0.0.1', port: 6379 };

const emailQueue = new Queue('email', {
  connection,
  defaultJobOptions: {
    attempts: 3,
    backoff: { type: 'exponential', delay: 5000 },
    removeOnComplete: true,
    removeOnFail: false
  }
});

module.exports = { emailQueue };

// api.js
const express = require('express');
const { emailQueue } = require('./queue');
const app = express();
app.use(express.json());

app.post('/orders', async (req, res) => {
  const orderId = 'ord_' + Date.now();

  // Save order to DB here first
  await emailQueue.add('send-order-confirmation', {
    orderId,
    email: req.body.email
  });

  res.status(202).json({ orderId, status: 'queued' });
});

app.listen(3000);

// worker.js
const { Worker } = require('bullmq');

const connection = { host: '127.0.0.1', port: 6379 };

new Worker('email', async (job) => {
  console.log('Sending email for', job.data.orderId);
  // Call email provider here
  // Update order notification_status in DB
}, { connection });

6. Scale up or scale out

5 min

Key point

One idea

Scale up means use a bigger machine. Scale out means use more machines or more instances.

In your hackathon design, do not say “it scales” without naming the bottleneck. Say what gets bigger, what gets copied, and what can break.

When to scale up

Scale up first when one service is simple, traffic is low, and you want fewer moving parts. For a college hackathon demo, this is often enough for your backend or database.

Example: move from a small free database to a paid plan with more RAM, CPU, storage, or connections. The trade-off is cost and a hard limit. One large machine can still fail.

When to scale out

Scale out when many similar requests can be handled by copies of the same service. API servers are usually easier to scale out than databases.

Example: run two backend instances behind a load balancer. Each instance should be stateless. Store sessions, uploads, and jobs outside the server instance.

Common mistake

Do not scale out a stateful server that keeps login sessions or in-memory carts without a plan. Users may hit instance A once and instance B next time.

Fix it by storing session data in a shared store, using JWT carefully, or keeping state in the database or cache. Then any instance can answer the request.

Example

Show it in config

For a Node or Python API, your project can read a port from the environment. This lets you run multiple copies locally or deploy replicas on a platform.

This is not the full load balancer setup. It is proof that your app is ready to run as more than one instance.

PORT=3001 node server.js
PORT=3002 node server.js

# In your design notes:
# Client -> Load balancer -> API instance 1 / API instance 2
# API instances are stateless.
# Database stores users, orders, and submissions.
# Redis cache stores hot reads, not source-of-truth data.

Your to-do

Choose your path

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.

Find one bottleneck: API CPU, database reads, file uploads, image generation, or slow third-party calls.
Pick scale up if one bigger plan solves it with less complexity.
Pick scale out if the work is repeatable and safe across multiple instances.
Write the limit: cost, failover, data consistency, connection limits, or deployment complexity.
Draw only the scaled part. Keep the rest of the diagram simple.

0 of 5 done

Tip

Use AI carefully

Ask an AI tool to challenge your scaling choice. Give it your app flow and ask: “What breaks if I run 3 API instances?”

Check the answer for real issues: sessions, file storage, background jobs, database connections, cache invalidation, and duplicate queue processing. Do not copy vague lines like “use Kubernetes” unless you actually use it.

Your to-do

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.

Open your system design section for your HackIndia project.
Add one line naming your current bottleneck and expected busy action.
Choose scale up or scale out for that bottleneck.
Add 2 bullets: why this choice, and what trade-off it creates.
Update your diagram to show a bigger resource or multiple API instances.

0 of 5 done

7. Explain trade-offs clearly

4 min

Key point

One idea

A trade-off is not a weakness. It is a choice with a cost.

Good system design does not say “this is best”. It says “we chose this because it fits our users, deadline, and constraints”.

What to compare

For a hackathon project, compare choices that a reviewer can see in your app. Do not write theory that your code does not use.

Common trade-offs are SQL vs NoSQL, cache vs fresh data, queue vs direct processing, scale up vs scale out, and managed service vs self-hosted.

Your to-do

Use this frame

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.

Name the decision you made.
State the option you chose.
State the option you rejected.
Explain the upside of your choice.
Explain the cost or risk you accepted.

0 of 5 done

Tip

Use real constraints

Tie your explanation to your project. Mention things like team size, demo deadline, expected users, free tier limits, or Indian user behaviour such as mobile-first usage and patchy networks.

A clear small reason beats a vague big claim. “We cache college list data for 10 minutes because it rarely changes” is stronger than “cache improves performance”.

Common mistake

Avoid fake certainty

Do not write “MongoDB is faster than PostgreSQL” or “queues are always better”. These are not useful without context.

Also avoid hiding downsides. If you used a simple design because the hackathon was 36 hours, say it. That sounds honest and practical.

Example

README trade-offs

Add a short section like this to your repository README. Keep it close to your architecture diagram and API list.

This example is for a campus event app that sends registration emails after a user signs up.

## Trade-offs

### 1. PostgreSQL instead of MongoDB
We chose PostgreSQL because our main data is relational: users, events, registrations, and colleges.
It lets us use joins and unique constraints to stop duplicate registrations.

Trade-off accepted: changing the schema takes more planning than a document database.
For a hackathon app, this is okay because our data model is small and stable.

### 2. Queue for email sending instead of sending inside the signup API
We push email jobs to a queue after saving the registration.
This keeps the signup API fast even if the email provider is slow.

Trade-off accepted: the email may arrive a few seconds later.
We also need a worker process, so deployment has one extra moving part.

What reviewers notice

Reviewers are not looking for one perfect answer. They want to see that you understand consequences.

If your app works and your README explains two real choices with costs, your system design proof becomes much stronger.

Your to-do

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.

Open your project README or create one.
Pick two design decisions from your app.
For each one, write the option chosen and the option rejected.
Add one upside and one accepted downside for each choice.
Commit the README change to your public repository.

0 of 5 done

System Design

1. Sketch the whole system

One page first

What to sketch

Build the first diagram

Example repo note

8. Submit your system design project

Proof beats polish

Submission checklist

What to include

2. Design APIs between parts

Contract first

Where APIs sit

Define each endpoint

4. Add cache and load balancing

Remember this

Where cache fits

Pick cache data

5. Use queues for slow work

Remember this

When to use it

Basic flow

Use AI carefully

Do not start tiny

Do this now

README structure

Use AI carefully

Avoid design theatre

Before you submit

Do this now

API contract example

Use AI carefully

Common API mistakes

Show trade-offs early

Do this now

3. Choose SQL or NoSQL

Pick for access

When SQL fits

When NoSQL fits

Decision steps

Avoid vague reasons

Design note example

Use AI carefully

Do this now

Common cache mistake

Where load balancing fits

Express cache example

Write the diagram note

Do this now

Node queue example

Avoid this mistake

Keep jobs small

What to document

Do this now

6. Scale up or scale out

One idea

When to scale up

When to scale out

Common mistake

Show it in config

Choose your path

Use AI carefully

Do this now

7. Explain trade-offs clearly

One idea

What to compare

Use this frame

Use real constraints

Avoid fake certainty

README trade-offs

What reviewers notice

Do this now