NodeDex

NodeDex operates as an independent enrichment layer on top of the Meshtastic protocol stack. It reads node telemetry from the live nodesProvider but maintains its own persistence, identity generation, and visualization pipeline. The system is designed to be fully offline — Cloud Sync is optional and additive.

When a node appears or updates on the mesh, the NodeDexNotifier provider processes the event: records an encounter (subject to a cooldown), updates signal records, caches device info, derives region from GPS, and tracks co-seen relationships. All derived data — sigils, traits, patina, field notes — is computed lazily through pure-function engines with zero side effects.

Key Source Paths

The NodeDexEntry is the central model — one instance per discovered node. It captures everything from first-seen timestamps to rolling encounter windows, signal records, co-seen relationship graphs, and cached device metadata. The model is independent of MeshNode; it reads from protocol data but persists its own enrichment layer.

Core Fields

Social Tags

Users can classify discovered nodes with one of four social tags. Tags are private metadata — never transmitted over the mesh, but included in JSON exports and Cloud Sync.

Computed Properties

NodeDexEntry exposes several derived getters computed from the raw data:

• isRecentlyDiscovered — True if first seen within the last 24 hours
• age / timeSinceLastSeen — Duration computations
• regionCount / coSeenCount / distinctPositionCount — Aggregate counts
• topCoSeenWeight — The strongest co-seen relationship count
• hasEnoughDataForTrait — Whether trait inference is meaningful

Every Meshtastic node receives a unique geometric sigil — a constellation-style procedural glyph generated entirely from its node number. The generation is deterministic: the same nodeNum always produces the same sigil. No randomness, no per-session variation, no network dependency.

Hash Function

The generator uses a murmur3-style integer hash finalizer for bit mixing. Multiple rounds of mixing extract independent parameters from a single 32-bit seed, ensuring that even sequential node numbers produce visually distinct sigils.

Sigil Parameters

Color Palette

Each sigil receives a unique 3-color combination (primary, secondary, tertiary) drawn from a curated 16-color palette. The selection is hash-derived with collision avoidance — all three colors are guaranteed to be distinct.

Geometry Pipeline

The renderer calls computePoints() to get normalized vertex positions (unit circle) and computeEdges() to get the line connections. Points include outer polygon vertices, inner ring vertices (scaled and offset-rotated), and an optional center point. Edges connect polygon sides, inter-ring struts, and optional radial lines governed by the symmetry fold value.

Traits are passive personality classifications inferred from real observable data — encounter patterns, position history, uptime, role, and activity frequency. Traits are never user-editable. The engine runs pure functions that take a NodeDexEntry and optional live metrics to produce a ranked classification with confidence scores and human-readable evidence.

Inference Thresholds

The Nine Traits

Scoring & Evidence

Each trait is scored independently on a 0.0 to 1.0 confidence scale. The engine provides two APIs:

• infer() — Returns a primary trait + optional secondary (legacy API)
• inferAll() — Returns the full ranked list of ScoredTrait objects, each carrying human-readable TraitEvidence observations

Evidence lines read like field journal entries: "Seen across 4 regions", "Encounter rate 12.3/day exceeds beacon threshold". A secondary trait is included when another trait scores above 0.5 alongside the primary.

Patina is a deterministic digital history score (0–100) measuring how much observable history a node has accumulated in your field journal. It is not fake damage or cosmetic aging — it is a numerical measure of genuine documentation depth. A score of 0 means "just discovered, almost nothing known." A score of 100 means "deeply documented, rich history across time, space, and relationships."

Six Axes

Each axis uses logarithmic or asymptotic curves so that early gains are meaningful but diminishing returns prevent runaway scores. A node seen 3 times over 2 days with 1 region scores ~15–25. A node seen 50 times over 30 days across 4 regions scores ~60–75.

Stamp Labels

The raw score maps to a human-readable stamp used in the UI:

Not everything about a node is visible immediately. Progressive Disclosure controls what information is revealed based on how much observable history has accumulated. New nodes start sparse — only a sigil and basic metadata. As encounters, time, and data accumulate, additional layers are progressively unlocked. This creates a sense of earned knowledge.

Five Disclosure Tiers

The overlay density ramps smoothly based on data richness — encounter count, age, region diversity, and co-seen relationships all contribute. The DisclosureState object exposes boolean flags that the UI reads directly, keeping disclosure logic out of widget code.

Sigil Evolution adds subtle visual depth to a node's sigil based on patina score. It does not create a second scoring system — it derives everything from the existing patina (0–100). Visual effects are intentionally subtle: slight line thickening, gentle color deepening, and micro-etch density increases.

Five Maturity Stages

Augment Marks

At Inscribed stage (tier 2) and above, tiny optional marks can appear near the sigil's outer ring, derived from the node's trait. Only one augment per sigil:

• Relay Mark — Small directional tick for router/relay nodes
• Wanderer Mark — Tiny arc segment for mobile nodes seen across regions
• Ghost Mark — Faint hollow dot for rarely-seen nodes

Each node receives a deterministic, single-line field journal observation based on its identity seed, primary trait, and accumulated history. Notes are fully deterministic: the same node number and trait always produce the same note. They read like entries in a naturalist's field journal.

