Update README.md
This commit is contained in:
@@ -1,25 +1,40 @@
|
||||
# TimeToLeave
|
||||
# ⏱️ TimeToLeave
|
||||
|
||||
|
||||
> **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.
|
||||
   
|
||||
|
||||
   
|
||||
## 🚀 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 <repository-url>
|
||||
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.*
|
||||
---
|
||||
*Built for developers who bike to the train and hate missing their connections.*
|
||||
|
||||
Reference in New Issue
Block a user