# nextcloud/maps architecture

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

- Interactive diagram: https://gitdiagram.com/nextcloud/maps
- Repository: https://github.com/nextcloud/maps

## Overview

Nextcloud Maps presents interactive personal and shared maps with favorites, photos, contacts, devices, tracks, custom-map files, and route planning. The principal workflow is a user opening the map, whose Vue application loads options and map-domain data through network requests to Nextcloud controllers; the map renders selectable layers and supports edits, imports, exports, and sharing. Backend services handle domain operations and persist data in Nextcloud files or the favorites database. README capabilities guide inclusion; some wiring and implementations are unsampled, so links below are limited to documented routes or source-supported calls.

Main entry points: [`appinfo/routes.php`](https://github.com/nextcloud/maps/blob/master/appinfo/routes.php) (HTTP routes), [`src/network.js`](https://github.com/nextcloud/maps/blob/master/src/network.js) (API client), [`src/views/App.vue`](https://github.com/nextcloud/maps/blob/master/src/views/App.vue) (Maps application), [`lib/Controller/FavoritesController.php`](https://github.com/nextcloud/maps/blob/master/lib/Controller/FavoritesController.php) (Favorites endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Map experience"]
  node_app["Maps application<br/>[App.vue]"]
  node_mapview["Map rendering<br/>[Map.vue]"]
  node_options["Map preferences"]
  node_routing["Route planning<br/>[RoutingMachine.vue]"]
  node_network["API client<br/>[network.js]"]
end

subgraph group_api["Nextcloud endpoints"]
  node_routes["HTTP routes<br/>[routes.php]"]
  node_favorites_api["Favorites endpoints"]
  node_contacts["Contacts endpoints"]
  node_photos["Photo endpoints"]
  node_tracks["Track endpoints"]
  node_devices["Device endpoints"]
  node_mymaps["Custom maps"]
end

subgraph group_domain["Map domains"]
  node_favorites_service["Favorites operations"]
  node_photo_service["Photo indexing"]
  node_track_service["Track operations<br/>[TracksService.php]"]
  node_device_service["Device operations<br/>[DevicesService.php]"]
  node_geo_service["Geophoto operations"]
end

subgraph group_storage["Persistence"]
  node_favorite_db[("Favorite records")]
  node_geo_db[("Photo records<br/>[GeophotoMapper.php]")]
  node_nextcloud_files[("Nextcloud files")]
end

node_user(("Nextcloud user"))
node_routing_services(("Routing providers"))

node_user -->|"opens"| node_app
node_app -->|"renders"| node_mapview
node_app -->|"requests data"| node_network
node_options -->|"loads preferences"| node_network
node_routing -->|"exports route"| node_network
node_network -->|"HTTP requests"| node_routes
node_routes -->|"dispatches"| node_favorites_api
node_routes -->|"dispatches"| node_contacts
node_routes -->|"dispatches"| node_photos
node_routes -->|"dispatches"| node_tracks
node_routes -->|"dispatches"| node_devices
node_routes -->|"dispatches"| node_mymaps
node_favorites_api -->|"calls"| node_favorites_service
node_favorites_service -->|"reads/writes"| node_favorite_db
node_favorites_api -->|"reads/writes"| node_nextcloud_files
node_contacts -->|"reads/writes"| node_nextcloud_files
node_photos -->|"calls"| node_photo_service
node_photo_service -->|"uses"| node_geo_service
node_geo_service -->|"reads/writes"| node_geo_db
node_tracks -->|"calls"| node_track_service
node_track_service -->|"reads/writes"| node_nextcloud_files
node_devices -->|"calls"| node_device_service
node_device_service -->|"imports/exports"| node_nextcloud_files
node_mymaps -->|"manages maps"| node_nextcloud_files
node_routing -.->|"requests routes"| node_routing_services

click node_app "https://github.com/nextcloud/maps/blob/master/src/views/App.vue"
click node_mapview "https://github.com/nextcloud/maps/blob/master/src/components/Map.vue"
click node_options "https://github.com/nextcloud/maps/blob/master/src/optionsController.js"
click node_routing "https://github.com/nextcloud/maps/blob/master/src/components/map/routing/RoutingMachine.vue"
click node_network "https://github.com/nextcloud/maps/blob/master/src/network.js"
click node_routes "https://github.com/nextcloud/maps/blob/master/appinfo/routes.php"
click node_favorites_api "https://github.com/nextcloud/maps/blob/master/lib/Controller/FavoritesController.php"
click node_contacts "https://github.com/nextcloud/maps/blob/master/lib/Controller/ContactsController.php"
click node_photos "https://github.com/nextcloud/maps/blob/master/lib/Controller/PhotosController.php"
click node_tracks "https://github.com/nextcloud/maps/blob/master/lib/Controller/TracksController.php"
click node_devices "https://github.com/nextcloud/maps/blob/master/lib/Controller/DevicesController.php"
click node_mymaps "https://github.com/nextcloud/maps/blob/master/lib/Controller/MyMapsController.php"
click node_favorites_service "https://github.com/nextcloud/maps/blob/master/lib/Service/FavoritesService.php"
click node_photo_service "https://github.com/nextcloud/maps/blob/master/lib/Service/PhotofilesService.php"
click node_track_service "https://github.com/nextcloud/maps/blob/master/lib/Service/TracksService.php"
click node_device_service "https://github.com/nextcloud/maps/blob/master/lib/Service/DevicesService.php"
click node_geo_service "https://github.com/nextcloud/maps/blob/master/lib/Service/GeophotoService.php"
click node_favorite_db "https://github.com/nextcloud/maps/blob/master/lib/DB/FavoriteShareMapper.php"
click node_geo_db "https://github.com/nextcloud/maps/blob/master/lib/DB/GeophotoMapper.php"

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,node_mapview,node_options,node_routing,node_network,node_user toneBlue
class node_routes,node_favorites_api,node_contacts,node_photos,node_tracks,node_devices,node_mymaps toneAmber
class node_favorites_service,node_photo_service,node_track_service,node_device_service,node_geo_service toneMint
class node_favorite_db,node_geo_db,node_nextcloud_files toneRose
class node_routing_services toneIndigo
```

## Components

### Map experience

- [Maps application](https://github.com/nextcloud/maps/blob/master/src/views/App.vue): `src/views/App.vue`
- [Map rendering](https://github.com/nextcloud/maps/blob/master/src/components/Map.vue): `src/components/Map.vue`
- [Map preferences](https://github.com/nextcloud/maps/blob/master/src/optionsController.js): `src/optionsController.js`
- [Route planning](https://github.com/nextcloud/maps/blob/master/src/components/map/routing/RoutingMachine.vue): `src/components/map/routing/RoutingMachine.vue`
- [API client](https://github.com/nextcloud/maps/blob/master/src/network.js): `src/network.js`

### Nextcloud endpoints

- [HTTP routes](https://github.com/nextcloud/maps/blob/master/appinfo/routes.php): `appinfo/routes.php`
- [Favorites endpoints](https://github.com/nextcloud/maps/blob/master/lib/Controller/FavoritesController.php): `lib/Controller/FavoritesController.php`
- [Contacts endpoints](https://github.com/nextcloud/maps/blob/master/lib/Controller/ContactsController.php): `lib/Controller/ContactsController.php`
- [Photo endpoints](https://github.com/nextcloud/maps/blob/master/lib/Controller/PhotosController.php): `lib/Controller/PhotosController.php`
- [Track endpoints](https://github.com/nextcloud/maps/blob/master/lib/Controller/TracksController.php): `lib/Controller/TracksController.php`
- [Device endpoints](https://github.com/nextcloud/maps/blob/master/lib/Controller/DevicesController.php): `lib/Controller/DevicesController.php`
- [Custom maps](https://github.com/nextcloud/maps/blob/master/lib/Controller/MyMapsController.php): `lib/Controller/MyMapsController.php`

### Map domains

- [Favorites operations](https://github.com/nextcloud/maps/blob/master/lib/Service/FavoritesService.php): `lib/Service/FavoritesService.php`
- [Photo indexing](https://github.com/nextcloud/maps/blob/master/lib/Service/PhotofilesService.php): `lib/Service/PhotofilesService.php`
- [Track operations](https://github.com/nextcloud/maps/blob/master/lib/Service/TracksService.php): `lib/Service/TracksService.php`
- [Device operations](https://github.com/nextcloud/maps/blob/master/lib/Service/DevicesService.php): `lib/Service/DevicesService.php`
- [Geophoto operations](https://github.com/nextcloud/maps/blob/master/lib/Service/GeophotoService.php): `lib/Service/GeophotoService.php`

### Persistence

- [Favorite records](https://github.com/nextcloud/maps/blob/master/lib/DB/FavoriteShareMapper.php): `lib/DB/FavoriteShareMapper.php`
- [Photo records](https://github.com/nextcloud/maps/blob/master/lib/DB/GeophotoMapper.php): `lib/DB/GeophotoMapper.php`
- **Nextcloud files**

### Other components

- **Nextcloud user**
- **Routing providers**

## Connections

- Nextcloud user → Maps application: opens
- Maps application → Map rendering: renders
- Maps application → API client: requests data
- Map preferences → API client: loads preferences
- Route planning → API client: exports route
- API client → HTTP routes: HTTP requests
- HTTP routes → Favorites endpoints: dispatches
- HTTP routes → Contacts endpoints: dispatches
- HTTP routes → Photo endpoints: dispatches
- HTTP routes → Track endpoints: dispatches
- HTTP routes → Device endpoints: dispatches
- HTTP routes → Custom maps: dispatches
- Favorites endpoints → Favorites operations: calls
- Favorites operations → Favorite records: reads/writes
- Favorites endpoints → Nextcloud files: reads/writes
- Contacts endpoints → Nextcloud files: reads/writes
- Photo endpoints → Photo indexing: calls
- Photo indexing → Geophoto operations: uses
- Geophoto operations → Photo records: reads/writes
- Track endpoints → Track operations: calls
- Track operations → Nextcloud files: reads/writes
- Device endpoints → Device operations: calls
- Device operations → Nextcloud files: imports/exports
- Custom maps → Nextcloud files: manages maps
- Route planning → Routing providers: requests routes