Project Homey: The Household’s External Brain

Index and high-level architecture for Homey's foundational product specification suite.

1. Project Overview

Homey is a local-first household management application designed to reduce cognitive load. It acts as a digital twin of the home, managing inventory through flexible locations and optional spatial grids while connecting that inventory to ingestion, planning, and recurring work.

The goal is simple: You shouldn’t have to remember anything about your house; you only need to consult Homey.

2. Core Philosophies

Cognitive Offloading: If the app doesn’t save the user’s brainpower, it isn’t working.
Shared Stewardship: The app is a neutral resource for planning and execution roles.
Spatial Reality: Information is mapped to physical locations, not just lists.
Proactive Intelligence: Timely nudges help prevent waste before it happens.

3. Project Documentation Suite

The foundational suite in this repository records both implemented behavior and longer-term product direction.

Category	Document	Key Focus
Vision	Foundation	Mission, vision, local-first principles, and whole-home direction.
	Household ecosystem	Planning-oriented and execution-oriented household intent.
	UX philosophy	Spatial mapping, progressive disclosure, and safe automation.
Product specifications	MVP 1.0	Kitchen and grocery starting scope.
	Digital twin	Flexible locations, inventory, and optional grids.
	Smart automation	Manual, OCR, and PDF ingestion with review.
	Planning and execution	Recipes, meal planning, inventory feedback, and shopping.
	Contextual notifications	Expiry, shopping, quiet-hours, and final-call nudges.
	Token bridge	Proposed temporary-token snapshot synchronization.
	Mission checklists	Proposed reusable blueprints and active missions.
Experience	App layout	Original layout and navigation direction.
	Branding	Personality, visual language, typography, and voice.

4. High-Level Architecture

Homey is built as a local-first application.

Database: Room on SQLite for reactive, offline household data.
Automation: On-device Google ML Kit text recognition plus local invoice parsing and an explicit review stage.
Synchronization: The Token Bridge specification describes a possible future snapshot exchange; it is not a current app feature.

5. Getting Started (For Developers)

To begin contributing:

Read the dated MVP status snapshot with its archival notice.
Review the current package structure.
Compare the relevant product specification with the implementation before treating older status or navigation language as current.

"Managing the house, so you don’t have to."