Skip to content

concepts-and-terminology.md

Latest commit

 

History

History
376 lines (260 loc) · 17 KB

concepts-and-terminology.md

File metadata and controls

376 lines (260 loc) · 17 KB

Menlo Home Management - Concepts & Terminology Guide

Overview

This document defines the key concepts, terminology, and design philosophy that guide the Menlo Home Management Application. These concepts emerged from our analysis of family workflows and AI integration patterns.

Core Design Philosophy

The "Blueberry Muffin" Approach to AI Integration

Definition: A design philosophy where AI agents are embedded seamlessly into existing workflows, like blueberries distributed throughout a muffin, rather than existing as separate, distinct features.

Origin: Named for how blueberries get added as part of the baking process, being added throughout the mixture and not inserted after the baking process as an afterthought.

Key Principles:

  • Embedded Intelligence: AI capabilities are woven into each feature rather than existing as standalone AI tools
  • Non-Intrusive Enhancement: AI operates in the background, providing suggestions without disrupting natural workflows
  • Contextual Awareness: AI understands the broader family context and cross-feature relationships
  • Natural Integration: Users interact with enhanced features, not "AI features"

Implementation Examples:

  • Planning Lists: AI interprets handwritten lists and suggests budget impact, but the wife still makes lists naturally
  • Budget Analysis: AI provides variance insights within the budget view, not as separate AI reports
  • Transaction Categorization: AI suggests categories during transaction entry, learning from corrections
  • Event Scheduling: AI detects conflicts during event creation, not as separate calendar analysis

What we want to avoid:

  • ❌ Separate "AI Assistant" tab with chat interface
  • ❌ "Generate with AI" buttons throughout the app
  • ❌ Distinct AI-powered features that require learning new workflows

As an alternative we have the Blueberry Muffin Pattern:

  • ✅ Enhanced budget variance detection with AI insights inline
  • ✅ Smart categorization suggestions during transaction entry
  • ✅ Contextual budget impact warnings during list creation
  • ✅ Intelligent conflict detection during event scheduling

User-Centric Concepts

The "CFO-COO Family Dynamic"

Definition: A recognition that family financial management naturally divides into strategic (CFO) and operational (COO) roles, requiring different tools and perspectives.

CFO Role (Husband):

  • Strategic financial planning and analysis
  • Budget variance analysis and optimization
  • Rental income modelling and ROI calculations
  • Tax planning and compliance reporting
  • Long-term financial goal tracking

COO Role (Wife):

  • Operational planning and coordination (shopping lists, meal planning)
  • Day-to-day family scheduling and event coordination
  • Resource allocation for immediate family needs
  • Workflow optimization for family efficiency

Design Implication: The application provides role-appropriate interfaces and AI assistance while maintaining shared data visibility.

"Natural Workflow Preservation"

Definition: The principle that technology should enhance existing successful workflows rather than replace them with "better" digital alternatives.

Wife's Handwritten Lists Example:

  • Natural Workflow: Wife writes shopping/planning lists by hand (muscle memory, thinking process)
  • Enhancement: Photo capture + AI interpretation provides digital benefits without disrupting the writing process
  • Value Add: Budget impact analysis, smart suggestions, family coordination - all invisible to the core workflow

Key Benefits:

  • Zero learning curve for primary workflow
  • Maintains cognitive benefits of handwriting
  • Adds digital coordination without digital friction
  • Respects personal productivity patterns

Technical Philosophy

"Privacy-First Local AI"

Definition: An architectural approach that prioritizes data privacy by processing all AI tasks locally, avoiding external AI service dependencies.

Implementation:

  • Local Models: Ollama hosting Microsoft Phi models on home server
  • No Cloud AI: No data sent to OpenAI, Claude, or other external AI services
  • Family Data Sovereignty: All financial and personal data remains within family control
  • Cost Control: No per-token or usage-based AI costs

Benefits:

  • Complete family financial data privacy
  • Predictable AI processing costs
  • No internet dependency for AI features
  • Full control over AI model versions and updates

"Hybrid Cloud-Local Architecture"

