CivicFix System Requirements Document

1. Introduction

CivicFix is an AI-powered civic issue reporter and prioritizer designed to streamline the process of reporting and managing civic issues such as potholes, garbage dumps, broken streetlights, and water leaks. The platform enables citizens to report issues efficiently while allowing municipal teams to prioritize and manage these reports effectively.

2. System Overview

2a. Product Interpretation and Delivery Boundary

CivicFix is a first-party application that facilitates the reporting and management of civic issues using AI-driven automation. The system includes the following components:

• Citizen Report Issue Page: A custom page for citizens to report issues by uploading a photo and pinning a location on a map.
• Public Map Dashboard: A public entry surface displaying open issues, their status, and upvote/confirm counts.
• Admin Dashboard: An identity access surface for municipal admins to manage reported issues, filter by severity/status, and mark issues as resolved.

Access: Application-owned identity with JWT-based authentication, supporting roles for citizens and admins.

Behavior Contracts:

• Report Civic Issue: Citizens upload a photo and pin a location, resulting in a new issue record.
• Classify and Prioritize Issue: The system classifies the issue and assigns a severity score.
• Detect Duplicate Issues: The system detects duplicates using geo-proximity and image embedding similarity.
• Suggest Auto-Routing: The system suggests routing to the likely responsible department.
• Manage Issues: Admins filter issues, mark them resolved, and view analytics.
• View Public Map Dashboard: Public users view open issues on a map.

2b. Source Content Inventory

Not applicable as no content_source directive was provided.

2c. Page Content and Component Coverage

Citizen Report Issue Page

• Photo Upload: Interface for uploading issue photos.
• Map Pinning: Interactive map for location pinning.
• Issue Submission: Form to submit the report with photo and location.
• Feedback: Confirmation message upon successful submission.

Public Map Dashboard

• Issue Map: Displays open issues with markers.
• Issue Details: Shows status and upvote/confirm count for each issue.
• Filter Options: Allows filtering by issue type and severity.

Admin Dashboard

• Issue Management: Interface to filter issues by severity/status.
• Resolution Marking: Option to mark issues as resolved.
• Analytics View: Displays analytics on reported issues.

3. Functional Requirements as Story Points

• As a Citizen Reporter, I should be able to upload a photo and pin a location on a map to report a civic issue. explicit
• As a System, I should classify the issue type and assign a severity score when a new issue is reported. explicit
• As a System, I should detect duplicate issues using geo-proximity and image embedding similarity. explicit
• As a System, I should suggest auto-routing to the likely responsible department for classified issues. explicit
• As a Municipal Admin, I should be able to filter issues by severity/status and mark them as resolved. basic_default
• As a Public User, I should be able to view open issues on a public map dashboard with their status and upvote/confirm count. explicit
• As a System, I should generate a weekly AI-generated area status digest. explicit

4. User Personas

• Citizen Reporter: Primary user reporting civic issues.
• Municipal Admin: User managing and triaging reported issues.

5. Core User Flows

Citizen Reporter Flow

1. Access the Citizen Report Issue page.
2. Upload a photo of the issue.
3. Pin the location on the map.
4. Submit the report.
5. Receive confirmation of submission.

Municipal Admin Flow

1. Access the Admin Dashboard.
2. Filter issues by severity or status.
3. Review issue details.
4. Mark issues as resolved.
5. View analytics for reported issues.

Public User Flow

1. Access the Public Map Dashboard.
2. View open issues on the map.
3. Check the status and upvote/confirm count of issues.

6. Visuals Colors and Theme

• Primary: #1E3A8A (Indigo)
• Primary Light: #3B82F6 (Light Blue)
• Secondary: #10B981 (Green)
• Accent: #F59E0B (Amber)
• Highlight: #EF4444 (Red)
• Background: #F3F4F6 (Gray)
• Surface: #FFFFFF (White)
• Text: #111827 (Dark Gray)
• Text Muted: #6B7280 (Muted Gray)
• Border: #D1D5DB (Light Gray)

7. Signature Design Concept

The Public Map Dashboard will feature a clean, interactive map interface with markers representing open issues. Each marker will display a tooltip with issue details upon hover. The design will use a minimalistic approach with a focus on usability and clarity. The map will be the focal point, with a sidebar for filtering options and a header displaying the application logo and navigation links.

8. Interaction Model & Motion Direction

The interaction model for the Public Map Dashboard is animated, featuring smooth transitions for map interactions and hover effects on issue markers. The design will prioritize clarity and ease of use, with restrained animations to enhance user experience without overwhelming the interface.

9. Non-Functional Requirements

• Performance: The system must handle concurrent user interactions efficiently. required_inference
• Security: JWT-based authentication must ensure secure access control for citizen and admin roles. explicit
• Scalability: The system should support scaling to accommodate increasing numbers of reports and users. required_inference

10. Tech Stack

• Frontend: Next.js (App Router), React, Tailwind CSS, Leaflet or Mapbox for maps
• Backend: Node.js/Express or FastAPI
• Database: MongoDB with geospatial indexing or PostgreSQL + PostGIS
• AI: Gemini Vision API or GPT-4V for image classification
• Auth: JWT-based
• Deployment: Vercel for frontend, Kubernetes for backend

11. Assumptions and Constraints

• The system assumes reliable internet connectivity for accessing map services and uploading images.
• The AI classification and duplicate detection rely on the accuracy of the Gemini Vision API or GPT-4V.

12. Glossary

• Civic Issue: Problems related to public infrastructure such as potholes, garbage dumps, etc.
• AI Pipeline: Automated process for classifying and prioritizing issues using artificial intelligence.
• JWT: JSON Web Token, a compact, URL-safe means of representing claims to be transferred between two parties.
• Geospatial Indexing: A method of storing spatial data in a database to enable efficient location-based queries.