14 Years of Student-Built Software
This was the alternative.
v1 - 2012
The official timetable was unusable. Beng built a jQuery replacement in a dorm room.
Beng
v2 - 2014
Rebuilt with Backbone + Marionette. Added module reviews, CORS bidding data, venue finder. A real product now.
Beng
Yang Shun
v3 - 2016
A complete rewrite in React + Redux. Mobile-first. Offline-capable. The version that's still running today.
Yang Shun
Li Kai
The People
Chronological · avatar size ∝ code impact
Beng
Yang Shun
Ashray
Xinan
Zhi An
Li Kai
Yi Jiang
E-Liang
Chris Goh
Zhao Wei
Jon Loh
Ravern
Kok Rui
Leslie Yip
Architecture
React + Redux SPA
Class components, CSS Modules, Webpack bundle. All timetable logic runs client-side.
Export Service (Koa)
Timetable image/PDF exports via Puppeteer. Elasticsearch for search.
Static Data via Reverse Proxy
Module JSON as flat files. Served through a reverse proxy, cached by Cloudflare.
The heavy lifting is client-side. The backend is thin and focused on data.
The Data Pipeline
Evolution
Architecture
No database. JSON files served via reverse proxy + Cloudflare.
Streaming with oboe.js to handle large timetable datasets without blowing memory.
Yi Jiang
E-Liang
What is React?
A JavaScript library for building UIs out of components. Instead of manipulating the DOM directly, you describe what the UI should look like, and React figures out how to update it.
class Timetable extends React.Component {
state = { semester: 1 };
render() {
return <div>Sem {this.state.semester}</div>;
}
}
In 2016 this was the only way to write React. Classes hold state, lifecycle methods control when things happen.
Function Components
The modern way to write React. Instead of classes, you write plain functions.
Hooks like useState and useEffect replace state and lifecycle methods.
Class component (2016)
class Counter extends React.Component {
state = { count: 0 };
render() {
return (
<button onClick={() =>
this.setState({ count:
this.state.count + 1 })}>
{this.state.count}
</button>);
}
}
Function component (today)
function Counter() {
const [count, setCount]
= useState(0);
return (
<button onClick={() =>
setCount(count + 1)}>
{count}
</button>);
}
Same result, less boilerplate. NUSMods was written with classes but the patterns still apply.
What is Redux?
A predictable state container. All app state lives in one store. Components dispatch actions, pure reducers compute the next state, and the UI re-renders.
Click a module to dispatch an action and watch it flow through. One-way data flow - easy to debug, test, and persist.
Redux Superpowers
Because all state is serializable and centralized, NUSMods gets powerful features almost for free.
Persistence
Every reducer wrapped with persistReducer - timetable survives reloads.
Undo
Custom undoHistory reducer watches REMOVE_MODULE / SET_TIMETABLE. Ctrl+Z restores module + colors.
URL Sharing
Same serializable state powers UI, localStorage, and URL query strings.
Year Migration
Custom stateReconciler auto-archives old timetables when the academic year changes.
const undoConfig = {
limit: 1,
actionsToWatch: [REMOVE_MODULE, SET_TIMETABLE],
};
export default combineReducers({
timetables: persistReducer(config,
undoHistory(undoConfig, timetableReducer)),
});
The Codebase is Approachable
Because the architecture is simple, you can contribute without understanding everything. Pick an issue. Ship a feature.
Degree Planner
The architecture scaled to a second major feature without a rewrite.
Drag-and-drop
Multi-year planning with react-beautiful-dnd
Persisted State
Own reducer with state migrations
Import / Export
Custom modules support
Prerequisite Checking
Validates module dependencies
Li Kai
Yi Jiang
E-Liang
Leslie Yip
Jonathan Loh
NUSMods is yours now.
Every version was someone's first big project. This one could be yours.