Before the Code — Architecture Design
Before writing a single line of code, I spent half a day on design.
The short version: that half day determined everything that came after. And the reason I needed it was simple — I'm not a developer. And I had already hit a wall before the design even started.
The First Wall — The Planning Session Overflowed First
It happened a few months back when I was building kimeunsoo.xyz. I was running Claude Code sessions back to back, excited. Hit the limit fast. When the AI lost context mid-session, the code started going sideways in small ways. As a non-developer, you don't immediately notice it's gone sideways. You just keep going, and then later you realize something's off.
The same thing happened during Pepper's planning phase. Just trying to work out the structure on Claude Pro ($20/month) — the planning session hit its limit before any actual implementation had started.
"How do I fix this?"
I worked through it with Claude and Gemini. The answer turned out to be a documentation system.
The core insight: the AI can't lose context when a session changes. That means the context has to live in a document — not in my head.
And another: when my thinking drifts, the AI goes with it.
Developers carry a rough mental model of the system structure. I don't. Mid-conversation, things shift. A design decision that seemed right yesterday might not seem right today. The AI doesn't catch that drift — it just starts writing code in the direction I was pointing, drift and all.
I needed an architecture anchor. A document structure that holds firm even when my thinking wavers. A single source of truth that doesn't move even as development progresses.
Three Documents — Made Before a Single Line of Code
context.md — The one single truth about the entire system. North Star, design principles, architecture, STATE A/B/C definitions — all in here. One absolute rule: update this document before changing any code. At the start of a new session, hand this one file to the AI and it can reconstruct the full context. This was the practical fix for the session limit problem.
schema.md — This one didn't exist at first. As I was writing context.md, I realized the data structure also needed to be clearly documented. What data goes into the Family Vault and how, how to cleanly separate data by family unit — without this, the AI would just improvise the database design. Fixing that later is far more painful than getting it right early.
roadmap.md — A hyper-granular execution plan breaking down the entire implementation into small steps. Each step ends with a clearly defined "success condition." The reason is simple: I need to be able to tell whether something worked. And I only give the AI one step at a time. Giving it multiple steps at once contaminates the context.
At the end of each session, a handover.md captures the current state and the next entry point. Starting a new session with context.md + handover.md is enough for the AI to know exactly where things stand. .gitignore also helps — excluding unnecessary files from the AI's context cuts down on wasted tokens.
This might sound obvious. But for a non-developer, even designing this setup was a real challenge. I worked through that with AI too.
The Structure Emerged from Throwing Use Cases
Once the documentation system was in place, the real design work began. This was most of that half day.
The design didn't start from abstract discussion. I kept throwing specific, everyday scenarios at the AI, and the structure built itself around them.
"In Korea, reservations go through Naver. Pepper has to know which hair salon I usually go to."
"But what if I'm traveling abroad and need to book a restaurant there? My current location and the booking location could be different — can the structure handle that?"
"What if I change salons? If I say 'I changed hair salons — it's OO Hair now,' it should automatically update."
Out of that exchange came a design: user's current location and the target booking location are resolved independently. "Book a haircut" (currently in Korea → Naver) and "Book a hotel in London" (currently in Korea but → global search) both get handled naturally within the same structure. Preferred salon info lives in the Vault and is automatically applied at the next booking. One sentence — "I changed salons" — updates it.
"What if Eunsoo asks for pocket money and Toss just deep-links right to the transfer?"
"What about a to-do system for Eunsoo and Eunje where clearing tasks earns points — and those points can be spent in a family marketplace on things like 'hang out with Dad'?"
That became the Action Ledger and Family Reward System. Not just a reminder app — a structure that connects behavior and rewards within the family. Whether I'll actually implement all of it, I don't know. But the data structure had to be able to support it from the start.
"What if the Family Vault holds not just documents but also our favorite restaurants and recipes — and Pepper operates on top of all of that?"
The scope of the Vault expanded here. Beyond financial assets and legal documents — to the tastes and memories of our family. Ask Pepper "Where should we eat out tonight?" and it can suggest places based on the restaurant history the Vault has built up.
Those conversations made the design. I didn't figure out the structure on my own — I kept throwing use cases at the AI and asking "Can the structure handle this?"
Extensibility Was the Core Concern
None of these use cases can be implemented right now. I knew that from the start.
But what mattered was building a structure that wouldn't need to be torn apart when new things got added later. I kept asking myself throughout the design: "Will this hold up when it scales?"
Some specific scenarios I thought through:
Four family members. A permissions structure has to be there from the beginning. What I can do with Eunsoo's account and what she can do with mine are different.
One person might have more than one email account. Multiple personal accounts, possibly work accounts too. The structure needs to support multiple account connections per person.
It might not just be our family. What if other families use it eventually? From the very first layer of data design, I applied full data isolation by family unit. Right now it's just us — but the structure is built to handle multiple families from day one.
I can't know every use case up front. So the structure had to be built as wide as possible from the start. That's also why schema.md became its own separate document.
What the Half Day Left Behind
When the design was done, three documents sat in front of me. context.md, schema.md, roadmap.md.
Not a single line of code. And yet, strangely, I felt confident. I knew what needed to be built, in what order, and how to verify that each step actually worked.
Time to build.