# adventurestay-utils – Technical Report

## Purpose

`adventurestay-utils` encapsulates all domain logic for adventure staycation packages (trekking, hills staycation, jungle safari, lodging). Web apps, APIs, or batch jobs can import this package to validate booking requests, check availability, price itineraries, and produce summaries without duplicating business rules or pulling Django/AWS dependencies into pure Python services.

## Domain Model

- **AdventurePackage** – immutable configuration for a single experience (category, prices, capacity, inclusions, etc.).
- **BookingRequest** – validated input describing a requested stay.
- **AdventureBooking** – confirmed reservation that ties a package, validated stay window, guest count, and calculated price together.

These dataclasses provide a clear contract across services and simplify serialization.

## Flow Overview

1. Create or load an `AdventurePackage`.
2. Use `PackageBookingValidator` to verify package configuration, requested nights, and guest counts producing a `BookingRequest`.
3. Pass the booking request to `PackageAvailabilityChecker` together with existing bookings for the same package to prevent overlapping stays exceeding capacity.
4. Run `AdventurePriceCalculator` to compute the total price considering the correct base pricing model, weekend surcharges, and peak-season multipliers.
5. Construct an `AdventureBooking` and feed it to `build_itinerary_summary` to display or send human-friendly confirmations.

## Design Notes

- **Date Handling** – Dates follow `[start, end)` semantics. Nights are computed as `(end_date - start_date).days`, matching hotel-style bookings.
- **Weekend Logic** – Any night touching Saturday or Sunday increases price by `20%` to reflect high demand.
- **Peak Season** – October through January carry a `30%` multiplier. The calculator scans every day in the stay to apply the surcharge when appropriate.
- **Package Validation** – Category-specific requirements (per-night vs per-person pricing) are enforced early via `PackageBookingValidator` so downstream code can rely on consistent configuration.
- **Reusability** – No Django, database, or AWS imports are present, enabling usage in CLIs, FastAPI services, or background workers. The upcoming AdventureStay Django project imports this module to keep the view layer thin.

## Future Work

- Extend pricing with promo codes or loyalty discounts.
- Add serialization helpers for storing packages/bookings in NoSQL stores.
- Provide optional NumPy/Pandas extras for analytics without bloating the core install.
