{
  "markdown": "# EstiMate\n\nA mobile-first contractor cost estimation app that uses Monte Carlo simulation to provide probabilistic risk analysis for job quotes. Built natively for iOS (SwiftUI) and Android (Jetpack Compose).\n\n## Overview\n\nEstiMate helps tradespeople and contractors move beyond single-point estimates to understand the range of likely costs and risks. Instead of guessing a single number, you input your estimates with uncertainty levels, and the app runs thousands of simulations to show you the probability distribution of total costs.\n\n**Key Value Propositions:**\n- Offline-first, no login required\n- Sophisticated risk analysis on mobile (usually reserved for enterprise desktop software)\n- Helps contractors avoid under-quoting with statistically safe quote recommendations\n- Generates professional PDF quotes for clients\n\n## Features\n\n### Core Estimation\n- **Project Management** - Create, save, and manage multiple project estimates\n- **Line Items** - Add materials, labor, subcontractors, and other costs\n- **Risk Levels** - 5-tier uncertainty system:\n  - Certain (±2%) - Fixed/contracted prices\n  - Low (±8%) - Known suppliers with stable pricing\n  - Medium (±15%) - Standard market variability\n  - High (±25%) - Volatile or uncertain costs\n  - Wild Guess (±40%) - Unknown scope items\n\n### Duration & Travel Estimation\n- **Job Duration** - Estimated days with complexity levels (Routine ±10% to Unknown Scope ±60%)\n- **Labor Configuration** - Hourly rates, hours per day, extra workers\n- **Travel Costs** - One-way travel time, traffic variability, site visits, mileage tracking\n- **Correlation Modeling** - Duration uncertainty automatically affects travel costs\n\n### Monte Carlo Simulation\n- 1,000+ iterations with convergence detection\n- Skewed distribution toward overages (realistic for construction projects)\n- Percentile outputs: P10, P50, P80, P90, P95\n- Cost breakdown by category (Materials, Duration, Travel)\n- Standard deviation and confidence level calculations\n\n### Results & Export\n- **Bell Curve Visualization** - Color-coded histogram of cost distribution\n- **Quote Recommendations** - Conservative (P50), Recommended (P80), Safe (P90)\n- **PDF Export** - Professional client-facing quotes with cost breakdowns\n- **Share** - Export via platform share sheets\n\n### Internationalization\n| Region | Currency | Distance | Terminology |\n|--------|----------|----------|-------------|\n| US | USD ($) | Miles | Contractor, Labor |\n| UK | GBP (£) | Miles | Tradesperson, Labour |\n| Canada | CAD ($) | Kilometers | Contractor, Labour |\n| Australia | AUD ($) | Kilometers | Tradie, Labour |\n| New Zealand | NZD ($) | Kilometers | Tradie, Labour |\n\n## Tech Stack\n\n### iOS\n- **Language:** Swift\n- **UI Framework:** SwiftUI\n- **Architecture:** MVVM\n- **Min iOS:** 14.0+\n- **Storage:** UserDefaults (local only)\n- **PDF:** PDFKit/UIGraphicsPDFRenderer\n- **Charts:** Apple Charts framework (iOS 16.4+)\n\n### Android\n- **Language:** Kotlin\n- **UI Framework:** Jetpack Compose\n- **Architecture:** MVVM with ViewModel + StateFlow\n- **Min SDK:** 26 (Android 8.0)\n- **Target SDK:** 34 (Android 14)\n- **Storage:** SharedPreferences + GSON\n- **PDF:** iText 7\n- **Navigation:** Jetpack Navigation Compose\n\n## Project Structure\n\n```\ncontractors_app/\n├── ios/RiskEstimator/           # iOS application\n│   └── RiskEstimator/\n│       ├── RiskEstimatorApp.swift      # App entry point\n│       ├── ContentView.swift           # Root navigation\n│       ├── ViewModels/\n│       │   └── EstimatorViewModel.swift\n│       ├── Models/\n│       │   ├── Project.swift\n│       │   ├── LineItem.swift\n│       │   ├── Worker.swift\n│       │   └── SimulationResult.swift\n│       ├── Services/\n│       │   ├── MonteCarloEngine.swift\n│       │   ├── StorageService.swift\n│       │   └── PDFService.swift\n│       ├── Views/\n│       │   ├── Screens/\n│       │   │   ├── HomeScreen.swift\n│       │   │   ├── EstimatorScreen.swift\n│       │   │   └── ResultsScreen.swift\n│       │   └── Components/\n│       │       ├── RiskSlider.swift\n│       │       ├── ComplexitySlider.swift\n│       │       ├── TrafficSlider.swift\n│       │       ├── BellCurveChart.swift\n│       │       └── ...\n│       └── Utils/\n│           ├── Localization.swift\n│           └── CurrencyFormatter.swift\n│\n├── android/RiskEstimator/       # Android application\n│   └── app/src/main/java/com/riskestimator/app/\n│       ├── MainActivity.kt\n│       ├── ui/\n│       │   ├── RiskEstimatorApp.kt\n│       │   ├── EstimatorViewModel.kt\n│       │   ├── screens/\n│       │   │   ├── HomeScreen.kt\n│       │   │   ├── EstimatorScreen.kt\n│       │   │   └── ResultsScreen.kt\n│       │   ├── components/\n│       │   │   ├── RiskSlider.kt\n│       │   │   ├── BellCurveChart.kt\n│       │   │   └── ...\n│       │   └── theme/\n│       ├── data/\n│       │   ├── model/\n│       │   └── repository/\n│       └── domain/\n│           ├── MonteCarloEngine.kt\n│           └── PDFService.kt\n│\n├── icons/                       # App icon assets\n├── PROGRESS.md                  # Project roadmap & status\n└── contractor_app_market_research.md\n```\n\n## Architecture\n\nBoth platforms follow the **MVVM (Model-View-ViewModel)** pattern:\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                         Views                            │\n│  (SwiftUI Views / Jetpack Compose Screens)              │\n└─────────────────────────────────────────────────────────┘\n                          │\n                          ▼\n┌─────────────────────────────────────────────────────────┐\n│                     ViewModel                            │\n│  - Manages UI state                                      │\n│  - Coordinates between Views and Services               │\n│  - Triggers simulations                                  │\n└─────────────────────────────────────────────────────────┘\n                          │\n          ┌───────────────┼───────────────┐\n          ▼               ▼               ▼\n┌─────────────────┐ ┌───────────┐ ┌─────────────────┐\n│ MonteCarloEngine│ │StorageRepo│ │   PDFService    │\n│                 │ │           │ │                 │\n│ - Simulation    │ │ - CRUD    │ │ - Generate PDF  │\n│ - Statistics    │ │ - Persist │ │ - Export        │\n└─────────────────┘ └───────────┘ └─────────────────┘\n                          │\n                          ▼\n┌─────────────────────────────────────────────────────────┐\n│                        Models                            │\n│  Project, LineItem, Worker, SimulationResult            │\n└─────────────────────────────────────────────────────────┘\n```\n\n## Data Models\n\n### Project\n```swift\nstruct Project {\n    id: UUID\n    name: String\n    clientName: String\n    createdAt: Date\n    profitMargin: Double        // Default 15%\n    lineItems: [LineItem]\n    workers: [Worker]           // iOS only\n    estimatedDays: Double\n    complexityLevel: ComplexityLevel\n    hourlyLaborRate: Double\n    hoursPerDay: Double\n    travelTimeMinutes: Double\n    trafficVariability: TrafficVariability\n    numberOfSiteVisits: Int     // 0 = auto-calculate\n    includeReturnTrip: Bool\n    mileageRate: Double\n    distance: Double\n}\n```\n\n### LineItem\n```swift\nstruct LineItem {\n    id: UUID\n    name: String\n    estimatedCost: Double\n    category: ItemCategory      // Material, Labor, Subcontractor, Other\n    riskLevel: RiskLevel        // Certain, Low, Medium, High, WildGuess\n}\n```\n\n### SimulationResult\n```swift\nstruct SimulationResult {\n    simulations: [Double]       // All iteration results\n    percentile10/50/80/90/95: Double\n    mean: Double\n    standardDeviation: Double\n    min, max: Double\n    // Category breakdowns\n    materialCostP50/P80: Double\n    durationCostP50/P80: Double\n    travelCostP50/P80: Double\n    iterationsRun: Int\n    isConverged: Bool\n}\n```\n\n## Risk/Variance Multipliers\n\n| Level | Variance | Use Case |\n|-------|----------|----------|\n| **Certain** | ±2% | Fixed contracts, locked prices |\n| **Low** | ±8% | Reliable suppliers, stable costs |\n| **Medium** | ±15% | Standard market variability |\n| **High** | ±25% | Volatile materials, uncertain labor |\n| **Wild Guess** | ±40% | Unknown scope, new vendors |\n\n| Complexity | Variance | Use Case |\n|------------|----------|----------|\n| **Routine** | ±10% | Repeat jobs, familiar scope |\n| **Moderate** | ±25% | Standard projects |\n| **Complex** | ±40% | Multi-trade, custom work |\n| **Unknown Scope** | ±60% | Discovery needed, unknowns |\n\n| Traffic | Variance | Use Case |\n|---------|----------|----------|\n| **Predictable** | ±10% | Rural, fixed schedule |\n| **Variable** | ±25% | Suburban, normal traffic |\n| **High Variability** | ±50% | Urban, rush hour |\n\n## Getting Started\n\n### iOS\n\n1. Open `ios/RiskEstimator/RiskEstimator.xcodeproj` in Xcode\n2. Select your target device or simulator\n3. Build and run (⌘R)\n\n**Requirements:**\n- Xcode 14.0+\n- iOS 14.0+ deployment target\n- Swift 5.0+\n\n### Android\n\n1. Open `android/RiskEstimator` in Android Studio\n2. Sync Gradle files\n3. Select your target device or emulator\n4. Build and run\n\n**Requirements:**\n- Android Studio Hedgehog or later\n- JDK 17\n- Android SDK 26+ (min) / 34 (target)\n\n## Monte Carlo Simulation\n\nThe simulation engine uses the **Box-Muller transform** to generate normally distributed random values with optional skew toward overages (reflecting real-world project behavior).\n\n### Algorithm\n\n```\nFor each iteration (1,000 - 10,000):\n    1. For each line item:\n       - Generate random variance based on risk level\n       - Apply skewed normal distribution (bias toward overages)\n       - Calculate simulated cost\n\n    2. For duration:\n       - Generate random variance based on complexity\n       - Calculate labor cost = days × hours × rate\n\n    3. For travel:\n       - Correlate visits with duration uncertainty\n       - Generate traffic variance\n       - Calculate travel time + mileage costs\n\n    4. Sum all costs + profit margin\n\nCalculate statistics from all iterations\nCheck for convergence (P80 standard error < 0.5%)\n```\n\n### Convergence Detection\n\nThe engine runs adaptively:\n- Minimum: 1,000 iterations\n- Maximum: 10,000 iterations\n- Stops early if P80 estimate stabilizes (standard error < 0.5%)\n\n## PDF Generation\n\nQuotes are generated for client presentation:\n- Professional formatting with project details\n- Cost breakdown by category\n- Profit margin folded into category costs (hidden from client)\n- No Monte Carlo jargon - just clear pricing\n- Exportable via platform share sheets\n\n## Storage\n\nBoth platforms use local-only storage:\n- **iOS:** UserDefaults with Codable serialization\n- **Android:** SharedPreferences with GSON\n\nNo cloud sync, no server required - works fully offline in the field.\n\n## Current Status\n\n**Version:** 1.1 (MVP Feature-Complete)\n\n### Completed\n- Full CRUD on projects\n- Monte Carlo engine with convergence detection\n- 5-tier risk system\n- Duration and travel uncertainty\n- Cost breakdown by category\n- PDF export\n- Multi-region/currency support\n\n### Roadmap (Phase 3)\n- [ ] Unit tests for simulation engine\n- [ ] Comprehensive error handling\n- [ ] Input validation\n- [ ] Crash reporting integration\n- [ ] Android release minification\n\nSee [PROGRESS.md](./PROGRESS.md) for detailed roadmap.\n\n## License\n\nProprietary - All rights reserved.\n",
  "bytes": 11229,
  "sha": "aa4bf6a65c76b567d0057d13e19afe884692349466d222a647c6af3d6ffa9f0d",
  "repo_slug": "physics-star-cat/contractors_app",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_physics_star_cat_lowriskquotes_38a791f3/readme"
}