Definition: A hosting strategy that combines cloud benefits (global CDN, reliability) with local control (data sovereignty, cost efficiency) using secure tunnelling.

Architecture Components:

  • Global Frontend: Cloudflare Pages (Angular PWA) for fast, distributed UI delivery
  • Secure Tunnel: Cloudflare Tunnel eliminates static IP requirement
  • Local Backend: Home server provides full data control and AI processing
  • Cost Optimization: ~80% cost reduction vs. full cloud hosting

"Cost-Conscious Experimentation"

Definition: An approach to technology adoption that prioritizes learning and validation over enterprise-grade infrastructure during the experimental phase.

Principles:

  • Low Initial Investment: Start with minimal hosting costs (~R165-365/month)
  • Validation-First: Prove family adoption before scaling infrastructure
  • Migration Path: Design for potential cloud migration if successful
  • South African Context: Consider local internet infrastructure and pricing

AI Integration Patterns

"Contextual Intelligence"

Definition: AI that understands relationships between different family management domains (budget, planning, scheduling) and provides cross-domain insights.

Examples:

  • Budget-Aware Scheduling: Event planning considers budget implications
  • Planning-Informed Budgeting: Shopping lists influence budget projections
  • Historical Pattern Learning: AI learns family patterns across all domains

"Correction-Based Learning"

Definition: An AI improvement mechanism where user corrections to AI suggestions become training data for better future suggestions.

Implementation:

  • Category Corrections: When users fix transaction categories, AI learns family-specific patterns
  • Budget Adjustments: When users modify AI budget suggestions, the system learns preferences
  • Scheduling Preferences: When users override AI scheduling suggestions, personal preferences are learned

Privacy Benefit: Learning happens locally without sending correction data to external services.

South African Context

"Local Financial Ecosystem Integration"

Definition: Design considerations specific to South African financial and regulatory environment.

Considerations:

  • SARS Compliance: Rental income reporting and deductible expense tracking
  • Banking Integration: CSV import support for major SA banks (FNB, Standard Bank, etc.)
  • Municipal Services: Electricity, water, and rates billing integration
  • Currency and Formatting: Rand (R) formatting and South African date formats

"Infrastructure Reality"

Definition: Acknowledging South African internet and hosting infrastructure realities in architectural decisions.

Factors:

  • Load Shedding: Power reliability considerations for home server hosting
  • Internet Costs: Data usage optimization for mobile family members
  • Latency: Johannesburg-based Cloudflare presence for optimal performance
  • ISP Options: Fiber, LTE, and fixed wireless considerations

Development Principles

"Vertical Slice Architecture"

Definition: A code organization pattern where features are implemented as complete vertical slices from UI to database, minimizing cross-cutting dependencies.

Benefits:

  • Independent Development: Features can be built and deployed independently
  • Clear Ownership: Each feature slice has clear responsibility boundaries
  • AI Integration: AI components are feature-specific rather than monolithic

"Progressive Enhancement"

Definition: A development approach where core functionality works without AI, and AI features enhance the experience progressively.

Implementation:

  • Baseline Functionality: Budget tracking, list management, event scheduling work without AI
  • AI Enhancement: Categorization, suggestions, insights add value on top
  • Graceful Degradation: System remains functional if AI components are unavailable

"Rich Domain Model with Agentic AI"

Definition: A domain-driven design approach where business logic is encapsulated in rich domain models, with agentic AI capabilities exposed as domain services through inversion of control patterns.

Core Principles:

  • Domain-Centric Architecture: Business rules and workflows are expressed in the domain layer, not in controllers or infrastructure
  • Agentic AI as Domain Services: AI agents are modelled as domain services that implement business interfaces
  • Inversion of Control: Domain models depend on AI abstractions, not concrete AI implementations
  • Infrastructure Separation: AI processing (Ollama, model management) is isolated in the infrastructure layer

Implementation Pattern:

// Domain Layer - Rich aggregate root with AI capabilities
public class PlanningList : AggregateRoot
{
    private readonly IBudgetImpactAnalyser _budgetAnalyser;
    
