TrainLCD

TrainLCD is a mobile application that simulates Japanese railway company LCDs, providing real-time navigation and station information for train passengers.

This app recreates the authentic experience of Japanese train travel by displaying station information in the same style as actual train LCD screens. Whether you're a tourist visiting Japan, a daily commuter, or simply fascinated by Japanese railway systems, TrainLCD offers an immersive and practical navigation experience.

Table of Contents

• Screenshots
• Features
• Getting Started
  • Prerequisites
  • Installation
  • Running the App
• Download
• Development
  • Project Structure
  • Available Scripts
  • Testing
• Contributing
• Code of Conduct
• Architecture
• Support
• Join our Community
• Data Sources
• Contributors
• Related Projects
• License

Screenshots

Screenshots and demo videos coming soon...

Features

• 🚆 Authentic LCD: Experience genuine Japanese train LCD interfaces with accurate styling from major railway companies
• 📍 Real-time Location Tracking: Automatically detect your current position and display relevant station information
• 🔔 Smart Notifications: Get notified when approaching or arriving at your destination station
• 🎨 Multiple Themes: Choose from various railway company themes including JR East, JR West, Tokyo Metro, and more
• 📱 Cross-platform: Available on both iOS and Android devices
• 🌐 Offline Support: Core functionality works without internet connection
• 🗾 Comprehensive Coverage: Supports major railway lines across Japan

Getting Started

Prerequisites

Before you begin, ensure you have met the following requirements:

• Node.js 24.x (pinned via .nvmrc; run nvm use to switch automatically)
• npm 11.x (bundled with Node.js 24; engines + engine-strict=true block npm install on other versions)
• React Native development environment set up
• Expo CLI installed globally
• Android Studio (for Android development)
• Xcode (for iOS development, macOS only)

Installation

1. Clone the repository:

   git clone https://github.com/TrainLCD/MobileApp.git
   cd MobileApp
   

2. Check out the font submodule (maintainers only):

   git submodule update --init --recursive
   

   The station numbering icons and the LED theme use commercially licensed typefaces, so they are kept in a private submodule (android/app/src/main/assets/fonts, ios/Fonts) that cannot be redistributed. The app builds and runs without it — those glyphs simply fall back to the system font — so outside contributors can skip this step and should expect the numbering to render in a different typeface than the released builds.

3. Install dependencies:

   npm install
   

   Note: Configure GQL_API_URL before running npm run gql:codegen to regenerate GraphQL types.

Running the App

Development Mode

To start the development server:

npm run start

Platform-specific Commands

• iOS: npm run ios
• Android: npm run android
• Android (local-only variant): npm run android:local
• Web: npm run web

npm run android installs the dev flavor (me.tinykitten.trainlcd.dev), which is the same application ID as the Canary build distributed through the stores, so it replaces an installed Canary build. npm run android:local installs the local flavor (me.tinykitten.trainlcd.local, shown as TrainLCD Local) instead, which coexists with both store builds. It points at the same staging backends as Canary.

Download

Join our Community

If you like this project, join our Discord community!
NOTE: English is welcome, but in the community, we usually use Japanese for discussions, announcements, etc. https://discord.gg/tsemdME9Nz

Development

Project Structure

src/
├── components/        # Reusable UI components
├── screens/           # Screen components
├── hooks/             # Custom React hooks
├── store/             # Jotai atoms and selectors
├── stacks/            # React Navigation stack definitions
├── providers/         # Context providers and integration wrappers
├── lib/               # API clients and shared integrations
├── config/            # Static configuration helpers
├── constants/         # Shared constants
├── utils/             # Utility functions and test helpers
├── test/              # Testing utilities and e2e harness
├── __mocks__/         # Jest mocks
├── __fixtures__/      # Test fixtures
├── @types/            # Global TypeScript declarations
├── models/            # Data models
├── index.tsx          # App entry point
├── translation.ts     # i18n resources
└── lineSymbolImage.ts # Line symbol metadata

