Hi, I'm Vũ Xuân Toàn (Vu Xuan Toan), a software developer and indie maker from Bắc Ninh, Vietnam, and the founder of Vu Xuan Toan Tech. In my intro post I mentioned Mầm Văn — the literature-learning platform I'm building for Vietnamese middle-school students (React, TypeScript, Supabase, Gemini AI). Today I want to share the part of the project I'm most proud of, because it isn't a feature for users — it's how I keep the whole system understandable while it changes every week.
The problem: the system grows faster than memory
Mầm Văn has two big portals (teacher and student), an AI content studio, a question bank, XP and mastery engines, a knowledge tree, grading workflows, notifications, an admin area… After a few months of intense building, "how does this all connect?" stopped being a question I could answer from memory.
So I built a complete map of every flow in the system — 262 nodes covering every screen, every engine, and the relationships between them (for example: publishing a lesson → notifies students, or rejecting a gift request → refunds the student's total XP wallet). Every node also lists the exact code files and functions that implement it, verified automatically against the codebase.
The rule: the map is part of the code
The map only stays true if it can never drift. So I work under one strict rule:
- Before changing any flow, I open the map and identify which nodes and relationships the change touches.
- After the change, I update the map, regenerate it, and ship it in the same commit as the code.
- The map and a full change history are republished automatically to my website in the same round.
You can see both, live:
- 🗺️ The system map (interactive, click a node to light up its cluster): https://vuxuantoan.me/so-do-mam-van.html
- 📜 The change history — every work session: what changed, in which files, with lines added/removed: https://vuxuantoan.me/lich-su-mam-van.html
Before & after, for every flow change
The part I like most: whenever a change modifies a flow, the history page automatically gets two buttons — "flow BEFORE this change" and "flow AFTER this change". Every version of the map is archived immutably, so I can reopen exactly how the system looked before any change and compare. When I recently removed an AI status bar from the question bank, the before-map still shows its node in the tree; the after-map doesn't. That makes design review honest: nothing about the system's shape is ever lost or misremembered.
Why bother?
Because an indie maker's scarcest resource isn't code — it's clarity. The map has already caught wrong assumptions before I wrote a line of code, and it lets anyone (a collaborator, a teacher using the platform, future me) understand a fairly complex product in minutes.
If you build long-lived side projects, I'd genuinely recommend stealing this workflow: one living map, updated in the same commit as the code, with archived before/after versions.
—
I'm Vũ Xuân Toàn. My home on the web is vuxuantoan.me, my code lives at github.com/vut08905, and Mầm Văn itself is live at mamvan.vercel.app. Say hi!
Top comments (0)