    public PlanningList(IBudgetImpactAnalyser budgetAnalyser)
    {
        _budgetAnalyser = budgetAnalyser;
    }
    
    public async Task<BudgetImpact> AnalyzeBudgetImpactAsync()
    {
        // Rich domain logic orchestrates AI capabilities
        return await _budgetAnalyser.AnalyzeImpactAsync(this.Items, this.TimeFrame);
    }
}

// Domain Service Interface
public interface IBudgetImpactAnalyser
{
    Task<BudgetImpact> AnalyzeImpactAsync(IEnumerable<PlanningItem> items, TimeFrame timeFrame);
}

// Infrastructure Layer - Concrete AI implementation
public class OllamaBudgetImpactAnalyser : IBudgetImpactAnalyser
{
    // Ollama integration details isolated here
}

Benefits:

  • Testability: Domain logic can be unit tested with mock AI services
  • Flexibility: AI implementation can be swapped (local Ollama vs cloud services) without changing domain logic
  • Business Focus: Domain models express business concepts, not technical AI concerns
  • Maintainability: Clear separation between business rules and AI infrastructure

"Purpose-Driven Naming"

Definition: A naming convention that describes what components do or their capabilities, avoiding generic suffixes like "Service", "Manager", or "Helper".

Good Examples:

  • BudgetImpactAnalyser - describes what it analyses
  • TransactionCategorizer - describes what it categorizes
  • ListPhotoInterpreter - describes what it interprets
  • ScheduleConflictDetector - describes what it detects
  • RentalIncomeCalculator - describes what it calculates

Avoid:

  • IntelligentBudgetService - generic "Service" suffix
  • AIListManager - generic "Manager" suffix
  • SmartScheduleHelper - generic "Helper" suffix
  • BudgetAIService - technology prefix + generic suffix

Benefits:

  • Clear Intent: Names immediately convey purpose and responsibility
  • Domain Language: Uses terminology from the family finance domain
  • Future-Proof: Names remain relevant regardless of implementation technology
  • Self-Documenting: Reduces need for additional documentation to understand component purpose

Success Metrics Philosophy

"Family Adoption Over Technical Metrics"

Definition: Prioritizing actual family usage and satisfaction over traditional technical performance metrics.

Key Metrics:

  • Wife's List Usage: Primary indicator of workflow integration success
  • Budget Accuracy: Improvement in budget variance tracking
  • Family Coordination: Reduction in scheduling conflicts and miscommunication
  • Cost Effectiveness: Maintaining target monthly hosting costs

"Sustainable Complexity"

Definition: Balancing advanced AI capabilities with maintainable, understandable systems that a single developer can manage.

Guidelines:

  • Local-First: Prefer local processing over complex cloud orchestration
  • Standard Technologies: Use established frameworks (EF Core, Angular) over cutting-edge alternatives
  • Clear Abstractions: AI integration through well-defined interfaces
  • Documentation-Driven: Every pattern and decision documented for future reference

How to Use This Guide

This guide serves multiple audiences and use cases:

For Developers

For Stakeholders

For System Architecture

Quick Lookups

  • Terminology Quick Reference table for definitions
  • Search for specific terms using your browser's find function (Ctrl+F)
  • Link to related documents for deeper technical details

Terminology Quick Reference

Term Definition
Blueberry Muffin AI AI embedded throughout workflows, not as separate features
CFO-COO Dynamic Strategic (husband) vs operational (wife) role differentiation
Natural Workflow Preservation Enhancing existing workflows rather than replacing them
Privacy-First Local AI All AI processing on home server, no external AI services
Hybrid Cloud-Local Frontend in cloud, backend/data on home server
Cost-Conscious Experimentation Low-cost validation before scaling investment
Contextual Intelligence AI that understands cross-domain relationships
Correction-Based Learning AI improvement through user feedback loops
Vertical Slice Architecture Feature-complete slices from UI to database
Family Adoption Metrics Success measured by actual family usage, not technical KPIs

This guide serves as the philosophical and terminological foundation for the Menlo Home Management Application, ensuring consistent understanding across all documentation and development efforts.