Fire Information Sheet: A1 Map Details & Discussion

by Admin 52 views
Fire Information Sheet: A1 Map Details & Discussion

Summary

Our goal is to enhance the map screen by adding a new, user-friendly tap-for-details bottom sheet. This feature will allow users to access key information about individual fires (hotspot markers) directly on the map. This includes vital data such as detection time, source, confidence level, fire radiative power (FRP), last update timestamp, distance and bearing from the user's location, risk level, and the data source. This comprehensive information aims to provide users with a clear and immediate understanding of the fire situation.

Motivation & Non-Goals

Why Now?

This feature is being prioritized now because it offers immediate value and builds trust with our users. This feature directly supports emergency usage scenarios by providing critical information quickly and accessibly. By offering detailed context and promoting transparency, we are taking a significant step towards user empowerment. Moreover, this enhancement serves as a natural and logical foundation for more advanced map features, such as clustering and overlays, planned for future development. This initial implementation allows us to lay the groundwork for more sophisticated functionalities while delivering tangible benefits to users immediately. We are committed to continuously improving our platform, and this feature represents a crucial step in that direction. Providing users with real-time fire information is essential for informed decision-making and safety, especially in emergency situations. This enhancement aligns perfectly with our commitment to delivering reliable and actionable data to our users, ensuring they have the tools they need when they need them most.

Non-Goals

It's important to define what this initiative will not include at this stage. This spec specifically excludes advanced overlays like risk heatmaps, real-time perimeter visualizations, future prediction capabilities, incident reporting functionalities, and fire marker clustering. These features are certainly on our radar, and we recognize their potential value. However, they fall outside the scope of this initial implementation. We plan to address these more complex features in future specifications and development cycles. By clearly outlining these non-goals, we aim to maintain focus and ensure the successful delivery of the core functionality described in this document. This phased approach allows us to prioritize effectively, manage resources efficiently, and iterate on our feature set based on user feedback and evolving needs. We are dedicated to a thoughtful and strategic development process, ensuring each addition to our platform is well-integrated and delivers maximum value.

API / Contracts

To ensure seamless integration and data flow, we have defined specific APIs and contracts:

  • Model: The FireIncident model will encapsulate the core data related to each fire incident. It will include the following attributes: id, lat (latitude), lon (longitude), detectedAt (detection timestamp), source (e.g., VIIRS, MODIS), confidence (confidence level), frp (fire radiative power), and lastUpdate (last update timestamp).
  • Service: The ActiveFiresService will be responsible for retrieving fire incident data. Specifically, the getIncidentsForViewport(LatLngBounds) method will return a List<FireIncident> representing the fires within the specified map viewport. We will maintain both live and mock versions of this service, selectable based on the MAP_LIVE_DATA flag. This allows for flexible testing and development in various environments. The service will handle the complexities of data retrieval and transformation, ensuring the UI receives consistent and reliable information.
  • BottomSheet UI Contract: The bottom sheet UI component will receive props based on the FireIncident model. In addition to the core incident data, it will also receive derived values such as distance and bearing from the user's location and the risk level associated with the fire (calculated using EffisService). This contract ensures the bottom sheet has all the necessary information to present a comprehensive view of the fire incident to the user. This clear definition of props ensures consistency and simplifies the development process, making it easier to maintain and update the bottom sheet in the future.
{
  "id": "viirs-202511051330-1",
  "lat": 55.8590,
  "lon": -3.2110,
  "detectedAt": "2025-11-05T13:29:00Z",
  "source": "VIIRS",
  "confidence": 0.97,
  "frp": 11.3,
  "lastUpdate": "2025-11-05T13:30:00Z"
}

Behavior

