Technical reference / system architecture

Navgame, Rogaining Event Entry & Navlight

Component structure, programming languages, data ownership and the connections between the GPS event platform, the national registration service and the desktop electronic-punch scoring system.

Source snapshot: 28 October 2026Implemented and planned paths identified separately
01

System map

Three separate products. Each retains its own data store. Rogaining Event Entry (REE) is the registration authority when selected for an event; Navgame also retains its own built-in entry system.

Implemented interface / clientPlanned result exchangeArrows show data direction; availability is described below.

Navgame

Web, phone & Garmin event platform

  • Course and map configuration
  • GPS checkpoint evidence
  • Native offline Event Mode
  • Scoring, Results and replay
  • Static spectator live tracking
Navgame PostgreSQL + R2Event/competition records and object artifacts; phones retain local SQLite state.
Product and account boundary: Geolinus

Rogaining Event Entry

National, association-branded registration

  • Entrant profiles and team composition
  • Versioned entry forms and categories
  • Quotes, capacity and entry deadlines
  • Payments, refunds and invoices
  • Versioned integration APIs
Separate REE PostgreSQL + R2Registration and financial records; object storage for association branding.
Product, identity and data boundary: ARA
Development and operation: Geolinus

Navlight

Windows desktop electronic-punch scoring

  • USB/serial tag and punch readers
  • Punch programming and tag readout
  • Course, team and category setup
  • Local scoring and review
  • Reports and local results server
Local LiteDB filesEvent database plus separate tag and punch history databases.
Independent desktop application
REE client on agents/development branch
REE → Navgame IMPLEMENTED

Hosted entry hand-off, event linkage and cursor-based roster projection. Organiser delegation authorises one selected REE event. Runtime enablement is configuration-controlled.

REE → Navlight DEVELOPMENT BRANCH

Read-only event and team-list API. The desktop client signs in, maps variants to local courses, previews changes and applies them locally. This is implemented on agents/development, not Navlight main.

Navlight → REE → Navgame PLANNED

Immutable result-batch upload to REE, followed by Navgame retrieval, review and publication. Team-composition write-back is also a later integration slice.

Data and identity boundary

Products exchange scoped, versioned API data. Navlight has no direct Navgame connection. There is no shared product database or cross-product account/profile linking.

02

Components & languages

Navgame and REE share a TypeScript monorepo but have independent runtime and database boundaries. Navlight is a separate C# solution.

Navgame

React UI, native execution, split cloud services

Shared browser & phone UI

TypeScript / TSXReactCSSVite

Play, Create, event administration, maps and Results. MapLibre GL renders maps. Capacitor hosts the shared UI on phones; native code owns Event Mode execution.

apps/client

Android & iOS runtime

Java · AndroidSwift · iOSTypeScript bridge

Native GPS capture, start/checkpoint/finish decisions, durable state and offline outboxes. SQLite persists local evidence. Android separates the UI/runtime and tracking processes.

apps/mobile/android · apps/mobile/ios · apps/mobile/src

Garmin companion

Monkey CConnect IQ

Watch-side GPS, checkpoint detection and result-evidence capture. The phone imports watch evidence and syncs it to the API.

apps/garmin-watch

API & background services

TypeScriptNode.jsFastifyPrisma / SQL

Event administration, bounded reads, scoring ingress and result projection. Separate workers render artifacts, publish live data, seal traces and archive trace sources.

apps/api · apps/live-publisher

Shared packages & edge

TypeScriptCloudflare Workers

domain holds shared rules; sdk holds contracts; trace-repository performs bounded, integrity-checked trace reads. Edge workers route API traffic, receive telemetry and serve R2 artifacts.

