Technical Guide: Implementing the Spothole Authority Front-End Management System

Practical Overview and Architecture

The Spothole Authority application is designed as the front-end management segment for municipal road condition oversight. According to project documentation, the solution addresses the immense financial and safety toll of degraded road infrastructure by providing an interactive interface for tracking, validating, and managing road damages. Municipal authorities utilize this dashboard to review deep learning-powered media validated reports, visualize geographic damage patterns via maps, and handle citizen communications. The underlying software architecture leverages a React.js front-end integrated with Material Design standards, utilizing Axios for RESTful communication with backend services. Architectural tiers separate the front-end dashboard presentation layer from core database and deep learning tiers.

System components communicate through defined API endpoints and manage authentication securely via Google OAuth 2.0. The application features extensive data visualization powered by Recharts, presenting donut charts for status-wise report counts and stacked bar charts for status and severity metrics. Furthermore, the map interface integrates React Google Maps to render custom markers, heat map layers, and street view capabilities. By centralizing reporting data into filterable datatables, administrators can easily sort, search, export CSV files, and manage user permissions to streamline municipal workflows.

Prerequisites and Installation Setup

Deploying the Spothole Authority front-end application requires strict adherence to documented prerequisites. Developers must first ensure that Node.js and npm are installed on their machine by following official instructions provided through the npm documentation portal. Additionally, setting up the environment demands active API configurations, including generating a valid Google Maps API key from the Google Developers console and configuring a Google OAuth client ID for authentication protocols. The front-end also depends on a fully operational backend service, specifically requiring the Flask and deep learning application repository to be cloned, configured, and tested locally using API testing tools like Postman prior to launching the dashboard interface.

To execute the local installation, developers must follow a sequence of terminal commands starting with repository cloning and dependency resolution. The documented setup process requires executing specific commands within the terminal or Git-Bash environment. Developers must configure their database and establish at least one authorized authority user before starting the application. Once API constants within the utility folder of the src component directory are updated to point to the local backend endpoints, developers can initiate the local development server to access and evaluate the dashboard interface directly within their browser environment.

Documented Implementation Workflow

The documented workflow for administrators using the Spothole Authority application centers around five major navigational sections: Dashboard, Map Region View, Manage Users, Profile, and the Sign-In screen. Upon successful authentication via Google OAuth 2.0, administrators land on the dashboard containing high-level analytics and filterable report data tables. Clicking on any individual report allows the authority to update its status and severity while providing a required custom description reason. The application subsequently triggers automated email notifications to keep citizens informed of report progress. The workflow also encompasses interactive map region views where custom markers display potholes color-coded by severity, enabling direct status updates from informational window popups.

To set up the application locally, developers execute the following commands in their terminal:

git clone https://github.com/nirbhayph/spothole.authority.git cd spothole.authority npm install

After installing dependencies and configuring the necessary Google Maps and OAuth credentials, developers finalize the integration by starting the application using npm:

npm start

This launches the React application locally at http://localhost:3000, allowing administrators to interact with zone-wise reports, manage active user access privileges, and review summarized performance statistics directly from their browser.

Known Limitations, Tradeoffs, and Error Scenarios

While the Spothole Authority application provides a robust interface for municipal tracking, several documented limitations and structural tradeoffs exist within its current scope. The application relies heavily on external third-party services, such as Google Maps and Unsplash APIs, meaning that network disruptions or changes in external API rate limits can impact dashboard mapping and visual asset generation. Furthermore, OAuth authentication is tightly coupled to a standalone database specifically configured to authorize registered authority email addresses, which introduces administrative overhead when onboarding new municipal staff members or managing credential updates across disparate administrative zones.

Error handling within the application accounts for standard web protocol failures, displaying dedicated error pages for 404 and 401 status codes. However, data synchronization relies heavily on local storage to maintain session states during communication with the Google API, introducing potential state management vulnerabilities if local storage tokens become corrupted or expire unexpectedly. Additionally, the current deployment model utilizes static hosting via GitHub Pages, which imposes architectural constraints on server-side rendering capabilities and requires explicit API routing configurations to maintain seamless communication with the backend Flask server.

Who Should Use It and Production Fit

The Spothole Authority application is specifically tailored for municipal administrative bodies, information technology capstone researchers, and civil engineering departments seeking an automated, machine learning-driven solution for urban road maintenance. Educational institutions, such as the Rochester Institute of Technology where this project originated, and municipal infrastructure planners represent the primary target audience. The tool fits environments requiring transparent citizen-to-authority communication channels, dynamic reporting dashboards, and geographic visualization of road degradation. Organizations struggling with low budgetary allocations for infrastructure upkeep can leverage this open-source platform to optimize repair schedules and minimize vehicle damage costs.

However, prospective users must evaluate its production fit against future development milestones outlined by the developer. The current release serves as a front-end management segment and lacks advanced production features such as a parent authority admin section, in-app work order assignment, dedicated worker mobile applications, push notification services, and automated social media integrations. Organizations requiring complex hierarchy management or multi-tiered permission systems will need to contribute to future work scopes or implement custom extensions. Nonetheless, for entities needing an open-source, media-validated pothole tracking dashboard with React and Flask foundations, this application offers a solid baseline.