# javierub32/urbanpulse architecture

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

- Interactive diagram: https://gitdiagram.com/javierub32/urbanpulse
- Repository: https://github.com/javierub32/urbanpulse

## Overview

UrbanPulse is a city-incident reporting and management system: residents use an Expo app to authenticate, report incidents, and explore incident information served by a Spring Boot API backed by PostGIS. The backend also documents role-aware incident access, mapping, status history, and atmospheric enrichment. The graph preserves these distinct areas, but unsampled frontend screens and backend subsystems have limited verifiable call relationships; dashed edges indicate unverified integration rather than inspected control flow.

Main entry points: [`backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/IncidentController.java`](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/IncidentController.java) (Incident endpoints), [`backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentService.java`](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentService.java) (Incident service), [`backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericIncidentEnrichmentService.java`](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericIncidentEnrichmentService.java) (Weather enrichment), [`frontend/src/app/_layout.tsx`](https://github.com/javierub32/urbanpulse/blob/main/frontend/src/app/_layout.tsx) (Expo client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile app"]
  node_mobile["Expo client<br/>[_layout.tsx]"]
  node_report["Report incident<br/>[report.tsx]"]
  node_browse["Browse incidents<br/>[explore.tsx]"]
  node_detailui["Incident detail<br/>[index.tsx]"]
  node_authui["Sign in<br/>[AuthContext.tsx]"]
end

subgraph group_identity["Identity and access"]
  node_authctl["Auth endpoints"]
  node_authsvc["Auth service<br/>[AuthService.java]"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_principal["User principal"]
end

subgraph group_incidents["Incident management"]
  node_incidentctl["Incident endpoints"]
  node_incidentsvc["Incident service"]
  node_incidentdata["Incident records"]
end

subgraph group_context["Mapping and context"]
  node_mapservice["Map queries"]
  node_enrichment["Weather enrichment"]
  node_meteo["Open-Meteo client"]
  node_atmos["Context service"]
end

subgraph group_persistence["Persistence"]
  node_contextrepo["Context repository"]
  node_database[("PostGIS")]
end

node_citizen(("Resident"))
node_api["Spring API"]

node_citizen -->|"uses"| node_mobile
node_mobile -->|"calls API"| node_api
node_citizen -.->|"reports"| node_report
node_report -.->|"submits report"| node_incidentctl
node_browse -.->|"requests incidents"| node_incidentctl
node_detailui -.->|"loads detail"| node_incidentctl
node_authui -.->|"authenticates"| node_authctl
node_authctl -->|"delegates to"| node_authsvc
node_authsvc -->|"issues token"| node_jwt
node_jwt -->|"creates principal"| node_principal
node_incidentctl -->|"delegates to"| node_incidentsvc
node_incidentctl -->|"requests map data"| node_mapservice
node_incidentsvc -.->|"manages records"| node_incidentdata
node_incidentsvc -->|"enriches incident"| node_enrichment
node_enrichment -.->|"fetches readings"| node_meteo
node_enrichment -.->|"stores context"| node_atmos
node_atmos -->|"reads and writes"| node_contextrepo
node_contextrepo -.->|"persists context"| node_database
node_api -->|"uses PostGIS"| node_database

click node_mobile "https://github.com/javierub32/urbanpulse/blob/main/frontend/src/app/_layout.tsx"
click node_report "https://github.com/javierub32/urbanpulse/blob/main/frontend/src/app/(tabs)/report.tsx"
click node_browse "https://github.com/javierub32/urbanpulse/blob/main/frontend/src/app/(tabs)/explore.tsx"
click node_detailui "https://github.com/javierub32/urbanpulse/blob/main/frontend/src/pages/incident-detail/index.tsx"
click node_authui "https://github.com/javierub32/urbanpulse/blob/main/frontend/src/context/AuthContext.tsx"
click node_api "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/UrbanPulseApplication.java"
click node_authctl "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/AuthController.java"
click node_authsvc "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AuthService.java"
click node_jwt "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/security/JwtService.java"
click node_principal "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/security/UrbanPulsePrincipal.java"
click node_incidentctl "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/IncidentController.java"
click node_incidentsvc "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentService.java"
click node_incidentdata "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/entity/IncidentEntity.java"
click node_mapservice "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentMapService.java"
click node_enrichment "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericIncidentEnrichmentService.java"
click node_meteo "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/integration/openmeteo/OpenMeteoClient.java"
click node_atmos "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericContextService.java"
click node_contextrepo "https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/repository/UrbanContextRepository.java"

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_mobile,node_report,node_browse,node_detailui,node_authui toneBlue
class node_authctl,node_authsvc,node_jwt,node_principal toneAmber
class node_incidentctl,node_incidentsvc,node_incidentdata,node_api toneMint
class node_mapservice,node_enrichment,node_meteo,node_atmos toneRose
class node_contextrepo,node_database,node_citizen toneIndigo
```

## Components

### Mobile app

- [Expo client](https://github.com/javierub32/urbanpulse/blob/main/frontend/src/app/_layout.tsx): `frontend/src/app/_layout.tsx`
- [Report incident](https://github.com/javierub32/urbanpulse/blob/main/frontend/src/app/(tabs)/report.tsx): `frontend/src/app/(tabs)/report.tsx`
- [Browse incidents](https://github.com/javierub32/urbanpulse/blob/main/frontend/src/app/(tabs)/explore.tsx): `frontend/src/app/(tabs)/explore.tsx`
- [Incident detail](https://github.com/javierub32/urbanpulse/blob/main/frontend/src/pages/incident-detail/index.tsx): `frontend/src/pages/incident-detail/index.tsx`
- [Sign in](https://github.com/javierub32/urbanpulse/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`

### Identity and access

- [Auth endpoints](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/AuthController.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/AuthController.java`
- [Auth service](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AuthService.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AuthService.java`
- [JWT service](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/security/JwtService.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/security/JwtService.java`
- [User principal](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/security/UrbanPulsePrincipal.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/security/UrbanPulsePrincipal.java`

### Incident management

- [Incident endpoints](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/IncidentController.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/IncidentController.java`
- [Incident service](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentService.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentService.java`
- [Incident records](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/entity/IncidentEntity.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/entity/IncidentEntity.java`

### Mapping and context

- [Map queries](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentMapService.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentMapService.java`
- [Weather enrichment](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericIncidentEnrichmentService.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericIncidentEnrichmentService.java`
- [Open-Meteo client](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/integration/openmeteo/OpenMeteoClient.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/integration/openmeteo/OpenMeteoClient.java`
- [Context service](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericContextService.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericContextService.java`

### Persistence

- [Context repository](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/repository/UrbanContextRepository.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/repository/UrbanContextRepository.java`
- **PostGIS**

### Other components

- **Resident**
- [Spring API](https://github.com/javierub32/urbanpulse/blob/main/backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/UrbanPulseApplication.java): `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/UrbanPulseApplication.java`

## Connections

- Resident → Expo client: uses (evidence: `README.md`)
- Expo client → Spring API: calls API (evidence: `README.md`)
- Resident → Report incident: reports
- Report incident → Incident endpoints: submits report
- Browse incidents → Incident endpoints: requests incidents
- Incident detail → Incident endpoints: loads detail
- Sign in → Auth endpoints: authenticates
- Auth endpoints → Auth service: delegates to (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/AuthController.java`)
- Auth service → JWT service: issues token (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AuthService.java`)
- JWT service → User principal: creates principal (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/security/JwtService.java`)
- Incident endpoints → Incident service: delegates to (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/IncidentController.java`)
- Incident endpoints → Map queries: requests map data (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/controller/IncidentController.java`)
- Incident service → Incident records: manages records (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentService.java`)
- Incident service → Weather enrichment: enriches incident (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/IncidentService.java`)
- Weather enrichment → Open-Meteo client: fetches readings (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericIncidentEnrichmentService.java`)
- Weather enrichment → Context service: stores context (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericIncidentEnrichmentService.java`)
- Context service → Context repository: reads and writes (evidence: `backend/src/main/java/com/leftjoiner/urbanpulse/urbanpulse/service/AtmosphericContextService.java`)
- Context repository → PostGIS: persists context
- Spring API → PostGIS: uses PostGIS (evidence: `README.md`)