android/               # Native Android project
ios/                   # Native iOS project
docs/                  # Architectural notes and runbooks
assets/                # Static media bundled with the app
utils/                 # Tooling scripts and codegen helpers

Available Scripts

• npm run start - Start the Expo development server
• npm run android / npm run ios - Build and launch native binaries
• npm run android:local - Build and launch the Android local flavor, which can be installed alongside the store builds
• npm run web - Serve the Expo web build
• npm run lint - Run Biome linter
• npm run format - Format code with Biome
• npm test - Run Jest tests
• npm run typecheck - Run TypeScript type checking
• npm run watch:test - Run tests in watch mode
• npm run gql:codegen - Regenerate GraphQL types after schema or documents change (requires GQL_API_URL)

Testing

This project uses Jest for testing. Run the test suite with:

npm test

For watch mode during development:

npm run watch:test

Backend (Cloudflare Workers)

The backend Worker (TTS synthesis, session issuance, feedback triage, review notifiers, the AI destination agent) lives in TrainLCD/functions, and the GraphQL API is served directly by TrainLCD/StationAPI. Neither is part of this repository. The GraphQL BFF that used to sit between the app and StationAPI has been retired.

Voice announcements (TTS) use a different engine per platform:

• iOS: synthesized remotely by Google Cloud Text-to-Speech (female voice) through the Worker's /tts endpoint and played back with expo-audio. When synthesis is unavailable — no signal, a tunnel, or an API outage — that announcement falls back to the on-device synthesizer so it is never silently dropped. See the spec for the wire contract.
• Android: synthesized on-device with the OS-native speech synthesizer via expo-speech.

Both paths share the same announcement text pipeline; the SSML fragments emitted by the templates are converted to plain text before reaching either engine (src/utils/speakableText.ts), because neither engine interprets SSML.

Contributing

We welcome contributions from the community! Here's how you can help:

How to Contribute

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and ensure they follow our coding standards
4. Run tests: npm test
5. Run linting: npm run lint
6. Commit your changes: git commit -m 'Add some amazing feature'
7. Push to the branch: git push origin feature/amazing-feature
8. Open a Pull Request

Development Guidelines

• Follow the existing code style and conventions
• Write clear, descriptive commit messages
• Add tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting

Reporting Issues

If you encounter any bugs or have feature requests:

1. Check if the issue already exists in our Issues
2. If not, create a new issue with:
   • Clear description of the problem
   • Steps to reproduce (for bugs)
   • Expected vs actual behavior
   • Device/platform information
   • Screenshots if applicable

Code of Conduct

This project adheres to a code of conduct that we expect all contributors to follow. Please be respectful and professional in all interactions.

Our Standards

• Be welcoming and inclusive
• Respect differing viewpoints and experiences
• Give and gracefully accept constructive feedback
• Focus on what is best for the community
• Show empathy towards other community members

Architecture

TrainLCD is built with:

• React Native with Expo - Cross-platform mobile development
• TypeScript - Type safety and better developer experience
• React Navigation - Navigation library
• Tanstack Query - Data fetching and caching
• Cloudflare Workers - Backend API (auth, TTS, feedback, remote config) with R2/KV storage
• Sentry - Error tracking and performance monitoring
• GraphQL with Code Generator - Typed queries and operations

Support

Community Support

• Join our Discord community for discussions and support
• Check out existing Issues and Discussions

Professional Support

For professional support or custom development, please contact the maintainers.

Acknowledgments

• Thanks to all contributors who have helped improve this project
• Special thanks to the Japanese railway companies for providing inspiration
• The open-source community for the excellent tools and libraries

Data Sources

• Bus-related data provided by Tokyo Metropolitan Bureau of Transportation (Toei), licensed under CC BY 4.0
• Station data provided by 駅データ.jp

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Related Projects

• StationAPI - Backend API for station data

License

This project is licensed under the MIT License - see the LICENSE file for details.