If you are reading this, you are probably already aware of LibrExam. LibrExam, as of now, has been my most monumental achievement in software development — and yet, it has been on a two-month-long development hiatus.
Apologies.
Nevertheless, my project uses a (clunky) decentralised content contribution system that I would like to talk about here. It’s highly likely someone has already built something similar to - but much better than - this, but I could not care less. I only believe in homegrown technology.
I have used GitHub to achieve this. This means that neither I nor the end-user has to shell out money or computing power for a server, though this also fundamentally makes the system centralised.

This image was actually created to reflect an unironic sentiment. I have repurposed it.
Let me elucidate how I did it. (Does this already sound like a LinkedIn post?)
Three kinds of JSON
Everything in this system is a JSON file sitting in a GitHub repo. No database, no backend, no server that I pay for. There are exactly three kinds of files.
1. The test itself. A test is split into subjects, subjects into sections, and sections into questions. Marking is defined per section - posM for a correct answer, negM for the penalty on a wrong one - which is how JEE-style papers work anyway. A (heavily trimmed) version of the sample test:
{
"title": "Sample Test",
"duration": 3600,
"author": "Sayak",
"subjects": [
{
"name": "Physics",
"sections": [
{
"name": "Section 1",
"posM": 4,
"negM": 1,
"questions": [
{
"type": "SMCQ",
"text": "What is the standard acceleration due to gravity on Earth?",
"options": ["...", "...", "...", "..."],
"answer": 0,
"solution": "Very obvious."
}
]
}
]
}
]
}
There are three question types: SMCQ (single correct), MMCQ (multiple correct, so answer becomes an array like [0, 2]) and NUM (numerical, where answer is just a number like 1.414). The duration is in seconds. Images are not embedded - image and simage (the solution’s image) are plain links to wherever the image happens to be hosted. I am aware this is cheating.
2. The repo’s index.json. Every test repo has one at its root. It lists the tests in that repo, along with just enough metadata for the browser to draw a card without downloading the entire test:
[
{
"name": "Sample Test",
"filename": "test1.json",
"author": "Sayak",
"duration": 3600,
"tags": ["physics", "mathematics", "maths", "jee"],
"description": "A sample Physics, Maths test",
"url": "https://raw.githubusercontent.com/librexam/testRepo/main/tests/test1.json"
}
]
3. The central indexedRepos.json. This one lives in my own repo, librexamtests, and is simply a list of every repo found so far - its name, when it was last pushed to, and its star count.
Here’s what happens
- The end-user creates an exam (which, obviously, follows a strict format). The file extension is
.json. - They then create a GitHub repository
OR
commit to an already existing repository. Each repository can host one or multiple tests. - Each repository has a root-level indexing JSON file that defines metadata for these exams. Updating this index is manual and is the responsibility of the repo contributors, for now — though I might help automate this in the future using a GitHub workflow.
- Each repository is tagged with the
librexam-testtopic. - I, on my behalf, have yet another central repository with a workflow that uses the GitHub API to find repos with this tag and index them. Since I am not using an API key here, I am rate-limited.
- My app, LibrExam, simply moves top-down beginning with my repo-that-has-indexed-repos.
- Voila.

An experience polished enough to attract 10 million dollars in VC funding.
What “top-down” actually means
Step 6 is doing a lot of heavy lifting, so here it is in slightly more detail. When you open the browser, LibrExam:
- Fetches
indexedRepos.jsonfrom my repo. - Fetches the
index.jsonof every single repo in that list, all at once. - Merges all of them into one list of test cards, which you can then search, sort and filter by tag.
- Only downloads the actual test when you click on one.
Every response also gets stashed in localStorage. If GitHub is down, or your Wi-Fi is having a moment, LibrExam quietly falls back to the last copy it saw. Stripped of all the logging, the core of it is this:
async function fetchIndex(url, cacheKey) {
try {
const res = await fetch(`${url}?t=${Date.now()}`);
if (!res.ok) throw new Error("Failed to load index");
const data = await res.json();
localStorage.setItem(cacheKey, JSON.stringify(data));
return data;
} catch (err) {
const cached = localStorage.getItem(cacheKey);
if (cached) return JSON.parse(cached);
throw err;
}
}
That ?t=${Date.now()} is important. It also brings me to the problems.
There are some problems with this approach
To begin with, I make a hard-write (by putting a timestamp) on my final indexed repo to avoid missing out on rapidly committed changes from the user-end repositories, regardless of whether there are any changes, thus bypassing cache issues.
The cache in question is GitHub’s own. Files on raw.githubusercontent.com are served with Cache-Control: max-age=300 - meaning the copy you receive can be up to five minutes old, no matter how recently it was pushed. The ?t= in the browser exists for the same reason: it makes every single request look like a brand new URL.
And with that, we come across the next problem. Updates happen only around once every 10 minutes, indiscriminately. There’s no synchronicity in this system. Somewhere, someday in the near future, someone might have to wait up to 10 minutes to try out the Star Wars Trivia 100-marker that their friend has made. Tragically, then, Buzzfeed might eat into LibrExam’s market share.
Then there is the rate limit. Without a token, the GitHub API hands you 60 requests an hour, and its search endpoint - the one that actually finds librexam-test repos - a measly 10 a minute, at 100 results a page. That is plenty for two repos. It is decidedly not plenty for two thousand.
Speaking of two thousand: step 2 of “top-down” means that every visitor’s browser fetches every repo’s index.json. With two repos, that is three requests. With five hundred, it is five hundred and one - per visitor, per visit. My serverless architecture would then very efficiently DDoS GitHub on my behalf.
And, my personal favourite: the browser builds the address of each index.json as raw.githubusercontent.com/<repo>/main/index.json. The branch name is hardcoded. If your repo’s default branch is still called master - which, until late 2020, was GitHub’s default for every new repo - LibrExam will simply never see your tests.
Finally, there is the concern of unmoderated content — a concern expressed by one of my patrons. Truthfully, I must say, I would be very happy if such a concern materialised, because only then could I truly say that my project has been a success.