{"id":34838352,"url":"https://github.com/punitmishra/railroad-arcade","last_synced_at":"2026-01-13T20:46:26.115Z","repository":{"id":328605918,"uuid":"1116106582","full_name":"punitmishra/railroad-arcade","owner":"punitmishra","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-28T13:01:11.000Z","size":1446,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-30T19:10:02.137Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://railroad-arcade-v5.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/punitmishra.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-14T07:55:41.000Z","updated_at":"2025-12-28T13:01:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/punitmishra/railroad-arcade","commit_stats":null,"previous_names":["punitmishra/railroad-arcade"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/punitmishra/railroad-arcade","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitmishra%2Frailroad-arcade","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitmishra%2Frailroad-arcade/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitmishra%2Frailroad-arcade/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitmishra%2Frailroad-arcade/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/punitmishra","download_url":"https://codeload.github.com/punitmishra/railroad-arcade/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/punitmishra%2Frailroad-arcade/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28400162,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-25T16:48:10.545Z","updated_at":"2026-01-13T20:46:26.108Z","avatar_url":"https://github.com/punitmishra.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"public/icons/icon-512x512.png\" alt=\"Railroad Arcade\" width=\"120\" height=\"120\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eRailroad Arcade\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eControl a real 2-level HO scale model railroad from anywhere in the world\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://railroad-arcade-v5.vercel.app\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/demo-live-00f0ff?style=for-the-badge\" alt=\"Live Demo\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-a855f7?style=for-the-badge\" alt=\"MIT License\"\u003e\n  \u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-1.4.1-ffd700?style=for-the-badge\" alt=\"Version 1.4.1\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/next.js-14-black?style=for-the-badge\u0026logo=next.js\" alt=\"Next.js 14\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/rust-backend-orange?style=for-the-badge\u0026logo=rust\" alt=\"Rust Backend\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#hardware-backend\"\u003eHardware Backend\u003c/a\u003e •\n  \u003ca href=\"#api-reference\"\u003eAPI Reference\u003c/a\u003e •\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is Railroad Arcade?\n\nRailroad Arcade is a full-stack IoT application that lets you control a real HO scale model railroad remotely. The system combines a **Next.js 14 frontend** deployed on Vercel with a **Rust-based backend** running on a Raspberry Pi that controls the physical hardware.\n\n**Play in Demo Mode** for free simulation, or switch to **Live Mode** to control actual trains, junctions, crossings, and scenery via the internet.\n\n### Live Demo \u0026 Downloads\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://railroad-arcade-v5.vercel.app\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Web_App-Play_Now-00f0ff?style=for-the-badge\u0026logo=pwa\" alt=\"Web App\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"#\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/App_Store-Coming_Soon-000000?style=for-the-badge\u0026logo=apple\" alt=\"App Store\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"#\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Google_Play-Coming_Soon-414141?style=for-the-badge\u0026logo=google-play\" alt=\"Google Play\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                              CLOUD (Vercel)                                  │\n├─────────────────────────────────────────────────────────────────────────────┤\n│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐  │\n│  │   Next.js 14    │  │   PostgreSQL    │  │      Upstash Redis          │  │\n│  │   Frontend      │  │   (Neon)        │  │   + QStash Queue            │  │\n│  │   + API Routes  │  │                 │  │                             │  │\n│  └────────┬────────┘  └────────┬────────┘  └──────────────┬──────────────┘  │\n│           │                    │                          │                  │\n│           │  Prisma ORM        │    Cache + Jobs          │                  │\n│           └────────────────────┴──────────────────────────┘                  │\n└─────────────────────────────────────┬───────────────────────────────────────┘\n                                      │\n                                      │ HTTPS (Live Mode)\n                                      ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         RASPBERRY PI (On-Premise)                            │\n├─────────────────────────────────────────────────────────────────────────────┤\n│  ┌─────────────────────────────────────────────────────────────────────┐    │\n│  │                    Rust Backend (Actix-web)                          │    │\n│  │                    Port 5000 - REST API                              │    │\n│  └───────────┬─────────────────┬─────────────────┬─────────────────────┘    │\n│              │                 │                 │                          │\n│              ▼                 ▼                 ▼                          │\n│  ┌───────────────┐  ┌──────────────────┐  ┌──────────────────┐              │\n│  │  PWM Drivers  │  │ Circuit Playground│  │   USB Camera     │              │\n│  │  (3 Tracks)   │  │ Express (CPX)     │  │  MJPEG Stream    │              │\n│  │              │  │  - 4 Servos       │  │  Port 8080       │              │\n│  │              │  │  - Gate Control   │  │                  │              │\n│  │              │  │  - LEDs/Sound     │  │                  │              │\n│  └───────┬──────┘  └────────┬─────────┘  └────────┬─────────┘              │\n│          │                  │                     │                         │\n└──────────┼──────────────────┼─────────────────────┼─────────────────────────┘\n           │                  │                     │\n           ▼                  ▼                     ▼\n    ┌──────────────────────────────────────────────────────┐\n    │              HO SCALE MODEL RAILROAD                  │\n    │  • 3 Trains (Level 1 \u0026 2)    • 3 Junctions           │\n    │  • 3 Crossings               • 6 Signals             │\n    │  • Distance Sensors (HC-SR04) • Scenery Lighting     │\n    └──────────────────────────────────────────────────────┘\n```\n\n### Repository Structure\n\n| Repository | Description | Stack |\n|------------|-------------|-------|\n| [railroad-arcade](https://github.com/punitmishra/railroad-arcade) | Frontend + Cloud APIs | Next.js, TypeScript, Prisma |\n| [pi-railroad-controller](https://github.com/punitmishra/pi-railroad-controller) | Raspberry Pi Backend | Rust, Actix-web |\n\n---\n\n## Features\n\n### Train Control\n- **Real-time Visualization** — Live SVG track with 3 animated trains across 2 levels\n- **Speed \u0026 Direction** — 0-100% speed control with forward/reverse\n- **Junction \u0026 Crossing Control** — Toggle switches and railroad crossings\n- **Autopilot Mode** — Automated train operation with station stops\n- **Emergency Stop** — Global safety stop across all trains\n\n### Game Modes\n| Mode | Description | Token Cost |\n|------|-------------|------------|\n| Free Play | Sandbox exploration | 2 |\n| Speed Run | Complete circuits fast | 5 |\n| Delivery Mission | Transport cargo | 5 |\n| Survival | Avoid collisions | 5 |\n| Time Attack | Score in time limit | 5 |\n\n### Hardware Control (Live Mode)\n- **PWM Motor Control** — Precise speed control for 3 train tracks\n- **Servo Junctions** — 4 servo-controlled track switches via CPX\n- **Crossing Gates** — Automated gate up/down with position sensing\n- **Distance Sensors** — HC-SR04 ultrasonic sensors for train detection\n- **LED Signals** — Red/Yellow/Green signal states based on proximity\n- **Scenery Lighting** — 7 independent lighting zones\n\n### Multi-Camera System\n- **Layout Options** — Single, dual, quad, and picture-in-picture\n- **MJPEG Streaming** — Real-time video with auto-retry\n- **Snapshot Gallery** — Capture, like, download, and share\n- **Camera Presets** — Overview, stations, action views\n\n### Progression \u0026 Social\n- **10 Achievements** — Unlock badges with toast notifications\n- **Leaderboards** — Global rankings by game mode (Demo \u0026 Live)\n- **Session History** — Timeline view with detailed stats\n- **Tournament System** — Daily, weekly, and championship events\n- **Social Sharing** — Share scores and snapshots via Web Share API\n\n### Platform Features\n- **PWA Support** — Install as app on any device\n- **Kiosk Mode** — Full-screen arcade cabinet support\n- **17 Sound Effects** — Synthesized arcade audio with haptic feedback\n- **Keyboard \u0026 Gamepad** — Full control support\n- **Mobile Optimized** — Capacitor-ready for iOS/Android\n\n### New in v1.4.1: Queue \u0026 Session Management\n- **Hardware Health Check** — Real-time Pi status with latency monitoring\n- **Session Lifecycle** — Heartbeat keep-alive with 60s timeout\n- **Real-time SSE** — Live hardware state from Rust backend (tracks, sensors, camera)\n- **Session Recording** — Record and playback with speed control (0.25x-4x)\n- **Spectator Mode** — Watch live sessions without joining queue\n- **Priority Queue** — Skip ahead with Priority (2x), Express (3x), or VIP (5x) tokens\n\n---\n\n## Quick Start\n\n### Frontend (Next.js)\n\n```bash\n# Clone and install\ngit clone https://github.com/punitmishra/railroad-arcade.git\ncd railroad-arcade\nnpm install\n\n# Configure environment\ncp .env.example .env\n```\n\n#### Required Environment Variables\n\n```bash\n# Database (PostgreSQL - recommend Neon for free tier)\nDATABASE_URL=\"postgresql://user:password@host/database?sslmode=require\"\n\n# Auth (generate secret with: openssl rand -base64 32)\nNEXTAUTH_URL=\"http://localhost:3000\"\nNEXTAUTH_SECRET=\"your-generated-secret\"\n\n# Redis (Upstash - free tier available)\nUPSTASH_REDIS_REST_URL=\"https://your-redis.upstash.io\"\nUPSTASH_REDIS_REST_TOKEN=\"your-token\"\n```\n\n#### Optional Environment Variables\n\n```bash\n# Raspberry Pi Hardware (for Live Mode)\nNEXT_PUBLIC_API_URL=\"http://raspberry-pi-ip:5000\"\n\n# Background Jobs (QStash)\nQSTASH_TOKEN=\"your-qstash-token\"\nQSTASH_CURRENT_SIGNING_KEY=\"...\"\nQSTASH_NEXT_SIGNING_KEY=\"...\"\n\n# Payments\nSTRIPE_SECRET_KEY=\"sk_...\"\nPAYPAL_CLIENT_ID=\"...\"\nCOINBASE_COMMERCE_API_KEY=\"...\"\n\n# Admin Access\nADMIN_KEY=\"your-admin-api-key\"\nADMIN_USER_IDS=\"user-id-1,user-id-2\"\nADMIN_EMAILS=\"admin@example.com\"\n```\n\n#### Database Setup \u0026 Run\n\n```bash\n# Generate Prisma client\nnpx prisma generate\n\n# Push schema to database\nnpx prisma db push\n\n# Run development server\nnpm run dev\n\n# Run tests (298 tests)\nnpm test\n```\n\nOpen http://localhost:3000 — Demo Mode works immediately!\n\n### Backend (Rust on Raspberry Pi)\n\n```bash\n# On Raspberry Pi\ngit clone https://github.com/punitmishra/pi-railroad-controller.git\ncd pi-railroad-controller\n\n# Build and run\ncargo build --release\n./target/release/pi-railroad-controller\n```\n\nThe backend runs on port 5000 (API) and port 8080 (camera stream).\n\n---\n\n## Hardware Backend\n\n### Rust API Server\n\nThe Raspberry Pi runs a Rust backend built with Actix-web that provides:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/status` | GET | System status, track states, distances |\n| `/api/tracks` | GET | All track states (speed, direction, running) |\n| `/api/tracks/:id/speed` | POST | Set track speed (0-100) |\n| `/api/tracks/:id/forward` | POST | Set forward direction |\n| `/api/tracks/:id/reverse` | POST | Set reverse direction |\n| `/api/tracks/:id/stop` | POST | Stop track |\n| `/api/emergency-stop` | POST | Emergency stop all tracks |\n| `/api/cpx/status` | GET | CPX status (servos, gate, temp) |\n| `/api/cpx/servo/:num/:angle` | POST | Set servo angle |\n| `/api/cpx/gate/:position` | POST | Set gate up/down |\n| `/api/cpx/led/:color` | POST | Set CPX LED color |\n| `/api/cpx/sound/:name` | POST | Play sound on CPX |\n| `/api/camera/start` | POST | Start camera stream |\n| `/api/camera/stop` | POST | Stop camera stream |\n| `/api/camera/status` | GET | Camera status |\n| `/api/distances` | GET | HC-SR04 sensor readings |\n| `/api/scenery` | GET/POST | Scenery state (time, lighting) |\n| `/api/schedules` | GET/POST/DELETE | Automation schedules |\n| `/api/sequences` | GET | Available automation sequences |\n| `/api/sequences/:id/run` | POST | Execute automation sequence |\n\n### Hardware Components\n\n| Component | Model | Purpose |\n|-----------|-------|---------|\n| SBC | Raspberry Pi 4 | Main controller |\n| Motor Driver | PCA9685 PWM | 3-channel train speed control |\n| Servo Controller | Circuit Playground Express | 4 junction servos + gate |\n| Distance Sensors | HC-SR04 (x6) | Train position detection |\n| Camera | USB Webcam | MJPEG streaming |\n| Power | 12V 5A + 5V 3A | Motors + Pi power |\n\n---\n\n## Tech Stack\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=nextjs\" width=\"48\" height=\"48\" alt=\"Next.js\" /\u003e\n      \u003cbr\u003eNext.js 14\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=ts\" width=\"48\" height=\"48\" alt=\"TypeScript\" /\u003e\n      \u003cbr\u003eTypeScript\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=rust\" width=\"48\" height=\"48\" alt=\"Rust\" /\u003e\n      \u003cbr\u003eRust\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=tailwind\" width=\"48\" height=\"48\" alt=\"Tailwind\" /\u003e\n      \u003cbr\u003eTailwind\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=prisma\" width=\"48\" height=\"48\" alt=\"Prisma\" /\u003e\n      \u003cbr\u003ePrisma\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=postgres\" width=\"48\" height=\"48\" alt=\"PostgreSQL\" /\u003e\n      \u003cbr\u003ePostgreSQL\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=redis\" width=\"48\" height=\"48\" alt=\"Redis\" /\u003e\n      \u003cbr\u003eRedis\n    \u003c/td\u003e\n    \u003ctd align=\"center\" width=\"96\"\u003e\n      \u003cimg src=\"https://skillicons.dev/icons?i=raspberrypi\" width=\"48\" height=\"48\" alt=\"Raspberry Pi\" /\u003e\n      \u003cbr\u003ePi 4\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Frontend Stack\n| Category | Technology |\n|----------|------------|\n| **Framework** | Next.js 14 (App Router) |\n| **Language** | TypeScript 5 |\n| **Database** | PostgreSQL (Neon) + Prisma ORM |\n| **Auth** | NextAuth.js v4 (JWT) |\n| **Styling** | Tailwind CSS |\n| **Caching** | Upstash Redis |\n| **Queue** | QStash (scheduled jobs) |\n| **Payments** | Stripe, PayPal, Coinbase Commerce |\n| **Real-time** | Server-Sent Events (SSE) |\n| **PWA** | next-pwa with Service Worker |\n| **Deployment** | Vercel (Edge + Serverless) |\n\n### Backend Stack (Raspberry Pi)\n| Category | Technology |\n|----------|------------|\n| **Language** | Rust 1.75+ |\n| **Framework** | Actix-web 4 |\n| **Hardware** | rppal (GPIO), serialport |\n| **Async** | Tokio runtime |\n| **Camera** | v4l2 + MJPEG |\n| **Config** | TOML |\n\n---\n\n## API Reference\n\n### Cloud API (Next.js)\n\n#### Public Endpoints\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/leaderboards` | GET | Fetch high scores by game mode |\n| `/api/tournaments` | GET | List active tournaments |\n| `/api/tournaments/[id]/leaderboard` | GET | Tournament rankings |\n| `/api/health` | GET | System health check |\n\n#### Authenticated Endpoints\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/user` | GET | Current user data + token balance |\n| `/api/user/modules` | POST | Unlock building module |\n| `/api/user/stats` | GET | Play statistics |\n| `/api/sessions` | GET/POST | Session history / Start session |\n| `/api/games` | POST/PUT | Start/end game session |\n| `/api/tournaments/[id]/register` | POST | Join tournament |\n| `/api/tournaments/[id]/submit` | POST | Submit score |\n| `/api/snapshots` | GET/POST | Snapshot gallery |\n\n#### Admin Endpoints\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/api/admin/grant-tokens` | POST | Grant tokens to user |\n| `/api/admin/tournaments/[id]` | PATCH/DELETE | Manage tournament |\n\n### Hardware API (Raspberry Pi)\n\nSee [docs/API.md](docs/API.md) for complete Rust backend API documentation.\n\n---\n\n## Environment Variables\n\n### Frontend (.env)\n\n```bash\n# Required\nDATABASE_URL=\"postgresql://...\"           # Neon PostgreSQL\nNEXTAUTH_URL=\"http://localhost:3000\"\nNEXTAUTH_SECRET=\"your-secret-here\"\n\n# Caching \u0026 Queue\nUPSTASH_REDIS_REST_URL=\"https://...\"\nUPSTASH_REDIS_REST_TOKEN=\"...\"\nQSTASH_URL=\"https://qstash.upstash.io\"\nQSTASH_TOKEN=\"...\"\n\n# Hardware Connection (Live Mode)\nNEXT_PUBLIC_API_URL=\"http://raspberry-pi.local:5000\"\n\n# Payments (optional)\nSTRIPE_SECRET_KEY=\"sk_...\"\nPAYPAL_CLIENT_ID=\"...\"\nCOINBASE_COMMERCE_API_KEY=\"...\"\n\n# Admin\nADMIN_KEY=\"your-admin-key\"\nADMIN_USER_IDS=\"user-id-1,user-id-2\"\n```\n\n### Backend (config.toml on Pi)\n\n```toml\n[server]\nhost = \"0.0.0.0\"\nport = 5000\n\n[hardware]\npwm_address = 0x40\ncpx_port = \"/dev/ttyACM0\"\n\n[camera]\ndevice = \"/dev/video0\"\nwidth = 640\nheight = 480\nfps = 30\n```\n\n---\n\n## Development\n\n### Frontend Commands\n\n```bash\nnpm run dev          # Development server\nnpm run build        # Production build\nnpm run start        # Production server\nnpm run lint         # ESLint\nnpm run test         # Jest tests (298 tests)\n```\n\n### Database Commands\n\n```bash\nnpx prisma generate  # Generate client\nnpx prisma db push   # Push schema\nnpx prisma studio    # GUI browser\nnpx prisma migrate dev  # Create migration\n```\n\n### Backend Commands (Rust)\n\n```bash\ncargo build          # Debug build\ncargo build --release # Production build\ncargo test           # Run tests\ncargo run            # Run server\n```\n\n---\n\n## Testing\n\n```bash\n# Run all tests\nnpm test\n\n# Current test coverage\n# - 12 test suites\n# - 298 tests passing\n# - API client tests\n# - Hardware adapter tests\n# - Game mode tests\n# - Token guard tests\n```\n\n---\n\n## Deployment\n\n### Frontend (Vercel)\n\n1. Push to GitHub\n2. Import in [Vercel](https://vercel.com)\n3. Add environment variables\n4. Deploy (automatic on push)\n\n### Backend (Raspberry Pi)\n\n```bash\n# Build release binary\ncargo build --release\n\n# Create systemd service\nsudo nano /etc/systemd/system/railroad.service\n\n# Enable and start\nsudo systemctl enable railroad\nsudo systemctl start railroad\n```\n\nSee [docs/HARDWARE.md](docs/HARDWARE.md) for complete Pi setup guide.\n\n---\n\n## Roadmap\n\n### Completed (v1.4.1)\n- [x] Rust backend API integration\n- [x] String trackId alignment with backend\n- [x] Camera control endpoints\n- [x] CPX servo/gate control\n- [x] Distance sensor readings\n- [x] Automation sequences\n- [x] Comprehensive API tests (298 tests)\n- [x] Hardware health check system\n- [x] Queue system for live mode sessions\n- [x] Session lifecycle with heartbeat/timeout\n- [x] Real-time SSE from Rust backend\n- [x] Session recording and playback\n- [x] Spectator mode (watch live sessions)\n- [x] Priority queue (3 tiers: Priority/Express/VIP)\n\n### Next Steps\n- [ ] WebSocket upgrade (replace SSE polling)\n- [ ] Multi-user concurrent control\n- [ ] Mobile app release (iOS/Android)\n- [ ] Voice control integration\n- [ ] Train collision detection\n- [ ] Automated scheduling system\n\n---\n\n## Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit changes: `git commit -m 'Add amazing feature'`\n4. Push to branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n---\n\n## Security\n\nFound a vulnerability? Please see [SECURITY.md](SECURITY.md) for our responsible disclosure policy.\n\n---\n\n## License\n\n[MIT License](LICENSE) — feel free to use and modify for your own projects.\n\n---\n\n## Acknowledgments\n\n- Train icons by [Lucide](https://lucide.dev)\n- Fonts: Orbitron, Space Grotesk, JetBrains Mono\n- Deployed on [Vercel](https://vercel.com)\n- Rust async runtime by [Tokio](https://tokio.rs)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with \u003cspan style=\"color: #00f0ff;\"\u003e\u0026#9829;\u003c/span\u003e for model railroad enthusiasts\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://railroad-arcade-v5.vercel.app\"\u003ePlay Now\u003c/a\u003e •\n  \u003ca href=\"https://github.com/punitmishra/railroad-arcade/issues\"\u003eReport Bug\u003c/a\u003e •\n  \u003ca href=\"https://github.com/punitmishra/railroad-arcade/discussions\"\u003eDiscussions\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpunitmishra%2Frailroad-arcade","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpunitmishra%2Frailroad-arcade","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpunitmishra%2Frailroad-arcade/lists"}