RTP Architecture Catalog & Diagram Directory¶
This directory contains the canonical visual architecture specifications, state-machine diagrams, and lifecycle flows for the LeafRTP engine. Each document models an end-to-end subsystem or critical invariant using client-rendered Mermaid diagrams accompanied by threading rules, failure attribution vocabulary, and requirement traceability.
For a narrative walkthrough of how these diagrams connect to diagnose runtime issues, see docs/dev/CODE_TOUR.md. For module import boundaries and package separation, see docs/dev/ARCHITECTURE.md.
Architectural Diagram Catalog¶
| # | Document | Primary Scope | Entry Point / Core Classes | Governing ADRs | S-00x Rules |
|---|---|---|---|---|---|
| 01 | 01-teleport-execution-pipeline.md |
End-to-end single /rtp execution (Setup → Load → Teleport → Cleanup) |
TeleportPipelineTask, LocationGenerator |
leafrtp-ADR-001, leafrtp-ADR-011, leafrtp-ADR-085, rtp-folia-ADR-002, leafrtp-ADR-086 | S-001, S-002, S-004, S-005 |
| 02 | 02-budgeted-cache-generator.md |
Background speculative queue refill (keptLocations) and budget pacing |
SelectionAPI.compute(), RegionQueueManager, RegionCacheTask |
leafrtp-ADR-004, leafrtp-ADR-011, anvil-api-ADR-001, leafrtp-ADR-059, leafrtp-ADR-068, leafrtp-ADR-085 | S-002, S-005 |
| 03 | 03-chunk-ticket-lifecycle.md |
Chunk reservation lifecycle, ticket registration, and guaranteed teardown | ChunkReservation, ChunkSet, MemoryTracker |
leafrtp-ADR-011, rtp-folia-ADR-002 | S-002, S-005 |
| 04 | 04-active-gc-sweep.md |
Periodic background audit and reclamation of stale tasks and orphaned tickets | ActiveGCSweepTask, MemoryTracker |
leafrtp-ADR-011 | S-002 |
| 05 | 05-scan-task-crawler.md |
Long-lived admin /rtp scan crawler, rate throttling, and .scan checkpoints |
ScanTask, ScanTaskProcessing, MemoryShape |
leafrtp-ADR-001, anvil-api-ADR-001 | S-004, S-005 |
| 06 | 06-plugin-setup-lifecycle.md |
Plugin bootstrap ordering, database initialization, and adapter detection | RTPBukkitPlugin.onEnable(), Configs.reload() |
leafrtp-ADR-003, leafrtp-ADR-013, leafrtp-ADR-016 | S-006 |
| 07 | 07-rtp-command-region-selection.md |
Command parsing, world/region overrides, permission evaluation, and unqueued branch | SelectionAPI.getRegion(), BukkitBaseRTPCmd |
leafrtp-ADR-001, leafrtp-ADR-007, leafrtp-ADR-085, leafrtp-ADR-086 | S-004, S-007 |
| 08 | 08-location-selection-per-attempt.md |
Core candidate selection attempt: shape → probe-first → chunk → vert → biome → safety | PregenTask.runAttempt(), LocationGenerator |
leafrtp-ADR-001, leafrtp-ADR-011, anvil-api-ADR-001, leafrtp-ADR-084, leafrtp-ADR-085, rtp-folia-ADR-002, leafrtp-ADR-086 | S-001, S-003, S-004, S-005 |
| 09 | 09-configuration-load-and-reload.md |
Configuration loading, locale bootstrap, atomic parser swap, and dormant regions | Configs.reloadAction(), ConfigParser, LanguageBootstrap |
leafrtp-ADR-013, leafrtp-ADR-027 | S-007 |
| 10 | 10-shutdown-and-flush-lifecycle.md |
Shutdown flush ordering: task drainage → DB commit → region teardown → ticket release | RTP.stop(), RTPBukkitPlugin.onDisable(), DatabaseAccessor |
leafrtp-ADR-006, leafrtp-ADR-011, leafrtp-ADR-016 | S-002, S-004 |
| 11 | 11-configuration-write-and-persist.md |
/rtp config set/add/remove persistence pipeline, atomic rename, and rollback |
ConfigWritePipeline, ConfigYamlDumper |
leafrtp-ADR-023, leafrtp-ADR-027 | S-007 |
| 12 | 12-network-model.md |
Multi-server and multi-proxy network protocol, packet sequence, and reservation tokens | RTPNetworkManager, ServerTokenManager, ProxyProtocolBridge |
leafrtp-ADR-022 | S-002, S-004 |
| 13 | 13-dual-layer-shape-architecture-and-l3-selection.md |
Dual-layer shape coordinate mapping, Chebyshev tiles, Hilbert curve, and L3 backlog | CircleOptimizedDualLayer, SquareOptimizedDualLayer, SegmentedKeyRunTable |
leafrtp-ADR-001, leafrtp-ADR-018, leafrtp-ADR-020, leafrtp-ADR-066, leafrtp-ADR-069 | S-001, S-004 |
| 14 | 14-group-placement-anchor-flow.md |
Multi-participant action placement, group anchor draw, and separated slot allocation | GroupPlacementDispatcher, SubspaceAnchorResolver, ActionManager |
leafrtp-ADR-073, leafrtp-ADR-074, leafrtp-ADR-075 | S-002, S-004 |
| 15 | 15-cost-governed-chunk-reads-and-native-admission.md |
Purpose-gated chunk resolution, thread-weighted deduplication, and in-flight admission | ImmediateLoadGovernor, LiveLoadGate, ProbeFirstGovernor, AnvilRegionOccupancyCache |
anvil-api-ADR-001, leafrtp-ADR-049, leafrtp-ADR-084, leafrtp-ADR-085, rtp-folia-ADR-002, leafrtp-ADR-086 | S-001, S-002, S-004, S-005 |
| 16 | 16-package-dag-and-decision-preservation-graph.md |
Core package hierarchy, 4-tier DAG architecture, and decision traceability hypergraph | RTPArchitectureTest, RTP, MemoryTracker, CoreCommandTreeBuilder |
ADR-000, leafrtp-ADR-006, ADR-094, ADR-115 | S-001..S-007 |
Subsystem Functional Map¶
The diagrams form an interconnected state machine covering distinct architectural concerns:
1. Teleport Orchestration & Command Dispatch¶
07/rtpCommand Region Selection: Evaluates player arguments, world/region permissions, override loops, and forks between hot-cache pop, public queue wait, or ad-hoc unqueued search (LoadPurpose.IMMEDIATE).01Teleport Execution Pipeline: Orchestrates the complete player lifecycle (Setup → Load → Teleport → Cleanup), binding chunk reservations and managing regional handoffs.14Group Placement Flow: Manages multi-player challenge, scatter, and arena placement by drawing a single anchor and distributing safe separated slots.
2. Candidate Selection & Algorithmic Geometry¶
08Location Selection Per Attempt: The decision core. Samples coordinates, evaluates world borders, passes probe-first gating, resolves chunks, adjusts elevation, filters biomes, and verifies environmental safety.13Dual-Layer Shape Architecture & L3 Backlog: Eliminates random rerolls using coarse Chebyshev macro-tiles, fine Hilbert space-filling curves, dyadic downsampling, and segmented run tables.
3. Chunk Resolution, Deduplication & Lifecycle Governance¶
15Cost-Governed Chunk Reads & Native Admission: Implements three-tier resolution (Resident Cache, Governed Deduplication, Cost-Governed Native Load Admission), zero-decode MCA occupancy checks, and thread-weighted cost balancing ($P_{\text{reject}} > \frac{C_{\text{file, async}}}{C_{\text{native, async}} + W_{\text{tick}}(\text{MSPT}) \cdot C_{\text{native, sync}}}$).02Budgeted Cache Generator: Manages periodic background queue refill pulses (LoadPurpose.SPECULATIVE), constrained byLiveLoadGateandHeapPressureMonitor.03Chunk Ticket Lifecycle: Tracks allocation and guaranteed release of platform chunk tickets (ChunkReservation) throughMemoryTracker.04Active GC Sweep: Provides the active safety net that catches and reclaims stalled tasks, expired tickets, and orphaned native tickets.
4. Configuration, Persistence & Lifecycle Ordering¶
06Plugin Setup Lifecycle: GovernsonEnablesequencing, database connection pools, config initialization, and platform adapter binding.09Configuration Load and Reload: Manages/rtp reloadmechanics, language bootstrapping, atomic parser swaps, and dormant region rebinding.10Shutdown and Flush Lifecycle: Enforces strict four-phase shutdown ordering to prevent data loss or leaked chunk tickets on/stopand/reload.11Configuration Write and Persist: Manages transactional/rtp configmutations with atomic temporary file swapping and rollback.
5. Multi-Server Networking & Admin Tools¶
12Network Model: Specifies multi-server proxy communication, heartbeat synchronization, reservation token lifecycle, and packet flows.05Scan Task Crawler: Drives asynchronous background pre-exploration (/rtp scan) to populate persistent spatial memory with bounded tick budgets.
6. Package Architecture, Modularity & Decision Traceability¶
16Core Package Architecture & Decision Traceability Map: Visual specification of the 4-tier package DAG inrtp-core, acyclic dependency rules (0.0% SonarQube package tangles), decoupled structural seams, and class-to-ADR decision traceability.
Absolute Prohibition Requirements (S-00x) Reference¶
Every architectural flow is designed to enforce the non-negotiable prohibition requirements codified in docs/dev/REQUIREMENTS.md section 3:
- S-001 (Destination Safety): Verified authoritatively in
08and15prior to player teleportation. No secondary checks in adapters. - S-002 (Chunk Tickets): Framed in
03and audited in04and10. Zero permanent force-loaded chunks; reservations closed on every exit path. - S-003 (Claim Protection): Executed via asynchronous verifier chains in
08. Zero teleports into protected land. - S-004 (Failure Visibility): Enforced across
01,07,08, and15. Futures always complete; errors attribute toFailTypesvocabulary without silent suppression. - S-005 (Async I/O): Zero synchronous chunk I/O on tick threads. Off-thread region reads (
AnvilIoPool), async chunk futures, and regional handoffs are modeled in01,08, and15. - S-006 (Fail-Closed Contract): Initialized in
06. Public APIs throwIllegalStateExceptionif invoked pre-initialization. - S-007 (Configurable Messages): Handled in
07,09, and11. All failure and busy notifications originate frommessages.yml.