# passaaqui/passaaqui-backend architecture

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

- Interactive diagram: https://gitdiagram.com/passaaqui/passaaqui-backend
- Repository: https://github.com/passaaqui/passaaqui-backend

## Overview

Passa Aqui is a REST backend connecting tourists with points of interest and local businesses. Its main journey spans account registration, discovery and navigation, POI check-ins and rewards, and local-product checkout with PIX payment. The graph also preserves documented supporting capabilities such as ratings, achievements, dashboards, and image storage. Sampled services and the source index support several internal links; unsampled controller wiring and other subsystem internals are not asserted.

Main entry points: [`src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java`](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java) (Business profiles), [`src/main/java/com/passaaqui/backend/infra/integration/storage/StorageService.java`](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/storage/StorageService.java) (Image storage), [`src/main/java/com/passaaqui/backend/modules/poi`](https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/poi) (POI management), [`src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java`](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java) (Route sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and profiles"]
  node_tourist["Tourist profiles"]
  node_shopkeeper["Business profiles"]
  node_auth["Authentication<br/>[AuthService.java]"]
end

subgraph group_discovery["Places and discovery"]
  node_poi["POI management"]
  node_city["Cities"]
  node_category["Categories"]
  node_directions["Directions"]
  node_routes["Route sessions<br/>[RouteService.java]"]
end

subgraph group_commerce["Local commerce"]
  node_products["Product catalog"]
  node_orders["Orders and checkout<br/>[OrderService.java]"]
  node_ratings["Ratings"]
  node_dashboard["Business dashboard"]
end

subgraph group_engagement["Tourism engagement"]
  node_checkin["POI check-ins"]
  node_achievements["Achievements"]
  node_websocket["Live updates"]
end

subgraph group_platform["Infrastructure"]
  node_payment["AbacatePay<br/>[AbacateClient.java]"]
  node_cache[("Redis cache<br/>[CacheService.java]")]
  node_storage["Image storage"]
  node_minio[("MinIO")]
  node_database[("PostgreSQL")]
end

node_traveler(("Tourist or business user"))
node_api(("REST API"))
node_routeprovider["OpenRouteService"]

node_traveler -->|"uses"| node_api
node_api -.->|"authenticates"| node_auth
node_api -.->|"discovers places"| node_poi
node_api -.->|"browses products"| node_products
node_auth -->|"creates profiles"| node_tourist
node_auth -->|"creates profiles"| node_shopkeeper
node_shopkeeper -->|"looks up category"| node_category
node_shopkeeper -->|"looks up city"| node_city
node_shopkeeper -->|"creates business POI"| node_poi
node_shopkeeper -->|"uploads images"| node_storage
node_tourist -->|"uploads images"| node_storage
node_tourist -->|"reads travel history"| node_poi
node_routes -->|"stores sessions"| node_cache
node_routes -->|"pushes updates"| node_websocket
node_routes -->|"loads destination"| node_poi
node_routes -->|"triggers arrival check-in"| node_checkin
node_products -->|"reads categories"| node_category
node_products -->|"reads POI"| node_poi
node_products -->|"uses image storage"| node_storage
node_orders -->|"requests payment"| node_payment
node_achievements -->|"uses image storage"| node_storage
node_storage -.->|"stores files"| node_minio
node_directions -.->|"calculates routes"| node_routeprovider

click node_tourist "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/tourist/service/TouristService.java"
click node_shopkeeper "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java"
click node_auth "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/auth/service/AuthService.java"
click node_poi "https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/poi"
click node_city "https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/city"
click node_category "https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/category"
click node_directions "https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/direction"
click node_routes "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java"
click node_products "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/product/service/ProductService.java"
click node_orders "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/order/service/OrderService.java"
click node_payment "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/abacatepay/AbacateClient.java"
click node_ratings "https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/product"
click node_dashboard "https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/dashboard"
click node_checkin "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/poi/service/PoiCheckinService.java"
click node_achievements "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/achievement/service/AchievementService.java"
click node_websocket "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/websocket/service/WebSocketService.java"
click node_cache "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/cache/CacheService.java"
click node_storage "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/storage/StorageService.java"
click node_minio "https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/storage/MinioStorageServiceImpl.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_tourist,node_shopkeeper,node_auth,node_traveler toneBlue
class node_poi,node_city,node_category,node_directions,node_routes toneAmber
class node_products,node_orders,node_ratings,node_dashboard,node_api,node_routeprovider toneMint
class node_checkin,node_achievements,node_websocket toneRose
class node_payment,node_cache,node_storage,node_minio,node_database toneIndigo
```

## Components

### Identity and profiles

- [Tourist profiles](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/tourist/service/TouristService.java): `src/main/java/com/passaaqui/backend/modules/tourist/service/TouristService.java`
- [Business profiles](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java): `src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java`
- [Authentication](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/auth/service/AuthService.java): `src/main/java/com/passaaqui/backend/modules/auth/service/AuthService.java`

### Places and discovery

- [POI management](https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/poi): `src/main/java/com/passaaqui/backend/modules/poi`
- [Cities](https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/city): `src/main/java/com/passaaqui/backend/modules/city`
- [Categories](https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/category): `src/main/java/com/passaaqui/backend/modules/category`
- [Directions](https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/direction): `src/main/java/com/passaaqui/backend/modules/direction`
- [Route sessions](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java): `src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java`

### Local commerce

- [Product catalog](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/product/service/ProductService.java): `src/main/java/com/passaaqui/backend/modules/product/service/ProductService.java`
- [Orders and checkout](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/order/service/OrderService.java): `src/main/java/com/passaaqui/backend/modules/order/service/OrderService.java`
- [Ratings](https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/product): `src/main/java/com/passaaqui/backend/modules/product`
- [Business dashboard](https://github.com/passaaqui/passaaqui-backend/tree/main/src/main/java/com/passaaqui/backend/modules/dashboard): `src/main/java/com/passaaqui/backend/modules/dashboard`

### Tourism engagement

- [POI check-ins](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/poi/service/PoiCheckinService.java): `src/main/java/com/passaaqui/backend/modules/poi/service/PoiCheckinService.java`
- [Achievements](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/achievement/service/AchievementService.java): `src/main/java/com/passaaqui/backend/modules/achievement/service/AchievementService.java`
- [Live updates](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/modules/websocket/service/WebSocketService.java): `src/main/java/com/passaaqui/backend/modules/websocket/service/WebSocketService.java`

### Infrastructure

- [AbacatePay](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/abacatepay/AbacateClient.java): `src/main/java/com/passaaqui/backend/infra/integration/abacatepay/AbacateClient.java`
- [Redis cache](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/cache/CacheService.java): `src/main/java/com/passaaqui/backend/infra/integration/cache/CacheService.java`
- [Image storage](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/storage/StorageService.java): `src/main/java/com/passaaqui/backend/infra/integration/storage/StorageService.java`
- [MinIO](https://github.com/passaaqui/passaaqui-backend/blob/main/src/main/java/com/passaaqui/backend/infra/integration/storage/MinioStorageServiceImpl.java): `src/main/java/com/passaaqui/backend/infra/integration/storage/MinioStorageServiceImpl.java`
- **PostgreSQL**

### Other components

- **Tourist or business user**
- **REST API**
- **OpenRouteService**

## Connections

- Tourist or business user → REST API: uses (evidence: `README.md`)
- REST API → Authentication: authenticates
- REST API → POI management: discovers places
- REST API → Product catalog: browses products
- Authentication → Tourist profiles: creates profiles (evidence: `src/main/java/com/passaaqui/backend/modules/auth/service/AuthService.java`)
- Authentication → Business profiles: creates profiles (evidence: `src/main/java/com/passaaqui/backend/modules/auth/service/AuthService.java`)
- Business profiles → Categories: looks up category (evidence: `src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java`)
- Business profiles → Cities: looks up city (evidence: `src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java`)
- Business profiles → POI management: creates business POI (evidence: `src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java`)
- Business profiles → Image storage: uploads images (evidence: `src/main/java/com/passaaqui/backend/modules/shopkeeper/service/ShopkeeperService.java`)
- Tourist profiles → Image storage: uploads images (evidence: `src/main/java/com/passaaqui/backend/modules/tourist/service/TouristService.java`)
- Tourist profiles → POI management: reads travel history (evidence: `src/main/java/com/passaaqui/backend/modules/tourist/service/TouristService.java`)
- Route sessions → Redis cache: stores sessions (evidence: `src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java`)
- Route sessions → Live updates: pushes updates (evidence: `src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java`)
- Route sessions → POI management: loads destination (evidence: `src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java`)
- Route sessions → POI check-ins: triggers arrival check-in (evidence: `src/main/java/com/passaaqui/backend/modules/route/service/RouteService.java`)
- Product catalog → Categories: reads categories (evidence: `src/main/java/com/passaaqui/backend/modules/product/service/ProductService.java`)
- Product catalog → POI management: reads POI (evidence: `src/main/java/com/passaaqui/backend/modules/product/service/ProductService.java`)
- Product catalog → Image storage: uses image storage (evidence: `src/main/java/com/passaaqui/backend/modules/product/service/ProductService.java`)
- Orders and checkout → AbacatePay: requests payment (evidence: `src/main/java/com/passaaqui/backend/modules/order/service/OrderService.java`)
- Achievements → Image storage: uses image storage (evidence: `src/main/java/com/passaaqui/backend/modules/achievement/service/AchievementService.java`)
- Image storage → MinIO: stores files (evidence: `README.md`)
- Directions → OpenRouteService: calculates routes (evidence: `README.md`)
