Materials And Practices

Executive Summary

MaterialsAndPractices is a comprehensive iOS application designed to support small-scale organic farming operations. The app serves as both a cultivation tracking system and an organic certification compliance tool, helping farmers maintain detailed records required for organic certification while optimizing their growing practices.

Key Features

• Plant Cultivar Database: Utilizes USDA open source data to provide detailed information on plant cultivars including growing seasons, hardy zones, and planting schedules
• Organic Certification Tracking: Maintains comprehensive records of all activities, amendments, and safety practices required for organic certification compliance
• Grow Management: Track active and completed growing operations with detailed timelines and outcomes
• Soil Health Monitoring: Comprehensive soil testing tools with visual pH spectrum, nutrient analysis, and laboratory management
• Lease Management: Complete agricultural lease agreement system with payment tracking and document generation
• Worker Time Tracking: Comprehensive time clock system with overtime detection and weekly reporting
• Safety Compliance: Built-in harvest safety checklists based on FDA Food Safety Modernization Act (FSMA) requirements
• Amendment Tracking: Record and track all soil amendments and organic inputs with full traceability
• Multi-language Support: Complete localization system with English and Spanish support

Application Architecture

Technology Stack

• Platform: iOS (SwiftUI), universal iPhone/iPad
• Data Persistence: Core Data with CloudKit sync (NSPersistentCloudKitContainer)
• Design System: Custom theming with light/dark mode support
• Device Support: Universal app — DataModelClasses/DeviceDetection.swift exposes size/orientation helpers used by adaptive views

View Hierarchy

MaterialsAndPracticesApp (Root)
├── ContentView (TabView Container)
│   ├── CurrentGrowsView (Active Grows Management)
│   │   ├── GrowRow (Individual Grow Display)
│   │   ├── EditGrowView (Create/Edit Grows)
│   │   └── GrowDetailView (Detailed Grow Information)
│   │       ├── WorkPractices (Work Activity Tracking)
│   │       ├── Amendments (Amendment Applications)
│   │       └── HarvestSafetyChecklistView (Safety Compliance)
│   └── CultivarListView (Plant Cultivar Database)
│       └── CultivarDetailView (Detailed Cultivar Information)
│           ├── Active Grows Grid (Current Cultivations)
│           └── Completed Grows Grid (Historical Data)

Core Data Models

• Cultivar: Plant variety information (USDA sourced)
• Grow: Individual growing operation tracking
• Work: Work activities and practices performed
• Amendment: Soil amendments and organic inputs applied
• SoilTest: Soil chemistry analysis results with pH, nutrients, and organic matter
• Lab: Laboratory contact information and testing history
• Field: Field management with soil test integration

Key Components

• CultivarSeeder: Populates database with USDA vegetable cultivar data
• Theme System: Centralized color and typography management
• Safety Compliance: FDA FSMA harvest safety checklist implementation
• Soil Testing Suite: pH spectrum visualization, nutrient analysis, and lab management
• Graphics Engine: Core Graphics components for soil health visualization

Development Guidelines

The codebase is plain SwiftUI over Core Data. The conventions worth knowing:

• Core Data entities use codeGenerationType="class" — Xcode auto-generates the NSManagedObject subclasses at build time. Per-entity business logic lives in DataModelClasses/<Entity>+Helpers.swift and <Entity>Extensions.swift files (the canonical extensions); do not hand-write +CoreDataClass.swift files at the source root.
• The Xcode project (Xcode 16+) uses PBXFileSystemSynchronizedRootGroup for most folders, so adding a .swift file to a registered folder is enough to wire it into the build — no manual project.pbxproj editing per file. Look at MaterialsAndPracticesApp.swift, Persistence.swift (under Core/), and the DataModelClasses/ extensions for the patterns in current use.
• SwiftUI views compose via NavigationView / NavigationStack with @FetchRequest for Core Data-backed lists. Theming goes through AppTheme (SharedUIViews/AppTheme.swift).
• DeviceDetection.swift provides device-class and orientation helpers; views can opt in to adaptive layouts via these, but there is no separate iPad-only navigation hierarchy.

Data Sources

Plant cultivar information is sourced from USDA open data initiatives, providing accurate and up-to-date information on:

• Plant families and varieties
• Growing seasons and climate zones
• Optimal planting schedules
• Hardy zone compatibility

Organic Certification Support