When interacting with the map, the following behaviors are expected:

  • Tapping a Fire Marker: When a user taps on a fire marker displayed on the map, a bottom sheet will be presented. This sheet will be populated with all the key fields described above, providing the user with detailed information about the selected fire incident. This immediate access to data allows for informed decision-making and a deeper understanding of the situation. The bottom sheet serves as the primary interface for displaying fire-specific information, ensuring a consistent and intuitive user experience.
  • Risk Level Display: The bottom sheet will prominently display the risk level associated with the fire's coordinates. This risk level will be calculated using the EffisService, ensuring the most up-to-date and accurate risk assessment is presented to the user. This information is critical for understanding the potential impact of the fire and making appropriate safety decisions. The integration with EffisService ensures we leverage specialized expertise for risk assessment, enhancing the overall quality and reliability of the information provided.
  • Source and Data Mode Chips: The bottom sheet will always display a source chip, indicating the data source for the fire incident (e.g., VIIRS, MODIS). Additionally, a data mode chip will be displayed, indicating whether the data is live or from a demo mode. These chips provide transparency and context to the user, allowing them to understand the origin and nature of the data being presented. This clear indication of data source and mode builds user trust and confidence in the platform.
  • Sheet Dismissal and Re-opening: The bottom sheet can be easily dismissed by the user. Tapping on another fire marker will automatically close the existing sheet and open a new one with the details for the newly selected fire. This seamless transition between fire incidents allows users to quickly explore and compare information across different fires. The intuitive dismissal and re-opening mechanism ensures a smooth and efficient user experience.
  • Error and Data Unavailability Handling: In the event of an error or data unavailability (e.g., network issues, service failures), the system will display friendly retry and fallback messaging to the user. This ensures a graceful degradation of the user experience and provides options for resolving the issue. Clear and helpful error messaging is crucial for maintaining user satisfaction and trust, even in challenging situations. The retry and fallback mechanisms are designed to minimize disruption and ensure users can still access critical information whenever possible.

Acceptance Criteria

To ensure the quality and reliability of this feature, we have established the following acceptance criteria:

  • Data Accuracy: Tapping a fire marker must open the details sheet, and the sheet must display the correct data from the model and service. This ensures the information presented to the user is accurate and consistent with the underlying data sources. Data accuracy is paramount for building user trust and ensuring the platform's value in emergency situations.
  • Distance, Bearing, and Risk Level Accuracy: The distance and bearing from the user's location to the fire, as well as the calculated risk level, must be presented accurately in the details sheet. These derived values provide critical context to the user, and their accuracy is essential for informed decision-making. We are committed to implementing robust algorithms and validation processes to guarantee the precision of these calculations.
  • Source and Data Mode Chip Functionality: The source chips (VIIRS/MODIS) must accurately reflect the data source for the fire incident. The demo chip must be visible when the system is in mock mode. These visual indicators provide transparency to the user and help them understand the context of the data they are viewing. The correct display of these chips is a key aspect of maintaining data integrity and user trust.
  • Unit Test Coverage: Unit tests for the FireIncident model mapping and ActiveFiresService logic (both live and mock versions) must achieve at least 80% coverage. This ensures the core components of the system are thoroughly tested and function as expected. High unit test coverage is a crucial part of our commitment to code quality and reliability.
  • Widget and Integration Tests: Widget and integration tests must be implemented and pass in the Continuous Integration (CI) environment for both Android and iOS platforms. These tests should specifically cover the tap marker → details sheet flow, ensuring the user interaction works seamlessly across different platforms. This rigorous testing approach guarantees a consistent and high-quality user experience on both mobile operating systems.
  • Error Handling and Fallbacks: Error paths (e.g., network failures, service outages) must offer retry and fallback mechanisms, and these mechanisms must be covered by tests. This ensures the system is resilient to failures and can gracefully handle unexpected situations. Robust error handling is critical for maintaining user satisfaction and ensuring access to information, even in challenging circumstances.
  • Accessibility: The user interface must adhere to accessibility best practices, including large tap targets, descriptive labels, and appropriate color palette usage. This ensures the platform is usable by individuals with disabilities and promotes inclusivity. Accessibility is a core value in our development process, and we are committed to creating a platform that is usable by everyone.

Test Plan

To validate the functionality and reliability of this feature, we will implement a comprehensive test plan encompassing the following areas:

  • Unit Tests: We will develop unit tests for the FireIncident model, ActiveFiresService (both live and mock implementations), and the logic for calculating derived fields like distance, bearing, and risk level. These tests will focus on verifying the correctness of individual components and ensuring they function as expected in isolation. Unit tests are essential for identifying and resolving bugs early in the development process.
  • Widget Tests: We will create widget tests specifically for the BottomSheet presentation and the tap flow (tapping a marker to open the sheet). These tests will ensure the user interface elements render correctly and the interaction flow is seamless and intuitive. Widget tests bridge the gap between unit tests and integration tests, verifying the behavior of individual UI components in a more realistic context.
  • Integration Tests: We will implement end-to-end (E2E) integration tests to cover the entire flow from tapping a marker on the map to displaying the details sheet. These tests will also validate the use of both mock and live data, ensuring the system works correctly in different environments. Integration tests are crucial for verifying the interaction between different components of the system and ensuring the overall functionality meets the requirements.

