Requirements doc
I wrote this to pin down what the app had to do across homes, zones and items, and to track what was built against what was still planned.
What happened next: Most of this shipped in 1.0. The two-person experience over iCloud was built, then held back for a later release.
Version 1.2 Updated to match what was built and decided, replacing version 1.1. This version adds the reusable multi-select and multi-edit layer and in-memory search filtering.
Status key: Built Partial Planned
Later status. The tags below are a snapshot from when this was written. Since then, Lists, backup and restore, private iCloud sync, internal TestFlight, AI parsing behind a key proxy with a consent gate, Unsorted, tag autocomplete, and zone rename and move have shipped. Barcode-label printing has moved into planning.
1. Product overview
HomeBase is a native iOS app for tracking every physical object across multiple locations (homes, storage units, cars) down to the shelf, drawer or bin. Items are categorized, multi-tagged, searchable and countable across all locations. The app adds media lookup (books now, DVDs and music planned), barcode and ISBN scanning, photo and file attachments, and quantity tracking.
Data is local-first on the device. A shared two-person experience over iCloud is a planned later phase, not a v1 requirement.
Primary users: a couple across two primary homes, expandable to more locations. Single-user and fully local today.
2. Core concepts and data model
2.1 HomesBuilt
A Home is a named physical place, for example "House #1, Brooklyn." It has an optional address, plus color and icon fields. Homes are user-created and unlimited.
| Planned | A picker for the home's color and icon. |
2.2 ZonesBuilt
Within a home, Zones define where things are, nested to any depth:
House #1 › Basement › Rack 3 › Shelf 4 › Blue Bin
Zone types: room, closet, drawer, shelf, rack, bin, box, cabinet, under-bed, vehicle, other.
| Built | Add a zone. |
| Built | Delete a zone, which deletes everything inside it. |
| Planned | Rename a zone. |
| Partial | Move a zone. |
| Built | Tiles show the number of zones directly inside and the total item count underneath. |
2.3 Storage taxonomy: rooms, furniture, slotsPartial
This is the foundation for the Home Builder, alongside the item-detail taxonomy. The data is built. The single "Add storage" picker is waiting on a rebuild.
The Home Builder lays out a home's structure in three tiers, all built from the same nested zone. A Room contains Furniture, and a piece of furniture contains Slots (its compartments). Storage nests without limit, so a slot can hold slots. Names without their own zone type map to the nearest type with a custom display name: a Dresser is a cabinet named "Dresser," and a Rod is "other" named "Rod." An Item can sit at any level: a room, a piece or a slot.
Any piece or slot can hold any slot type. Each piece arrives with default features and a suggested order of slots, which guides the picker without limiting it.
| Tier | Options |
|---|---|
| Slots (8) | Drawer, Shelf, Rod (hanging), Bin or Basket, Box, Cubby, Hook, Compartment |
| Furniture: bedroom and clothing | Closet, Wardrobe, Dresser, Chest of Drawers, Nightstand, Under-bed |
| Furniture: living and dining | Bookshelf, Cabinet, Sideboard, Media Unit, Storage Bench, Trunk |
| Furniture: general and utility | Shelving Unit, Rack, Pantry, Kitchen Island, Vanity |
| Furniture: garage and office | Tool Chest, Filing Cabinet, Vehicle |
Each of the 14 rooms suggests a starting kit. Each room also has a longer "See more" list, and the full palette orders the kit first, then the extras, then everything else.
| Room | Suggested kit |
|---|---|
| Bedroom | Closet, Dresser, Nightstand |
| Living Room | Media Unit, Bookshelf, Cabinet |
| Kitchen | Two Cabinets, Pantry |
| Garage | Shelving Unit, Rack, Tool Chest |
| Bathroom | Vanity, Cabinet |
| Office | Bookshelf, Cabinet, Filing Cabinet |
| Kids Room | Closet, Dresser, Bookshelf |
| Laundry | Cabinet, Shelving Unit |
| Pantry | Pantry, Shelving Unit |
| Basement | Shelving Unit, Rack |
| Entryway | Closet, Cabinet, Storage Bench |
| Dining Room | Sideboard, Cabinet |
| Attic | Rack, Shelving Unit |
| Walk-in Closet | Wardrobe, Shelving Unit |
Sourcing. The lists are an 80/20 drawn from retail storage taxonomies (IKEA, Wayfair, The Container Store, Home Depot, Lowe's) and furniture-type references (Family Handyman, Wikipedia). The test for inclusion is whether something can store things, so decor is never a container. A rug or a painting is only ever an item.
2.4 ItemsBuilt
An Item lives in exactly one zone, or in none. Items are multi-tagged.
| Planned | Items without a zone collect in "Unsorted." |
Core fields: name, description, quantity, category, tags, zone, status, condition, dates added, modified and purchased, purchase price, estimated value, notes, and privacy. Privacy is stored but not enforced yet.
Built Fields by category, stored and editable:
| Category | Extra fields |
|---|---|
| Clothing | size, color, brand, garment, season |
| Books | ISBN, author, publisher, year, genre, cover |
| Media | format, director, artist, album, label |
| Electronics | model number, connector types, serial number |
| Food | unit |
| Documents | document type |
| Auto | vehicle, part type |
| Pet | pet name, supply type |
Reserved-name rule. Some field names are reserved by the database framework, and a field that uses one silently comes back empty. Fields use qualified names instead.
2.5 CategoriesBuilt
A category decides which of those extra fields appear. The details editor shows them as a tray of chips that reveal themselves as needed, shared by every add flow and the item form.
The categories: Clothing, Kitchen, Food and Pantry, Freezer, Bathroom, First Aid, Cleaning, Documents, Electronics, Books, DVDs and Blu-ray, Music, Automotive, Pet, Yard and Garden, Tools, Furniture, Décor, Sporting, Holiday, Misc.
| Planned | Custom categories. |
2.6 Smart collectionsBuilt
Collections are lists driven by a category or a field, not by a physical zone. Books is every item in the Books category. The same mechanism powers tappable author, genre and tag links, and will power Unsorted and roll-up groupings.
2.7 TagsBuilt
Tags are free-form and multi-select per item.
| Planned | An autocomplete picker. |
2.8 ContainersPlanned
A bin or box that is an item and also holds items. Today a bin is only a zone.
3. Roles and privacyPlanned
This is deferred. Item-level privacy (Shared, Mine, Partner) is stored but not enforced. Ownership (who owns something versus who can see it) and roles arrive with the multi-user model.
4. Sync and storage
4.1 Local-firstBuilt
The primary store is Core Data on the device. It works fully offline, with lightweight migration turned on.
4.2 Shared syncPlanned
One flag switches to the CloudKit-backed store for iCloud shared sync, with no schema rewrite. It requires the paid Apple Developer Program. CloudKit sharing versus a Supabase backend is still an open decision. Until then, each phone holds its own local data.
4.3 AttachmentsPartial
| Built | Photos from the library or camera. |
| Built | Files and PDFs, with a viewer. |
| Audio and video notes are out of scope. |
5. Features
5.1 Adding itemsPartial
| Built | A single-item form with the fields for its category. |
| Built | Scan a Book: camera, then Open Library lookup, then an automatic save to Books, a confirmation, and Done or Scan another. |
| Built | Barcode, ISBN and UPC scanning through Open Library and Open Food Facts. |
| Partial | Assist Add, which reads a typed description. |
| Partial | Bulk Add, which takes a pasted list. |
| Planned | Voice entry, and a photo of a whole shelf. |
| Planned | Adding into the zone you're viewing by default. |
5.2 Media lookupPartial
| Built | Books through Open Library. |
| Built | Groceries through Open Food Facts. |
| Planned | DVDs through OMDb and music through MusicBrainz, by title. |
5.3 Viewing and editingBuilt
Tapping an item opens view mode. It is read-only and shows only the fields that have values. Quantity appears only above 1. The photo or cover shows as a preview, tags and book fields are tappable, and items without a zone show a Choose button that opens the picker. View mode also offers Delete. Edit opens the full form.
| Planned | A full-bleed image header. |
| Planned | A zoomable full-screen image viewer. |
5.4 Search, filter and sortPartial
| Built | Full-text search. |
| Built | Category filters, plus clothing size and color filters. |
| Built | A live count of items and units. |
| Built | Filtering runs in memory from the filter state. An earlier version set the filter on the data request, and it silently reset whenever the screen was rebuilt (entering multi-select hides the tab bar, for example), so the filter disappeared. |
| Planned | Filters for location, zone, tag, status, date and photo; all sort options; and a redesign of the query and results. |
5.5 Move and organizePartial
| Built | Moving a single item by editing its zone. |
| Built | Multi-select: long-press any item to enter selection mode, with Select All, Move, Delete and Edit. |
| Built | Editing one selected item opens the normal editor. Editing several opens multi-edit: it shows the fields they share for their category, marks values that differ as "(mixed)," outlines changed fields in green, clears category-specific fields if the category changes, and applies everything after a confirm. |
| Built | Multi-select works on zone browsing, Search, Recently added and the field-based lists. |
| Planned | Moving a whole zone or container, and a move history. |
5.6 DeleteBuilt
The main path is long-press, then multi-select, then Delete, with Move and Edit alongside. Swipe-to-delete stays in lists as a shortcut. Deleting a zone that has things in it asks whether to move them, delete them or cancel. Settings offers a full wipe and an items-only wipe.
| Planned | Undo. |
5.7 CountingBuilt
Each item has a quantity, and filtered views total both items and units.
| Planned | Combining, splitting and roll-ups. |
5.8 Wishlist and insurance
| Planned | A wishlist or shopping mode. |
| Insurance valuation is out of scope. |
6. NavigationBuilt
Two tabs, Home and Search, with a centered Add button. Settings opens as a sheet from Home. This replaced version 1.0's five-tab layout.
| Surface | What it holds |
|---|---|
| Home | First-run, single-home and multi-home states; carousels of homes, zones and recently added; stats; the Books collection |
| Search | Full-text search, filters and the count; long-press multi-select |
| Add | Add Item, Assist, Bulk, New Zone, Scan a Book, Quick Add (one after another) |
| Any item list or grid | Long-press for the shared multi-select layer: Delete, Move, Edit and multi-edit |
7. Technical stack
SwiftUI targeting iOS 26 and Liquid Glass, with modern SwiftUI APIs. Core Data with a programmatic model, local now and CloudKit-ready. AVFoundation and VisionKit for scanning. Open Library and Open Food Facts for live lookups, with OMDb and MusicBrainz planned. The Anthropic API for parsing typed descriptions. Distribution is free signing over USB for now, then TestFlight after the $99 enrollment.
8. Build and distributionBuilt
Xcode on a Mac with a free Apple Developer account, installed over USB and re-signed every seven days. Built one feature at a time, each with an explicit success test. The $99 a year program unlocks TestFlight and CloudKit.
9. Out of scope for now
Web and Android, NFC tags, barcode-label printing, loan tracking, expiration alerts, grocery-delivery integration, audio and video notes, insurance valuation, a recent-activity feed, and an Organize tab (multi-edit covers it).
10. Status snapshot
Built Built: the data model, Home and browsing, Scan a Book with covers, smart collections, view and edit modes, multi-select with multi-edit on every item surface, delete everywhere, in-memory search filtering and local storage.
Planned Next: adding into a zone from Assist and Bulk, the Unsorted collection, the search redesign as one batch, category screens, onboarding and first-time use, and CloudKit shared sync.