Skip to content

About

gives the vibe of the street

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

7 Commits

Folders and files

Repository files navigation

Boston 311 Call Stream

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.

Boston 311 Data Visualization

✨ Features

πŸ—ΊοΈ Interactive Map

  • 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

πŸ“‹ Smart Sidebar

  • 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

πŸ” Detailed Modal Views

  • 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

πŸ“Š Data Processing

  • 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

πŸš€ Getting Started

Prerequisites

  • Node.js (version 18 or higher)
  • pnpm (recommended) or npm

Installation

  1. Clone the repository

    git clone <repository-url>
    cd streetvibe
  2. Install dependencies

    pnpm install
    # or
    npm install
  3. Start the development server

    pnpm dev
    # or
    npm run dev
  4. Open your browser Navigate to http://localhost:3000

Building for Production

pnpm build
pnpm start

πŸ—οΈ Architecture

Tech Stack

  • 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

Project Structure

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

πŸ“ˆ Data Insights

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

Data Sources

  • 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

🎨 Design Principles

User Experience

  • 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

Visual Design

  • 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

πŸ”§ Configuration

Environment Variables

The application supports the following optional environment variables:

# For custom map styles (if needed)
NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_token_here

Image Domains

The application is configured to load images from:

  • spot-boston-res.cloudinary.com (Boston's official image storage)

πŸ“± Usage

Exploring Requests

  1. Browse the sidebar to see recent 311 requests
  2. Click any item to see detailed information
  3. Use the map to explore geographic distribution
  4. Click markers on the map for quick access to details

Understanding the Data

  • Open requests are shown in red
  • Closed requests are shown in green
  • Photo indicator (πŸ“·) shows requests with images
  • Larger markers indicate currently selected items

Navigation

  • "View on Map" button zooms to the exact location
  • Modal close returns to the main view
  • Sidebar selection syncs with map highlighting

🀝 Contributing

We welcome contributions! Please consider:

  1. Bug Reports: Use GitHub issues to report problems
  2. Feature Requests: Suggest new functionality or improvements
  3. Code Contributions: Fork the repo and submit pull requests
  4. Documentation: Help improve this README or add code comments

Development Guidelines

  • Follow the existing TypeScript patterns
  • Use Tailwind CSS for styling
  • Ensure accessibility compliance
  • Add error boundaries for robust error handling

πŸ“„ License

This project is open source and available under the MIT License.

πŸ“‹ Development Roadmap

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

πŸ™ Acknowledgments

  • 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.

About

gives the vibe of the street

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages