# 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:**
   ```bash
   git clone <repository-url>
   cd TimeToLeave
   ```

2. **Install dependencies:**
   ```bash
   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:
```bash
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.

```bash
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.