update documentation
This commit is contained in:
+103
-65
@@ -1,93 +1,131 @@
|
||||
# User Guide
|
||||
|
||||
Welcome to the TimeToLeave User Guide! This document explains how to use the TimeToLeave web dashboard and mobile application to plan your departures seamlessly.
|
||||
TimeToLeave helps you answer one practical question: when do I need to leave for my next appointment?
|
||||
|
||||
## 🚀 How TimeToLeave Works
|
||||
The app imports events with locations, finds the nearest usable transport station, checks live train and local transit data, calculates walking or biking time, and shows a live leave-by countdown.
|
||||
|
||||
TimeToLeave acts as your personal departure planner. Instead of manually checking train schedules, you simply sync your calendar. The app calculates the best public transport connections to your upcoming appointments, monitors real-time delays, and tells you exactly when to leave home.
|
||||
## Web Dashboard
|
||||
|
||||
### Core Workflow
|
||||
1. **Sync Your Calendar:** Import your `.ics` file or provide a calendar URL.
|
||||
2. **Set Your Origin:** Define your home station or let the app use your current location.
|
||||
3. **Automatic Planning:** The app queries real-time public transport data (via HAFAS and WienerLinien) to find the best connections.
|
||||
4. **Leave Status:** The dashboard displays a clear status: `Leave now`, `On time`, `Delayed +X min`, or `Departure missed`.
|
||||
### Departure Desk
|
||||
|
||||
---
|
||||
Open `/` to see the next upcoming event. The card shows:
|
||||
|
||||
## 🌐 Web Dashboard
|
||||
- Event title and appointment time.
|
||||
- Destination address or place.
|
||||
- A live countdown badge.
|
||||
- Leave-by, arrive-by, and buffer times.
|
||||
- Train and bike mode selector.
|
||||
- Train journeys with delay, platform, cancellation, arrival, and transfer information.
|
||||
- Optional final walking route from the arrival station to the destination.
|
||||
- Optional door-to-door bike route.
|
||||
- Nearby Wiener Linien stops and live departures when destination coordinates are available.
|
||||
|
||||
The web dashboard is designed for planning and monitoring your upcoming events from a desktop or laptop.
|
||||
The dashboard currently focuses on the next upcoming event. Imported and manually added events are stored locally in the browser.
|
||||
|
||||
### Main Dashboard (`/`)
|
||||
This is the default view when you open the application. It displays a list of your upcoming events sorted by date. Each event card shows:
|
||||
- **Event Title & Time:** The name of the appointment and when it starts.
|
||||
- **Destination Station:** The nearest station to your event.
|
||||
- **Leave Status:** A color-coded indicator of your current standing:
|
||||
- 🔴 **Red:** Time is up ("Now") or you're extremely close to departure.
|
||||
- 🟠 **Orange:** Urgent! You need to leave within 10 minutes.
|
||||
- 🟡 **Yellow:** Moderate urgency (within 30 minutes).
|
||||
- 🟢 **Green:** Relaxed (within 60 minutes).
|
||||
- 🔵 **Blue:** Plenty of time remaining (over 1 hour).
|
||||
### Add or Edit Events
|
||||
|
||||
### Calendar Sync (`/calendar`)
|
||||
Use this page to connect your personal calendar.
|
||||
- **URL Import:** Paste a public `.ics` calendar URL. The app will fetch upcoming events automatically.
|
||||
- **File Import:** Upload a `.ics` file directly from your computer.
|
||||
Use the add/edit event modal from the web interface to create or change local events. Editing is modal-based; there is no separate `/add-event` page.
|
||||
|
||||
### Event Details (`/event/[id]`)
|
||||
Click on any event from the dashboard to view detailed planning information:
|
||||
- **Journey Options:** A list of available trains/buses with scheduled vs. real departure times.
|
||||
- **Delay Information:** Real-time delays are highlighted. Cancelled journeys are clearly marked.
|
||||
- **Local Routing:** See how long it takes to bike or walk from your home to the departure station.
|
||||
### Calendar Page
|
||||
|
||||
### Manual Event Entry (`/add-event`)
|
||||
If you don't have a calendar synced, or you have a one-off appointment, you can manually add an event by specifying the title, destination, and time.
|
||||
Open `/calendar` to import and review events.
|
||||
|
||||
---
|
||||
Available import sources:
|
||||
|
||||
## 📱 Mobile Application
|
||||
| Source | Description |
|
||||
| --- | --- |
|
||||
| URL | Paste an allowed public ICS URL. The backend fetches and parses future events with locations. |
|
||||
| File | Upload a local `.ics` file. The backend parses the file content. |
|
||||
| Google | Connect Google Calendar through OAuth, sync events, and disconnect when needed. |
|
||||
|
||||
The mobile app is perfect for on-the-go checks, leveraging your phone's native capabilities.
|
||||
Imported events are merged into local storage. The calendar view also includes batch destination editing so locations can be corrected before using them for route planning.
|
||||
|
||||
### Event List Screen
|
||||
The home screen mirrors the web dashboard, showing your upcoming events and their real-time status. You can pull-to-refresh to get the latest transit data.
|
||||
## Mobile App
|
||||
|
||||
### Event Detail Screen
|
||||
Tap on an event to see:
|
||||
- The best journey options and real-time platform information.
|
||||
- A countdown timer to your departure.
|
||||
- Step-by-step bike/walk directions to the station.
|
||||
The mobile app includes:
|
||||
|
||||
### Calendar Import Screen
|
||||
Import your calendar directly on the device. The mobile app can read your device's native calendar apps (via `expo-calendar`) if you prefer not to use a remote `.ics` URL.
|
||||
- Event list.
|
||||
- Add/edit event screen.
|
||||
- Event detail screen.
|
||||
- Calendar import screen.
|
||||
- Settings screen.
|
||||
|
||||
### Settings Screen
|
||||
Customize your experience:
|
||||
- **Buffer Time:** Set a default buffer (e.g., arrive 5 minutes early).
|
||||
- **Departure Buffer:** Add extra time for the actual transit journey.
|
||||
- **Toggle Options:** Enable/disable the walking or biking route suggestions based on your preference.
|
||||
- **Notifications:** Configure push notifications so you get an alert exactly when it's time to leave.
|
||||
### Calendar Import
|
||||
|
||||
---
|
||||
The mobile calendar import screen supports:
|
||||
|
||||
## ⏱️ Understanding "Leave Status"
|
||||
- ICS URL import through the configured backend.
|
||||
- Native device-calendar sync for the next 30 days.
|
||||
- Calendar selection before native sync.
|
||||
- Source grouping for CalDAV/DAVx, Apple, Google, Exchange, subscribed, local, CardDAV, ActiveSync, and other calendars when the device reports that metadata.
|
||||
|
||||
The "Leave Status" is the heart of TimeToLeave. It is calculated dynamically by comparing the **real departure time** of your best non-cancelled journey against the **current time**.
|
||||
If no native calendar selection is saved, the sync uses all available calendars.
|
||||
|
||||
### Event Detail
|
||||
|
||||
Tap an event to see:
|
||||
|
||||
- Leave-by and arrive-by times.
|
||||
- Train journeys from the saved origin station to the destination station.
|
||||
- Optional walking route for the final leg.
|
||||
- Optional bike route.
|
||||
- Nearby destination stops and live Wiener Linien departures.
|
||||
|
||||
### Settings
|
||||
|
||||
Use settings to configure:
|
||||
|
||||
- Origin station.
|
||||
- Current-location origin lookup.
|
||||
- Reminder buffer.
|
||||
- Arrival buffer.
|
||||
- Walking option visibility.
|
||||
- Bike option visibility.
|
||||
- Notifications.
|
||||
- Dark/light theme.
|
||||
|
||||
## Leave-By Status
|
||||
|
||||
The countdown and leave-by time are calculated from the selected transport mode.
|
||||
|
||||
For train mode, the app looks for a non-cancelled journey that arrives early enough after accounting for the final walk and arrival buffer. For bike mode, it subtracts the bike route duration from the target arrival time.
|
||||
|
||||
Countdown colors:
|
||||
|
||||
| Color | Meaning |
|
||||
| --- | --- |
|
||||
| Red | Leave time is now or already passed. |
|
||||
| Orange | Leave time is within 10 minutes. |
|
||||
| Yellow | Leave time is within 30 minutes. |
|
||||
| Green | Leave time is within 60 minutes. |
|
||||
| Blue | More than 60 minutes remain. |
|
||||
|
||||
Text statuses can include:
|
||||
|
||||
| Status | Meaning |
|
||||
| :--- | :--- |
|
||||
| **Leave now** | Your train departs within 15 minutes. Head out! |
|
||||
| **On time** | Everything is running smoothly, and you have a comfortable window. |
|
||||
| **Delayed +X min** | Your train is delayed. You can stay home a bit longer! |
|
||||
| **Departure missed** | The best available journey has already departed. A new search may be required. |
|
||||
| **All journeys cancelled** | Unfortunately, all connections for this time slot are cancelled. |
|
||||
| --- | --- |
|
||||
| `Leave now` | The selected departure is close enough that you should go. |
|
||||
| `On time` | The selected connection is currently usable. |
|
||||
| `Delayed +N min` | The selected journey is delayed by more than 10 minutes. |
|
||||
| `Departure missed` | The selected departure has already left. |
|
||||
| `All journeys cancelled` | Every returned journey is cancelled. |
|
||||
| `No journey data` | No usable journey data is available. |
|
||||
|
||||
## 🔒 Privacy & Data
|
||||
## Notifications
|
||||
|
||||
TimeToLeave is designed with privacy in mind:
|
||||
- Calendar data is processed server-side solely for the purpose of event extraction and is not permanently stored beyond the active session.
|
||||
- Geolocation data is used exclusively for calculating routes and finding nearby stations. It is never shared with third parties.
|
||||
Web reminders use browser notifications when permission is granted. Mobile reminders use local Expo notifications.
|
||||
|
||||
---
|
||||
Mobile notifications are scheduled from stored events and settings. Because the mobile store does not retain live journey data, scheduled notification times use a conservative fallback based on event time, arrival buffer, and reminder buffer.
|
||||
|
||||
*Happy traveling! Built for developers who bike to the train and hate missing their connections.*
|
||||
## Data and Privacy
|
||||
|
||||
Event data is stored locally in the browser or on the device. Some features send the minimum required request data to external services:
|
||||
|
||||
- Destination text is sent to Nominatim for geocoding.
|
||||
- Coordinates are sent to OSRM for bike/walk route calculation.
|
||||
- Station IDs and journey times are sent to ÖBB HAFAS.
|
||||
- Coordinates or stop IDs are sent to Wiener Linien for nearby stops and departures.
|
||||
- Google Calendar sync uses Google OAuth and server-side token cookies.
|
||||
- Remote ICS imports fetch the provided calendar URL through the backend.
|
||||
|
||||
See the root [Privacy Policy](../PRIVACY_POLICY.md) for more detail.
|
||||
|
||||
Reference in New Issue
Block a user