# dong-awa/howtogo architecture

> Architecture diagram of the GitHub repository dong-awa/howtogo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dong-awa/howtogo
- Repository: https://github.com/dong-awa/howtogo

## Overview

HowToGo is a client-side Minecraft mapping and navigation mod. Players mark roads and places on Xaero’s World Map, choose a destination, travel mode and route preference, preview a route, then start navigation with HUD guidance and optional voice announcements. The graph preserves the documented Create rail and station layer, transit planning, map editing/rendering and phone integration. Some subsystem links rely on README descriptions because their implementations were not sampled; those links are identified by README evidence rather than implying source inspection.

Main entry points: [`src/main/java/bili/dongsz/howtogo/HowToGo.java`](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/HowToGo.java) (Mod Events), [`src/main/java/bili/dongsz/howtogo/client/DestinationScreen.java`](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/DestinationScreen.java) (Destination Picker), [`src/main/java/bili/dongsz/howtogo/route/RoadRouter.java`](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/route/RoadRouter.java) (Road Router), [`src/main/java/bili/dongsz/howtogo/client/Navigation.java`](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/Navigation.java) (Navigation State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_editing["Road Mapping"]
  node_entry["Mod Events<br/>[HowToGo.java]"]
  node_edit["Road Editing"]
  node_snap["Road Snapping<br/>[RoadSnapper.java]"]
  node_renderer["World Map Rendering<br/>[RoadLayer.java]"]
end

subgraph group_network["Map Data"]
  node_editor["Network Editor<br/>[RoadEditor.java]"]
  node_networkdata["Road Network<br/>[RoadNetwork.java]"]
  node_roadstore[("Road Persistence<br/>[RoadStore.java]")]
  node_roadfile["Road Storage Format<br/>[RoadStorage.java]"]
  node_rail["Create Rail Layer"]
  node_railnames[("Rail Names<br/>[RailNameStore.java]")]
  node_transitdata["Transit Lines<br/>[TransitLine.java]"]
  node_transitstore[("Transit Persistence")]
end

subgraph group_planning["Trip Planning"]
  node_destinations["Destination Sources<br/>[Destinations.java]"]
  node_poi["POI Destinations"]
  node_stations["Station Destinations"]
  node_planner["Road Router<br/>[RoadRouter.java]"]
  node_transitplanner["Transit Planner"]
  node_preferences["Route Preferences"]
  node_prefstore[("Preference Storage")]
  node_config["Client Configuration<br/>[RoadConfig.java]"]
end

subgraph group_guidance["Navigation UI"]
  node_screen["Destination Picker"]
  node_navigation["Navigation State<br/>[Navigation.java]"]
  node_hud["Navigation HUD"]
  node_narration["Voice Guidance<br/>[Narration.java]"]
  node_phonepicker["Phone Picker"]
end

node_player(("Player"))
node_xaero["Xaero World Map"]
node_create["Create Mod"]
node_mcphone["McPhone"]

node_player -->|"edits roads"| node_edit
node_xaero -->|"hosts map layer"| node_renderer
node_renderer -.->|"renders network"| node_networkdata
node_entry -->|"registers input"| node_edit
node_entry -->|"ticks navigation"| node_navigation
node_entry -->|"ticks rail layer"| node_rail
node_entry -->|"ticks storage"| node_roadstore
node_edit -->|"snaps placement"| node_snap
node_edit -->|"applies edits"| node_editor
node_editor -->|"mutates graph"| node_networkdata
node_roadstore -->|"serializes network"| node_roadfile
node_roadstore -.->|"loads and saves"| node_networkdata
node_create -.->|"supplies track data"| node_rail
node_rail -->|"stores names separately"| node_railnames
node_rail -->|"provides stations"| node_stations
node_player -->|"chooses trip"| node_screen
node_destinations -->|"includes POIs"| node_poi
node_destinations -->|"includes stations"| node_stations
node_screen -->|"lists destinations"| node_destinations
node_screen -->|"previews route"| node_planner
node_screen -->|"sets route options"| node_preferences
node_planner -->|"routes on graph"| node_networkdata
node_planner -->|"uses preferences"| node_preferences
node_transitplanner -->|"plans walk legs"| node_planner
node_transitplanner -.->|"uses transit lines"| node_transitdata
node_screen -->|"starts navigation"| node_navigation
node_navigation -->|"drives HUD"| node_hud
node_navigation -->|"announces turns"| node_narration
node_preferences -->|"persists choices"| node_prefstore
node_entry -->|"loads preferences"| node_prefstore
node_player -.->|"selects destination"| node_phonepicker
node_phonepicker -->|"starts trip"| node_navigation
node_config -->|"configures routing"| node_planner
node_config -.->|"configures voice"| node_narration

click node_entry "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/HowToGo.java"
click node_edit "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadEditSession.java"
click node_snap "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadSnapper.java"
click node_editor "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/road/RoadEditor.java"
click node_networkdata "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/road/RoadNetwork.java"
click node_roadstore "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadStore.java"
click node_roadfile "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/road/RoadStorage.java"
click node_rail "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RailTrackStore.java"
click node_railnames "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RailNameStore.java"
click node_transitdata "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/transit/TransitLine.java"
click node_transitstore "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/transit/TransitLineStorage.java"
click node_destinations "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/Destinations.java"
click node_poi "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/PoiDestinationSource.java"
click node_stations "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/CreateStationSource.java"
click node_planner "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/route/RoadRouter.java"
click node_transitplanner "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/route/TransitPlanner.java"
click node_preferences "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/route/RoutePreferences.java"
click node_prefstore "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/store/RoutePreferenceStore.java"
click node_screen "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/DestinationScreen.java"
click node_navigation "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/Navigation.java"
click node_hud "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/NavHudRenderer.java"
click node_narration "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/Narration.java"
click node_renderer "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadLayer.java"
click node_phonepicker "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/compat/mcphone/DestinationPickerPage.java"
click node_config "https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/RoadConfig.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_edit,node_snap,node_renderer toneBlue
class node_editor,node_networkdata,node_roadstore,node_roadfile,node_rail,node_railnames,node_transitdata,node_transitstore toneAmber
class node_destinations,node_poi,node_stations,node_planner,node_transitplanner,node_preferences,node_prefstore,node_config toneMint
class node_screen,node_navigation,node_hud,node_narration,node_phonepicker toneRose
class node_player,node_xaero,node_create,node_mcphone toneIndigo
```

## Components

### Road Mapping

- [Mod Events](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/HowToGo.java): `src/main/java/bili/dongsz/howtogo/HowToGo.java`
- [Road Editing](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadEditSession.java): `src/main/java/bili/dongsz/howtogo/client/RoadEditSession.java`
- [Road Snapping](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadSnapper.java): `src/main/java/bili/dongsz/howtogo/client/RoadSnapper.java`
- [World Map Rendering](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadLayer.java): `src/main/java/bili/dongsz/howtogo/client/RoadLayer.java`

### Map Data

- [Network Editor](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/road/RoadEditor.java): `src/main/java/bili/dongsz/howtogo/road/RoadEditor.java`
- [Road Network](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/road/RoadNetwork.java): `src/main/java/bili/dongsz/howtogo/road/RoadNetwork.java`
- [Road Persistence](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RoadStore.java): `src/main/java/bili/dongsz/howtogo/client/RoadStore.java`
- [Road Storage Format](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/road/RoadStorage.java): `src/main/java/bili/dongsz/howtogo/road/RoadStorage.java`
- [Create Rail Layer](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RailTrackStore.java): `src/main/java/bili/dongsz/howtogo/client/RailTrackStore.java`
- [Rail Names](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/RailNameStore.java): `src/main/java/bili/dongsz/howtogo/client/RailNameStore.java`
- [Transit Lines](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/transit/TransitLine.java): `src/main/java/bili/dongsz/howtogo/transit/TransitLine.java`
- [Transit Persistence](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/transit/TransitLineStorage.java): `src/main/java/bili/dongsz/howtogo/transit/TransitLineStorage.java`

### Trip Planning

- [Destination Sources](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/Destinations.java): `src/main/java/bili/dongsz/howtogo/client/Destinations.java`
- [POI Destinations](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/PoiDestinationSource.java): `src/main/java/bili/dongsz/howtogo/client/PoiDestinationSource.java`
- [Station Destinations](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/CreateStationSource.java): `src/main/java/bili/dongsz/howtogo/client/CreateStationSource.java`
- [Road Router](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/route/RoadRouter.java): `src/main/java/bili/dongsz/howtogo/route/RoadRouter.java`
- [Transit Planner](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/route/TransitPlanner.java): `src/main/java/bili/dongsz/howtogo/route/TransitPlanner.java`
- [Route Preferences](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/route/RoutePreferences.java): `src/main/java/bili/dongsz/howtogo/route/RoutePreferences.java`
- [Preference Storage](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/store/RoutePreferenceStore.java): `src/main/java/bili/dongsz/howtogo/store/RoutePreferenceStore.java`
- [Client Configuration](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/RoadConfig.java): `src/main/java/bili/dongsz/howtogo/RoadConfig.java`

### Navigation UI

- [Destination Picker](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/DestinationScreen.java): `src/main/java/bili/dongsz/howtogo/client/DestinationScreen.java`
- [Navigation State](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/Navigation.java): `src/main/java/bili/dongsz/howtogo/client/Navigation.java`
- [Navigation HUD](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/NavHudRenderer.java): `src/main/java/bili/dongsz/howtogo/client/NavHudRenderer.java`
- [Voice Guidance](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/client/Narration.java): `src/main/java/bili/dongsz/howtogo/client/Narration.java`
- [Phone Picker](https://github.com/dong-awa/howtogo/blob/main/src/main/java/bili/dongsz/howtogo/compat/mcphone/DestinationPickerPage.java): `src/main/java/bili/dongsz/howtogo/compat/mcphone/DestinationPickerPage.java`

### Other components

- **Player**
- **Xaero World Map**
- **Create Mod**
- **McPhone**

## Connections

- Player → Road Editing: edits roads
- Xaero World Map → World Map Rendering: hosts map layer
- World Map Rendering → Road Network: renders network
- Mod Events → Road Editing: registers input (evidence: `src/main/java/bili/dongsz/howtogo/HowToGo.java`)
- Mod Events → Navigation State: ticks navigation (evidence: `src/main/java/bili/dongsz/howtogo/HowToGo.java`)
- Mod Events → Create Rail Layer: ticks rail layer (evidence: `src/main/java/bili/dongsz/howtogo/HowToGo.java`)
- Mod Events → Road Persistence: ticks storage (evidence: `src/main/java/bili/dongsz/howtogo/HowToGo.java`)
- Road Editing → Road Snapping: snaps placement (evidence: `src/main/java/bili/dongsz/howtogo/client/RoadEditSession.java`)
- Road Editing → Network Editor: applies edits (evidence: `src/main/java/bili/dongsz/howtogo/client/RoadEditSession.java`)
- Network Editor → Road Network: mutates graph (evidence: `src/main/java/bili/dongsz/howtogo/road/RoadEditor.java`)
- Road Persistence → Road Storage Format: serializes network (evidence: `src/main/java/bili/dongsz/howtogo/road/RoadStorage.java`)
- Road Persistence → Road Network: loads and saves (evidence: `src/main/java/bili/dongsz/howtogo/client/RoadStore.java`)
- Create Mod → Create Rail Layer: supplies track data
- Create Rail Layer → Rail Names: stores names separately (evidence: `src/main/java/bili/dongsz/howtogo/client/RailTrackStore.java`)
- Create Rail Layer → Station Destinations: provides stations
- Player → Destination Picker: chooses trip
- Destination Sources → POI Destinations: includes POIs
- Destination Sources → Station Destinations: includes stations
- Destination Picker → Destination Sources: lists destinations
- Destination Picker → Road Router: previews route
- Destination Picker → Route Preferences: sets route options
- Road Router → Road Network: routes on graph (evidence: `src/main/java/bili/dongsz/howtogo/route/RoadRouter.java`)
- Road Router → Route Preferences: uses preferences (evidence: `src/main/java/bili/dongsz/howtogo/route/RoadRouter.java`)
- Transit Planner → Road Router: plans walk legs
- Transit Planner → Transit Lines: uses transit lines
- Destination Picker → Navigation State: starts navigation
- Navigation State → Navigation HUD: drives HUD
- Navigation State → Voice Guidance: announces turns (evidence: `src/main/java/bili/dongsz/howtogo/HowToGo.java`)
- Route Preferences → Preference Storage: persists choices (evidence: `src/main/java/bili/dongsz/howtogo/store/RoutePreferenceStore.java`)
- Mod Events → Preference Storage: loads preferences (evidence: `src/main/java/bili/dongsz/howtogo/HowToGo.java`)
- Player → Phone Picker: selects destination
- Phone Picker → Navigation State: starts trip (evidence: `src/main/java/bili/dongsz/howtogo/compat/mcphone/DestinationPickerPage.java`)
- Client Configuration → Road Router: configures routing (evidence: `src/main/java/bili/dongsz/howtogo/RoadConfig.java`)
- Client Configuration → Voice Guidance: configures voice
