# onebusaway/wayfinder architecture

> Architecture diagram of the GitHub repository onebusaway/wayfinder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onebusaway/wayfinder
- Repository: https://github.com/onebusaway/wayfinder

## Overview

##### Project Identification & Purpose
- Wayfinder is a next-generation transit information web application built on SvelteKit. It is designed to replace an older enterprise webapp and provides real-time transit data by integrating with OneBusAway (OBA) APIs, map providers (Google Maps or OpenStreetMap), geocoding services, and an optional trip-planner (via OpenTripPlanner).
- The application is a full-stack web application with a strong emphasis on client-side interactivity (via numerous Svelte components) and server-side endpoints (for API calls).

##### Analyzing the File Structure
- The top-level directories and files (like .env.example, package.json, vite.config.js, svelte.config.js, and tailwind.config.js) indicate standard project configuration and build tooling.
- The src/ directory is the heart of the application:
- The src/routes directory contains both pages (layouts, +page.svelte) and API endpoints (under /api) for various transit functionalities (e.g., arrivals-and-departures, alerts, trip details).
- The src/components directory holds modular Svelte components for UI parts such as maps, search fields, navigation, trip planner, alerts, stops, surveys, etc.
- The src/lib contains shared utility functions, providers (for GoogleMap and OpenStreetMap), analytics integrations, theming, and other common functionality.
- The src/config has configuration scripts (like mapSource.js and routeConfig.js) that define how map data and routes are handled.
- The src/locales directory provides multi-language support.
- Additional directories (tests, static, assets) also clarify that the project incorporates automated testing, static assets (images, styles, and manifests), and front-end styling (with TailwindCSS/postcss).

##### Key Components
a. Client-Side Application (Frontend):
- Assets & Styles: Represent the static assets (images, CSS) that the UI loads to render the application.
- SvelteKit Routing: A clear component representing how UI pages (the +page.svelte, +layout.svelte) are organized.

b. Server-Side Functionality / API Endpoints:
- Middleware/Helpers: Include a smaller block that shows the utility libraries and helpers (from src/lib and tests verifying functionality like geocoder, route helpers, etc.).

c. External Services & Providers:
- OBA API Server: A block to represent the external OneBusAway REST API (configured via environment variables).
- Providers: Visual blocks for Google Maps and/or OpenStreetMap, as well as the specific map configuration in src/config and provider wrappers in src/lib/Provider.
- Geocoding / Places API: Represent the geocoding services (Google Places specifically as indicated in the README).
- Trip Planner API: Optionally include a block for OpenTripPlanner if used, based on the provided OTP server URL.
- Analytics Service: Represent Plausible Analytics integration (see src/lib/Analytics) as it feeds into external metrics.

d. Config & Environment:
- Environment Variables: A secondary component that shows how key visual and operational configurations (header details, API keys, region information) are passed to both the frontend and backend.
- Build & Deployment Tools: Although not a functional component of the runtime architecture, include a note or a mini-block representing Vite, SvelteKit, and CI/CD workflows from GitHub Actions.

##### Defining Relationships and Data Flows
- From Client (UI Components) ⇨ API Endpoints (e.g., requests for transit data, route planning, alerts) and vice versa.
- From API Endpoints ⇨ External Services: e.g., OBA Server API, Trip Planner API, Geocoding API.
- From the environment/config component to both the frontend and API components (highlighting dependency on environment configuration for API keys, map parameters, branding, etc.).
- From analytics components integrated within client-side libraries sending data to external analytics endpoints.
- That some API endpoints not only retrieve data but may also perform data transformation (utilizing utilities in src/lib).

##### Noting Architectural Patterns
- SvelteKit’s File-Based Routing: Highlight this pattern especially in how API endpoints and pages are structured.
- Component-Based Architecture: Emphasize the division of the UI into reusable components.
- Clear Separation Between Presentation/UI Layer and the Data Access / Business Logic Layer provided in the /api endpoints and utility libraries.
- Modular, Organized Configuration for External Dependencies driven via .env and configuration scripts.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FS["SvelteKit Routing & Pages"]:::frontend
        FC["UI Components (Svelte Components)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API["API Endpoints"]:::api
        UTIL["Utility Libraries & Helpers"]:::api
    end

    %% External Services
    subgraph "External Services"
        OBA["OBA Service API"]:::external
        MAP["Map Providers Integration"]:::external
        GEO["Geocoding Service"]:::external
        OTP["Trip Planner API"]:::external
        ANALYTICS["Analytics Service"]:::external
    end

    %% Configuration & Tools
    subgraph "Configuration & Tools"
        CONFIG["Env & Build Configurations"]:::config
        BUILD["CI/CD & Testing"]:::config
    end

    %% Data Flow Connections
    FC -->|"fetches transit data"| API
    API -->|"utilizes"| UTIL
    API -->|"calls"| OBA
    API -->|"calls"| GEO
    API -->|"calls"| OTP
    FC -->|"renders maps via"| MAP
    FC -->|"integrates"| ANALYTICS

    CONFIG -->|"configures"| FS
    CONFIG -->|"configures"| API

    %% Click Events
    click FS "https://github.com/onebusaway/wayfinder/tree/main/src/routes"
    click FC "https://github.com/onebusaway/wayfinder/tree/main/src/components"
    click API "https://github.com/onebusaway/wayfinder/tree/main/src/routes/api"
    click MAP "https://github.com/onebusaway/wayfinder/tree/main/src/lib/Provider"
    click GEO "https://github.com/onebusaway/wayfinder/blob/main/src/routes/api/oba/geocode-location/+server.js"
    click OTP "https://github.com/onebusaway/wayfinder/blob/main/src/routes/api/otp/plan/+server.js"
    click ANALYTICS "https://github.com/onebusaway/wayfinder/tree/main/src/lib/Analytics"
    click CONFIG "https://github.com/onebusaway/wayfinder/blob/main/.env.example"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
```
