time_to_leave/REWRITE_PLAN.md

ÖBB Planner — Next.js Rewrite Plan

Status: Planned Created: 2024 Scope: Full rewrite from CRA + Express to Next.js App Router with new features

---

1. Current State

Layer	Technology	Files
Backend	Express.js + CORS + node-ical	server/index.js (~140 lines)
Frontend	Create React App (React 19)	oebb-planner.jsx (~700 lines monolithic component)
Tests	Jest + Supertest	server/__tests__/*.test.js
Build	Separate npm start for server + react-scripts start for frontend	Two independent processes

Problems with current architecture

• Two separate processes to manage
• Monolithic component (~700 lines) — no component breakdown
• CRA is deprecated; react-scripts is unmaintained
• No TypeScript
• Inline styles make theming/maintenance painful
• No proper state management pattern
• Duplication between oebb-planner.jsx and oebb-planner-app/src/App.js

---

2. New Features (Beyond Rewrite)

2.1 Calendar View (/calendar)

A browsable month view that lets you navigate between months, see events as badges on dates, and click into a day to see event + train details.

How it works:

• User imports calendar via the existing ICS flow
• Events are stored in React state / localStorage
• A month grid shows event dots on dates that have events
• Clicking a day shows that day's events with their train info
• Clicking an event scrolls to / expands the full event card

UI wireframe:

┌──────────────────────┬──────────────────────┐
│  ←  November 2024  → │ [Day] [Week] [Month] │
├──────────────────────┼──────────────────────┤
│ Su Mo Tu We Th Fr Sa │  Thursday, 14 Nov    │
│  1  2  3  4  5  6  7 │                      │
│  8  9 10 11 12 13 14 │  ● 14:00 Graz Hbf    │
│          ●       ●   │     🚂 Leave 13:10   │
│ 15 16 17 18 19 20 21 │     🚲 Leave 11:07   │
│            ●       ● │                      │
│ ...                  │  ● 17:00 Linz Hbf    │
│                      │     🚂 Leave 15:30   │
│                      │     🚲 Leave 15:45   │
└──────────────────────┴──────────────────────┘

2.2 Bicycle Routing

API choice: OSRM Public Demo Server (router.project-osrm.org)

• Free, no API key required, open source
• Supports bicycle profile
• Returns distance, duration, turn-by-turn steps
• For production: self-host or switch to OpenRouteService

Geocoding: Nominatim (OpenStreetMap) to convert station/event location names to coordinates for routing.

Data flow:

Origin station (name) → already have coords from geolocation
Destination station (name) → geocode via Nominatim → get coordinates
                            → OSRM bicycle route → distance + duration
                            → cache in TripData alongside train journeys

2.3 Train vs Bicycle Comparison

Each event card shows both travel modes side by side:

┌───────────────────────────────────────────────────┐
│ 🏔 Meeting in Graz                               │
│ 📍 Graz Hbf · 14:00 · Thu, 14 Nov                │
├───────────────────────────────────────────────────┤
│  🚂 NEXT BEST TRAIN            🚲 BYCYCLE         │
│  RJX 5234 on time                42 km            │
│  DEP 13:22  ARR 14:35          2h 15min          │
│  PLAT 3                          0 emissions      │
│  Leave by 13:10                 Leave by 11:07    │
└───────────────────────────────────────────────────┘

---

3. Target Architecture

oebb_planner/
├── package.json
├── next.config.ts
├── tsconfig.json
├── postcss.config.mjs               ← Tailwind v4 uses @tailwindcss/postcss; no tailwind.config.ts needed
├── vitest.config.ts                  ← must exist before Phase 7; deferred from Phase 1
├── src/
│   ├── app/
│   │   ├── layout.tsx                    ← root layout (fonts, providers, navbar)
│   │   ├── page.tsx                      ← main planner page (event cards)
│   │   ├── globals.css
│   │   ├── calendar/
│   │   │   └── page.tsx                  ← browsable calendar view (NEW)
│   │   ├── api/
│   │   │   ├── hafas/
│   │   │   │   └── route.ts              ← POST → proxy to ÖBB HAFAS
│   │   │   ├── calendar/
│   │   │   │   ├── route.ts              ← GET → fetch remote ICS calendar
│   │   │   │   └── parse/
│   │   │   │       └── route.ts          ← POST → parse raw ICS body
│   │   │   ├── geocode/
│   │   │   │   └── route.ts              ← GET → Nominatim geocoding (NEW)
│   │   │   ├── bike-route/
│   │   │   │   └── route.ts              ← GET → OSRM bicycle routing (NEW)
│   │   │   └── health/
│   │   │       └── route.ts              ← GET → liveness check
│   │   └── not-found.tsx
│   ├── components/
│   │   ├── layout/
│   │   │   ├── Header.tsx                ← logo, server status, clock
│   │   │   └── Navbar.tsx                ← navigation between pages (NEW)
│   │   ├── calendar/
│   │   │   ├── CalendarPanel.tsx          ← collapsible import panel
│   │   │   ├── CalendarView.tsx           ← month grid component (NEW)
│   │   │   ├── DayEvents.tsx             ← events for a selected day (NEW)
│   │   │   ├── UrlTab.tsx
│   │   │   └── FileTab.tsx
│   │   ├── event/
│   │   │   ├── EventCard.tsx             ← single event card (with train+bike)
│   │   │   ├── TrainSection.tsx          ← train data in event card
│   │   │   ├── BikeSection.tsx           ← bicycle data in event card (NEW)
│   │   │   ├── JourneyList.tsx           ← all departures table
│   │   │   └── LeaveByBadge.tsx
│   │   ├── add-event/
│   │   │   └── AddEventModal.tsx
│   │   └── ui/
│   │       ├── Chip.tsx
│   │       ├── Button.tsx
│   │       └── LoadingSpinner.tsx
│   ├── hooks/
│   │   ├── useServerHealth.ts             ← polls /api/health every 30s
│   │   ├── useClock.ts                    ← ticking clock (every 10s)
│   │   ├── useGeolocation.ts              ← GPS positioning
│   │   ├── useOriginStation.ts            ← finds nearest ÖBB station
│   │   ├── useJourneys.ts                 ← fetches + caches train data
│   │   ├── useBikeRoute.ts               ← fetches bicycle route (NEW)
│   │   ├── useCalendar.ts                 ← calendar import logic
│   │   └── useEventsStore.ts             ← shared events state (NEW)
│   ├── lib/
│   │   ├── hafas-client.ts               ← HAFAS API client (class HafasClient)
│   │   ├── calendar-utils.ts             ← ICS helpers (extractEvents, cleanLocation)
│   │   ├── countdown-utils.ts            ← calculateCountdown, leaveBy helpers
│   │   ├── formatting.ts                 ← formatTime, formatDate, formatDateTime, formatDuration, formatDistance
│   │   ├── demo.ts                       ← demo journey generator
│   │   ├── constants.ts                  ← HAFAS_URL, NOMINATIM_URL, OSRM_URL, HAFAS_TIMEOUT_MS, DEFAULT_DAYS, APP_VERSION
│   │   ├── status-utils.ts               ← StatusUtils.checkServerStatus() (used by useServerHealth)
│   │   ├── live-status-utils.ts          ← LiveStatusUtils.getLiveStatus() (stub; live data TBD)
│   │   ├── geocoding-client.ts           ← Nominatim client (NEW)
│   │   ├── bike-routing-client.ts        ← OSRM client (NEW)
│   │   └── index.ts                      ← re-exports all lib modules
│   └── types/
│       └── index.ts                       ← all TypeScript interfaces
├── src/lib/__tests__/                     ← unit tests live alongside lib, not at repo root
│   ├── hafas-client.test.ts
│   ├── geocoding-client.test.ts
│   ├── calendar-utils.test.ts
│   ├── countdown-utils.test.ts
│   └── bike-routing-client.test.ts        ← NEW
├── src/app/api/__tests__/                 ← API route tests
│   ├── hafas.test.ts
│   ├── calendar.test.ts
│   ├── geocode.test.ts                    ← NEW
│   ├── bike-route.test.ts                 ← NEW
│   └── health.test.ts
├── public/
│   ├── favicon.ico
│   └── robots.txt
├── .env.example
└── README.md

---

4. TypeScript Types

src/types/index.ts

// ── HAFAS / Train ───────────────────────────────────────────

interface Journey {
  id: string;
  sD: Date;          // scheduled departure
  rD: Date;          // real departure
  sA: Date;          // scheduled arrival
  rA: Date;          // real arrival
  delay: number;     // minutes
  platform: string;
  changes: number;
  trains: string[];
  cancelled: boolean;
}

interface Station {
  name: string;
  extId: string;
}

// ── Events ───────────────────────────────────────────────────

interface Event {
  id: string;
  title: string;
  destination: string;
  eventTime: Date;
  source: "manual" | "calendar";
}

// ── Trip Data (per event) ────────────────────────────────────

interface TripDataEntry {
  journeys: Journey[];
  destName: string;
  demo: boolean;
  loading: boolean;
  bikeRoute?: BikeRoute | null;       // NEW
  bikeLoading?: boolean;              // NEW
  bikeError?: string | null;          // NEW
  destCoords?: { lat: number; lng: number }; // NEW (cached geocode)
}

// ── Bicycle Routing (NEW) ────────────────────────────────────

interface BikeRoute {
  distance: number;       // meters
  duration: number;       // seconds
  steps?: BikeStep[];
}

interface BikeStep {
  name: string;
  distance: number;
  duration: number;
  instruction: string;
}

// ── Geocoding (NEW) ──────────────────────────────────────────

interface GeocodeResult {
  lat: number;
  lng: number;
  display_name: string;
}

// ── Calendar Import ──────────────────────────────────────────

interface CalendarEvent {
  id: string;
  title: string;
  destination: string;
  eventTime: string;    // ISO string from API
  source: "calendar";
}

// ── UI Helpers ───────────────────────────────────────────────

interface CountdownInfo {
  label: string;
  color: string;
  urgent: boolean;
}

type ServerStatus = null | true | false;
type LiveStatus   = null | true | false;
type LocState     = "pending" | "granted" | "denied";
type CalStatus    = null | "loading" | "ok" | "error";

---

5. New API Routes

POST /api/hafas

• Purpose: Proxy to fahrplan.oebb.at/bin/mgate.exe
• Body: { svcReqL: [...] } — HAFAS service requests
• Returns: HAFAS JSON response
• Timeout: 12s

GET /api/calendar?url=<ics_url>&days=14

• Purpose: Fetch and parse a remote ICS calendar
• Returns: CalendarEvent[]
• Supports: https://, webcal://

POST /api/calendar/parse

• Purpose: Parse raw ICS content sent in request body
• Body: Raw ICS text
• Returns: CalendarEvent[]

GET /api/geocode?name=Graz+Hbf&countrycodes=at (NEW)

• Purpose: Proxy to Nominatim for address→coordinates
• Upstream: nominatim.openstreetmap.org/search?q={name}&format=json&limit=1&countrycodes=at
• Returns: { lat, lng, display_name }
• Caching: In-memory cache with TTL to avoid rate limits

GET /api/bike-route?fromLat=...&fromLng=...&toLat=...&toLng=... (NEW)

• Purpose: Proxy to OSRM for bicycle routing
• Upstream: router.project-osrm.org/route/v1/bicycle/{lon1},{lat1};{lon2},{lat2}?overview=false
• Returns: { distance, duration, steps: [...] }

GET /api/health

• Purpose: Liveness check
• Returns: { ok: true, ts: ISOString, version: "2.0.0" }

---

6. Key Technical Decisions

Decision	Choice	Rationale
Framework	Next.js 15 App Router	Modern standard; API routes are serverless-compatible
Language	TypeScript (strict)	Type safety across frontend and backend
Styling	Tailwind CSS v4	Replaces 700 lines of inline styles; v4 uses CSS-native config, no tailwind.config.ts
State	React hooks + Context	No Redux needed for this scale
API proxy	Next.js Route Handlers	Same logic as Express, no Express dependency
ICS parsing	Keep node-ical	Already works, well-tested
Bike routing	OSRM public demo	Free, no API key, good enough for dev
Geocoding	Nominatim	Free, open source, good Austria coverage
Testing	Vitest + Testing Library	Faster than Jest for TS, better DX
Deployment	Vercel (recommended) or any Node host	Single artifact

---

7. Migration Phases

Phase 1 — Scaffold Next.js Project (~30 min)

1. Initialize Next.js 15 with App Router, TypeScript, Tailwind CSS
2. Set up tsconfig.json with strict mode
3. Create .env.example with PORT, HAFAS_URL, NOMINATIM_URL, OSRM_URL
4. Configure next.config.js (rewrites if needed)
5. Configure vitest.config.ts
6. Set up postcss.config.mjs

Phase 2 — Types + Library Layer (~2 hours)

7. Define TypeScript types in src/types/index.ts
8. Port lib/hafas-client.ts — HafasClient class with searchStation() and fetchJourneys()
9. Port lib/calendar-utils.ts — extractEvents() + cleanLocation() (reusable in API routes AND tests)
10. Port lib/countdown-utils.ts, lib/formatting.ts, lib/constants.ts, lib/demo.ts, lib/status-utils.ts, lib/live-status-utils.ts
11. Create lib/geocoding-client.ts — Nominatim client (NEW)
12. Create lib/bike-routing-client.ts — OSRM client (NEW)

Phase 3 — API Routes (~45 min)

13. src/app/api/hafas/route.ts — POST handler, same logic as Express
14. src/app/api/calendar/route.ts — GET handler for remote ICS
15. src/app/api/calendar/parse/route.ts — POST handler for ICS body
16. src/app/api/geocode/route.ts — GET handler for Nominatim (NEW)
17. src/app/api/bike-route/route.ts — GET handler for OSRM (NEW)
18. src/app/api/health/route.ts — health check

Phase 4 — Custom Hooks (~2.5 hours)

19. useServerHealth.ts — polls /api/health every 30s
20. useClock.ts — interval that updates now every 10s
21. useGeolocation.ts — wraps navigator.geolocation
22. useOriginStation.ts — finds nearest station from geolocation
23. useJourneys.ts — the complex fetchAll logic, per-event journey fetching
24. useBikeRoute.ts — fetches bicycle route for an event (NEW)
25. useCalendar.ts — URL/file import with merge logic
26. useEventsStore.ts — shared events state via Context (NEW)

Phase 5 — UI Components (~3.5 hours)

27. ui/Chip.tsx — small badge component
28. ui/Button.tsx — styled button
29. ui/LoadingSpinner.tsx — loading indicator
30. event/LeaveByBadge.tsx — countdown badge
31. event/JourneyList.tsx — departure rows
32. event/TrainSection.tsx — train data in event card
33. event/BikeSection.tsx — bicycle data in event card (NEW)
34. event/EventCard.tsx — composes train + bike sections
35. calendar/UrlTab.tsx
36. calendar/FileTab.tsx
37. calendar/CalendarPanel.tsx
38. add-event/AddEventModal.tsx
39. layout/Header.tsx
40. layout/Navbar.tsx (NEW)

Phase 6 — Calendar Page (~1 hour)

41. calendar/CalendarView.tsx — month grid component (NEW)
42. calendar/DayEvents.tsx — events for a selected day (NEW)
43. app/calendar/page.tsx — calendar route (NEW)

Phase 7 — Tests (~2 hours)

Install test dependencies first: npm install -D vitest @vitejs/plugin-react @testing-library/react @testing-library/jest-dom jsdom and create vitest.config.ts. Update the test script in package.json to vitest.

44. Migrate server/__tests__/*.test.js → src/app/api/__tests__/*.test.ts
45. Add unit tests for src/lib/calendar-utils.ts, src/lib/countdown-utils.ts in src/lib/__tests__/
46. Add API tests for geocode and bike-route in src/app/api/__tests__/ (NEW)
47. Add component smoke tests with @testing-library/react (optional)

Phase 8 — Cleanup (~30 min)

48. Delete old server/ directory
49. Delete old oebb-planner-app/ directory
50. Delete oebb-planner.jsx
51. Update README.md with new architecture and instructions
52. Final integration test

---

8. Dependencies

Runtime (installed)

{
  "dependencies": {
    "next": "16.2.6",
    "react": "19.2.4",
    "react-dom": "19.2.4",
    "node-ical": "^0.18.0"
  }
}

Development (installed)

{
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^19",
    "@types/react-dom": "^19",
    "tailwindcss": "^4",
    "@tailwindcss/postcss": "^4",
    "eslint": "^9",
    "eslint-config-next": "16.2.6"
  }
}

To be installed before Phase 7 (tests)

{
  "devDependencies": {
    "vitest": "^2.0.0",
    "@vitejs/plugin-react": "^4.0.0",
    "@testing-library/react": "^16.0.0",
    "@testing-library/jest-dom": "^6.0.0",
    "jsdom": "^25.0.0"
  }
}

Note: Tailwind v4 no longer requires autoprefixer or a separate tailwind.config.ts — configuration is done via CSS and @tailwindcss/postcss.

---

9. Environment Variables

# .env.example

# Server port
PORT=3001

# ÖBB HAFAS API
HAFAS_URL=https://fahrplan.oebb.at/bin/mgate.exe

# Nominatim geocoding (OpenStreetMap)
NOMINATIM_URL=https://nominatim.openstreetmap.org

# OSRM bicycle routing
OSRM_URL=https://router.project-osrm.org

# Nominatim user-agent / referer (required by their ToS)
NOMINATIM_USER_AGENT=OebbPlanner/1.0

---

10. Benefits of the Rewrite

1. Single process — npm run dev starts everything
2. Type safety — TypeScript catches bugs at compile time
3. Composability — 700-line component becomes ~15 focused components
4. Reusability — lib/ functions testable independently
5. Deployable — one artifact, works on Vercel / any Node host
6. Maintainable — hooks encapsulate side effects, components are pure UI
7. Modern tooling — no more CRA, no more react-scripts eject anxiety
8. Bicycle routing — complete picture of train vs bike for each event
9. Calendar view — browse events by date, not just a flat list
10. Train+bike comparison — side-by-side travel times in each event card

---

11. Estimated Effort

Phase	Description	Est. Time
1	Scaffold Next.js + Tailwind + TS	30 min
2	Types + lib layer (incl. geocode, bike-route)	2 hours
3	API routes (incl. geocode, bike-route)	45 min
4	Custom hooks (incl. bike-route, events-store)	2.5 hours
5	UI Components (incl. bike section, navbar)	3.5 hours
6	Calendar page (incl. month view, day events)	1 hour
7	Tests (API + lib + component)	2 hours
8	Cleanup (delete old dirs, update README)	30 min
Total		~13-14 hours