packages/* · infra/cloudflare

Website & route stories

PHPHTML / CSS / JavaScriptReact / TypeScript

WordPress serves navgame.net and plugins, with MariaDB separate from competition storage. Travelogue is a React/TypeScript route-story surface, packaged for WordPress delivery.

apps/wordpress · apps/travelogue

Rogaining Event Entry

National service with association-scoped data

Entrant & administrator web app

TypeScript / TSXReactCSSVite

Association branding, event discovery, team entry, profile management and organiser administration. Hosted at entries.rogaining.au.

apps/registration-web

Registration API

TypeScriptNode.jsFastifyPrisma / SQL

Owns registration truth: entries, published form versions, quotes, capacity, payments, change requests, invoices and audit records. Independently deployed on Railway with its own PostgreSQL database.

apps/registration-api

Domain rules

TypeScript

Reusable registration validation, form configuration, age/gender categories and pricing logic. Shared by the REE frontend and backend.

packages/registration-domain

API contracts & clients

TypeScriptOpenAPI / JSONGenerated C#

Registration DTOs and clients, versioned Navgame integration and Navlight roster contracts. The conformance kit includes generated clients, fixtures and a mock server.

packages/registration-sdk

Payments & transactional email

TypeScriptStripe ConnectResend

Server-side Stripe Checkout and signed webhook processing; durable confirmation/invoice delivery. Shared transport packages are parameterised by product, preserving each product’s records and authority.

packages/stripe-connect-v2 · packages/transactional-mail

Identity & association websites

Auth0 / OIDCHTTPS APIs

ARA identity is separate from Navgame identity. Association websites link to a top-level branded REE page; their CMS accounts are not registration identities.

Navgame uses a confidential server client with an event delegation. Navlight uses a public desktop client with PKCE.

Navlight

Windows / WPF / .NET 10 / MVVM

Desktop presentation

C#XAML / WPFCommunityToolkit.Mvvm

Views and view-models present event setup, courses, categories, teams, readers and scoring. MahApps.Metro supplies desktop controls; commands and messages coordinate UI actions.

Navlight/Views · ViewModels · Commands · Messages

Scoring & reporting

C#HTML / CSS / JavaScript

Services unpack tag visits, apply course/category rules and score teams. Reporting builds output including IOF XML; EmbedIO exposes a local/LAN results server with web resources.

Navlight/Services · Services/Scoring · Reporting · Api · Resources

Reader hardware interface

C#System.IO.PortsUSB / serial

A separate library discovers readers, decodes Navlight bytes and handles tag/punch operations. Includes a simulator for reader testing.

Navlight.UsbReader

Local persistence & migration

C#LiteDBLegacy SQLite / EF Core

Current storage uses an event LiteDB file plus tags.litedb and punches.litedb. Repository services and stores isolate access. Entity Framework/SQLite classes read legacy databases for migration.

Navlight/Data · Stores · Services/RepositoryServices · Migration

REE connection

C#Generated v1 clientOIDC / PKCE

The development branch implements system-browser sign-in, Windows DPAPI token protection, event/roster reads, course mapping, category translation and local sync state. Ordinary refresh preserves local tags and scores.

Navlight/Integrations/RogaineEventEntry

Tests & Windows packaging

C# / xUnit / MoqMSI

The solution contains the WPF application, reader library, test project and installer project. The checked source targets net10.0-windows; the older README's .NET 6 dependency is stale.

Navlight.Tests · Navlight.Setup · Navlight.sln
03

Navgame service structure

The API codebase is deployed as separate workload roles. Scoring commands, read traffic, trace handling and artifact generation have distinct execution lanes.

Score-bearing command path

Native evidence reaches a durable server ledger before result projection. Trace arrival alone does not trigger result computation.

Phone / watch evidenceNative checkpoint and finish capture; durable phone outbox
Gateway → scoring ingressAuthenticate, validate and deduplicate bounded commands
PostgreSQL ledger & jobCommit evidence, advance team revision, queue projection
Result projectorCompute the affected team and persist Results for readers

Read API + legacy compatibility
General reads and administration use the read role. Older client writes use a dedicated compatibility role feeding the same scoring ledger.

Telemetry + trace services
Trace chunks upload through scoped Cloudflare/R2 paths. A sealer establishes source integrity; archival and trace-repository reads stay separate from scoring.

Live publisher + edge delivery
The independent publisher writes static spectator artifacts to R2. Spectators read them at the edge without entering the Event Mode API path.

Artifact worker
Durable jobs render share media and other artifacts. Request handlers enqueue or read completed outputs; they do not render complete traces inline.

04

Data flows & integration status

The entry provider and scoring provider are separate choices in the architecture. The Navlight result-return combination is a target design, not an end-to-end released capability.

Event combinations
Entry authority Scoring Path and status
Navgame Navgame
Entry → native evidence → Navgame scoring → Navgame Results
EXISTING PRODUCT PATH
REE Navgame
REE hosted entry → Navgame roster → native evidence → Navgame Results
IMPLEMENTED · CONFIGURATION-GATED
REE Navlight
REE roster → Navlight → REE result batch → Navgame review/publication
ROSTER CLIENT ON DEVELOPMENT BRANCH RESULT RETURN PLANNED
Navgame Navlight No supported integration. The approved architecture requires REE entries for Navlight scoring.
REE → Navlight: implemented read and local-apply sequence
  1. The operator signs in with the ARA identity in the system browser using Authorization Code + PKCE. Windows DPAPI protects stored tokens.
  2. Navlight reads accessible events through GET /v1/navlight/events and event detail through GET /v1/navlight/events/{eventId}. Discovery pages are capped at 25 events.
  3. GET /v1/navlight/events/{eventId}/roster returns up to 100 changes per page with stable identifiers, revisions and an opaque cursor.
  4. The desktop maps REE variants to local courses, translates categories and previews team changes. The operator resolves mappings/conflicts and confirms Apply.
  5. Local team/course updates complete before the sync cursor advances. Ordinary refresh retains Navlight-owned tags, punches and scoring history. Explicit event replacement is a separate confirmed operation.
REE ↔ Navgame: delegation, hosted entry and operational roster
  1. An organiser chooses REE in Navgame Entry Management and authorises one selected REE event through REE sign-in. This creates event-specific delegation; it does not merge accounts.
  2. The entrant completes the hosted REE entry form and payment flow. REE remains authoritative for team composition, fees and financial records.
  3. Navgame reconciles a versioned operational roster using bounded cursor reads. It retains source identifiers/revisions for gameplay and final-instructions delivery.
  4. Navgame owns the course, native event execution and its result publication. The integration can be disabled through runtime configuration.
Navlight → REE → Navgame: planned result exchange
  1. Navlight authors an immutable result batch carrying stable REE team IDs, roster/source revisions and integrity metadata.
  2. REE validates and retains the batch as Navlight-authored evidence. REE transports the scoring output; it does not recompute Navlight scores.
  3. A linked Navgame event retrieves a finalised batch, stages it for review and publishes only through its authorised publication flow.

This is the approved design. The inspected Navlight development branch and REE v1 roster API implement read/sync, not this result-upload pipeline.

05

Ownership, identity & shared infrastructure

Authority stays with the owning product
Concern Navgame REE Navlight
Primary authority Courses, gameplay, live tracking and Navgame publication Registration, teams, forms, fees, payments and refunds Tags, punches, local scoring and manual review
Human sign-in Geolinus/Navgame Auth0 tenant Separate ARA Auth0 tenant ARA sign-in for REE access; scoped scoring-operator authority
Persistence PostgreSQL; R2 objects; native SQLite; WordPress MariaDB separately Dedicated PostgreSQL; R2 branding objects Local event/tag/punch LiteDB files
Hosting / execution Railway services, Cloudflare edge, phones and Garmin Separate Railway project and web/API deployables Windows desktop; USB/serial devices; local/LAN results HTTP

Navgame and REE use shared source packages for Stripe Connect and transactional mail, with separate product records and permissions. Matching email addresses do not establish cross-product identity. API access is permission-scoped; none of these integrations queries another product's database directly.

Source evidence & scope

This is a source-based architecture snapshot, not a claim that every implemented branch is installed or every optional integration is enabled in production.

  • Navgame / REE: repository snapshot 1943838f; canonical docs/ARCHITECTURE.md, docs/ENTRY_SCORING_INTEGRATION_ARCHITECTURE.md, registration OpenAPI contracts, workspace manifests and native source. Service structure checked against the current split-role architecture.
  • Navlight integration branch: agents/development · b0628f8e; REE integration notes; WPF project and dependencies.
  • Navlight main comparison: main · 226e8987. The REE client is on the development branch. Framework versions come from project files; LiteDB and legacy SQLite roles were checked in implementation source.

Reviewed 28 October 2026. Planned paths are dashed and labelled; source implementation, deployment and physical-device verification are separate evidence.