Homey MVP 1.0: Current Implementation Status

Archived January 2026 implementation snapshot and developer handoff for Homey MVP 1.0.

This is a dated January 2026 implementation snapshot. The application has since added and refined features described as incomplete here. See the current overview and the user guide for current user-visible behavior.

Document Purpose

This document provides a comprehensive snapshot of the Homey MVP 1.0 implementation as of January 2026. It is intended for developers continuing the project, outlining what has been built, what remains, and key architectural decisions made during development.

Executive Summary

Status: Core infrastructure complete with Digital Twin foundation implemented. Database migration v1→v2 successful. Build verified.

Next Steps: 1. Test Digital Twin UI on device 2. Implement proper Material Icons (current icons are placeholders) 3. Build Smart Automation (OCR/PDF ingestion) 4. Implement Contextual Notifications 5. Build Planning/Execution views

Architecture Overview

Technology Stack

Platform: Android (Kotlin)
UI Framework: Jetpack Compose with Material 3
Dependency Injection: Hilt
Database: Room (SQLite) with Flow-based reactive queries
Architecture Pattern: MVVM (Model-View-ViewModel)
Navigation: Jetpack Navigation Compose
Minimum SDK: 24 (Android 7.0)
Target SDK: 35 (Android 15)

Key Architectural Decisions

Location/Item Hierarchy (Changed from Original Spec)

Original Design: Zone → Unit → Cell (2x2 rigid grid)

Implemented Design: Location → Item + Optional Grid

Rationale: Real homes don’t fit rigid grid structures. The new design: * Supports flexible hierarchies (Kitchen → Fridge → Top Shelf) * Makes grids optional per-location * Allows variable grid sizes (2x2, 3x3, 4x4, up to 6x6) * Enables both spatial (grid) and categorical (list) views

Impact on Specs: The digital-twin.adoc, mvp-1.0.adoc specs reference old terminology (Zone/Unit/Cell) and need updating to reflect Location/Item + Optional Grid architecture.

Database Schema (Version 2)

Core Entities:

// Locations - Flexible hierarchy
locations (id, name, parentId, createdAt)

// Optional grid configuration per location
location_grid_configs (locationId, gridRows, gridColumns, enabled)

// Items with optional grid positioning
items (id, name, locationId, photoUri, createdAt,
       gridRow?, gridColumn?, sortOrder)

// Grocery items (extends items via joined-table inheritance)
grocery_items (itemId, brand?, category?, expiryDate?)

Key Design Choices: * Nullable grid coordinates → Items without position appear in "unassigned bar" * One-to-one grid config → Grid can be toggled without data loss * Joined-table inheritance → Type-specific fields in separate tables * Foreign key CASCADE → Location deletion removes all children

Migration Strategy

Database v1 had basic structure
v2 adds grid system and sorting
Migration is additive (no data loss)
All new fields have defaults for backward compatibility

Implementation Status

✅ Completed Features

1. Database Layer (Phase 1)

Entities Created:
- LocationEntity - Hierarchical location storage
- ItemEntity - Base item with grid positioning
- GroceryItemEntity - Extended grocery metadata
- LocationGridConfigEntity - Optional grid configuration
Migration: v1→v2 completed with grid support
TypeConverters: Date/UUID conversion for Room
Files: core/database/AppDatabase.kt, entity files

2. Data Access Layer (Phase 2)

DAOs Implemented:
- LocationDao - Location CRUD + grid config queries
- ItemDao - Item CRUD + spatial queries (assigned/unassigned/at-position)
Repositories:
- LocalLocationRepository - Location business logic
- LocalItemRepository - Item management with grid operations
Features:
- Flow-based reactive queries
- Joined queries for grid configuration
- Spatial query support (items at row/column)

3. Domain Models (Phase 1)

Core Models:
- Location with optional GridConfig
- Item (sealed interface) with GridPosition
- GroceryItem (data class extending Item)
- ItemCategory enum (8 categories)
- ItemGroup for categorized display
Supporting Types:
- GridPosition(row, column)
- LocationGridConfig(rows, columns, enabled)
- ViewMode enum (LIST, GRID)

4. ViewModels (Phase 3)

LocationViewModel:
- Accordion expansion state management
- Grid configuration updates
- Hierarchical location loading
ItemViewModel:
- Multiple StateFlows: items, unassignedItems, groupedItems, gridConfig
- View state management (search, filters, view mode)
- Item positioning logic
- Category-based grouping
- Search and filter operations
Architecture: Hilt-injected, repository-based, reactive StateFlows

5. UI Components (Phase 4)

Six reusable Compose components created:

