Keldra - Household Logistics Coordinator

Keldra is a smart household logistics coordinator that reduces the mental load of keeping your kitchen stocked. It goes beyond simple lists by telling you what to order, from where, and when.

Built with React, Firebase, and Vertex AI.

Features

Inventory Management

• Batch Tracking - FIFO (First In, First Out) consumption with expiry dates
• PDCR Learning - Per-Day Consumption Rate automatically adjusts based on usage
• Product Grouping - Consolidate product variants under canonical names
• Category Management - Default and custom categories with icons and colors

Smart Procurement

• Multi-Channel - Manage online delivery, local shops, markets, and specialty stores
• Store Configuration - Delivery windows, minimum orders, cutoff rules
• Product-Store Mapping - Assign preferred stores to products with priority
• "I'm At the Store" Mode - Context-aware shopping interface

Timeline & Projections

• 14-Day Forecast - Daily stock projections to predict when you'll run out
• Kitchen Radar - Visual timeline with health scores and events
• Event Integration - Deliveries, guest events, and meals appear in timeline
• Historical Accuracy - Compare predictions vs actuals

Recipe & Meal Planning

• Recipe Management - Create, edit, and organize recipes
• AI Recipe Generation - Generate recipes from images, text, or chat
• Meal Planning Calendar - Weekly calendar with meal slots
• Recipe-Aware Shopping - Automatically add ingredients to shopping list
• Household Ratings - Per-person recipe ratings

AI Features (Vertex AI Gemini 2.5 Flash)

• Receipt Scanning - Auto-extract items from receipt photos
• Product Parsing - Extract product details from images
• Recipe Generation - Create recipes from images or descriptions
• Smart Grouping - Suggest grouping similar products

Additional Features

• Daily Briefing - Card-based dashboard with actionable insights
• Guest Calendar - Plan for guest events with consumption impact
• Offline-First - Works without internet (Firestore persistence)
• Dark Mode - Full dark mode support
• PWA - Installable on mobile devices

Tech Stack

Layer	Technology
Frontend	React 18, TypeScript, Vite, Tailwind CSS
Backend	Firebase Cloud Functions (Node.js 20)
Database	Firestore with offline persistence
AI	Vertex AI Gemini 2.5 Flash
Hosting	Firebase Hosting
CI/CD	Google Cloud Build

Quick Start

Prerequisites

• Node.js 18+
• Firebase CLI (npm install -g firebase-tools)
• Firebase project with Firestore and Auth enabled

Installation

# Clone repository
git clone https://github.com/rutgertuit/stockmaster.git
cd stockmaster

# Install frontend dependencies
cd frontend
npm install

# Install Cloud Functions dependencies (optional)
cd ../functions
npm install

Configuration

1. Create frontend/.env with Firebase config:

VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id
VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

2. Login to Firebase:

firebase login
firebase use your-project-id

Development

cd frontend
npm run dev

Open http://localhost:5173

Deployment

# Deploy frontend
firebase deploy --only hosting

# Deploy Cloud Functions
firebase deploy --only functions

# Deploy Firestore rules
firebase deploy --only firestore:rules

Project Structure

stockmaster/
├── frontend/                # React frontend
│   ├── src/
│   │   ├── components/     # React components (85+)
│   │   ├── hooks/          # Custom hooks (22)
│   │   ├── types/          # TypeScript interfaces (16)
│   │   ├── utils/          # Utility functions (18)
│   │   └── lib/            # Firebase setup
│   └── package.json
│
├── functions/               # Cloud Functions
│   └── src/
│       ├── api/            # HTTP endpoints
│       │   ├── receiptParse.ts
│       │   ├── productParse.ts
│       │   ├── recipeParse.ts
│       │   ├── calculateTimeline.ts
│       │   └── suggestProductGrouping.ts
│       └── scheduled/      # Scheduled functions
│           ├── dailyTimelineCalculation.ts
│           └── weeklyPdcrUpdate.ts
│
├── firebase.json           # Firebase config
├── firestore.rules         # Security rules
├── firestore.indexes.json  # Database indexes
└── cloudbuild.yaml         # CI/CD config

Navigation

Tab	Description
Overzicht	Daily briefing with actionable cards
Voorraad	Product inventory with Action Deck
Boodschappen	Shopping list, stores, timeline
Planning	Recipes and meal planning
Meer	Setup, guests, settings

Data Model

All user data is scoped under households/{householdId}/:

• products - Inventory with batches and PDCR
• recipes - Recipes with ingredients and ratings
• mealPlans - Weekly meal calendar
• stores - Procurement channels
• productMappings - Product-store assignments
• timeline - 14-day projections (Cloud Functions only)
• guestEvents - Guest calendar
• consumptionEvents - Usage tracking

Documentation

Document	Purpose
SETUP_GUIDE.md	Full setup instructions
CLAUDE.md	AI assistant guidance
PROMPTS.md	AI prompts for data extraction
BUILD_PLAN.md	Architectural vision
CURRENT_STATUS.md	Detailed status
HANDOVER_NOTES.md	Quick reference
DEPLOYMENT_SETUP.md	Deployment configuration
frontend/README.md	Frontend documentation
frontend/ENV_SETUP.md	Environment setup

Development Status

Completed Phases (1-10)

• Phase 1-5: Foundation, inventory, PDCR, AI scanning, categories
• Phase 6: Store & procurement infrastructure
• Phase 7: Timeline & projection engine
• Phase 8: Daily briefing & smart UI
• Phase 9: Store-aware shopping
• Phase 10: Recipe integration & meal planning

Future Enhancements

• Phase 11: UI cleanup & refinement (deferred)

License

Private project - Keldra