An interactive web application for visualizing and exploring Boston's 311 service requests in real-time. Built with Next.js, TypeScript, and MapLibre GL, this application provides an intuitive interface to browse, search, and analyze citizen service requests across the city.
- Live visualization of 311 service requests on an interactive map
- Clickable markers that reveal detailed information about each request
- Dynamic focusing - zoom to specific locations with smooth animations
- Visual indicators - different colors for request types, larger markers for selected items
- Hover tooltips showing request titles for quick reference
- Real-time data showing the 100 most recent incidents
- Clickable entries that sync with the map view
- Visual status indicators with color-coded badges (Open, Closed, In Progress)
- Photo indicators showing which requests include submitted photos
- Responsive highlighting of selected items
- Rich information display with organized card layouts
- Photo galleries showing submitted and resolution photos from Cloudinary
- Timeline visualization with color-coded status indicators
- Location details including neighborhood, ZIP code, and coordinates
- Department information and request categorization
- "View on Map" integration for seamless navigation
- CSV-based data loading from Boston's 311 dataset
- Smart filtering to show the most recent 100 incidents
- Date-based sorting with newest requests displayed first
- Data validation using Zod schemas for type safety
- Error handling for malformed data entries
- Node.js (version 18 or higher)
- pnpm (recommended) or npm
-
Clone the repository
git clone <repository-url> cd streetvibe
-
Install dependencies
pnpm install # or npm install -
Start the development server
pnpm dev # or npm run dev -
Open your browser Navigate to http://localhost:3000
pnpm build
pnpm start- Frontend Framework: Next.js 15 with App Router
- Language: TypeScript for type safety
- Styling: Tailwind CSS for utility-first styling
- State Management: React Query (TanStack Query) for data fetching
- Maps: MapLibre GL with react-map-gl
- Data Validation: Zod for runtime type checking
- Icons: Lucide React for consistent iconography
src/
βββ app/ # Next.js app router pages
β βββ globals.css # Global styles and CSS variables
β βββ layout.tsx # Root layout component
β βββ page.tsx # Main application page
βββ components/ # React components
β βββ Map.tsx # Interactive map component
β βββ MapMarker.tsx # Custom map marker component
β βββ ServiceRequestModal.tsx # Detailed view modal
β βββ Sidebar.tsx # Request list sidebar
βββ hooks/ # Custom React hooks
β βββ use-311-data.ts # Data fetching and processing
βββ types/ # TypeScript type definitions
β βββ boston-311.ts # 311 data schemas
βββ lib/ # Utility functions
βββ utils.ts # Helper functions
The application uses real Boston 311 data, providing insights into:
- Request Types: Parking violations, code enforcement, street maintenance, etc.
- Geographic Distribution: Visualization of where requests are concentrated
- Timeline Patterns: When requests are opened and resolved
- Department Workload: Which city departments handle different types of requests
- Resolution Tracking: Visual indicators of request status and completion
- Primary Dataset: Boston's official 311 service request data
- Photos: Cloudinary-hosted images submitted by citizens and city workers
- Geographic Data: Coordinate-based mapping with neighborhood information
- Immediate Visual Feedback: Clicking any item immediately shows its location
- Contextual Information: Hover states and tooltips provide quick insights
- Responsive Design: Works seamlessly on desktop and mobile devices
- Progressive Enhancement: Graceful degradation when images fail to load
- Clean Interface: Minimal design focusing on data clarity
- Color Coding: Consistent color scheme for status and request types
- Typography: Clear hierarchy with readable fonts
- Spacing: Generous whitespace for easy scanning
The application supports the following optional environment variables:
# For custom map styles (if needed)
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_token_hereThe application is configured to load images from:
spot-boston-res.cloudinary.com(Boston's official image storage)
- Browse the sidebar to see recent 311 requests
- Click any item to see detailed information
- Use the map to explore geographic distribution
- Click markers on the map for quick access to details
- Open requests are shown in red
- Closed requests are shown in green
- Photo indicator (π·) shows requests with images
- Larger markers indicate currently selected items
- "View on Map" button zooms to the exact location
- Modal close returns to the main view
- Sidebar selection syncs with map highlighting
We welcome contributions! Please consider:
- Bug Reports: Use GitHub issues to report problems
- Feature Requests: Suggest new functionality or improvements
- Code Contributions: Fork the repo and submit pull requests
- Documentation: Help improve this README or add code comments
- Follow the existing TypeScript patterns
- Use Tailwind CSS for styling
- Ensure accessibility compliance
- Add error boundaries for robust error handling
This project is open source and available under the MIT License.
See our TODO.md for the complete implementation plan, including:
- Migration to Elasticsearch for real-time data streaming
- Multi-city support (Boston + Cambridge + future expansion)
- Kubernetes deployment architecture
- Performance optimization goals
- City of Boston for providing open 311 data
- MapLibre for the excellent mapping library
- Cloudinary for hosting citizen-submitted photos
- Next.js team for the robust React framework
Built with β€οΈ for civic transparency and community engagement.