# exobrienx/urbanreport architecture

> Architecture diagram of the GitHub repository exobrienx/urbanreport, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/exobrienx/urbanreport
- Repository: https://github.com/exobrienx/urbanreport

## Overview

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: [`app/lib/prisma.ts`](https://github.com/exobrienx/urbanreport/blob/main/app/lib/prisma.ts) (Prisma client), [`app/lib/services/ReporteService.ts`](https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/ReporteService.ts) (Reporte service), [`app/components/map/CityMap.tsx`](https://github.com/exobrienx/urbanreport/blob/main/app/components/map/CityMap.tsx) (City map), [`app/layout.tsx`](https://github.com/exobrienx/urbanreport/blob/main/app/layout.tsx) (App shell)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_app_layout["App shell<br/>nextjs layout<br/>[layout.tsx]"]
  node_app_home["Landing<br/>nextjs page<br/>[page.tsx]"]
  node_app_ciudadano["Citizen area<br/>nextjs page<br/>[page.tsx]"]
  node_app_admin["Admin area<br/>nextjs page<br/>[page.tsx]"]
  node_app_tecnico["Tech area<br/>nextjs page<br/>[page.tsx]"]
  node_report_modal["Report modal<br/>ui form<br/>[ReportModal.tsx]"]
  node_city_map["City map<br/>map view<br/>[CityMap.tsx]"]
  node_cluster_sheet["Cluster sheet<br/>map panel<br/>[ClusterSheet.tsx]"]
  node_map_controls["Map controls<br/>map ui<br/>[MapControls.tsx]"]
end

subgraph group_api["API Layer"]
  node_api_reports["Reports API<br/>route handler<br/>[route.ts]"]
  node_api_ai_classify["AI classify<br/>route handler<br/>[route.ts]"]
  node_api_auth["Auth API<br/>route handler<br/>[route.ts]"]
end

subgraph group_domain["Domain Logic"]
  node_use_city_map["Map hook<br/>react hook<br/>[useCityMap.ts]"]
  node_middleware{{"Route guard<br/>edge middleware<br/>[middleware.ts]"}}
  node_auth_lib["Auth config<br/>[auth.ts]"]
  node_permissions["Permissions<br/>rbac<br/>[permissions.ts]"]
  node_reporte_service["Reporte service<br/>domain service<br/>[ReporteService.ts]"]
  node_incidencia_service["Incidencia service<br/>domain service"]
  node_priority_service["Priority service<br/>domain service<br/>[PriorityService.ts]"]
  node_haversine_service["Geo distance<br/>geo service"]
  node_ai_service["AI service<br/>[AIService.ts]"]
  node_response_factory["Responses<br/>api helper<br/>[ResponseFactory.ts]"]
  node_upload_photo["Upload photo<br/>upload helper<br/>[uploadPhoto.ts]"]
  node_nextauth_types["Auth types<br/>type augment<br/>[next-auth.d.ts]"]
end

subgraph group_data["Persistence"]
  node_prisma_client[("Prisma client<br/>db client<br/>[prisma.ts]")]
  node_r2_store[("Photo storage<br/>object storage<br/>[r2.ts]")]
  node_schema["Schema<br/>[schema.prisma]"]
end

subgraph group_ops["Operations"]
  node_create_admin["Create admin<br/>provision script<br/>[create-admin.ts]"]
  node_create_tecnico["Create tech<br/>provision script<br/>[create-tecnico.ts]"]
end

node_app_layout -->|"shells"| node_app_home
node_app_layout -->|"frames"| node_app_ciudadano
node_app_layout -->|"frames"| node_app_admin
node_app_layout -->|"frames"| node_app_tecnico
node_app_ciudadano -->|"submits"| node_report_modal
node_app_admin -->|"operates"| node_city_map
node_app_tecnico -->|"operates"| node_city_map
node_city_map -->|"state"| node_use_city_map
node_city_map -->|"shows"| node_cluster_sheet
node_city_map -->|"controls"| node_map_controls
node_report_modal -->|"posts"| node_api_reports
node_report_modal -->|"uploads"| node_upload_photo
node_upload_photo -->|"stores"| node_r2_store
node_api_reports -->|"orchestrates"| node_reporte_service
node_api_reports -->|"formats"| node_response_factory
node_api_reports -->|"persists"| node_prisma_client
node_api_ai_classify -->|"delegates"| node_ai_service
node_api_auth -->|"configures"| node_auth_lib
node_middleware -->|"enforces"| node_permissions
node_auth_lib -->|"extends"| node_nextauth_types
node_reporte_service -->|"derives"| node_incidencia_service
node_reporte_service -->|"rates"| node_priority_service
node_reporte_service -->|"measures"| node_haversine_service
node_reporte_service -->|"writes"| node_prisma_client
node_incidencia_service -->|"reads/writes"| node_prisma_client
node_ai_service -->|"reads"| node_prisma_client
node_schema -->|"models"| node_prisma_client
node_create_admin -->|"provisions"| node_prisma_client
node_create_tecnico -->|"provisions"| node_prisma_client
node_permissions -->|"depends"| node_auth_lib

click node_app_layout "https://github.com/exobrienx/urbanreport/blob/main/app/layout.tsx"
click node_app_home "https://github.com/exobrienx/urbanreport/blob/main/app/page.tsx"
click node_app_ciudadano "https://github.com/exobrienx/urbanreport/blob/main/app/acceso/page.tsx"
click node_app_admin "https://github.com/exobrienx/urbanreport/blob/main/app/admin/page.tsx"
click node_app_tecnico "https://github.com/exobrienx/urbanreport/blob/main/app/tecnico/page.tsx"
click node_report_modal "https://github.com/exobrienx/urbanreport/blob/main/app/components/ui/Ciudadano/ReportModal.tsx"
click node_city_map "https://github.com/exobrienx/urbanreport/blob/main/app/components/map/CityMap.tsx"
click node_cluster_sheet "https://github.com/exobrienx/urbanreport/blob/main/app/components/map/ClusterSheet.tsx"
click node_map_controls "https://github.com/exobrienx/urbanreport/blob/main/app/components/map/MapControls.tsx"
click node_use_city_map "https://github.com/exobrienx/urbanreport/blob/main/app/lib/hooks/useCityMap.ts"
click node_api_reports "https://github.com/exobrienx/urbanreport/blob/main/app/api/reports/route.ts"
click node_api_ai_classify "https://github.com/exobrienx/urbanreport/blob/main/app/api/ai/classify/route.ts"
click node_api_auth "https://github.com/exobrienx/urbanreport/blob/main/app/api/auth/[...nextauth]/route.ts"
click node_middleware "https://github.com/exobrienx/urbanreport/blob/main/middleware.ts"
click node_auth_lib "https://github.com/exobrienx/urbanreport/blob/main/app/lib/auth.ts"
click node_permissions "https://github.com/exobrienx/urbanreport/blob/main/app/lib/permissions.ts"
click node_reporte_service "https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/ReporteService.ts"
click node_incidencia_service "https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/IncidenciaService.ts"
click node_priority_service "https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/PriorityService.ts"
click node_haversine_service "https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/HaversineService.ts"
click node_ai_service "https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/AIService.ts"
click node_response_factory "https://github.com/exobrienx/urbanreport/blob/main/app/lib/factories/ResponseFactory.ts"
click node_prisma_client "https://github.com/exobrienx/urbanreport/blob/main/app/lib/prisma.ts"
click node_r2_store "https://github.com/exobrienx/urbanreport/blob/main/app/lib/r2.ts"
click node_upload_photo "https://github.com/exobrienx/urbanreport/blob/main/app/lib/uploadPhoto.ts"
click node_schema "https://github.com/exobrienx/urbanreport/blob/main/prisma/schema.prisma"
click node_create_admin "https://github.com/exobrienx/urbanreport/blob/main/scripts/create-admin.ts"
click node_create_tecnico "https://github.com/exobrienx/urbanreport/blob/main/scripts/create-tecnico.ts"
click node_nextauth_types "https://github.com/exobrienx/urbanreport/blob/main/types/next-auth.d.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_layout,node_app_home,node_app_ciudadano,node_app_admin,node_app_tecnico,node_report_modal,node_city_map,node_cluster_sheet,node_map_controls toneBlue
class node_api_reports,node_api_ai_classify,node_api_auth toneAmber
class node_use_city_map,node_middleware,node_auth_lib,node_permissions,node_reporte_service,node_incidencia_service,node_priority_service,node_haversine_service,node_ai_service,node_response_factory,node_upload_photo,node_nextauth_types toneMint
class node_prisma_client,node_r2_store,node_schema toneRose
class node_create_admin,node_create_tecnico toneIndigo
```

## Components

### Presentation

Next.js pages and client components for citizen, technician, admin, and map experiences

- [App shell](https://github.com/exobrienx/urbanreport/blob/main/app/layout.tsx): nextjs layout · Global app shell and providers entry point · `app/layout.tsx`
- [Landing](https://github.com/exobrienx/urbanreport/blob/main/app/page.tsx): nextjs page · Public landing page · `app/page.tsx`
- [Citizen area](https://github.com/exobrienx/urbanreport/blob/main/app/acceso/page.tsx): nextjs page · Citizen-facing access and reporting entry point · `app/acceso/page.tsx`
- [Admin area](https://github.com/exobrienx/urbanreport/blob/main/app/admin/page.tsx): nextjs page · Admin workspace · `app/admin/page.tsx`
- [Tech area](https://github.com/exobrienx/urbanreport/blob/main/app/tecnico/page.tsx): nextjs page · Technician workspace · `app/tecnico/page.tsx`
- [Report modal](https://github.com/exobrienx/urbanreport/blob/main/app/components/ui/Ciudadano/ReportModal.tsx): ui form · Citizen incident submission UI · `app/components/ui/Ciudadano/ReportModal.tsx`
- [City map](https://github.com/exobrienx/urbanreport/blob/main/app/components/map/CityMap.tsx): map view · Main operational map for incidents and clustering · `app/components/map/CityMap.tsx`
- [Cluster sheet](https://github.com/exobrienx/urbanreport/blob/main/app/components/map/ClusterSheet.tsx): map panel · Cluster drilldown and grouped incident view · `app/components/map/ClusterSheet.tsx`
- [Map controls](https://github.com/exobrienx/urbanreport/blob/main/app/components/map/MapControls.tsx): map ui · Filtering and map interaction controls · `app/components/map/MapControls.tsx`

### API Layer

Route handlers that expose report, AI, and auth entry points

- [Reports API](https://github.com/exobrienx/urbanreport/blob/main/app/api/reports/route.ts): route handler · Create and query incident reports · `app/api/reports/route.ts`
- [AI classify](https://github.com/exobrienx/urbanreport/blob/main/app/api/ai/classify/route.ts): route handler · AI classification endpoint for incoming reports · `app/api/ai/classify/route.ts`
- [Auth API](https://github.com/exobrienx/urbanreport/blob/main/app/api/auth/[...nextauth]/route.ts): route handler · NextAuth entry point · `app/api/auth/[...nextauth]/route.ts`

### Domain Logic

Authentication, authorization, services, and shared helpers

- [Map hook](https://github.com/exobrienx/urbanreport/blob/main/app/lib/hooks/useCityMap.ts): react hook · Client map state and interaction orchestration · `app/lib/hooks/useCityMap.ts`
- [Route guard](https://github.com/exobrienx/urbanreport/blob/main/middleware.ts): edge middleware · Enforces access control on protected routes · `middleware.ts`
- [Auth config](https://github.com/exobrienx/urbanreport/blob/main/app/lib/auth.ts): auth config · NextAuth configuration and session setup · `app/lib/auth.ts`
- [Permissions](https://github.com/exobrienx/urbanreport/blob/main/app/lib/permissions.ts): rbac · Role and route authorization rules · `app/lib/permissions.ts`
- [Reporte service](https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/ReporteService.ts): domain service · Report submission and orchestration logic · `app/lib/services/ReporteService.ts`
- [Incidencia service](https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/IncidenciaService.ts): domain service · Incident record normalization and handling · `app/lib/services/IncidenciaService.ts`
- [Priority service](https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/PriorityService.ts): domain service · Priority and urgency derivation · `app/lib/services/PriorityService.ts`
- [Geo distance](https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/HaversineService.ts): geo service · Distance calculation for location-based routing · `app/lib/services/HaversineService.ts`
- [AI service](https://github.com/exobrienx/urbanreport/blob/main/app/lib/services/AIService.ts): ai service · Classification and inference logic · `app/lib/services/AIService.ts`
- [Responses](https://github.com/exobrienx/urbanreport/blob/main/app/lib/factories/ResponseFactory.ts): api helper · Standardized API response creation · `app/lib/factories/ResponseFactory.ts`
- [Upload photo](https://github.com/exobrienx/urbanreport/blob/main/app/lib/uploadPhoto.ts): upload helper · Photo upload workflow for citizen reports · `app/lib/uploadPhoto.ts`
- [Auth types](https://github.com/exobrienx/urbanreport/blob/main/types/next-auth.d.ts): type augment · Session and role type extensions · `types/next-auth.d.ts`

### Persistence

Prisma schema plus database and object storage boundaries

- [Prisma client](https://github.com/exobrienx/urbanreport/blob/main/app/lib/prisma.ts): db client · Database access entry point · `app/lib/prisma.ts`
- [Photo storage](https://github.com/exobrienx/urbanreport/blob/main/app/lib/r2.ts): object storage · R2-compatible storage boundary for uploads · `app/lib/r2.ts`
- [Schema](https://github.com/exobrienx/urbanreport/blob/main/prisma/schema.prisma): prisma schema · Data model and migrations source of truth · `prisma/schema.prisma`

### Operations

Repo-managed scripts for provisioning privileged users

- [Create admin](https://github.com/exobrienx/urbanreport/blob/main/scripts/create-admin.ts): provision script · Privileged admin user provisioning · `scripts/create-admin.ts`
- [Create tech](https://github.com/exobrienx/urbanreport/blob/main/scripts/create-tecnico.ts): provision script · Privileged technician user provisioning · `scripts/create-tecnico.ts`

## Connections

- 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
