hiha-arvio/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Hiha-Arvio (Finnish: "Sleeve Estimate") is a .NET 8 MAUI cross-platform application that generates semi-random time estimates based on physical shake input (accelerometer on mobile, mouse movement on desktop). This is a humor app for "pulling an estimate from your sleeve."

Platforms (in priority order): iOS (primary) → Web (Blazor) → macOS

Critical Requirements

Specification Compliance

• ALWAYS read spec.md before implementing features - contains RFC 2119 formal requirements (MUST, REQUIRED, SHALL)
• Design reference: docs/plans/2025-11-18-hiha-arvio-design.md contains validated architecture decisions
• Nullable reference types MUST be enabled
• All compiler warnings MUST be treated as errors
• Minimum test coverage: 95% (enforced in CI/CD)

Architecture Constraints

MVVM Pattern with Strict Separation:

• Models: Plain data objects only, no business logic
• ViewModels: All presentation logic, must be 100% testable without UI dependencies
• Views: Thin layer, data binding only, minimal presentation code
• Services: All business logic and infrastructure concerns

Dependency Injection:

• All services MUST be injected via constructor (no service locator, no new keyword in ViewModels)
• Register services in MauiProgram.cs
• Platform-specific implementations use conditional compilation (#if IOS, #elif WINDOWS || MACCATALYST)

Testing Requirements

• Test coverage MUST be ≥95% (measured with Coverlet, enforced in CI/CD)
• Testing stack: xUnit + NSubstitute (mocking) + FluentAssertions (assertions)
• All tests MUST use deterministic randomness (seeded RNG)
• Mock all external dependencies (sensors, database, file system)
• Use test data builders for complex objects

Technology Stack

• Framework: .NET 8 MAUI (LTS)
• Language: C# 12 with nullable reference types
• Database: SQLite via sqlite-net-pcl
• MVVM: CommunityToolkit.Mvvm (source generators)
• Testing: xUnit, NSubstitute, FluentAssertions, Coverlet

Core Architecture

Service Layer (All Injectable)

IAccelerometerService

• Platform abstraction: accelerometer (iOS) or mouse movement (desktop/web)
• Emits observable stream of sensor data

IShakeDetectionService

• Processes accelerometer stream
• Detects shake start/stop, calculates normalized intensity [0.0-1.0]
• Tracks shake duration for easter egg trigger (>15 seconds)

IEstimateService

• Generates estimates based on: intensity, duration, mode
• Implements intensity → range mapping:
  • Intensity <0.3: narrow range (first 20% of pool)
  • Intensity 0.3-0.7: medium range (first 50% of pool)
  • Intensity >0.7: full range (entire pool)
• Easter egg: duration >15s forces Humorous mode
• MUST use cryptographically secure RNG (System.Security.Cryptography.RandomNumberGenerator)

IStorageService

• Settings: Preferences API
• History: SQLite with auto-pruning (max 10 estimates)
• All operations MUST be async

Key Models

EstimateResult: Id, Timestamp, EstimateText, Mode, ShakeIntensity, ShakeDuration
EstimateMode enum: Work, Generic, Humorous
ShakeData: Intensity, Duration, IsShaking
AppSettings: SelectedMode, MaxHistorySize

Estimate Pools (from spec.md §3.2.2)

Work Mode:

• Gentle: "2 hours", "4 hours", "1 day", "2 days", "3 days", "5 days", "1 week"
• Hard: adds "15 minutes", "30 minutes", "2 weeks", "1 month", "3 months", "6 months", "1 year"

Generic Mode:

• Gentle: "1 minute" → "3 hours"
• Hard: "30 seconds" → "1 month"

Humorous Mode (easter egg):

• "tomorrow", "eventually", "next quarter", "when hell freezes over", "3 lifetimes", "Tuesday", "never", "your retirement"

Platform-Specific Implementation

iOS (Primary Platform)

• Accelerometer via Microsoft.Maui.Devices.Sensors.Accelerometer
• Shake detection: magnitude = sqrt(x² + y² + z²), threshold 2.5g
• Must request motion permissions in Info.plist
• Haptic feedback on shake detection (recommended)
• Target iOS 15+

Web (Blazor WebAssembly)

• Mouse movement simulation: track delta over 200ms window, calculate velocity
• PWA manifest for home screen install
• Support Device Orientation API for mobile browsers (optional)

macOS

• Mouse movement tracking (similar to web)
• Keyboard shortcut: Cmd+Shift+S for manual shake trigger
• Native menu bar integration

Project Structure (When Implemented)

HihaArvio.sln
├── src/HihaArvio/              # Main MAUI project
│   ├── Models/
│   ├── ViewModels/
│   ├── Views/
│   ├── Services/
│   │   ├── Interfaces/
│   │   └── Platform/         # Platform-specific implementations
│   └── MauiProgram.cs
├── tests/
│   ├── HihaArvio.Tests/                # Unit tests
│   ├── HihaArvio.IntegrationTests/     # Integration tests
│   └── HihaArvio.UITests/              # UI automation (future)
├── docs/plans/                          # Design documents
└── spec.md                              # Formal specification

Development Commands

Build Commands

• Build all platforms: dotnet build HihaArvio.sln
• Build specific framework: dotnet build HihaArvio.sln -f net8.0
• Build iOS: dotnet build HihaArvio.sln -f net8.0-ios
• Build macOS: dotnet build HihaArvio.sln -f net8.0-maccatalyst

Test Commands

• Run all tests: dotnet test tests/HihaArvio.Tests/HihaArvio.Tests.csproj
• Run specific test class: dotnet test tests/HihaArvio.Tests/HihaArvio.Tests.csproj --filter "FullyQualifiedName~EstimateModeTests"
• Run single test: dotnet test --filter "FullyQualifiedName~TestClassName.TestMethodName"

Code Coverage

• Generate coverage: dotnet test tests/HihaArvio.Tests/HihaArvio.Tests.csproj --collect:"XPlat Code Coverage"
• Coverage files: Located in tests/HihaArvio.Tests/TestResults/{guid}/coverage.cobertura.xml

Run Commands

• iOS Simulator: dotnet build src/HihaArvio/HihaArvio.csproj -t:Run -f net8.0-ios
• macOS: dotnet build src/HihaArvio/HihaArvio.csproj -t:Run -f net8.0-maccatalyst

Notes

• All commands should be run from the repository root directory
• Xcode must be installed and configured (xcode-select -p should point to Xcode.app)
• MAUI workload must be installed (dotnet workload list should show maui)

Critical Implementation Notes

Easter Egg Behavior

• Hidden feature: NO UI indication
• Trigger: shake duration >15 seconds
• Effect: temporarily force EstimateMode.Humorous
• Do NOT expose in Settings or UI

Shake Detection Algorithm

1. Monitor sensor stream (accelerometer or mouse)
2. Calculate magnitude/velocity
3. Detect start: exceeds threshold
4. Track peak intensity during session
5. Detect end: below threshold for 500ms continuous
6. Normalize to [0.0, 1.0]

Performance Requirements

• Shake response: <100ms latency
• Estimate display: <200ms after shake stop
• History load: <500ms
• All database operations: async, non-blocking

Security

• Use System.Security.Cryptography.RandomNumberGenerator for estimate selection
• No external data transmission
• All data stored locally only
• Request minimum required permissions

Code Quality Enforcement

• Enable nullable reference types across all projects
• Treat warnings as errors
• Follow EditorConfig rules (when defined)
• Code analysis: StyleCop + built-in analyzers enabled
• CI/CD must enforce 95% coverage threshold and fail builds below this

Implementation Status

Completed Milestones

Milestone 1: Project Setup & Core Models (✅ Complete)

• Solution structure with src/HihaArvio and tests/HihaArvio.Tests
• Core models: EstimateMode, EstimateResult, ShakeData, AppSettings
• 48 tests, all passing
• Build verification: all platforms (net8.0, iOS, macOS)

Milestone 2: Services Layer (✅ Complete)

• IEstimateService + EstimateService (25 tests)
  • Estimate generation with intensity-based range selection
  • Easter egg logic (>15s → Humorous mode)
  • Cryptographically secure RNG
• IStorageService + StorageService (14 tests)
  • SQLite-based persistence
  • Settings and history storage
  • Auto-pruning based on MaxHistorySize
• IShakeDetectionService + ShakeDetectionService (22 tests)
  • Shake detection with 1.5g threshold
  • Intensity calculation and normalization (0.0-1.0)
  • Duration tracking
  • Event-based notification (ShakeDataChanged)
• Integration tests (10 tests)
  • Service interaction verification
  • Full flow: shake → estimate → storage
• Total: 119 tests, all passing
• Coverage: 51.28% line (low due to MAUI template), 87.5% branch
• Build: 0 warnings, 0 errors across all platforms

Remaining Work

Milestone 3: ViewModels Layer (Not Started)

• MainViewModel (estimate display, settings)
• HistoryViewModel (estimate history)
• SettingsViewModel (mode selection, history management)

Milestone 4: Views/UI Layer (Not Started)

• MainPage (shake screen, estimate display)
• HistoryPage (estimate list)
• SettingsPage (mode toggle, history clear)
• Navigation infrastructure

Milestone 5: Platform-Specific Implementations (Not Started)

• IAccelerometerService interface
• iOS implementation (real accelerometer)
• Desktop/Web implementation (mouse movement simulation)

Milestone 6: Integration & Polish (Not Started)

• Platform testing
• Performance optimization
• Documentation finalization

Important Implementation Order

Per design document, phased development:

1. Phase 1: iOS app (primary platform, accelerometer-based)
2. Phase 2: Web app (Blazor, mouse simulation)
3. Phase 3: macOS app (native integration)

Focus on Phase 1 first to validate core shake detection and estimate generation logic.