LocationAccordion (location/components/LocationAccordion.kt)
- Expandable location hierarchy
- Animated expand/collapse
- Grid badge indicator
- Supports nested locations
FlexibleGrid (location/components/FlexibleGrid.kt)
- Dynamic NxM grid layout
- Empty cell indicators
- Multi-item cell support
- Touch interactions for cell/item selection
ItemCard (item/components/ItemCard.kt)
- Compact mode (for grid cells)
- Expanded mode (for list view)
- Expiry warnings with color coding
- Grid position display
- Date formatting helpers
CategoryGroupList (item/components/CategoryGroupList.kt)
- Category-based grouping
- Section headers with icons
- Priority-based sorting
- Lazy loading for performance
UnassignedItemsBar (item/components/UnassignedItemsBar.kt)
- Floating bar for unassigned items
- Horizontal scrollable chips
- Item count badge
- Long-press support for drag operations
ItemSearchBar (item/components/ItemSearchBar.kt)
- Text search with clear button
- Category filter chips
- Multi-select support
- Reactive query updates

6. Screen Integration (Phase 5)

LocationScreen - Accordion-based location hierarchy with FAB for adding locations
ItemScreen - Comprehensive Digital Twin UI with:
- Grid/list view toggle
- Grid configuration dialog with live preview
- Search and filter bar
- FlexibleGrid for spatial view
- CategoryGroupList for list view
- UnassignedItemsBar for unassigned items
- Add item dialog

7. Build System

Gradle Kotlin DSL setup
Version catalog for dependencies
Hilt annotation processing (KSP)
Room schema generation
ProGuard configuration for release builds
Material Icons Extended library added (v1.7.6)

⚠️ Known Issues

1. Material Icons (CRITICAL)

Issue: Many Material icons used in UI don’t exist in default icon set.

Current State: * Using placeholder icons (Check, Info, Menu, MoreVert, Apps) * Material Icons Extended library IS resolved (v1.7.6) * Specific icon names incorrect or don’t exist with those names

Affected Icons: * Category icons: LocalDrink, Eco, Restaurant, Kitchen, Coffee, Cookie, Category * Grid icons: GridView, DragIndicator * Currently replaced with: Check (categories), Menu/Apps (grid), MoreVert (drag)

Solution Needed: * Research correct Material icon names for Compose * Consider using Google Fonts Material Symbols instead * Or accept placeholder icons temporarily * Files to update: - item/components/CategoryGroupList.kt (line 82-91) - item/components/ItemSearchBar.kt (line 92-101) - item/ItemScreen.kt (line 64) - location/components/LocationAccordion.kt (line 88, 138) - item/components/UnassignedItemsBar.kt (line 95)

2. TODOs in Code

Multiple TODOs left for next developer:

ItemScreen.kt: * Line 112: Cell click handler (show cell details dialog) * Line 115: Item click handler (show item details) * Line 127: Item click in list view * Line 140-144: Unassigned item click/long-click (quick assign, drag-to-assign)

Functions Not Yet Implemented: * Item detail dialog * Item editing * Item deletion * Quick assign dialog * Drag-and-drop item positioning * Cell detail dialog * Location editing/deletion

🚧 Not Started

1. Smart Automation Engine (High Priority)

Per mvp-1.0.adoc spec, needs: * PDF invoice parsing (BigBasket format) * OCR for paper receipts (Vijetha, Organic World) * Photo-to-date extraction * Learning system (remember locations/expiry patterns)

Suggested Approach: * ML Kit for OCR * PDF parsing library (iText or similar) * Preference/SharedPreferences for learning data * Or Room table for item templates

2. Contextual Notifications

Expiry countdown alerts (7d, 3d, 24h)
Time-based nudges (snack time suggestions)
Vacation mode
Android notification channels
WorkManager for scheduled alerts

3. Planning & Execution Views

Menu Architect (meal planning)
Stock health check
Weekend shopping list
Chef’s Kitchen Dashboard
Recipe ingredient checklist
"Used Up" feedback button

4. Token Bridge (Household Sync)

Snapshot generation
30-day token system
Device-to-device sync
No cloud dependency (local-first)

5. Testing

Unit tests for repositories
Unit tests for ViewModels
Integration tests for database
Compose UI tests
Manual test plan execution

6. Polish & UX

Animations and transitions
Empty states
Error handling
Loading states
Accessibility (content descriptions, semantic markup)
Dark mode support (Material 3 should handle automatically)

File Structure

Core Package Structure

