City Operations Platform

Foundry-style Data & Execution platform for NYC 311 service request management

Mission & Objectives

Primary Goal: Build an operational platform that ingests real NYC 311 data, models it as a clean ontology, exposes structured APIs, and provides an operator dashboard with AI-powered insights for resource optimization.

Key Philosophy: Make data actionable.

System Architecture

Data Pipeline
NYC 311 Open Data → Prisma ORM → PostgreSQL
Backend
Next.js API Routes + TypeScript
AI Layer
OpenAI GPT-4o-mini with structured outputs
Frontend
React + Tailwind CSS (Vercel-inspired)

Core Ontology

Incident
311 service requests with normalized categories, severity scores, lifecycle states (open/in_progress/closed)
Crew
Simulated city crews with specialties, capacity, borough assignments, and performance tracking
IncidentAssignment
Join table linking incidents to crews with assignment timestamps and status tracking
AiSuggestion
Persisted AI recommendations with context snapshots for validation and feedback loops

API Reference

GET /api/incidents
Query incidents with filters (category, borough, time range). Returns paginated incident list.
GET /api/summary
Aggregated operational metrics: inflow, throughput, backlog, status breakdown, top categories/boroughs, time-series throughput data
GET /api/ops/state
High-leverage internal endpoint designed for AI analysis and operator dashboards:
  • Fetch unassigned incidents with severity and location data
  • Calculate crew performance metrics (completion rate, avg resolution time, efficiency scores)
  • Compute system-wide efficiency (utilization, coverage by borough/category)
  • Flag low-performing crews with actionable explanations
  • Identify resource gaps and optimization opportunities
Security Note: Would be protected with authentication/RBAC in production
GET /api/summary/llm
AI-generated operational summary. Analyzes efficiency metrics and provides natural language insights with recommended prioritization actions. LLM receives only aggregated metrics, never raw incidents.
GET /api/crew/suggestions/llm
AI-powered crew assignment recommendations. Analyzes ops state and suggests optimal incident-to-crew mappings with efficiency reasoning and predicted outcomes.
POST /api/incidents/[id]/assign
Manual or AI-suggested crew assignment. Creates IncidentAssignment record and updates incident status. Validates crew capacity and specialty match.

Crew Allocation Strategy

Allocation Logic
AI analyzes unassigned incidents and crew state to recommend assignments based on: (1) Specialty matching (sanitation crew → sanitation incidents), (2) Geographic proximity (borough-based), (3) Current workload balance, (4) Historical crew performance, (5) Incident severity prioritization
Performance Measurement
Crews tracked on: Completion rate (% of assignments closed),Avg resolution time (hours from assignment to closure),Efficiency score (composite: speed + volume + specialty match rate),Utilization (active assignments / capacity)
Efficiency Insights
System identifies crews performing <45% below average or with 2x+ resolution times and flags for review. Provides borough/category coverage gaps and rebalancing recommendations.

Data Refresh & Rate Limiting

Data Ingestion Schedule
NYC 311 data is ingested from the Open Data API every 7 days. The dashboard header displays a countdown showing when the next data ingestion will occur. The dashboard loads data once on page load and does not auto-refresh.
AI Endpoint Scheduling
AI-powered endpoints (/api/summary/llm, /api/crew/suggestions/llm) are scheduled to run automatically after each data ingestion (every 7 days). Insights are generated once and cached for 7 days, eliminating unnecessary OpenAI API calls. If cache is empty, endpoints can still generate insights on-demand.

Scripts

ingest-311-scheduled.ts
Scheduled data ingestion script. Fetches NYC 311 data from the Open Data API every 7 days, normalizes incidents, and automatically triggers AI insights generation after ingestion completes.
generate-ai-insights.ts
Generates AI-powered summary insights and crew assignment suggestions. Called automatically after data ingestion to pre-warm the cache for 7 days.
seed-crews.ts
Seeds the database with simulated city crews for testing and demonstration purposes.
seed-assignment-history.ts
Seeds historical incident assignments for testing crew performance metrics and efficiency analysis.

Key Features

Automated 7-day data ingestion from NYC 311 Open Data API with scheduled AI insights generation
AI-powered operational efficiency analysis
Intelligent crew assignment optimization
Crew performance metrics and low-performer identification
Resource utilization and coverage gap analysis
Geographic incident distribution tracking
Predicted outcome simulation for assignment decisions
Structured API endpoints for operational state and metrics access
City Operations Platform v1.0 • Built with Next.js, Prisma, PostgreSQL, OpenAI