How exobrienx/urbanreport works
1. Overall shape
- UrbanReport is a Next.js App Router application for urban incident reporting, built as a PWA-style citizen reporting platform with separate experiences for citizens, technicians, and admins.
- The repo is organized around a single web app plus internal API routes, with persistence handled through Prisma and external integrations for authentication, file storage, and AI classification.
2. User-facing application shells
- The main routes live under app/: public landing (app/page.tsx), citizen access (app/acceso), technician area (app/tecnico), admin area (app/admin), and a permissions test page (app/test-permisos).
- app/layout.tsx, app/globals.css, and app/components/Provider.tsx establish the global shell, styling, and client-side providers used across all roles.
3. Role separation and access control
- Authentication is wired through app/lib/auth.ts and the NextAuth route at app/api/auth/[...nextauth]/route.ts.
- Authorization is enforced by middleware.ts plus app/lib/permissions.ts, indicating route-level protection and role-based visibility for citizen/admin/technician flows.
- types/next-auth.d.ts extends auth types, likely to carry role/permission data through sessions.
4. Core business domain: incident reporting
- The main domain centers on incident reports (reporte/incidencia) submitted by citizens and processed for operational routing.
- app/api/reports/route.ts is the main entry point for creating or querying reports.
- Domain logic is split into focused services in app/lib/services/: ReporteService, IncidenciaService, PriorityService, and HaversineService, which suggests a workflow that normalizes report data, derives incident records, computes urgency, and measures geographic distance.
5. AI-assisted classification
- app/api/ai/classify/route.ts exposes an AI classification endpoint, backed by app/lib/services/AIService.ts.
- This is likely used to categorize incoming reports or infer incident type/priority from user input and/or images before persistence or routing.
- The presence of a dedicated AI API boundary suggests classification is decoupled from the main report submission flow.
6. Map-centric user experience
- The repository includes a dedicated map subsystem under app/components/map/ with CityMap.tsx, ClusterSheet.tsx, and MapControls.tsx.
- app/lib/hooks/useCityMap.ts and helpers in app/lib/utils/mapHelpers.ts / app/lib/utils/geo.ts indicate map state, clustering, filtering, and geospatial computation are handled on the client with shared utility logic.
- The map is likely the main operational view for visualizing report density and dispatching work across the city.
7. Citizen submission UI
- Citizen-facing reporting is concentrated in app/components/ui/Ciudadano/ReportModal.tsx, which likely collects the incident description, category, location, and possibly a photo.
- app/lib/uploadPhoto.ts and app/lib/r2.ts show that image uploads are stored in an object store compatible with R2, rather than in the app database.
- This creates a clear split: metadata goes to Prisma-backed storage, while media assets go to object storage.
8. Data persistence and schema
- The database layer is centered on prisma/schema.prisma and versioned through migrations in prisma/migrations/.
- app/lib/prisma.ts is the Prisma client entry point used by API routes and services.
- Migrations include user fields like rut and telefono, implying the platform tracks citizen/operator identity details beyond basic auth.
9. Shared infrastructure and API response handling
- app/lib/factories/ResponseFactory.ts suggests a standardized API response shape across endpoints.
- Utility and service modules are used to keep route handlers thin and push business logic into reusable boundaries.
- This separation is important for diagramming: route handlers are orchestration points, while services contain domain logic.
10. Admin and technician operational areas
- app/admin and app/tecnico are distinct role-based workspaces, likely for report triage, assignment, and status updates.
- Empty placeholder folders under app/admin/reportes, app/admin/tecnicos, and app/api/admin indicate planned or modularized admin capabilities.
- The scripts/create-admin.ts and scripts/create-tecnico.ts utilities show that privileged users are provisioned through repo-managed scripts rather than self-service signup.
11. Request flow at a high level
- A citizen submits a report from the UI.
- The app may upload a photo to object storage, classify the incident through the AI endpoint/service, and persist the final report/incident in the database via Prisma.
- Admin/technician interfaces and the city map then read from the same persisted data to prioritize and visualize work.
12. Architectural boundaries to show in a diagram
- Presentation layer: Next.js pages and React components.
- Application/API layer: route handlers under app/api/*.
- Domain layer: services in app/lib/services/*, permissions, and utilities.
- Persistence layer: Prisma + database, plus separate object storage for photos.
- External services: NextAuth for auth, R2-style storage for uploads, and AI classification for report processing.
13. Practical diagram takeaway
- The most important dependency chain is: client UI → API route → domain service → Prisma/R2/AI dependency.
- The second important chain is: auth/middleware → role-specific pages and endpoints.
- The map is the primary cross-cutting visualization layer consuming the same incident data produced by the reporting pipeline.
Main entry points: prisma.ts Prisma client · ReporteService.ts Reporte service · CityMap.tsx City map · layout.tsx App shell
Components 29
Presentation
Next.js pages and client components for citizen, technician, admin, and map experiences
- App shell · Global app shell and providers entry point
app/layout.tsx - Landing · Public landing page
app/page.tsx - Citizen area · Citizen-facing access and reporting entry point
app/acceso/page.tsx - Admin area · Admin workspace
app/admin/page.tsx - Tech area · Technician workspace
app/tecnico/page.tsx - Report modal · Citizen incident submission UI
app/components/ui/Ciudadano/ReportModal.tsx - City map · Main operational map for incidents and clustering
app/components/map/CityMap.tsx - Cluster sheet · Cluster drilldown and grouped incident view
app/components/map/ClusterSheet.tsx - Map controls · Filtering and map interaction controls
app/components/map/MapControls.tsx
API Layer
Route handlers that expose report, AI, and auth entry points
- Reports API · Create and query incident reports
app/api/reports/route.ts - AI classify · AI classification endpoint for incoming reports
app/api/ai/classify/route.ts - Auth API · NextAuth entry point
app/api/auth/[...nextauth]/route.ts
Domain Logic
Authentication, authorization, services, and shared helpers
- Map hook · Client map state and interaction orchestration
app/lib/hooks/useCityMap.ts - Route guard · Enforces access control on protected routes
middleware.ts - Auth config · NextAuth configuration and session setup
app/lib/auth.ts - Permissions · Role and route authorization rules
app/lib/permissions.ts - Reporte service · Report submission and orchestration logic
app/lib/services/ReporteService.ts - Incidencia service · Incident record normalization and handling
app/lib/services/IncidenciaService.ts - Priority service · Priority and urgency derivation
app/lib/services/PriorityService.ts - Geo distance · Distance calculation for location-based routing
app/lib/services/HaversineService.ts - AI service · Classification and inference logic
app/lib/services/AIService.ts - Responses · Standardized API response creation
app/lib/factories/ResponseFactory.ts - Upload photo · Photo upload workflow for citizen reports
app/lib/uploadPhoto.ts - Auth types · Session and role type extensions
types/next-auth.d.ts
Persistence
Prisma schema plus database and object storage boundaries
- Prisma client · Database access entry point
app/lib/prisma.ts - Photo storage · R2-compatible storage boundary for uploads
app/lib/r2.ts - Schema · Data model and migrations source of truth
prisma/schema.prisma
Operations
Repo-managed scripts for provisioning privileged users
- Create admin · Privileged admin user provisioning
scripts/create-admin.ts - Create tech · Privileged technician user provisioning
scripts/create-tecnico.ts
Connections 30
- App shell → Landing: shells · Global app shell frames public and role-based pages
- App shell → Citizen area: frames · Shared layout applies to citizen experience
- App shell → Admin area: frames · Shared layout applies to admin experience
- App shell → Tech area: frames · Shared layout applies to technician experience
- Citizen area → Report modal: submits · Citizen area drives incident submission UI
- Admin area → City map: operates · Admin area consumes the operational map
- Tech area → City map: operates · Technician area also uses the map view
- City map → Map hook: state · Map view delegates state and clustering behavior
- City map → Cluster sheet: shows · Map renders cluster drilldown UI
- City map → Map controls: controls · Map uses filtering and interaction controls
- Report modal → Reports API: posts · Citizen report form sends data to report API
- Report modal → Upload photo: uploads · Incident photos are uploaded separately from metadata
- Upload photo → Photo storage: stores · Photo assets are written to object storage
- Reports API → Reporte service: orchestrates · Report route delegates business logic to services
- Reports API → Responses: formats · API responses are standardized
- Reports API → Prisma client: persists · Report operations write through Prisma
- AI classify → AI service: delegates · AI route uses classification service
- Auth API → Auth config: configures · NextAuth route uses shared auth configuration
- Route guard → Permissions: enforces · Middleware applies role-based route protection
- Auth config → Auth types: extends · Auth session types carry role-specific data
- Reporte service → Incidencia service: derives · Reports are normalized into incident records
- Reporte service → Priority service: rates · Service computes urgency and priority
- Reporte service → Geo distance: measures · Service uses geo distance in routing decisions
- Reporte service → Prisma client: writes · Core report workflow persists through Prisma
- Incidencia service → Prisma client: reads/writes · Incident handling depends on the database layer
- AI service → Prisma client: reads · AI-assisted processing may consult persisted data
- Schema → Prisma client: models · Prisma client is generated from the schema
- Create admin → Prisma client: provisions · Admin provisioning writes privileged user records
- Create tech → Prisma client: provisions · Technician provisioning writes privileged user records
- Permissions → Auth config: depends · Authorization rules rely on authenticated session data