Repository: mini-tokyo-3d Clone: https://github.com/moses-y/mini-tokyo-3d

The Problem

This repo provides a real-time 3D digital map of Tokyo’s public transport system, but the engineering foundation shows gaps typical of a demo-grade codebase: no test suite, no CI/CD gate, and dependencies without a lockfile. A contributor or client wanting to extend or operationalize the map faces unguarded code paths and reproducibility risk.

What This Does

The system visualizes trains, aircraft, and stations across Tokyo in 3D. Core logic lives in src/: src/index.js boots the application, src/controls/index.js handles UI interactions (pan, zoom, tilt, search), src/layers/index.js manages 3D layer rendering, and src/data-classes/index.js defines data models. Feed data comes from data/—stations.json, railways.json, flight-statuses.json, and 30+ train-timetable JSON files. Asset dictionaries (assets/dictionary-*.json) internationalize labels. The Express server (listed among frameworks) likely serves the app or an API, while public/index.html is the visual entry point. Data flows from JSON feeds into React/Vue components rendered on the 3D map, with no observed backend database—state appears in-memory or fetched on demand.

How It Is Wired

  • ENTRY POINTS: public/index.html loads the UI; src/index.js initializes the app context; src/controls/index.js binds mouse/touch gestures; src/layers/index.js toggles visibility of rail/air/ground layers; src/data-classes/index.js structures stop/train objects.
  • OUTSIDE TOUCHES: The code reads data/ JSON files directly (no ORM or DB abstraction observed), serves static assets, and exposes no external API beyond what Express configures. Dictionary files are imported for UI translation; timetable data is loaded per-line (e.g., data/train-timetables/jreast-yamanote.json).
  • HUB/CYCLE: src/index.js appears to aggregate layer and control setups, but no explicit call graph was provided. The widest blast radius likely stems from src/layers/index.js—modifying layer logic affects every visual element simultaneously.
  • UNMAPPED: Wiring between src/data-classes/index.js and the actual data-loaders in data/train-timetables/ has not been mapped for this brief.

How To Use It

Setup:

# Clone verbatim
git clone https://github.com/moses-y/mini-tokyo-3d

# Install dependencies (package.json implies npm/pnpm; exact scripts not documented in the excerpt)
npm install

Configuration: .env.example is present; copy to .env and adjust any secret-shaped paths flagged in the code-health audit. Environment variables likely control API keys or server ports, but the exact var names are not documented in the provided structure.

Running it: The entry point is public/index.html opened in a browser. No CLI start command is evidenced; typical Node/Express setups use node src/index.js or npm run dev (script not confirmed). Launch by serving public/ or running the Express entry if configured.

Real-World Use

A mobility analyst could ingest data/stations.json and data/railways.json to overlay custom route data. Example workflow:

import stations from '../data/stations.json';
import { addLayer } from './src/layers/index.js';
stations.forEach(s => addLayer('rail', { id: s.id, name: s.name }));

This would render station markers on the existing 3D map without modifying the core rendering pipeline.

Code Health & Issues

MEASURED ANALYSIS (static analysis, repository-wide):

  • Med – No test files detected – untested code paths – repository-wide
  • Med – No CI/CD pipeline detected – no automated build/test gate – .github/ or CI config
  • Low – Dependencies declared without a lockfile – non-reproducible builds – package.json
  • Low – Secret-shaped paths present; code-health audit confirms or clears them – docs/developer-guide/api/secrets.md, docs/fr/developer-guide/api/secrets.md, docs/ja/developer-guide/api/secrets.md

Additional observations from structure: LICENSE is present; 193 doc files exist in multiple languages; no lockfile alongside package.json; .github/ contains only FUNDING.yml.

The Bottom Line

The repo delivers a functional, visually impressive 3D transport map with solid data ingestion and i18n scaffolding. However, the absence of tests, CI, and a lockfile makes it unsuitable for production extension without auditing. Teams comfortable with rapid prototyping and manual reproducibility checks can leverage it quickly; others should budget time for the identified SDLC gaps before integrating into a regulated pipeline.