A modern web application for generating and managing switchlists for model railroad operations, built with Next.js, TypeScript, and a rich UI.
Switch This is a sophisticated web-based tool designed to help model railroaders create and manage switchlists efficiently. The application provides a clean, intuitive interface for organizing and tracking rolling stock, industries, and train routes across different locations on a model railroad layout. It eliminates the need for spreadsheets or paper-based methods in managing operational sessions.
In model railroading, switchlists are documents that tell operators which rail cars need to be picked up or dropped off at various industries on the layout. They simulate the paperwork that real railroads use to manage freight operations, adding realism and purpose to operating sessions.
- Industry Management: Create, edit, and organize industries at various locations
- Location Tracking: Manage stations and blocks across your railroad layout
- Rolling Stock Inventory: Track all your rail cars with details including road name, road number, and AAR type
- Train Routes: Define freight routes between yards with intermediate station stops
- Layout State Management: View and modify the current state of your entire layout
- Responsive Design: Works seamlessly on desktop and mobile devices
- MongoDB Integration: Persistent storage of all railroad data
- Next.js - React framework with App Router
- TypeScript - Type-safe JavaScript
- Material-UI - React UI components
- Tailwind CSS - Utility-first CSS framework
- MongoDB - NoSQL database for data storage
- Jest - Testing framework
- React Testing Library - Testing utilities
- Node.js 18.0 or later
- npm or yarn package manager
- MongoDB (local instance or remote connection)
- Docker and Docker Compose (optional, for containerized setup)
- Clone the repository:
git clone [repository-url]
cd switch-this- Install dependencies:
npm install
# or
yarn install- Set up environment variables:
Create a
.envfile based on the provided example and configure your MongoDB connection details.
Your .env file should include the following variables:
# MongoDB Connection
MONGODB_URI=mongodb://localhost:27017/switch-this
MONGODB_DB=switch-this
# API Configuration
API_URL=http://localhost:3000/api
NEXT_PUBLIC_API_URL=http://localhost:3000/api
# Authentication (if implemented)
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRY=7d
# Development Settings
NODE_ENV=development
- Start the MongoDB container (if using Docker):
docker-compose up -d- Seed the database (optional):
npm run seed
# or
yarn seed- Run the development server:
npm run dev
# or
yarn dev- Open http://localhost:3000 in your browser to see the application.
The project follows a component-based architecture with a focus on:
- Clean, maintainable code through TDD (Test-Driven Development)
- Type safety with TypeScript
- Responsive design principles
- Strict adherence to XP (Extreme Programming) practices
src/- Source codeapp/- Main application code (Next.js App Router)api/- API routes for industries, locations, rolling stock, and train routescomponents/- Reusable UI componentsindustries/- Industry management pageslayout-state/- Layout state management functionalityrolling-stock/- Rolling stock managementtrain-routes/- Train route managementshared/- Shared components, hooks, contexts, and servicesstyles/- Global styles
data/- Sample data for developmentlib/- Core utilities, services, and constantstest/- Test utilities and integration tests
docker/- Docker configuration for development
Below is a UML diagram representing the core entities and their relationships in the Switch This application:
classDiagram
class BaseEntity {
+string _id
+string ownerId
}
class Location {
+string stationName
+string block
+string description
+LocationType locationType
}
class Industry {
+string name
+string locationId
+string blockName
+string description
+IndustryType industryType
+Track[] tracks
}
class Track {
+string name
+number length
+number capacity
+number maxCars
+string[] placedCars
+string[] acceptedCarTypes
}
class RollingStock {
+string roadName
+string roadNumber
+string aarType
+string description
+string color
+string note
+string homeYard
+RollingStockLocation currentLocation
+CarDestination destination
}
class TrainRoute {
+string name
+string routeNumber
+string routeType
+string originatingYardId
+string terminatingYardId
+string[] stations
+string description
}
class Switchlist {
+string trainRouteId
+string name
+string createdAt
+string status
+string notes
}
class CarDestination {
+Object immediateDestination
+Object finalDestination
}
class RollingStockLocation {
+string industryId
+string trackId
}
BaseEntity <|-- Location
BaseEntity <|-- Industry
BaseEntity <|-- Track
BaseEntity <|-- RollingStock
BaseEntity <|-- TrainRoute
BaseEntity <|-- Switchlist
Industry "1" --> "1" Location : located at
Industry "1" *-- "many" Track : contains
RollingStock "many" --> "1" RollingStockLocation : has current
RollingStock "many" --> "0..1" CarDestination : has
Switchlist "1" --> "1" TrainRoute : uses
TrainRoute "1" --> "many" Location : goes through
RollingStock "many" --> "0..1" Track : placed on
The project uses Jest and React Testing Library for testing. Run tests with:
npm test
# or
yarn testFor test coverage:
npm run test:coverage
# or
yarn test:coverageContributions are welcome! Please follow the TDD approach and adhere to the Arlo Belshee git commit notation for all contributions.
[Add your license information here]