- Doors
app/api/v1 · lib/mcp · server pagesCheck who is calling, validate the input, then call the one facade. They decide nothing themselves.
- Use cases
lib/use-casesChain read facts → calculate → write. They know ports and calculation only, never requests, cookies or the database.
- Calculation
packages/core · lib/calcInput in, output out. No database, clock or network, and even the current time is an argument. Tested without a database.
- Data
lib/dataOnly reads and writes the database and outside APIs. Hidden behind ports, so swapping it changes nothing above.
ikie has many doors. The web app, the iOS app and the user's own Claude (over MCP) all call the same server. External calendars like Google, iCloud and Outlook connect too, and so do task sources like Notion and Linear. The more doors and outside systems you have, the more often someone asks "where should this decision live?" When the answer wobbles, the same feature behaves slightly differently behind each door.
So we set principles. Writing them in a wiki wasn't enough, though, because that's the first thing forgotten when things get busy. Instead, we gave the principles something that enforces them. Most are tests that read the code and check the rule, and CI runs them. Code that breaks a principle gets a red light before a person ever reviews it. The one principle tests can't easily check (number 8) is kept by a working rule.
1. Store only facts
Store facts, never state derived from them. If a value can be rebuilt from other stored values, we don't store it.
Occurrences of a repeating event can always be rebuilt from the rule, so we don't store them (We don't store repeating events). We don't store the paid plan (Hyper) either. We record only the facts (an App Store subscription, or a plan we granted directly) and compute the current plan on every request. When a plan ends and a calendar account goes over the free limit, its paused state is computed, not stored. So subscribing again needs nothing to be undone.
In the same spirit, a change in conditions never rewrites the user's settings or data. When a plan ends, we don't delete anything or flip settings. Each feature is simply gated the way we declared.
Where we broke it. A sweep of the whole codebase against our principles turned up several stored derived values. One was "this occurrence doesn't exist", stored and read in two shapes: a removed date (EXDATE) and a cancelled occurrence exception. External formats need both shapes to round-trip, so we kept the storage and gathered the decision into one function (occurrenceGone).
What enforces it. Every database column has to be declared in the model (model.ts) with why it's stored and how it maps to external calendars. CI blocks an undeclared column. Writing the same fact in two places is blocked by one-source.test.ts: the permission ladder, the list of item states, the "is it finished" check, and so on.
2. The server decides, screens just draw
Every policy and rule decision is made by the server. Screens show what the server decided and take input.
For each calendar, the server also sends what can be changed and, if not, why (can, why). Web and iOS draw it as is. If screens decided, web and iOS would each write the same rule, and one day only one of them would get fixed.
Where we broke it. Screens were re-deciding whether a calendar seen through a public link could be subscribed to, whether saving "this occurrence only" also changed the repeat rule, and whether a repeating task could have a deadline. Some input was even dropped silently. We moved every decision to the server and turned the silent drops into explicit errors (series_only, due_repeat).
What enforces it. Screen components can't import server code, and they reach the server only through the generated API client. We don't use Next.js server actions ("use server") at all, so the web screens call the public API just like iOS and MCP do.
3. Pure calculation is the largest layer
Decisions are pure functions: input in, output out. No database, clock or network, and the current time comes in as an argument.
Permissions (canEdit), expanding repeats, save plans, which alerts should fire, free time, and the three-way merge with external calendars are all pure calculation. The data layer only reads the facts a decision needs and applies the writes the calculation chose. Whether a repeating series can be split, for example, is decided by one pure function given the facts the data layer read after taking locks.
// Data layer: lock, read the facts, and just ask the calculation
const block = splitBlock({ rows, external, pendingAlarmClaims }, from, expectedRevision, now);
if (block) throw new PlanError(block);
That lets us test the trickiest rules without a database, in milliseconds. With the clock as an argument, time conditions like "an alert stuck for more than five minutes" reproduce exactly in tests.
What enforces it. The calculation layer may import only approved pure libraries, and a test blocks any use of Date.now(), randomness, fetch or environment variables there. The data layer is also blocked from computing boards or alerts.
4. Thin doors, one facade
The public API, MCP and server pages all call the same single facade. A door checks who's calling and validates the request body. It decides nothing and has no side effects of its own.
Where we broke it. This principle came from a bug. Editing a Google Calendar event through the user's Claude (MCP) never reached Google. Sending edited events outward was done by the public API's door (its HTTP adapter), and MCP, being just another door, didn't know about it. Pasting the same code into that door would have hidden the symptom, only for it to come back with the next door we added.
So we changed the structure instead of the door. Every door now calls one facade, and item writes go through one path (writeItems). It applies the change, then sends edited external events with the calendar owner's account after responding. What to send is decided by pure calculation. Now the same thing happens whichever door you use.
What enforces it. Tests block a door that imports a use-case module directly, re-implements the viewer's time zone or language rules, or decides what to send outward. Every use case must have a public API route, so web, iOS and MCP call the same path.
5. Every boundary is a port
The outside world (external calendars, the database, secret storage, the clock) and the boundaries between our own layers all connect through declared interfaces. Adding a new outside system means adding an adapter.
There is one calendar sync engine, and it knows only the shape CalendarPort. Google, iCloud (CalDAV), Outlook and .ics subscriptions are all adapters behind that port. The per-field three-way merge lives in pure calculation, so every external calendar is reconciled by the same rules. Task sources follow the same shape: Notion, Todoist, Linear, Google Tasks, Microsoft To Do and GitHub plug into one engine through their own adapters.
That's why adding MCP didn't mean writing a new server. The MCP server is a thin adapter calling the same facade and the same schemas as the public API.
What enforces it. Tests fail if the sync engine imports any external adapter or client, or if an adapter knows about the database. API routes and server-rendered pages can't call the data layer directly either. They use only ports and the composition root (the one place that plugs implementations into ports).
6. Shared app rules are written once, as data
App policy that web and iOS must share isn't written per platform. It's declared once as data, and both apps' interpreters are tested against the same scenarios.
"What to fetch when, and how to show what changed" isn't business logic, but both apps must behave identically: fetch units, prefetching, when to commit the selected day during a swipe. We declare these as data in packages/policy. The web reads them with a TypeScript interpreter. iOS reads Swift code generated from that data with a Swift interpreter. Both interpreters run the same scenario JSON.
Where we broke it. An interpreter can end up called only by tests while the app quietly does its own thing. When we checked for this with our code graph, three real cases turned up. For example, iOS was choosing which board days to rewrite with its own code instead of the policy interpreter.
What enforces it. Every policy rule needs an implementation on each platform it declares, and app code must actually use it. A graph built automatically from the code (the TypeScript compiler API for TypeScript, tree-sitter for Swift) checks this, and CI blocks violations.
7. No LLM on the server
The app server is the board (calendar and tasks) and its rules. Judgment comes from the Claude the user connects over MCP. We build no AI-only tables, columns or rules.
The user's Claude is a tool the user connected. It isn't a separate actor with its own account. It works with the user's own permissions, and history records it as a "connected app". Whatever Claude needs, it does with app features: tasks, nesting, tags, notes. We once had AI-only work tables and columns. We moved those records into notes, links and tags, then dropped them all.
The one exception is an on-device model. When reading a quick line like "dentist tomorrow at 3", iPhone and Mac can use a model on the device. It reads through the same port as our rule-based parser, and if the model is missing or fails, the rule-based reader takes over. Both readers are measured against the same test set. Reading and creating are also separate. Only the dedicated parsing API calls functions that read text, and the creation API accepts values only.
What enforces it. A test blocks any creation path that calls a text-reading function. There is no path that reads and creates in one step.
8. Look before you build, and fix structure, not symptoms
If a well-maintained open-source project exists, use it first. If you build it yourself, leave the reason. When fixing, fix the structure that produced the symptom, not the symptom.
rrule handles repeat rules, ical.js iCalendar files, tsdav CalDAV, Base UI selection behavior, Radix Colors our palette, Style Dictionary design tokens, swift-openapi-generator the iOS API client, and PGlite our test database. Whatever we build ourselves gets its reason in the PR. The small custom pager we chose over UICollectionView for the week view is one example.
Where we broke it. When the week view stuttered, the home screen files held 44 comments like "this used to stutter". Patch one spot and it came back somewhere else. This time we changed the structure and measured each step. Our codebase-wide review against these principles worked the same way. It found 168 places that drifted and we fixed 166. One turned out to be a misread, and one is a debug-only demo we kept with a written reason.
Fallbacks follow the same principle. We add one only when we can state its intent. Otherwise we fail clearly. If a repeating series tied to an external calendar can't be split, we don't split it half-right. We refuse with a 409.
Smaller rules, enforced the same way
Some rules aren't as big as principles, but tests guard them the same way.
| Rule | Why | Enforced by |
|---|---|---|
| Hand-written files up to 300 lines, and on the web, lines up to 300 characters | Small enough to read in one go | Web and Swift size tests (0 files over 300 lines today) |
| No raw colors or font sizes in screen CSS | One set of design tokens for web and iOS | Style test, token contrast test |
| UI strings go into all 6 language files together | A global app | Key, placeholder and ICU syntax tests |
| A new API route goes into the OpenAPI document | iOS and MCP read the same contract | OpenAPI test |
| Lint warnings fail the build too | Warnings that pile up get ignored | Biome |
What happens when tests hold the principles
When tests hold the principles, reviews spend less time re-explaining them. The test name is the principle, and a red light says which one was broken. Want to change a principle? Open a PR that changes the test, and discuss it there.
Where it helped most was adding new doors and new outside systems. The iOS app calls the same public API as the web. MCP is an adapter over the same facade. A new calendar or task source is one adapter. We don't have to ask "where do I need to change things this time?" The structure already holds the answer.