The application maintains detailed records supporting organic certification requirements including:

• Complete input tracking and traceability
• Worker safety training documentation
• Harvest safety protocol compliance
• Amendment application records with timing and quantities

Worker Time Clock System

The application includes a comprehensive time tracking system for farm workers with the following features:

Time Clock Functionality

• Clock In/Out: Workers can clock in and out with automatic time tracking
• Weekly Calculations: Automatic calculation of work hours for Monday through Sunday work weeks
• Overtime Detection: Automatic detection and highlighting of overtime hours (>40 hours/week)
• Multi-Worker Support: Independent time tracking for multiple workers
• Data Integrity: Proper handling of incomplete time entries and week boundary calculations

Test Coverage

The time clock system includes comprehensive test coverage with all tests passing:

✅ Basic Time Clock Tests

• testCreateTimeClockEntry - Validates time clock entry creation and worker relationships
• testClockInClockOut - Tests clock in/out functionality and hours calculation

✅ Weekly Hours Calculation Tests

• testWeeklyHoursCalculation - Validates accurate weekly hour totals across Monday-Sunday
• testOvertimeDetection - Tests overtime detection for hours exceeding 40/week
• testWeekBoundaryCalculation - Ensures proper week separation (Sunday to Monday transitions)
• testYearAndWeekNumberTracking - Validates correct year and week number storage

✅ Edge Cases Tests

• testMultipleWorkersTimeTracking - Ensures independent tracking for multiple workers
• testIncompleteTimeEntry - Handles active/incomplete time entries properly

Build and Test Instructions

To run the tests:

# Using Xcode
xcodebuild test -scheme MaterialsAndPractices -destination 'platform=iOS Simulator,name=iPhone 14'

# Using Xcode GUI
# Open MaterialsAndPractices.xcodeproj
# Press Cmd+U to run all tests
# Navigate to Test Navigator to run specific test suites

🧪 Test Coverage Status

✅ Time Clock System Tests (TimeClockTests.swift)

All time clock tests pass validation ensuring reliable worker time tracking functionality:

Basic Time Clock Tests

• ✅ testCreateTimeClockEntry - Validates time clock entry creation and worker relationships
• ✅ testClockInClockOut - Tests clock in/out functionality and hours calculation

Weekly Hours Calculation Tests

• ✅ testWeeklyHoursCalculation - Validates accurate weekly hour totals across Monday-Sunday
• ✅ testOvertimeDetection - Tests overtime detection for hours exceeding 40/week
• ✅ testWeekBoundaryCalculation - Ensures proper week separation (Sunday to Monday transitions)
• ✅ testYearAndWeekNumberTracking - Validates correct year and week number storage

Edge Cases Tests

• ✅ testMultipleWorkersTimeTracking - Ensures independent tracking for multiple workers
• ✅ testIncompleteTimeEntry - Handles active/incomplete time entries properly

✅ Harvest Calendar Tests (HarvestCalendarTests.swift)

Comprehensive harvest calendar functionality with date range validation:

Harvest Quality and Calculation Tests

• ✅ testHarvestQualityColors - Validates harvest quality visual indicators and opacity values
• ✅ testHarvestQualityCalculation - Tests harvest quality determination for different weeks
• ✅ testGrowingSeasonBoundaries - Validates growing season boundaries (weeks 10-40)

Harvest Calculator Tests

• ✅ testBasicHarvestCalculation - Tests harvest period calculations for standard cultivars
• ✅ testShortSeasonCrop - Validates calculations for fast-growing crops (25-30 days)
• ✅ testLongSeasonCrop - Tests calculations for long-season crops (95-120 days)
• ✅ testYearBoundaryHarvest - Handles harvest calculations across year boundaries
• ✅ testInvalidGrowingDays - Gracefully handles invalid growing days formats

Week Number and Date Range Tests

• ✅ testWeekNumberCalculations - Validates week number calculations throughout the year
• ✅ testConsecutiveWeekNumbers - Tests week number consistency across boundaries
• ✅ testCultivarGrowingDaysParsing - Tests parsing of various growing days formats
• ✅ testCultivarInvalidGrowingDays - Handles invalid growing days with defaults

Performance Tests

• ✅ testHarvestCalculationPerformance - Ensures calculations are fast enough for real-time use
• ✅ testHarvestQualityPerformance - Validates performance of quality lookups

