Sprint‐3‐Navigation Paths - G33-Moviles-2026-1/Wiki GitHub Wiki
Feature Description
The navigation paths feature allows users to find a walking route between any two rooms on campus. The user enters an origin room and a destination room (or selects a destination directly from a room detail screen), taps "Show me the way", and receives a numbered list of step-by-step directions along with an estimated travel time. The origin can also be determined automatically by locating the nearest campus node to the device's GPS position. Previously queried routes are cached so repeated queries are answered instantly without a network call. Users can navigate backwards and forwards through their query history within the session and across app restarts.
Caching Strategies:
Flutter — LRU Cache (In-Memory + Persistent)
The navigation path feature uses an LRU (Least Recently Used) cache with a capacity of 10 routes, backed by a local SQLite table for persistence across app restarts. When the user queries a route that was previously fetched, the result is returned instantly from the in-memory LRU without any network call. The LRU order is persisted to the local database after every query and every history navigation, so on the next app launch the cache is restored in the correct eviction order and the most recently queried route is displayed immediately.
This strategy was chosen to avoid redundant network calls for repeated route queries within a session and across sessions, while bounding memory usage with the eviction policy.
Kotlin — LRU Cache (In-Memory + DataStore Persistence)
The navigation feature implements a least recently used caching strategy with a capacity of 10 routes, utilizing a linked hash map structure to manage in-memory access and eviction. This memory-based cache is backed by a persistent key-value store that saves a serialized snapshot of the entire navigation state—including the cached routes, the path history, and the current history index—whenever the state changes. When a user requests a route, the system first queries the in-memory structure; if the data is present, it is returned instantly and its access order is updated. If the route is not found, it is fetched from the network and added to the cache, triggering the eviction of the oldest entry if the maximum capacity has been reached.
This persistence mechanism ensures that both the cached routes and the user's navigation history are fully restored when the app restarts. By serializing the state into a JSON format and saving it to local storage, the application avoids redundant network calls for previously calculated paths and preserves the user's exact position within their navigation history. This strategy was chosen to provide a seamless, responsive experience that maintains continuity across sessions while strictly bounding memory usage through a defined eviction policy.
Local Storage:
Flutter - Navigation Paths SQLite Table
Stores up to 10 previously fetched routes in LRU order to restore the in-memory cache across app restarts. Fully replaced on every cache write.
| Column | Type | Description |
|---|---|---|
| cacheKey | TEXT (PK) | "originRoom|destRoom" composite key |
| originText | TEXT | Origin room identifier |
| destText | TEXT | Destination room identifier |
| stepsJson | TEXT | JSON-encoded list of step strings |
| totalTimeSeconds | INTEGER | Estimated travel time in seconds |
| accessedAt | INTEGER | Epoch ms — defines LRU eviction order on reload |
Lifecycle: Fully replaced (delete all + insert all) after every successful route query and after every history navigation. Loaded once on navigation screen open to restore the in-memory LRU cache and display the last queried route.
Kotlin — Navigation State DataStore
Stores a serialized snapshot of the complete navigation state in a persistent key-value store, ensuring the LRU cache and path history are preserved across app restarts.
| Column | Type | Description |
|---|---|---|
| cacheKey | STRING | Normalized composite key ("ORIGIN |
| origin | STRING | Name or identifier of the starting point |
| destination | STRING | Name or identifier of the destination point |
| steps | ARRAY (STRING) | List of specific text instructions for the path |
| totalTimeSeconds | INTEGER | Total estimated travel time in seconds |
| lastAccessedAt | lastAccessedAt | Epoch ms timestamp used to define the LRU eviction order |
Lifecycle: This structure is part of the NavigationSnapshot and is persisted to the local key-value store whenever a new route is fetched or an existing one is accessed. On app launch, these entries are loaded into the in-memory cache, ensuring that previously queried paths are available immediately and in the correct priority order.