Vacation Time Optimizer

A web application that helps users maximize their time off by finding optimal vacation periods around public holidays and weekends. Given a number of PTO days and a date range, it calculates the best combinations to get the most consecutive days off.

Tech Stack

Project Structure

```

vacation-time/

├── app/

│ ├── main.py # FastAPI entry point

│ ├── api/routes.py # API endpoints

│ ├── core/

│ │ ├── holidays.py # Nager.Date API client with caching

│ │ ├── optimizer.py # Vacation optimization algorithm

│ │ └── calendar_gen.py # ICS file generation

│ ├── models/schemas.py # Pydantic models

│ └── templates/ # Jinja2 HTML templates

├── static/style.css # Custom styles

├── tests/ # Pytest tests

├── pyproject.toml # Project configuration

└── requirements.txt # Dependencies

```

Instructions for AI Agent

When working with this codebase, follow these guidelines:

1. Understanding the Architecture

2. Development Setup

Before making changes, ensure the environment is ready:

```bash

Install dependencies

pip install -e ".[dev]"

Run development server

uvicorn app.main:app --reload

Run tests

pytest tests/ -v

Run with coverage

pytest tests/ --cov=app

```

3. Key API Endpoints

When modifying or adding endpoints, be aware of:

4. Optimization Algorithm

The core algorithm in `app/core/optimizer.py` works as follows:

1. Fetches public holidays for the specified country and date range

2. Builds a calendar marking each day as HOLIDAY, WEEKEND, or WORKDAY

3. Finds vacation "clusters" by trying different PTO allocations

4. Expands clusters to include adjacent weekends and holidays

5. Returns all unique options sorted by total days off

When modifying this logic, maintain the stateless design and ensure all edge cases are tested.

5. Testing Requirements

6. Frontend Considerations

7. Code Style and Best Practices

8. Common Tasks

**Adding a new country:**

The Nager.Date API automatically supports multiple countries - no code changes needed unless custom holiday logic is required.

**Modifying optimization logic:**

Edit `app/core/optimizer.py` and ensure tests cover the changes.

**Updating dependencies:**

Modify `pyproject.toml` and run `pip install -e ".[dev]"` to update.

**Adding new endpoints:**

Add routes to `app/api/routes.py` and corresponding templates to `app/templates/`.

Constraints

Example Usage

User provides:

The optimizer will return the best combinations of PTO allocation that maximize consecutive days off around US public holidays and weekends in 2026.