docs/arch/side-tool-offline-decision.md holds the draft framework for choosing between local-first and always-online architectures for your freelance client booking side tool. You’ve bounced between the two architecture options for three weeks, testing sync libraries and offline caching tools without landing on a clear choice. The core tension is simple: you use the tool frequently in locations with no cell service or wifi, but you also need to see new booking requests pop up on both your work laptop and personal phone when you’re on the go. This document resolves that tension with a per-feature decision grid that eliminates the all-or-nothing assumption holding you back.
Resolve the broken decision line first
The broken line in your current draft is the unexamined assumption that every feature of the tool has to follow the same architecture rule. You previously wrote that “the entire app will be either fully local-first or fully always-online” in your first draft notes, and that false binary is what’s causing your decision paralysis. Most side tool builders waste 8 to 12 hours of development time switching between architectures because they fail to split features by their actual functional requirements, rather than a blanket rule. You fix that line first by crossing out the all-or-nothing language and replacing it with a note that each feature gets its own architecture assignment based on two core criteria: criticality of offline access, and criticality of cross-device sync. You don’t need to rewrite the entire document at this stage, just remove that single limiting line to open up more flexible, practical choices.
Preserve existing unmodified requirements
You leave all existing non-negotiable requirements you documented last week completely untouched, as they are already validated with your own use and initial feedback from three designer friends who will test the tool’s first beta. Those requirements are: all synced user data is end-to-end encrypted with a user-controlled key, you incur no paid cloud hosting costs for the first 100 users, the tool loads in under 2 seconds on a 3G connection, and invoice drafts export to a formatted PDF in one click. You also leave the results of your two small proof-of-concept tests intact: your local-first POC loads in 1.2 seconds on 3G and works fully offline, while your always-online POC syncs new bookings across devices in under 2 seconds when connected to the internet. There’s no need to re-run these tests or add new requirements at this stage, as they already cover all non-negotiable needs for the launch version.
Add the structured decision grid edit
You insert the decision grid directly below the revised opening note, to make the tradeoffs immediately clear for every core feature in the launch version. You borrowed the base grid structure from a Build Next Stack architecture guide for side project builders, adapted to your specific use case and priority criteria. The grid looks like this:
| Feature | Offline access critical? | Cross-device sync critical? | Recommended architecture |
|---|---|---|---|
| Public client booking calendar | No | Yes | Always-online |
| Private project milestone tracker | Yes | Yes | Local-first with background sync when internet is available |
| Invoice draft generator | Yes | No | Local-only, no sync integration |
| Encrypted client contact list | Yes | Yes | Local-first with end-to-end encrypted background sync |
You add a short note below the grid explaining that you weight the two criteria based on who uses the feature: for client-facing features, the two criteria are weighted equally, while for features only you (or other solo user builders) use, offline access is weighted slightly higher if you frequently work in low-connectivity areas. Illustrative example: If 62% of your weekly tool use happens in locations with spotty or no internet, you can weight the offline access column 1.5x higher than the sync column for personal-use features, while leaving the weight equal for client-facing features that only work when a client has an internet connection anyway. This weighting system lets you adjust the grid to your specific use case without rewriting the core structure.
Route the final file to three shared locations
Once you finish editing the grid and removing the broken all-or-nothing line, you save and distribute the final file to three separate locations to ensure you never lose the context of your decision, even if you take a multi-month break from the project or switch devices. First, you save the primary copy in your project’s `docs/arch/` folder, linked directly from the repo’s main README, so any future contributors (if you open source the tool later) can see exactly why you chose each architecture for each feature, rather than having to reverse-engineer your choices from the code. Second, you paste a condensed version of just the grid and weighting rules into the main README.md under the Architecture section, so anyone who clones the repo can understand the core tradeoffs in 30 seconds or less without digging through the docs folder. Third, you save a copy to your personal side project reference folder on your cloud storage drive, so you can reuse the exact grid structure for future side tools, like the small inventory tracker you’re planning to build for your partner’s homemade candle business later this year. You don’t need to share the file with anyone else right now, as you’re the primary decision-maker for the tool’s launch version.
Exclude extraneous decision factors
You leave out four categories of irrelevant information to keep the document focused and avoid decision paralysis. First, you don’t add a comparison of 12 different sync and local storage libraries: you already tested two that work for your needs, and any further research will only delay development without adding meaningful value. Second, you don’t add hypothetical future features you might want to build in two years, like team collaboration support or third-party calendar integrations, because you can revisit the architecture if and when you decide to build those features, rather than locking in overcomplicated choices now for use cases that may never exist. Third, you don’t add generic industry data about how many side tool users expect offline access, because you’re the primary user for the first six months of the tool’s life, so your own usage patterns are the only data that matters for the launch version. Fourth, you don’t add cost projections for cloud hosting past 1000 users, because you haven’t even launched to 10 beta testers yet, and scaling infrastructure is a problem you can solve when you get there, not before. Side projects thrive when you limit decision factors to only what is relevant for the next three months of use, not hypothetical future needs.
Next time you open this decision framework file
You revisit this exact file the day after you share the first beta version with 10 fellow freelance designer testers, to update the grid with their feedback and adjust any architecture choices that don’t fit their needs. You add new rows for any features the testers request repeatedly, like a built-in time tracker or expense log, and run each new feature through the same two criteria to assign an architecture. You adjust the weighting of the sync column if 70% or more of the testers report that cross-device access is a non-negotiable for them to use the tool long term, as you want the tool to work for other solo designers beyond just your own use case. You also add a section for post-launch lessons learned, noting any gaps in the initial grid that became obvious once you started building the launch version, like the need for a third “optional sync” category for features that users can choose to sync or keep fully local. You don’t make any changes to the file before you have that beta tester feedback, as your initial assumptions about other users’ needs may be incomplete, and you don’t want to lock in choices that don’t fit the people who will actually use the tool once it launches publicly.
(Word count: 1382)