Constitution Gates

To ensure the quality and integrity of the feature, we have defined the following constitution gates:

  • C1: Code Quality & Tests (CI): This gate ensures the code meets our quality standards and is adequately tested. The Continuous Integration (CI) system will automatically run unit, widget, and integration tests to verify the functionality and identify any regressions. This gate is critical for maintaining code health and preventing the introduction of bugs.
  • C2: Secrets & Logging (CI): This gate focuses on security and maintainability. The CI system will check for proper handling of secrets and ensure logging is implemented appropriately for debugging and monitoring purposes. Secure handling of sensitive information and effective logging are essential for protecting user data and ensuring the platform's stability.
  • C3: Accessibility (PR Review): This gate emphasizes accessibility. During the Pull Request (PR) review process, we will specifically assess the user interface for accessibility compliance, ensuring it meets the needs of users with disabilities. Accessibility is a core value, and this gate ensures it is considered throughout the development lifecycle.
  • C4: Trust & Transparency (PR Review): This gate focuses on building user trust. During the PR review, we will ensure the feature provides clear and transparent information to the user, including data sources and any limitations. Transparency is key to building user confidence and ensuring the platform is used responsibly.
  • C5: Resilience & Fallbacks (CI + PR Review): This gate addresses robustness and error handling. The CI system will run tests to verify fallback mechanisms, and the PR review will assess the overall resilience of the feature in the face of potential failures. Resilience is crucial for ensuring the platform remains functional and provides value to users, even in challenging circumstances.

Dependencies / Risks

  • Dependencies: This feature depends on the availability and functionality of the EffisService (both live and mock implementations) and utilizes the MAP_LIVE_DATA flag to control data source selection. These dependencies introduce potential risks if these services are unavailable or experience issues. Careful coordination and testing are required to mitigate these risks.
  • Risks: Potential risks include API response schema changes in the EffisService or other data providers, as well as limitations in the mobile map UX that could hinder the presentation of information. These risks could impact the functionality and usability of the feature.
  • Mitigations: To mitigate these risks, we will implement comprehensive tests, including integration tests that validate the interaction with external services. We will also incorporate fallback messaging to handle potential errors or data unavailability gracefully. Proactive monitoring and communication with dependent service providers are also essential for managing these risks effectively. We will also explore alternative UI approaches if map UX limitations become a significant concern.

Tasks

To successfully deliver this feature, we have identified the following key tasks:

  • [ ] Design/Contracts Finalized: This task involves finalizing the design of the bottom sheet UI, including the layout, information presentation, and user interactions. It also includes solidifying the API contracts for data retrieval and integration with other services. A well-defined design and clear contracts are crucial for ensuring a smooth and efficient development process.
  • [ ] Implementation: This task encompasses the actual coding and development of the feature, including the model, service logic, UI components, and integration with the map. This is the core development effort and requires careful attention to code quality, performance, and adherence to design specifications.
  • [ ] Tests: This task involves writing and executing unit, widget, and integration tests to validate the functionality and reliability of the feature. Thorough testing is essential for identifying and resolving bugs and ensuring the feature meets the required quality standards. We are committed to a test-driven development approach, where tests are written before the code to ensure comprehensive coverage.
  • [ ] Docs & Screenshots: This task includes creating documentation for the feature, including API documentation, user guides, and technical specifications. It also involves capturing screenshots and creating visual aids to illustrate the feature's functionality and usage. Clear and comprehensive documentation is crucial for onboarding new developers and ensuring the feature is well-understood and maintained over time.

Links

  • Related Specs: Placeholder for clustering/overlays future specs. This section will link to future specifications that address more advanced map features, such as fire marker clustering and overlay visualizations. These features are planned for subsequent development cycles and will build upon the foundation established by this initial feature.
  • Draft PR: (to link later). This will provide a direct link to the draft Pull Request (PR) where the code changes for this feature are being developed. This allows for easy tracking of the implementation progress and facilitates collaboration among developers. The PR will serve as the central location for code reviews, discussions, and feedback.
  • Notes: Designed for extensibility for future overlays & incident layers. This note highlights that the design of this feature has been carefully considered to ensure it can be easily extended in the future to support additional map overlays and incident layers. This forward-thinking approach ensures the platform remains flexible and adaptable to evolving user needs and technological advancements.