# yoavamar132/global-city-map architecture

> Architecture diagram of the GitHub repository yoavamar132/global-city-map, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yoavamar132/global-city-map
- Repository: https://github.com/yoavamar132/global-city-map

## Overview

This is a JavaFX client/server application for browsing and managing city maps, with user authentication, role-specific workflows, purchases and subscriptions, map viewing, and content administration. The main user path runs from connection setup through login or guest browsing, then into catalogs, purchase or owned-map workflows, and map display. Requests and responses use shared serializable message types; server services mediate database repositories. Several server routing and UI subsystems are present in the tree but unsampled, so their links are marked unverified rather than inferred as confirmed calls.

Main entry points: [`client/src/main/java/gcm/client/network/GcmClient.java`](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/network/GcmClient.java) (Client transport), [`server/src/main/java/gcm/server/controllers/RequestHandler.java`](https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/controllers/RequestHandler.java) (Server request handler), [`client/src/main/java/gcm/client/controllers/menu`](https://github.com/yoavamar132/global-city-map/tree/main/client/src/main/java/gcm/client/controllers/menu) (Role menus), [`client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java`](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java) (Purchase catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_clientapp["Client application<br/>[ClientApp.java]"]
  node_connection["Connection setup"]
  node_navigator["Scene navigation"]
  node_login["Login and registration"]
  node_menus["Role menus"]
end

subgraph group_maps["Map workflows"]
  node_guestcatalog["Guest city catalog"]
  node_guestmaps["Guest city maps"]
  node_purchasecatalog["Purchase catalog"]
  node_purchasescreen["Map purchase flow"]
  node_purchasesession["Purchase session"]
  node_mymaps["Owned maps"]
  node_subscriptions["Subscriptions"]
  node_mapviewer["Map viewer"]
  node_baselayer["Map base layer"]
  node_overlays["Map overlays"]
  node_contentadmin["Content administration"]
end

subgraph group_protocol["Shared protocol"]
  node_gcmclient["Client transport<br/>[GcmClient.java]"]
  node_request["Request types<br/>[GcmRequest.java]"]
  node_response["Response envelope<br/>[GcmResponse.java]"]
  node_domain["Map and user data<br/>[MapSheet.java]"]
end

subgraph group_server["Server services"]
  node_server["Server request handler"]
  node_auth["Authentication service<br/>[AuthService.java]"]
  node_catalog["Catalog service"]
  node_city["City service<br/>[CityService.java]"]
  node_mapservice["Map service<br/>[MapService.java]"]
end

subgraph group_storage["Data access"]
  node_repositories[("Database repositories")]
  node_dbmanager[("Database manager<br/>[DbManager.java]")]
end

node_visitor(("Visitor or user"))

node_visitor -.->|"starts client"| node_connection
node_connection -->|"sets client"| node_clientapp
node_clientapp -->|"starts navigation"| node_navigator
node_clientapp -->|"shows welcome"| node_login
node_visitor -.->|"submits credentials"| node_login
node_login -->|"sends login"| node_gcmclient
node_login -->|"routes by role"| node_navigator
node_navigator -.->|"loads menu"| node_menus
node_menus -->|"opens catalog"| node_guestcatalog
node_guestcatalog -->|"requests cities"| node_gcmclient
node_guestcatalog -->|"passes map list"| node_guestmaps
node_menus -->|"opens purchase catalog"| node_purchasecatalog
node_purchasecatalog -->|"loads cities"| node_gcmclient
node_purchasecatalog -->|"sets selection"| node_purchasesession
node_purchasecatalog -->|"opens purchase"| node_purchasescreen
node_menus -->|"opens owned maps"| node_mymaps
node_mymaps -->|"requests maps"| node_gcmclient
node_mymaps -->|"passes selected map"| node_mapviewer
node_mymaps -->|"opens subscriptions"| node_subscriptions
node_mapviewer -->|"uses base layer"| node_baselayer
node_mapviewer -->|"uses overlays"| node_overlays
node_menus -->|"opens admin options"| node_contentadmin
node_contentadmin -.->|"requests admin actions"| node_server
node_gcmclient -->|"transmits request"| node_request
node_gcmclient -->|"receives response"| node_response
node_gcmclient -.->|"sends over connection"| node_server
node_server -.->|"dispatches auth"| node_auth
node_server -.->|"dispatches catalog"| node_catalog
node_server -.->|"dispatches city requests"| node_city
node_server -.->|"dispatches map requests"| node_mapservice
node_auth -->|"uses user repository"| node_repositories
node_catalog -->|"uses catalog repository"| node_repositories
node_city -->|"uses city repository"| node_repositories
node_mapservice -->|"uses map repositories"| node_repositories

click node_clientapp "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/utill/ClientApp.java"
click node_connection "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/ui/ClientConnectionController.java"
click node_navigator "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/utill/SceneNavigator.java"
click node_login "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/LoginController.java"
click node_menus "https://github.com/yoavamar132/global-city-map/tree/main/client/src/main/java/gcm/client/controllers/menu"
click node_guestcatalog "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/catalogPublic/GuestCatalogController.java"
click node_guestmaps "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/catalogPublic/GuestCityMapsController.java"
click node_purchasecatalog "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java"
click node_purchasescreen "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/BuyMapScreenController.java"
click node_purchasesession "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/PurchaseSession.java"
click node_mymaps "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/MyMapsController.java"
click node_subscriptions "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/UserSubscriptionsController.java"
click node_mapviewer "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/map/MapViewerController.java"
click node_baselayer "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/map/MapBaseLayerController.java"
click node_overlays "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/map/MapOverlayLayerController.java"
click node_contentadmin "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/menu/ContentWorkerMenuController.java"
click node_gcmclient "https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/network/GcmClient.java"
click node_request "https://github.com/yoavamar132/global-city-map/blob/main/common/src/main/java/common/messages/GcmRequest.java"
click node_response "https://github.com/yoavamar132/global-city-map/blob/main/common/src/main/java/common/messages/GcmResponse.java"
click node_domain "https://github.com/yoavamar132/global-city-map/blob/main/common/src/main/java/common/model/MapSheet.java"
click node_server "https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/controllers/RequestHandler.java"
click node_auth "https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/AuthService.java"
click node_catalog "https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/CatalogService.java"
click node_city "https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/CityService.java"
click node_mapservice "https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/MapService.java"
click node_repositories "https://github.com/yoavamar132/global-city-map/tree/main/server/src/main/java/gcm/server/data"
click node_dbmanager "https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/data/DbManager.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_clientapp,node_connection,node_navigator,node_login,node_menus,node_visitor toneBlue
class node_guestcatalog,node_guestmaps,node_purchasecatalog,node_purchasescreen,node_purchasesession,node_mymaps,node_subscriptions,node_mapviewer,node_baselayer,node_overlays,node_contentadmin toneAmber
class node_gcmclient,node_request,node_response,node_domain toneMint
class node_server,node_auth,node_catalog,node_city,node_mapservice toneRose
class node_repositories,node_dbmanager toneIndigo
```

## Components

### Client experience

- [Client application](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/utill/ClientApp.java): `client/src/main/java/gcm/client/utill/ClientApp.java`
- [Connection setup](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/ui/ClientConnectionController.java): `client/src/main/java/gcm/client/controllers/ui/ClientConnectionController.java`
- [Scene navigation](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/utill/SceneNavigator.java): `client/src/main/java/gcm/client/utill/SceneNavigator.java`
- [Login and registration](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/LoginController.java): `client/src/main/java/gcm/client/controllers/LoginController.java`
- [Role menus](https://github.com/yoavamar132/global-city-map/tree/main/client/src/main/java/gcm/client/controllers/menu): `client/src/main/java/gcm/client/controllers/menu`

### Map workflows

- [Guest city catalog](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/catalogPublic/GuestCatalogController.java): `client/src/main/java/gcm/client/controllers/catalogPublic/GuestCatalogController.java`
- [Guest city maps](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/catalogPublic/GuestCityMapsController.java): `client/src/main/java/gcm/client/controllers/catalogPublic/GuestCityMapsController.java`
- [Purchase catalog](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java): `client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java`
- [Map purchase flow](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/BuyMapScreenController.java): `client/src/main/java/gcm/client/controllers/user_util/BuyMapScreenController.java`
- [Purchase session](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/PurchaseSession.java): `client/src/main/java/gcm/client/controllers/user_util/PurchaseSession.java`
- [Owned maps](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/MyMapsController.java): `client/src/main/java/gcm/client/controllers/user_util/MyMapsController.java`
- [Subscriptions](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/user_util/UserSubscriptionsController.java): `client/src/main/java/gcm/client/controllers/user_util/UserSubscriptionsController.java`
- [Map viewer](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/map/MapViewerController.java): `client/src/main/java/gcm/client/controllers/map/MapViewerController.java`
- [Map base layer](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/map/MapBaseLayerController.java): `client/src/main/java/gcm/client/controllers/map/MapBaseLayerController.java`
- [Map overlays](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/map/MapOverlayLayerController.java): `client/src/main/java/gcm/client/controllers/map/MapOverlayLayerController.java`
- [Content administration](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/controllers/menu/ContentWorkerMenuController.java): `client/src/main/java/gcm/client/controllers/menu/ContentWorkerMenuController.java`

### Shared protocol

- [Client transport](https://github.com/yoavamar132/global-city-map/blob/main/client/src/main/java/gcm/client/network/GcmClient.java): `client/src/main/java/gcm/client/network/GcmClient.java`
- [Request types](https://github.com/yoavamar132/global-city-map/blob/main/common/src/main/java/common/messages/GcmRequest.java): `common/src/main/java/common/messages/GcmRequest.java`
- [Response envelope](https://github.com/yoavamar132/global-city-map/blob/main/common/src/main/java/common/messages/GcmResponse.java): `common/src/main/java/common/messages/GcmResponse.java`
- [Map and user data](https://github.com/yoavamar132/global-city-map/blob/main/common/src/main/java/common/model/MapSheet.java): `common/src/main/java/common/model/MapSheet.java`

### Server services

- [Server request handler](https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/controllers/RequestHandler.java): `server/src/main/java/gcm/server/controllers/RequestHandler.java`
- [Authentication service](https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/AuthService.java): `server/src/main/java/gcm/server/service/AuthService.java`
- [Catalog service](https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/CatalogService.java): `server/src/main/java/gcm/server/service/CatalogService.java`
- [City service](https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/CityService.java): `server/src/main/java/gcm/server/service/CityService.java`
- [Map service](https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/service/MapService.java): `server/src/main/java/gcm/server/service/MapService.java`

### Data access

- [Database repositories](https://github.com/yoavamar132/global-city-map/tree/main/server/src/main/java/gcm/server/data): `server/src/main/java/gcm/server/data`
- [Database manager](https://github.com/yoavamar132/global-city-map/blob/main/server/src/main/java/gcm/server/data/DbManager.java): `server/src/main/java/gcm/server/data/DbManager.java`

### Other components

- **Visitor or user**

## Connections

- Visitor or user → Connection setup: starts client
- Connection setup → Client application: sets client (evidence: `client/src/main/java/gcm/client/controllers/ui/ClientConnectionController.java`)
- Client application → Scene navigation: starts navigation (evidence: `client/src/main/java/gcm/client/utill/ClientApp.java`)
- Client application → Login and registration: shows welcome (evidence: `client/src/main/java/gcm/client/utill/ClientApp.java`)
- Visitor or user → Login and registration: submits credentials
- Login and registration → Client transport: sends login (evidence: `client/src/main/java/gcm/client/controllers/LoginController.java`)
- Login and registration → Scene navigation: routes by role (evidence: `client/src/main/java/gcm/client/controllers/LoginController.java`)
- Scene navigation → Role menus: loads menu (evidence: `client/src/main/java/gcm/client/utill/SceneNavigator.java`)
- Role menus → Guest city catalog: opens catalog (evidence: `client/src/main/java/gcm/client/controllers/menu/UserMenuController.java`)
- Guest city catalog → Client transport: requests cities (evidence: `client/src/main/java/gcm/client/controllers/catalogPublic/GuestCatalogController.java`)
- Guest city catalog → Guest city maps: passes map list (evidence: `client/src/main/java/gcm/client/controllers/catalogPublic/GuestCatalogController.java`)
- Role menus → Purchase catalog: opens purchase catalog (evidence: `client/src/main/java/gcm/client/controllers/menu/UserMenuController.java`)
- Purchase catalog → Client transport: loads cities (evidence: `client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java`)
- Purchase catalog → Purchase session: sets selection (evidence: `client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java`)
- Purchase catalog → Map purchase flow: opens purchase (evidence: `client/src/main/java/gcm/client/controllers/catalog/BuyMapCatalogController.java`)
- Role menus → Owned maps: opens owned maps (evidence: `client/src/main/java/gcm/client/controllers/menu/UserMenuController.java`)
- Owned maps → Client transport: requests maps (evidence: `client/src/main/java/gcm/client/controllers/user_util/MyMapsController.java`)
- Owned maps → Map viewer: passes selected map (evidence: `client/src/main/java/gcm/client/controllers/user_util/MyMapsController.java`)
- Owned maps → Subscriptions: opens subscriptions (evidence: `client/src/main/java/gcm/client/controllers/user_util/MyMapsController.java`)
- Map viewer → Map base layer: uses base layer (evidence: `client/src/main/java/gcm/client/controllers/map/MapViewerController.java`)
- Map viewer → Map overlays: uses overlays (evidence: `client/src/main/java/gcm/client/controllers/map/MapViewerController.java`)
- Role menus → Content administration: opens admin options (evidence: `client/src/main/java/gcm/client/controllers/menu/ContentWorkerMenuController.java`)
- Content administration → Server request handler: requests admin actions
- Client transport → Request types: transmits request (evidence: `client/src/main/java/gcm/client/network/GcmClient.java`)
- Client transport → Response envelope: receives response (evidence: `client/src/main/java/gcm/client/network/GcmClient.java`)
- Client transport → Server request handler: sends over connection
- Server request handler → Authentication service: dispatches auth (evidence: `server/src/main/java/gcm/server/controllers/RequestHandler.java`)
- Server request handler → Catalog service: dispatches catalog (evidence: `server/src/main/java/gcm/server/controllers/RequestHandler.java`)
- Server request handler → City service: dispatches city requests (evidence: `server/src/main/java/gcm/server/controllers/RequestHandler.java`)
- Server request handler → Map service: dispatches map requests (evidence: `server/src/main/java/gcm/server/controllers/RequestHandler.java`)
- Authentication service → Database repositories: uses user repository (evidence: `server/src/main/java/gcm/server/service/AuthService.java`)
- Catalog service → Database repositories: uses catalog repository (evidence: `server/src/main/java/gcm/server/service/CatalogService.java`)
- City service → Database repositories: uses city repository (evidence: `server/src/main/java/gcm/server/service/CityService.java`)
- Map service → Database repositories: uses map repositories (evidence: `server/src/main/java/gcm/server/service/MapService.java`)
