Inspiration
ErrandOS started with a familiar problem: a list of errands looks simple until the day begins. A grocery run, a package drop-off, a pharmacy pickup, and a stop at the dry cleaner may each be easy on their own. Put them together, add business hours and a fixed deadline, and it becomes harder to decide what to do first and how to avoid driving back and forth.
Most to-do lists capture what needs doing, but they don’t help much with when or where. A route app can take you from one address to another, but it usually expects you to already know which stops to make and in what order. ErrandOS brings those pieces together: it aims to turn an unstructured list into a practical plan for the day.
The idea is to make planning feel lighter. Instead of asking someone to manually estimate each stop, consider every time constraint, and compare possible routes in their head, ErrandOS can help structure the list and produce an itinerary. The map and schedule make the plan easier to scan, while a baseline comparison gives users a sense of the potential time and fuel savings.
We also wanted the app to remain approachable when external services aren’t configured. That is why the project includes demo and fallback behavior: someone can explore the flow without first setting up AI or geocoding credentials. The Johns Creek demo errands offer a concrete example of the kind of day the product is designed to plan.
The broader inspiration is that small planning improvements can make a busy day feel more manageable. ErrandOS is not meant to make a person’s decisions for them. It is meant to take some of the route math and schedule coordination off their plate, so they can review a proposed order and adjust their plans with more context.
What it does
ErrandOS helps a user turn errands into a scheduled route. On the frontend, the user can enter errands or provide a plain-language description for extraction. Errands can carry details such as a location, estimated duration, priority, and timing constraints. The structured list gives the planner more useful information than a set of task names alone.
Once the errands are ready, the app can build an itinerary from a departure time and optional start or final destination. The backend uses travel-time and distance data to assess stop sequences. It accounts for timing constraints such as earliest and latest arrival, opening and closing times, and a final arrival deadline. It then returns ordered stops with estimated arrival and departure times, travel durations, distances, and any constraint warnings.
The itinerary view pairs a stop list and schedule with a map, so a user can inspect the proposed route geographically and chronologically. ErrandOS also compares the optimized plan with a baseline order and calculates estimated differences in travel time, distance, fuel use, and fuel cost. Fuel estimates use vehicle mileage and fuel price assumptions, which can be adjusted through configuration.
The experience is designed to keep working in a demo setup. The frontend includes sample errands and simulated optimization, while backend services include fallbacks for unavailable optional providers. This lets someone try the product without an AI API key. Actual extraction, geocoding, and routing behavior depends on the configured services and available location data.
The project exposes a FastAPI backend with endpoints for extracting errands, optimizing itineraries, geocoding locations, and checking service health. The Next.js frontend provides the landing page, planner, itinerary, execution, and settings screens. Together, these parts demonstrate a workflow from raw errand input through a route a user can review.
How we built it
ErrandOS is a small full-stack application with a Next.js frontend and a FastAPI backend. The frontend uses React and TypeScript for its pages and components, with Tailwind CSS for styling. Its app routes separate the landing page, planner, itinerary, execution view, and settings. Shared components handle errand entry, list display, metrics, and map presentation.
The planner connects to backend endpoints through a frontend API client. It supports turning natural-language text into structured errands, then submits the errand data and planning details to the optimization endpoint. Itinerary state is shared in the frontend so the user can move from planning to reviewing the resulting route. The map is rendered with Leaflet and React Leaflet, loaded dynamically so browser-only map code is not evaluated during server-side rendering.
The backend is organized around FastAPI routes, Pydantic schemas, and service modules. The schemas define the shapes of errand requests, itinerary requests, stops, and optimization results. The extraction service can use an optional AI provider, while fallback parsing allows the demo to remain usable without that integration. Geocoding and routing are also designed around configurable providers and fallback behavior.
For optimization, the service obtains travel-time and distance matrices, then evaluates possible stop orders. The implementation has multiple strategies: exhaustive search for smaller errand sets, a heuristic for larger sets, and an OR-Tools path when that dependency is available. Timing constraints are represented during evaluation, and infeasible sequences can be rejected. The service also builds a baseline route, which feeds the savings calculations.
The savings service derives estimated fuel usage and cost from distance, vehicle MPG, and fuel price. This keeps the assumptions visible as configuration rather than treating the displayed numbers as universal facts. The API returns the optimized result, baseline, savings, and a flag indicating whether the result is simulated.
We used environment variables for optional AI, geocoding, routing, and vehicle configuration. The repository includes an .env.example, backend tests, and a SPEC.md describing API contracts. This separation makes it easier to evolve the interface and services independently while keeping their request and response shapes documented.
Challenges we ran into
One challenge was translating casual language into structured data. People describe errands in different ways: they may mention a store, a deadline, a closing time, or an approximate duration in the same sentence. An application needs to extract those details into fields consistently, yet provider availability and model behavior can vary. We addressed this by defining structured schemas and keeping fallback parsing available, but extraction quality remains something that benefits from real-world examples and continued refinement.
Routing with constraints is another challenge. A route that is shortest by distance may be a poor plan if a pharmacy closes early or an appointment has a fixed arrival window. The optimizer therefore needs to account for travel, stop durations, and time windows, and explain when a route cannot satisfy them. This is more involved than sorting errands by proximity. Different optimization approaches also have different tradeoffs: exhaustive search can consider all orders for small lists, while a heuristic can return a result more quickly as the number of stops grows.
External location and routing services introduce uncertainty. Geocoding can return ambiguous results, routing services can be unavailable, and the quality of a route depends on coordinates and travel estimates. The demo and fallback paths help make the product usable without credentials, but simulated values must be distinguishable from provider-backed results so people don’t mistake estimates for live directions.
We also had to connect backend results to a coherent frontend flow. Errands begin as user input, become structured objects, move into an optimization request, and then need to appear consistently across the schedule, map, and metrics. Preserving data and state across those views is important, especially when a user navigates between planning and reviewing the itinerary.
Finally, communicating savings responsibly is not trivial. A comparison needs a baseline, and fuel cost depends on assumptions such as vehicle efficiency and price per gallon. The calculations can help users understand a potential difference, but they should be presented as estimates rather than guarantees. Making these assumptions explicit and ensuring demo-mode figures are clearly labeled are important next steps for trust and clarity.
Accomplishments that we're proud of
We’re proud that ErrandOS demonstrates an end-to-end planning workflow rather than stopping at a mockup or a single optimization function. A user can begin with a list of errands, structure the tasks, request an itinerary, and inspect the result through both a schedule and map. The pieces are connected through documented API contracts and shared frontend state.
The project also brings together several concerns that often live in separate tools: natural-language task extraction, time-aware ordering, route visualization, and a comparison against a baseline. Errand planning is not just a mapping problem, and the app reflects that by including estimated stop duration and timing constraints in the planning model.
We’re proud of the range of optimizer strategies in the backend. It can use exhaustive search for smaller errand sets, a heuristic for larger sets, and OR-Tools if that library is available. Having more than one path gives the project a way to balance route quality and compute time as the problem size changes. The optimizer also has a way to report infeasible time-window scenarios rather than silently presenting every route as valid.
The demo path is another accomplishment. Optional AI and geocoding credentials can complicate first use, so the included sample day and fallbacks make it easier to try the product locally. That matters for project reviews and development: people can exercise the overall experience before configuring external providers.
We also built the app with practical structure. The frontend separates pages and reusable components, the backend groups routes, models, and services, and the API shape is captured in SPEC.md. Backend tests cover areas such as schemas, optimization, savings, geocoding, extraction, and health checks. This gives future contributors a clearer starting point than a single large file would.
Finally, the product has a clear identity and a focused promise: “Your day. Optimized.” The landing page explains the core value in accessible terms, while the planner and itinerary views support that message with a concrete workflow. ErrandOS is still a prototype with room to improve, but it already communicates and demonstrates the central idea: help people coordinate a multi-stop day with less manual planning.
What we learned
Building ErrandOS reinforced that a useful planning tool depends on more than a clever route algorithm. The input data matters just as much. If an errand lacks a reliable location, if its duration is inaccurate, or if its deadline is unclear, even a strong optimizer cannot produce a dependable schedule. We learned to treat extraction, validation, and user review as core parts of the experience rather than plumbing around the algorithm.
We learned that constraints make planning meaningfully different from simple sorting. The closest stop is not always the best next stop, and a short route can still fail if it arrives after a business closes. Representing earliest arrivals, latest arrivals, stop time, and final deadlines helped us think about the user’s day as a schedule, not just a sequence of map pins.
We also saw why fallback behavior matters. External AI, geocoding, and routing services can make an application more capable, but they can add configuration steps and failure modes. A demo experience lets a reviewer or developer understand the product without external credentials. At the same time, fallback results should be communicated clearly. Simulated locations and estimates are useful for demonstrating a workflow, but users need to know when data is approximate.
Another lesson was to make assumptions inspectable. Fuel savings depend on vehicle mileage and fuel price, and route comparisons depend on how the baseline is defined. Showing an estimate without its underlying assumptions can imply more certainty than the system has. Returning those values and documenting them helps make the calculation understandable and opens a path to user-specific settings.
We learned that good architecture helps product iteration. Separating UI components, API routes, schemas, and service logic makes it possible to refine one part without rewriting the entire app. Keeping the API contract in SPEC.md also gives frontend and backend work a shared reference point.
Most of all, we learned to think through the whole interaction. A technically valid optimized route is not enough if the user cannot understand why a stop comes first, see the schedule, or recognize that a constraint may be tight. The route, warnings, map, and metrics need to work together. The next stage should focus on making the plan transparent and adjustable, so people can trust the recommendation and still remain in control.
What's next for ErrandOS
The next step for ErrandOS is to make the planning output more dependable and easier to act on. That starts with improving location handling: clearly displaying geocoding candidates, allowing users to confirm or correct an address, and keeping the map aligned with the selected place. Better location data will improve both routing and the user’s confidence in the itinerary.
We also want to refine the schedule model. Errands may have opening times, closing times, earliest or latest arrival requirements, and a duration. The UI should make these constraints easy to enter and edit, then explain when the proposed plan has to wait or cannot satisfy a deadline. A user should be able to adjust stop order or timing and see how that affects the rest of the day.
A related priority is distinguishing real provider-backed results from demo or simulated estimates. The current project includes fallbacks that help the experience run without API keys, which is valuable for onboarding and development. As the product matures, it should show users whether locations and travel estimates are live, simulated, or approximate. Savings should also make their assumptions visible, including MPG and fuel price.
We would like to strengthen the optimization approach with more robust integration between route costs and time windows, and to evaluate how each solver behaves on realistic errand sets. The existing exhaustive, heuristic, and optional OR-Tools paths provide a foundation. Future work could compare solution quality, handle larger lists more predictably, and improve explanations for infeasible plans.
The app could also benefit from persistence and personalization. Saving common places, vehicle settings, and recurring errands would reduce repetitive entry. A user might want to start from home, end at a different destination, or reuse a familiar set of stops. Those settings should make a plan more personal without making the interface harder to use.
Finally, we want to bring the itinerary closer to real use: better mobile layouts, a clear execution mode for completing stops, and a smooth way to update the plan if an errand takes longer or a stop changes. These improvements would move ErrandOS from a compelling planning prototype toward a practical day-to-day assistant while keeping the user in charge of the final plan.
Built With
- ai-powered
- axios
- css
- date-fns
- extraction
- fastapi
- geocoding
- jest
- language
- leaflet.js
- lucide
- natural
- next.js
- openstreetmap
- optimization
- or-tools
- osrm
- pydantic
- pytest
- python
- react
- route
- tailwind
- typescript
- zod