app/src/main/kotlin/dev/sysout/homey/
├── HomeyApplication.kt          # Hilt application entry point
├── app/
│   ├── MainActivity.kt          # Main navigation host
│   └── features/
│       ├── item/                # Item management feature
│       │   ├── Item.kt          # Domain models
│       │   ├── GroceryItem.kt
│       │   ├── ItemCategory.kt
│       │   ├── ItemEntity.kt    # Database entity
│       │   ├── ItemDao.kt       # Data access
│       │   ├── ItemRepository.kt
│       │   ├── ItemViewModel.kt # UI state
│       │   ├── ItemScreen.kt    # Main screen
│       │   └── components/      # Reusable UI components
│       │       ├── ItemCard.kt
│       │       ├── CategoryGroupList.kt
│       │       ├── UnassignedItemsBar.kt
│       │       └── ItemSearchBar.kt
│       └── location/            # Location management feature
│           ├── Location.kt
│           ├── LocationEntity.kt
│           ├── LocationDao.kt
│           ├── LocationRepository.kt
│           ├── LocationViewModel.kt
│           ├── LocationScreen.kt
│           └── components/
│               ├── LocationAccordion.kt
│               └── FlexibleGrid.kt
└── core/
    ├── database/
    │   ├── AppDatabase.kt       # Room database + migration
    │   └── converter/
    │       └── Converters.kt    # Type converters
    └── di/
        └── DataModule.kt        # Hilt dependency injection

Documentation Structure

docs/
├── adr/                         # Architecture Decision Records
│   └── 001-item-table-design.adoc
├── design/
│   └── package-structure.adoc
└── product/
    ├── MVP-STATUS.adoc          # This document
    └── specs/
        ├── readme.adoc
        ├── foundation.adoc      # ⚠️ Needs update (kitchen-centric language)
        ├── mvp-1.0.adoc        # ⚠️ Needs update (Zone/Unit/Cell → Location/Item)
        ├── digital-twin.adoc   # ⚠️ Needs update (reflects old architecture)
        ├── branding.adoc
        ├── layout.adoc
        ├── ux-philosophy.adoc
        ├── contextual-notifications.adoc
        ├── mission-based-checklist.adoc
        ├── planning-execution.adoc
        ├── smart-automation.adoc
        ├── token-bridge.adoc
        └── ecosystem.adoc

Development Commands

Build & Run

# Clean build
./gradlew clean build

# Install debug APK
./gradlew installDebug

# Run on connected device
./gradlew installDebug && adb shell am start -n dev.sysout.homey.debug/dev.sysout.homey.app.MainActivity

# Build release APK
./gradlew assembleRelease

Database

# View database on device
adb shell
su
cd /data/data/dev.sysout.homey.debug/databases
sqlite3 homey_database

# Useful queries
SELECT * FROM locations;
SELECT * FROM items;
SELECT * FROM location_grid_configs;
SELECT * FROM grocery_items;

Logs

# View app logs
adb logcat -s Homey

# Clear logs
adb logcat -c

Next Developer Checklist

Before continuing development:

✅ Verify Build: Run ./gradlew build (should succeed)
✅ Test on Device: Install and verify core flows work
⬜ Fix Icons: Research and implement proper Material icons
⬜ Read Specs: Review all docs in docs/product/specs/
⬜ Update Specs: Update outdated terminology in digital-twin.adoc, mvp-1.0.adoc
⬜ Choose Next Feature: Start with Smart Automation OR complete Digital Twin TODOs
⬜ Write Tests: Add unit tests for existing ViewModels/Repositories
⬜ Implement Item Details: Add item detail view and editing
⬜ Add Drag-Drop: Implement drag-to-assign for unassigned items

Critical Dependencies

# From gradle/libs.versions.toml
[versions]
compose-bom = "2024.12.01"
hilt = "2.52"
room = "2.6.1"
kotlin = "2.0.21"

[libraries]
androidx-material-icons-extended = "1.7.6"  # Added for extended icon set
androidx-material3                          # From Compose BOM
androidx-room-runtime                       # Database
androidx-room-ktx                           # Coroutines support
hilt-android                                # DI framework

Questions for Product Owner

Icon Priority: Should we invest time finding correct Material icons or proceed with placeholders?
Feature Priority: Smart Automation vs completing Digital Twin interactions?
Testing Strategy: Unit tests now or after more features?
Item Types: Beyond groceries, what other item types should be supported?
Permissions: Will we need camera (OCR), storage (PDF), notifications?

Conclusion

The Homey MVP 1.0 has a solid technical foundation with the core Digital Twin architecture implemented. The database schema is flexible and future-proof, the UI framework is in place, and the reactive architecture supports real-time updates.

The path forward is clear: complete the Digital Twin interactions, implement Smart Automation for data ingestion, and build out the notification system. The architecture supports these features without major refactoring.

Estimated Completion Time: * Digital Twin polish: 1-2 weeks * Smart Automation: 2-3 weeks * Notifications: 1 week * Planning/Execution views: 2-3 weeks * Total MVP 1.0: 6-9 weeks from current state

Document maintained by Development Team Last updated: 2026-01-14 Next review: When Smart Automation begins