The generator maintains 8 template families per trait (64+ total templates). Template selection is hash-derived from the node number, and interpolation fills in real values: {regions}, {encounters}, {rate}, {distance}, {lastSeen}, {coSeen}, etc.

The Collector Album presents discovered nodes as collectible trading cards in a grid layout, grouped by trait or rarity. Each card features the node's sigil with holographic shimmer effects scaled by rarity tier. The album uses a "mystery slot" pattern to suggest undiscovered nodes without implying a fixed total.

Grid Layout

• 3 columns on phones (< 600dp), 4 columns on tablets
• Card aspect ratio: 5:7 (portrait, matching SigilCard)
• 8dp spacing grid, 16dp horizontal padding
• Sticky group headers with collection counts
• 2 mystery slots appended per group

Rarity Tiers

Holographic Effect

Rare, Epic, and Legendary cards receive an animated rainbow shimmer overlay rendered via CustomPainter. The effect uses a diagonal gradient with spectral color bands that drift slowly across the card surface, creating the look of a premium holographic trading card.

Card Flip Animation

Cards flip with a 3D perspective transform (380ms, easeOutBack curve, 0.0025 perspective). The back face shows additional node metadata. Press feedback scales cards to 90% over 80ms.

Album Cover

The album opens with a cover section (260px tall) showing the user's Explorer Title emblem, discovery statistics, and a rarity breakdown bar. The cover animates in over 600ms.

The Elemental Atmosphere is an optional ambient visual system that renders data-driven particle effects behind NodeDex and map views. Effects are purely cosmetic, non-interactive, and never obstruct content. The system respects reduce-motion preferences and auto-throttles on low-end devices.

Four Effects

Performance Budget

Context Multipliers

Effect intensity is scaled by screen context:

• Constellation screen: 1.0× (full effect)
• Map overlays: 0.3× (subtle, must not interfere with map readability)
• Node detail screen: 0.25× (very subtle background)

NodeDex data persists in a dedicated SQLite database (nodedex.db) managed by the NodeDexDatabase lifecycle class and the NodeDexSqliteStore read/write layer. The database is currently at schema version 4 with full forward migration support.

Schema

Migration History

Write Strategy

Writes use a debounced batch strategy: individual saveEntry() calls are queued and flushed together after a short delay. This reduces SQLite write amplification during rapid encounter processing. Critical writes (user edits, imports) use saveEntryImmediate() to bypass the debounce. Corruption is handled by deleting and recreating the database — data loss is acceptable since Cloud Sync provides the recovery path.

Cloud Sync is an optional premium feature that backs up NodeDex data to Firestore and syncs across devices. The system uses an outbox pattern for writes and a watermark-based pull for reads. The app remains fully functional without Cloud Sync — all data lives in SQLite first.

Outbox Pattern

Conflict Resolution

Numeric fields use max-wins (encounterCount, messageCount, bestSnr, bestRssi). Timestamps use earliest for firstSeen and latest for lastSeen. User-owned fields (socialTag, userNote) use last-write-wins via updatedAtMs timestamps. Near-simultaneous edits within a 5-second window are flagged as conflicts.

NodeDex supports full JSON export and import with a sophisticated merge preview system. You can export your entire field journal as a JSON file and import it on another device — even without Cloud Sync.

Import Preview

Before applying an import, the system generates a complete ImportPreview that analyzes every entry against the local store without modifying any data. The preview reports:

• New entries (not in local store)
• Merge candidates (existing entries with additional data)
• Field conflicts (socialTag or userNote differs between local and imported)
• New co-seen edges, encounter records, and regions per entry

Merge Strategies

Regardless of strategy, numeric fields always use max-wins and encounters/regions/co-seen edges are additively merged. Only user-owned fields (socialTag, userNote) are subject to conflict resolution.

Explorer titles are prestige labels earned through actual mesh exploration — node count, region diversity, distance records, and encounter breadth. No grinding, no gamification. Just recognition of real activity. Titles are computed from NodeDexStats and displayed on the Album cover.

The NodeDex UI is built with Riverpod 3.x providers that compose the pure-function engines into reactive state. Each screen reads derived providers — no engine is ever called directly from widget code.

Main Screen

The NodeDexScreen presents a searchable, filterable, sortable list of all discovered nodes. Users can toggle between List mode (detailed tiles with metrics) and Album mode (collector card grid). Filter chips support trait-based and social-tag-based filtering. Sort options include last seen, first seen, encounter count, and distance.

Detail Screen

The NodeDexDetailScreen shows the full profile for a single node: animated sigil header, trait badge with evidence, field note, discovery stats, signal records, social tag editor, user note, region history, recent encounters timeline, co-seen links, and live device telemetry. UI elements are gated by the DisclosureState — sparse nodes show minimal information.

Constellation Screen

The ConstellationScreen wraps the ConstellationPainter in a gesture-aware viewport with pinch-to-zoom, pan, and tap-to-select. It includes a detail panel that slides up when a node or edge is selected, showing relationship details and navigation to the full profile.

Key Providers