✅ Device Detection and Adaptive UI Tests (DeviceDetectionAndAdaptiveUITests.swift)

Tests for the device-detection helpers and responsive layout calculations in DataModelClasses/DeviceDetection.swift:

Device Detection Tests

• ✅ testDeviceTypeDetection - Tests detection of iPad, iPhone, and iPad Pro variants
• ✅ testIPadProSizeDetection - Tests iPad Pro size variant detection (11" vs 12.9")
• ✅ testDeviceOrientationDetection - Tests landscape/portrait orientation detection

Size Class and Responsive Design Tests

• ✅ testColumnCountCalculation - Tests adaptive column count for different size classes
• ✅ testNavigationStyleDetection - Tests sidebar vs tab navigation selection
• ✅ testAdaptiveSpacingCalculation - Tests responsive spacing calculations
• ✅ testAdaptivePaddingCalculation - Tests responsive padding calculations

Dashboard and Layout Tests

• ✅ testDashboardTileCalculations - Tests tile sizing for different screen widths
• ✅ testTileGridLayout - Tests grid layout calculations for dashboard tiles
• ✅ testResponsiveImageSizing - Tests image scaling while maintaining aspect ratio
• ✅ testResponsiveFontSizing - Tests font scaling for different screen sizes

Accessibility Tests

• ✅ testAccessibilityScaling - Tests scaling for different content size categories
• ✅ testMinimumTouchTargetSize - Tests minimum 44pt touch target enforcement

Performance and Edge Case Tests

• ✅ testDeviceDetectionPerformance - Ensures device detection is fast enough
• ✅ testSizeClassCalculationPerformance - Tests layout calculation performance
• ✅ testResponsiveLayoutPerformance - Tests responsive layout performance
• ✅ testZeroAndNegativeSizes - Handles edge cases with zero/negative values
• ✅ testExtremeAspectRatios - Handles extreme aspect ratios gracefully

📊 Test Summary

• Total Test Files: ~34 active suites (run find MaterialsAndPracticesTests -name "*.swift" for the current list).
• Coverage Areas: Time tracking & multi-block clock, harvest calendar, harvest creation, device detection, navigation flow, view loading, Core Data notifications, lease workflow, work-order/amendment flows, supplier and training workflows, localization, color assets, profile images, environment configuration, seed library, Zappa Farms data loader, and more.
• Status: 0 failing, with 11 deliberately skipped tests carrying XCTSkip comments that document the structural fix needed (see SUGGESTED_UPDATES.md for the inventory).

The detailed sections above (TimeClockTests, HarvestCalendarTests, DeviceDetectionAndAdaptiveUITests) describe three representative suites. Other notable suites include HarvestCreationTests (regression coverage for the lot-code/Core-Data-rename work), ZappaFarmsDataLoaderTests, and WorkSegmentTimeClockIntegrationTests.

🚀 Running Specific Test Suites

# Run time clock tests only
xcodebuild test -scheme MaterialsAndPractices -destination 'platform=iOS Simulator,name=iPhone 14' -only-testing:MaterialsAndPracticesTests/TimeClockTests

# Run harvest calendar tests only
xcodebuild test -scheme MaterialsAndPractices -destination 'platform=iOS Simulator,name=iPhone 14' -only-testing:MaterialsAndPracticesTests/HarvestCalendarTests

# Run device detection tests only
xcodebuild test -scheme MaterialsAndPractices -destination 'platform=iOS Simulator,name=iPhone 14' -only-testing:MaterialsAndPracticesTests/DeviceDetectionAndAdaptiveUITests

Documentation

For comprehensive project documentation, please see the docs/ directory:

• docs/USER_GUIDE.md - Complete user guide for farmers and farm managers
• docs/FarmLedgerSchema.md - Farm accounting and record-keeping guidance
• docs/ARCHITECTURE.md - Application architecture overview
• docs/DATASTRUCTURE.md - Core Data schema documentation
• docs/LEASE_IMPLEMENTATION_SUMMARY.md - Lease management system documentation
• docs/HELP_SYSTEM_INTEGRATION.md - In-app help system and localization
• docs/WORKER_MANAGEMENT_IMPLEMENTATION.md - Worker time tracking documentation
• docs/COLOR_THEME_DOCUMENTATION.md - Design system and theming guide
• SUGGESTED_UPDATES.md - Recommended improvements for future iterations