NUSMods v4 #4314
Description
This is an umbrella issue for the next generation of NUSMods — NUSMods v4.
I'm inspired to start this due to advancements in AI such that we can use vibe coding agentic engineering to upgrade the current iteration of NUSMods, which is almost ten years old as of this year.
Conventional wisdom tells you software rewrites never succeed. There are good reasons to that but with AI, things have changed and it's a good time to challenge that advice and test the limits of what technology in this age.
Goals
- Modernize tech stack
- Improve code base structure with better modularization
- Pay off tech debt
- Improve UX
- Pave the way for new features
Plan
That said, big projects always pose risk, and there's a non-zero chance that this initiative falls through. That's fine, at least we tried. To mitigate risk, we'll break down this project into a few phases and have clear steps and milestones. Even if we don't complete the project, the work done in the process will still improve maintainability of the project and benefit future generations.
We'll start with the obvious, easier changes that nobody will disagree with, such as upgrading non-user facing aspects such as tooling. Then slowly move up the stack and improve the product, changing the UX and adding/killing features.
Phase 1 – Tooling upgrades
Since we want to use AI to do the heavy-lifting, we need to make things easier for AI to do its thing. The first step is to upgrade tooling so that AI can easily verify correctness (somewhat). Tooling improvements are also easier for humans to verify. Development experiemce improvements that good for humans tend to also be good for AI.
Issue: #4319
Phase 2 — Documentation, Modules & abstractions
We eventually want to rewrite the user interface, which means both versions of the website will co-exist for a bit (potentially for a long time depending on how long the rewrite takes).
Issue: #4318
Documentation
Before we do that, we (I) should be familiar with what exists, and that's where documentation comes in helpful. AI makes documentation trivial, so we can firstly generate some engineering docs, feature list, etc. for the current repo.
Modules & abstractions
Next, it'll be good to extract out the business logic (stuff are independent of UI and doesn't change often) into standalone packages/modules (not referring to the timetable ones), so that both current and new interfaces can use them.
The nusmoderator package was a first step (albeit a thin one), but the idea is there. I suspect some parts of the timetable reducer can also be extracted out. While we do this, we can also add more tests and design good module boundaries / APIs.
I do not know which parts can be abstracted and extracted out yet, but this is a job for AI. Will update after AI has analyzed the code.
Phase 3 — Build v4
The new app will live in another directory within the repo, while depending on the common modules. Having both current and new in the same repo is useful as we can tell AI to "Refer to feature A in website and rebuild it in v4 using the new UI components and metaframework".
A list of modules, pages, features, flows will be documented so that both humans/AI can refer to it and work through them.
Next, create a list of UI components that are being used and build them using modern approaches like Tailwind & Base UI.
Then we can start with migrating the product, by starting with simpler pages. The order is TBD, but obviously we'll work on the common parts (e.g. timetable state that many pages depend on) first, and other stuff later.
For backwards compatibility, localStorage keys and URLs should be maintained or a migration path should be provided.
While the new app is being developed, the current one still needs to be maintained until the new one is launched.
Phase 4 — Testing & Launch
Similar to v3, we can publish the new site as v4.nusmods.com and gather volunteers to test on a separate domain first.
After ironing out the common issues, we can use Cloudflare proxies to dynamically serve current/new websites on nusmods.com, then add a switch on nusmods.com to let people try out the new version, with a way to switch back to the old one in case they encounter bugs and are blocked.
After a while, make v4 the default, delete v3.
Comments and suggestions welcome!