top of page

Home Services Quote Calculator 
Modular architecture and business-rules modeling

Executive Technical Summary

A modular Python console application that computes residential house cleaning and yard service quotes using structured, rule-driven pricing logic. The system models tier-based service pricing, labor costs, surcharges, discounts, and tax calculations while maintaining strict separation between user interaction and business logic. The project emphasizes refactoring a procedural, state-heavy implementation into a clean, object-oriented design that prioritizes correctness, clarity, and long-term maintainability.

 

Key Focus Areas: business-rule modeling, object-oriented refactoring, elimination of global state, and testable computation logic.

System Architecture Overview

The application is organized around explicit architectural boundaries that isolate pricing logic from input/output concerns.

Architecture layers:

  • CLI Interface Layer: Collects user input and displays calculated quotes

  • Quote Orchestration Layer: Coordinates quote creation and execution

  • Domain Model Layer: Encapsulates service-specific quote behavior

  • Pricing Rules Layer: Centralizes all pricing constants and rate logic

  • Calculation Utilities: Perform deterministic mathematical operations

This design ensures that pricing logic can evolve independently of the user interface.

Repository Structure

The repository is organized to isolate business-rule–driven pricing logic from user interaction and execution flow. Pricing rules, quote computation, and orchestration are implemented as independent modules, supporting testable and maintainable backend logic in Python.

  

home-services-quote-calculator/

├── src/

│   ├── house_cleaning_quote.py     # House cleaning quote logic

│   ├── yard_service_quote.py       # Yard service quote logic

│   ├── pricing_rules.py            # Centralized pricing rules

│   ├── calculator.py               # Quote orchestration

│   └── main.py                     # CLI entry point

├── README.md

└── requirements.txt

Core Design Decisions & Rationale

Refactoring from Procedural to Object-Oriented Design

The project was refactored from a procedural script using global variables into a class-based architecture.

Rationale:

  • Improves readability and reasoning about system state

  • Enables isolated testing of pricing logic

  • Reduces unintended side effects

  •  

Elimination of Global State

All pricing data and intermediate values are encapsulated within objects and passed explicitly.

Rationale:

  • Prevents hidden dependencies

  • Improves predictability and correctness

  • Simplifies debugging and extension

 

Centralized Pricing Rules

All rates, thresholds, and constants are defined in a dedicated pricing rules module.

Rationale:

  • Single source of truth for business logic

  • Simplifies future pricing changes

  • Avoids duplication and inconsistency

 

Explicit Calculation Stages

Quotes are calculated in clearly defined steps:

  1. Base service cost

  2. Labor charges

  3. Surcharges

  4. Discounts

  5. Tax calculation

  6. Final total

Rationale:

  • Improves transparency

  • Enables verification at each stage

  • Supports auditability and testing

Pricing Model & Business Rules

The system supports:

  • Tier-based house cleaning pricing by square footage

  • Yard service pricing for mowing, edging, shrub pruning, and labor

  • Property-size-based surcharges

  • Optional senior discounts

  • Sales tax applied as a final computation step

All pricing behavior is deterministic and rule-driven.

Data Flow & Calculation Pipeline

  1. User selects service type via CLI

  2. Required inputs are collected and validated

  3. Appropriate quote object is instantiated

  4. Pricing rules are applied step-by-step

  5. Final quote breakdown is displayed

 

No state persists beyond a single execution, ensuring stateless behavior.

Validation & Input Handling Strategy

Validation ensures:

  • Numeric inputs fall within expected ranges

  • Required values are provided

  • Invalid selections are rejected early

Input handling is intentionally kept separate from pricing logic.

Testing & Verification Approach

System correctness was verified through:

  • Manual execution of representative pricing scenarios

  • Boundary testing around pricing tiers and discounts

  • Verification of intermediate calculation steps

  • Refactoring validation by comparing outputs before and after redesign

The architecture is designed to support straightforward unit testing with minimal refactoring.

Tools & Technologies

  • Language: Python 3

  • Paradigm: Object-Oriented Programming

  • Execution Environment: Console application

  • Standard Library: math, dataclasses

  • Dependencies: None (standard library only)

Outcome & Engineering Takeaways

Engineering Capabilities Demonstrated

  • Refactoring procedural code into modular OO design

  • Business-rule–driven system modeling

  • Elimination of global state

  • Clear separation of concerns

  • Deterministic, testable computation logic

  

System Qualities Achieved

  • Maintainability: centralized rules and clean structure

  • Correctness: explicit, staged calculations

  • Extensibility: prepared for testing, persistence, or UI expansion

  • Clarity: readable and auditable pricing logic

bottom of page