{"id":30111132,"url":"https://github.com/chad-syntax/railway-world","last_synced_at":"2025-08-10T05:07:41.031Z","repository":{"id":282328292,"uuid":"948226982","full_name":"chad-syntax/railway-world","owner":"chad-syntax","description":"3d representation of railway projects in the web","archived":false,"fork":false,"pushed_at":"2025-04-15T02:41:37.000Z","size":474,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-15T03:25:54.441Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/chad-syntax.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}},"created_at":"2025-03-14T00:49:35.000Z","updated_at":"2025-04-15T02:41:40.000Z","dependencies_parsed_at":"2025-03-14T01:45:47.164Z","dependency_job_id":"feb9f5f4-697d-435f-9027-e0f92dbc0935","html_url":"https://github.com/chad-syntax/railway-world","commit_stats":null,"previous_names":["chad-syntax/railway-world"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chad-syntax/railway-world","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chad-syntax%2Frailway-world","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chad-syntax%2Frailway-world/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chad-syntax%2Frailway-world/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chad-syntax%2Frailway-world/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chad-syntax","download_url":"https://codeload.github.com/chad-syntax/railway-world/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chad-syntax%2Frailway-world/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269677801,"owners_count":24457876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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-08-10T05:07:39.163Z","updated_at":"2025-08-10T05:07:41.016Z","avatar_url":"https://github.com/chad-syntax.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Follow on X](https://img.shields.io/twitter/follow/chad_syntax?style=social\u0026logo=twitter)](https://x.com/chad_syntax)\n\n# Railway World\n\nA 3D interactive visualization tool for Railway infrastructure. This application renders your Railway services as structures in a Minecraft-inspired world and visualizes network traffic between services in real-time.\n\nThis is a quick side project to re-familiarize myself with threejs and web graphics. I do not plan on maintaining this or adding much to it. In fact if I were to make this for real, I would probably try using godot.\n\n## Features\n\n- Interactive 3D world with first-person controls (WASD + mouse look, Space/Ctrl to fly)\n- Visualization of Railway services as structures with distinct characteristics\n- Real-time visualization of network traffic between services\n- Centralized \"Internet\" globe representing external traffic\n- GraphQL integration with Railway's API for fetching service data\n- Client-server architecture for real-time updates\n\n## Host your own Railway World... on Railway!\n\n[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/BcMvgp?referralCode=chad)\n\n### Required Environment Variables\n\n- `RAILWAY_WORLD_TOKEN` - Your Railway API token [token docs](https://docs.railway.com/guides/public-api#creating-a-token)\n- `RAILWAY_WORLD_PROJECT_ID` - The ID of the Railway project you want to visualize (copy from project settings)\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js (v22.14.0 recommended)\n- A Railway account with API access\n- Your Railway API token\n- The project ID of the Railway project you want to visualize\n\n### Installation\n\n1. Clone this repository\n\n```bash\ngit clone https://github.com/yourusername/railway-world.git\ncd railway-world\n```\n\n2. Install dependencies\n\n```bash\nnpm install\n```\n\n3. Copy the .env.example and set env vars\n\n```bash\ncp .env.example .env\n```\n\n```bash\nRAILWAY_WORLD_TOKEN=\"your-railway-token\"\nRAILWAY_WORLD_PROJECT_ID=\"your-railway-project-id\"\nMOCK_DATA=\"false\"\n```\n\nThe `MOCK_DATA` environment variable can be set to `\"true\"` to use mock data instead of making real API calls to Railway. This is useful for development and testing without hitting the Railway APIs.\n\n4. Start the development server (both backend and frontend)\n\n```bash\nnpm run dev\n```\n\n4. Open your browser and navigate to `http://localhost:5173`\n\n5. The 3D visualization will load automatically using your configured environment variables\n\n## Controls\n\n- **W/A/S/D**: Move forward/left/backward/right\n- **Mouse**: Look around\n- **Space**: Fly up\n- **Ctrl**: Fly down\n- **Click**: Enable pointer lock (press ESC to exit)\n\n## Architecture\n\nThe application consists of:\n\n1. **Frontend Client**: Three.js-based 3D visualization\n2. **Backend Server**: Fastify server that communicates with Railway's GraphQL API\n3. **Railway GraphQL APIs**: Outside API dependency for fetching Railway App data\n\n### Project Structure\n\n- `src/client.ts`: Frontend client entry point\n- `src/server.ts`: Backend server entry point\n- `src/lib/`: Core library code\n  - `types.ts`: TypeScript type definitions\n  - `constants.ts`: Application constants\n  - `utils.ts`: Shared utility functions\n  - `colors.ts`: Color definitions for visualization\n  - `mock-data.ts`: Mock data for development/testing\n  - `client/`: Frontend-specific code\n    - `three/`: Three.js visualization components\n      - `World.ts`: Main Three.js scene management\n      - `ServiceStructure.ts`: Service visualization as 3D structures\n      - `InternetGlobe.ts`: Central globe representing external traffic\n      - `RequestBlock.ts`: Visualization of network requests\n      - `ConnectionLine.ts`: Network connection visualization\n      - `VolumeStructure.ts`: Volume-based service visualization\n      - `WorldObject.ts`: Base class for all 3D objects\n      - `Billboard.ts`: Base class for billboard text overlays\n      - `AuthorBillboard.ts`: Author attribution display\n      - `ProjectBillboard.ts`: Project information display\n      - `Player.ts`: First-person player controls and camera\n    - `websocket.ts`: WebSocket client for real-time updates\n    - `fetch-railway-data.ts`: Railway API data fetching\n  - `server/`: Backend-specific code\n    - `graphql/`: Railway GraphQL API integration\n    - `handlers/`: API route handlers\n    - `LiveDataService.ts`: Service for managing live data updates\n\n## Development\n\n### Running in Development Mode\n\n```bash\n# Start both frontend and backend in development mode\nnpm run dev\n\n# Start only the frontend\nnpm run dev:client\n\n# Start only the backend\nnpm run dev:server\n```\n\n### Building for Production\n\n```bash\nnpm run build\n```\n\nThe production build will be in the `dist` directory. To run the production server:\n\n```bash\nnpm start\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchad-syntax%2Frailway-world","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchad-syntax%2Frailway-world","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchad-syntax%2Frailway-world/lists"}