From 6fb7941d56b1e1d558490c95fce9d6badc063729 Mon Sep 17 00:00:00 2001 From: Florian Egger Date: Mon, 11 May 2026 19:09:24 +0200 Subject: [PATCH] Update README.md --- README.md | 169 ++++++++++++++++++++++++++---------------------------- 1 file changed, 82 insertions(+), 87 deletions(-) diff --git a/README.md b/README.md index 4c3fb30..6a7cd31 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,40 @@ -# TimeToLeave +# ⏱️ TimeToLeave -![TimeToLeave Logo](https://via.placeholder.com/150) +> **TimeToLeave** is a smart departure planner that tells you exactly when to leave home to catch your public transport for upcoming appointments. It syncs with your personal calendar, checks real-time train/bus departures (HAFAS & WienerLinien), calculates your bike route to the station, and provides a live "Leave Status" based on real-time delays. -> **TimeToLeave** is a comprehensive time-off management application designed to streamline vacation, sick leave, and work-from-home request handling for both employees and administrators. This tool helps organizations improve transparency and ensure compliance with internal policies. +![Platform](https://img.shields.io/badge/platform-Web_%26_Mobile-blue) ![Next.js](https://img.shields.io/badge/Next.js-16.2-green) ![React Native](https://img.shields.io/badge/React%20Native-0.81-blue) ![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue) -![GitHub release (latest by date)](https://img.shields.io/github/v/release/fegger/TimeToLeave) ![GitHub issues](https://img.shields.io/github/issues/fegger/TimeToLeave) ![GitHub stars](https://img.shields.io/github/stars/fegger/TimeToLeave) ![GitHub license](https://img.shields.io/github/license/fegger/TimeToLeave) +## 🚀 How It Works -## 🚀 Getting Started +1. **Sync Your Calendar:** Import your `.ics` file or provide a calendar URL. The app extracts your upcoming events and destinations. +2. **Set Your Origin:** Define your home station or let the app use your current geolocation. +3. **Journey Calculation:** The app queries the HAFAS protocol and WienerLinien APIs to find the best public transport connections to your event destination. +4. **Real-Time Monitoring:** It monitors your train's real-time departure time, accounts for delays, and adds your local travel time (e.g., biking to the station) to calculate a dynamic countdown. +5. **Leave Status:** You get a clear status: `Leave now`, `On time`, `Delayed +X min`, or `Departure missed`. -These instructions will get you a copy of the project running on your local machine for development and testing purposes. +## 🧱 Project Structure + +This project uses a monorepo setup (npm workspaces) to manage multiple, interconnected parts: + +| Directory | Description | +| :--- | :--- | +| `apps/web/` | The main web dashboard built with **Next.js 16**, React 19, and Tailwind CSS 4. | +| `apps/mobile/` | The on-the-go mobile client built with **React Native 0.81** and **Expo 54**. | +| `packages/core/` | Shared domain logic, types (`Event`, `Journey`, `Station`), countdown utilities, and status calculators. | +| `packages/api-client/` | A lightweight client that handles API proxies for HAFAS requests, calendar parsing, geocoding, and bike routing. | + +## 🛠 Development & Running the Application ### Prerequisites -* Node.js (version 20.x or higher recommended) -* npm/yarn (version 9.x or higher recommended) +* Node.js (version 20.x or higher) +* npm (version 9.x or higher) ### Installation 1. **Clone the repository:** ```bash - git clone https://github.com/fegger/TimeToLeave.git + git clone cd TimeToLeave ``` @@ -29,114 +44,94 @@ These instructions will get you a copy of the project running on your local mach ``` 3. **Environment variables:** - * For `apps/web` and `apps/mobile`, copy `.env.example` to `.env` in each app directory and update the values as needed. + * For `apps/web` and `apps/mobile`, copy `.env.example` to `.env` in each app directory and update the backend API URL and any required keys. -## 🧱 Project Structure Overview - -This project uses a monorepo setup to manage multiple, interconnected parts: - -* **`apps/`**: Contains the primary deployable applications. - * `apps/web`: The main web interface for the user, built using Next.js, React, and Tailwind CSS. - * `apps/mobile`: The mobile application client built using React Native and Expo. -* **`packages/`**: Contains reusable, domain-specific logic and shared utilities. - * `packages/core`: Core business logic, domain models, and utilities like date manipulation using date-fns. - * `packages/api-client`: Handles interactions with the backend API, including authentication, request submissions, and calendar integration. - -## 🛠 Development & Running the Application - -The `package.json` defines several scripts to assist with development: +### Available Scripts | Script | Command | Description | | :--- | :--- | :--- | -| `dev` | `npm run dev -w apps/web` | Starts the development server for the Web application. | -| `dev:mobile` | `npm run start -w apps/mobile` | Starts the mobile client development server. | -| `build` | `npm run build -w apps/web` | Builds the production bundle for the Web application. | -| `test` | `npm run test -w apps/web` | Runs unit and integration tests for the Web application. | -| `lint` | `npm run lint -w apps/web && npm run lint -w apps/mobile` | Runs linting checks across both web and mobile clients. | +| `dev` | `npm run dev` | Starts the Next.js development server for the Web dashboard. | +| `dev:mobile` | `npm run dev:mobile` | Starts the Expo development server for the Mobile client. | +| `build` | `npm run build` | Builds the production bundle for the Web application. | +| `test` | `npm run test` | Runs Vitest for the Web app and Jest for the Mobile app. | +| `lint` | `npm run lint` | Runs ESLint across both web and mobile clients. | +| `typecheck` | `npm run typecheck` | Runs TypeScript type checking across all workspaces. | -### Development Workflow Tip +## 📝 Key Features & Tech Stack -When working on shared logic, modify files in `packages/core` or `packages/api-client`. Remember to run tests or restart the services to ensure changes are propagated correctly across the consuming apps. +### Web Application (`apps/web`) +* **Framework:** Next.js 16.2.6 (App Router) +* **UI:** React 19.2.4 with Tailwind CSS 4 +* **State Management:** Zustand (for events and station selection) +* **Routing:** Next.js built-in routing for `/add-event`, `/calendar`, and `/event` views. -## 📝 Web Application Overview +### Mobile Application (`apps/mobile`) +* **Framework:** React Native 0.81 via Expo 54 +* **Navigation:** React Navigation 7 (Native Stack) +* **Device APIs:** + * `expo-location`: For geocoding your current position. + * `expo-calendar`: For native calendar event integration. + * `expo-notifications`: For native push notifications when it's time to leave. + * `@react-native-async-storage/async-storage`: For persisting settings and local state. -The web application is built with the following technologies: +### Core Logic (`packages/core`) +* **Countdown Utilities:** Calculates time-deltas and assigns color codes (Red/Orange/Yellow/Green/Blue) based on urgency. +* **HAFAS Time Parsing:** Highly accurate timezone-aware parsing for HAFAS timestamps, specifically handling `Europe/Vienna` (CET/CEST) and DST transitions. +* **WienerLinien Support:** Native types and handling for Vienna public transport departures. +* **Leave Status:** Derives human-readable statuses (`Leave now`, `Delayed +10 min`, etc.) by comparing the best non-cancelled journey's real departure time against the current time. -* **Framework:** Next.js (version 16.2.6) -* **UI Library:** React (version 19.2.4) -* **Styling:** Tailwind CSS (version 4) -* **Date Manipulation:** date-fns (version 4.1.0) -* **iCalendar Parsing:** node-ical (version 0.26.1) +## 📄 API Client Usage -### Key Features of the Web Client +The `@timetoleave/api-client` package provides a clean interface to interact with your backend proxy, which handles the heavy lifting of HAFAS protocol communication and calendar parsing. -* Dashboard for requesting and managing time off -* Real-time updates on approval status -* Integration with personal calendars via iCalendar +```typescript +import { ApiClient } from "@timetoleave/api-client"; -## 📱 Mobile Application Overview +// Initialize with your backend URL +const api = new ApiClient("http://localhost:3000"); -The mobile application leverages the following technologies: +// 1. Sync your calendar +const events = await api.fetchCalendar("https://example.com/calendar.ics", 7); -* **Framework:** React Native (version 0.81.5) via Expo (version 54.0.33) -* **Navigation:** React Navigation (version 7.2.4) -* **Data Persistence:** AsyncStorage (version 3.0.2) -* **Device APIs:** Expo modules for calendar, location, and notifications +// 2. Search for a station by name +const stations = await api.searchStation("Wien Mitte"); -### Key Features of the Mobile Client +// 3. Find journeys between stations for a specific date +const journeys = await api.searchJourneys( + stations[0].extId, // From + "dest:extId", // To + new Date() // Date +); -* Geolocation-based request policies -* Calendar event integration -* Native push notifications for status updates +// 4. Get a bike route from your current location to the station +const bikeRoute = await api.getBikeRoute( + 48.2082, 16.3738, // From lat/lng + stations[0].lat, stations[0].lng // To lat/lng +); +``` ## 🛡️ Testing & Quality Assurance The project provides comprehensive scripts for maintaining code quality: -* **Linting:** Use `npm run lint` to catch stylistic and structural errors. -* **Type Checking:** Use `npm run typecheck` to ensure type safety across the codebase. +* **Linting:** Use `npm run lint` to catch stylistic and structural errors via ESLint 9. +* **Type Checking:** Use `npm run typecheck` to ensure strict type safety across the codebase via TypeScript 5. * **Testing:** - * The web application uses Vitest (version 4.1.5) for unit and integration tests. - * The mobile application uses Jest (version 29.7.0) for testing React Native components. - -## 📄 API Documentation - -The API client handles all interactions with the backend. The main features include: - -* **Authentication:** Secure token management -* **Request Management:** Submitting and updating time-off requests -* **Calendar Integration:** Reading and writing calendar events -* **Policy Checking:** Validating requests against organizational rules - -To use the API client, import it into your project: -```typescript -import { createApiClient } from "@timetoleave/api-client"; - -const apiClient = createApiClient("YOUR_BACKEND_API_URL"); -``` - -[Detailed API documentation](https://example.com/api-documentation) will be available once the backend services are finalized. - -## 🤝 Contributing - -Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for more information. - -## 📜 License - -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + * The web application uses **Vitest** (v4.1.5) with **jsdom** and **@testing-library/react**. + * The mobile application uses **Jest** (v29.7.0) with **jest-expo** and **react-test-renderer**. ## 📂 File Structure ```text ├── apps/ │ ├── mobile/ # Mobile application using React Native and Expo -│ └── web/ # Web application using Next.js +│ └── web/ # Web application using Next.js and Tailwind CSS ├── packages/ -│ ├── api-client/ # API client utilities -│ └── core/ # Shared core utilities and types +│ ├── api-client/ # API client for HAFAS, Calendar, and Routing proxies +│ └── core/ # Shared domain types, countdowns, and HAFAS time utilities ├── node_modules/ # Third-party dependencies └── README.md # The file you're reading now ``` ---- -*This README was generated based on the detected monorepo structure and dependencies.* \ No newline at end of file +--- +*Built for developers who bike to the train and hate missing their connections.*