time_to_leave/docs/DEVELOPMENT.md

Development Guide

This guide covers setting up the development environment, running the applications, and maintaining code quality.

🛠 Prerequisites

• Node.js: Version 20.x or higher.
• npm: Version 9.x or higher.

📥 Installation

1. Clone the repository:

   git clone <repository-url>
   cd TimeToLeave
   

2. Install dependencies:

   npm install
   

   This installs dependencies for the root workspace as well as all apps and packages.

3. Environment Variables:

   • Web App: Copy apps/web/.env.example to apps/web/.env and configure your HAFAS/Geocoding API keys.
   • Mobile App: Copy apps/mobile/.env.example to apps/mobile/.env and set the backend API URL.

▶️ Running the Applications

Script	Command	Description
dev	npm run dev	Starts the Next.js development server (Web) on http://localhost:3000.
dev:mobile	npm run dev:mobile	Starts the Expo development server (Mobile) and opens the Expo Go simulator.
build	npm run build	Builds the production bundle for the Web application.

🧪 Testing & Quality Assurance

The project enforces strict typing and linting across all workspaces.

Script	Command	Description
test	npm run test	Runs Vitest for the Web app (using jsdom & React Testing Library) and Jest for the Mobile app (using jest-expo).
lint	npm run lint	Runs ESLint 9 across the entire monorepo.
typecheck	npm run typecheck	Runs TypeScript 5 type checking across all workspaces.

Testing Specific Packages

If you want to run tests for a specific workspace:

cd apps/web && npm test
cd apps/mobile && npm test
cd packages/core && npm run typecheck

🐳 Docker Support (Web App)

The web application includes a Dockerfile and docker-compose.yml for containerized development or deployment.

cd apps/web
docker-compose up --build

📁 Web App Routing (Next.js 16)

The web app uses the Next.js App Router. Key routes include:

Route	Description
/	Dashboard: Lists upcoming events and their real-time leave status.
/calendar	Calendar Sync: Interface to import .ics files or paste calendar URLs.
/add-event	Manual Entry: Add a new event manually without a calendar source.
/event/[id]	Event Details: Deep dive into a specific event, showing journey options, delays, and local routing.

Backend API Routes

The web app acts as a proxy for external APIs. These are located in apps/web/src/app/api/:

Endpoint	Method	Description
/api/health	GET	Health check for the backend proxy.
/api/calendar	GET	Fetch and parse remote .ics files.
/api/calendar/parse	POST	Parse raw .ics content.
/api/hafas	POST	Generic HAFAS protocol endpoint (TripSearch, LocMatch).
/api/geocode	GET	Forward geocoding (Nominatim).
/api/geocode/reverse	GET	Reverse geocoding.
/api/bike-route	GET	Bicycle routing between coordinates.
/api/walk-route	GET	Walking routing between coordinates.
/api/wienerlinien/stops	GET	Find nearby WienerLinien stops.

📱 Mobile App Structure

The mobile app is organized into the following directories:

• src/screens/: UI screens (EventListScreen, EventDetailScreen, AddEventScreen, CalendarImportScreen, SettingsScreen).
• src/navigation/: React Navigation configuration (AppNavigator.tsx).
• src/services/: API integration and data fetching services.
• src/store/: Local state management and AsyncStorage integration.

⚠️ Development Notes

1. Next.js 16 Breaking Changes: The web app runs on Next.js 16.2+, which introduces breaking changes in routing and API conventions. Always check node_modules/next/dist/docs/ if you encounter unexpected behavior.
2. HAFAS Timezones: Never parse HAFAS times using standard Date methods. Use @timetoleave/core utilities (parseHafasTime, hafasDateTime) to ensure accurate CET/CEST and DST handling.