# passaaqui/passaaqui-mobile architecture

> Architecture diagram of the GitHub repository passaaqui/passaaqui-mobile, 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-mobile
- Repository: https://github.com/passaaqui/passaaqui-mobile

## Overview

PassaAqui is a mobile platform for tourists to explore local points of interest, earn rewards, and redeem products, and for shopkeepers to manage stores and orders. The graph follows those two user journeys and includes shared authentication, API, and real-time infrastructure. Some feature branches are represented from the README and file tree; unsampled implementation details and their internal links are not asserted.

Main entry points: [`src/services/api/api.ts`](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/services/api/api.ts) (REST API client), [`src/features/home/screens/HomeScreen.tsx`](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/home/screens/HomeScreen.tsx) (Home and profile choice), [`src/features/user/auth/services/authService.ts`](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/auth/services/authService.ts) (Tourist authentication), [`src/features/shopkeeper/auth/services/shopkeeperAuthService.ts`](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/auth/services/shopkeeperAuthService.ts) (Shopkeeper authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["App and identity"]
  node_home["Home and profile choice<br/>[HomeScreen.tsx]"]
  node_tourist_auth["Tourist authentication<br/>[authService.ts]"]
  node_shop_auth["Shopkeeper authentication"]
end

subgraph group_tourist["Tourist exploration"]
  node_map["Map and navigation<br/>[MapScreen.tsx]"]
  node_route_session["Route session hooks<br/>[useRouteSession.ts]"]
  node_poi["POIs and check-ins<br/>[poiService.ts]"]
  node_route_service["Routing service<br/>[routeService.ts]"]
  node_route_socket["Route event listener<br/>[useRouteSocket.ts]"]
  node_achievements["Achievements"]
  node_travel_history["Travel history"]
end

subgraph group_commerce["Shopping and rewards"]
  node_shop_browse["Product discovery"]
  node_product_detail["Product details and ratings"]
  node_checkout["Checkout and Pix"]
  node_order_service["Tourist order service<br/>[orderService.ts]"]
  node_purchased["Purchased products"]
  node_review_screen["Product review"]
  node_review_media["Review media picker<br/>[useReviewMedia.ts]"]
  node_review_create["Review submission hook<br/>[useCreateReview.ts]"]
  node_review_service["Review service<br/>[reviewService.ts]"]
end

subgraph group_shopkeeper["Shopkeeper operations"]
  node_catalog["Product catalog<br/>[CatalogScreen.tsx]"]
  node_product_form["Product management"]
  node_category_modal["Category selection<br/>[CategoryModal.tsx]"]
  node_orders["Order management<br/>[OrdersScreen.tsx]"]
  node_dashboard["Shop metrics"]
  node_plans["Shop plans<br/>[PlansScreen.tsx]"]
end

subgraph group_platform["Shared platform"]
  node_api["REST API client<br/>[api.ts]"]
  node_tourist_store["Tourist auth state<br/>[authStore.ts]"]
  node_shop_store["Shopkeeper auth state"]
  node_stomp["WebSocket client<br/>[stompClient.ts]"]
end

node_tourist(("Tourist"))
node_shopkeeper_actor(("Shopkeeper"))

node_tourist -->|"opens app"| node_home
node_shopkeeper_actor -->|"opens app"| node_home
node_home -.->|"enters tourist flow"| node_tourist_auth
node_home -.->|"enters shop flow"| node_shop_auth
node_tourist -->|"explores map"| node_map
node_map -.->|"navigates"| node_route_session
node_route_session -->|"calls route operations"| node_route_service
node_route_service -->|"sends REST requests"| node_api
node_tourist -->|"checks in"| node_poi
node_map -.->|"receives route events"| node_route_socket
node_route_socket -->|"subscribes"| node_stomp
node_route_socket -->|"normalizes check-in"| node_route_service
node_tourist -->|"views achievements"| node_achievements
node_tourist -->|"views visited cities"| node_travel_history
node_tourist -->|"discovers products"| node_shop_browse
node_shop_browse -.->|"opens product"| node_product_detail
node_tourist -->|"redeems with Pix"| node_checkout
node_checkout -.->|"creates order"| node_order_service
node_tourist -.->|"reviews purchases"| node_purchased
node_purchased -.->|"opens review"| node_review_screen
node_review_screen -->|"selects media"| node_review_media
node_review_screen -->|"submits review"| node_review_create
node_review_create -->|"creates review"| node_review_service
node_review_service -->|"uploads review"| node_api
node_shopkeeper_actor -->|"manages catalog"| node_catalog
node_catalog -.->|"manages products"| node_product_form
node_product_form -->|"selects category"| node_category_modal
node_shopkeeper_actor -->|"manages orders"| node_orders
node_shopkeeper_actor -->|"views metrics"| node_dashboard
node_shopkeeper_actor -->|"configures plans"| node_plans
node_tourist_auth -->|"authenticates via"| node_api
node_shop_auth -->|"authenticates via"| node_api
node_tourist_auth -->|"updates auth state"| node_tourist_store
node_shop_auth -->|"updates auth state"| node_shop_store
node_api -->|"reads auth token"| node_tourist_store
node_api -->|"reads auth token"| node_shop_store

click node_home "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/home/screens/HomeScreen.tsx"
click node_tourist_auth "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/auth/services/authService.ts"
click node_shop_auth "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/auth/services/shopkeeperAuthService.ts"
click node_map "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/screens/MapScreen.tsx"
click node_route_session "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/hooks/useRouteSession.ts"
click node_poi "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/poi/services/poiService.ts"
click node_route_service "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/services/routeService.ts"
click node_route_socket "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/hooks/useRouteSocket.ts"
click node_achievements "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/achievements/screens/AchievementScreen.tsx"
click node_travel_history "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/settings/screens/TravelHistoryScreen.tsx"
click node_shop_browse "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/shop/screens/GlobalShopScreen.tsx"
click node_product_detail "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/shop/screens/ProductDetailScreen.tsx"
click node_checkout "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/payment/screens/SummaryOrderScreen.tsx"
click node_order_service "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/payment/services/orderService.ts"
click node_purchased "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/screens/PurchasedScreen.tsx"
click node_review_screen "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/screens/ReviewProductScreen.tsx"
click node_review_media "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/hooks/useReviewMedia.ts"
click node_review_create "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/hooks/useCreateReview.ts"
click node_review_service "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/services/reviewService.ts"
click node_catalog "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/catalog/screens/CatalogScreen.tsx"
click node_product_form "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/products/hooks/useCreateProductForm.ts"
click node_category_modal "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/components/CategoryModal.tsx"
click node_orders "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/orders/screens/OrdersScreen.tsx"
click node_dashboard "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/dashboard/screens/DashboardScreen.tsx"
click node_plans "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/plans/screens/PlansScreen.tsx"
click node_api "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/services/api/api.ts"
click node_tourist_store "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/stores/user/auth/authStore.ts"
click node_shop_store "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/stores/shopkeeper/auth/shopkeeperAuthStore.ts"
click node_stomp "https://github.com/passaaqui/passaaqui-mobile/blob/main/src/services/socket/stompClient.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_home,node_tourist_auth,node_shop_auth toneBlue
class node_map,node_route_session,node_poi,node_route_service,node_route_socket,node_achievements,node_travel_history toneAmber
class node_shop_browse,node_product_detail,node_checkout,node_order_service,node_purchased,node_review_screen,node_review_media,node_review_create,node_review_service toneMint
class node_catalog,node_product_form,node_category_modal,node_orders,node_dashboard,node_plans toneRose
class node_api,node_tourist_store,node_shop_store,node_stomp,node_tourist,node_shopkeeper_actor toneIndigo
```

## Components

### App and identity

- [Home and profile choice](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/home/screens/HomeScreen.tsx): `src/features/home/screens/HomeScreen.tsx`
- [Tourist authentication](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/auth/services/authService.ts): `src/features/user/auth/services/authService.ts`
- [Shopkeeper authentication](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/auth/services/shopkeeperAuthService.ts): `src/features/shopkeeper/auth/services/shopkeeperAuthService.ts`

### Tourist exploration

- [Map and navigation](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/screens/MapScreen.tsx): `src/features/user/map/screens/MapScreen.tsx`
- [Route session hooks](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/hooks/useRouteSession.ts): `src/features/user/map/hooks/useRouteSession.ts`
- [POIs and check-ins](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/poi/services/poiService.ts): `src/features/user/map/poi/services/poiService.ts`
- [Routing service](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/services/routeService.ts): `src/services/routeService.ts`
- [Route event listener](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/map/hooks/useRouteSocket.ts): `src/features/user/map/hooks/useRouteSocket.ts`
- [Achievements](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/achievements/screens/AchievementScreen.tsx): `src/features/user/achievements/screens/AchievementScreen.tsx`
- [Travel history](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/settings/screens/TravelHistoryScreen.tsx): `src/features/user/settings/screens/TravelHistoryScreen.tsx`

### Shopping and rewards

- [Product discovery](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/shop/screens/GlobalShopScreen.tsx): `src/features/user/shop/screens/GlobalShopScreen.tsx`
- [Product details and ratings](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/shop/screens/ProductDetailScreen.tsx): `src/features/user/shop/screens/ProductDetailScreen.tsx`
- [Checkout and Pix](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/payment/screens/SummaryOrderScreen.tsx): `src/features/user/payment/screens/SummaryOrderScreen.tsx`
- [Tourist order service](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/payment/services/orderService.ts): `src/features/user/payment/services/orderService.ts`
- [Purchased products](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/screens/PurchasedScreen.tsx): `src/features/user/purchased/screens/PurchasedScreen.tsx`
- [Product review](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/screens/ReviewProductScreen.tsx): `src/features/user/purchased/screens/ReviewProductScreen.tsx`
- [Review media picker](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/hooks/useReviewMedia.ts): `src/features/user/purchased/hooks/useReviewMedia.ts`
- [Review submission hook](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/hooks/useCreateReview.ts): `src/features/user/purchased/hooks/useCreateReview.ts`
- [Review service](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/user/purchased/services/reviewService.ts): `src/features/user/purchased/services/reviewService.ts`

### Shopkeeper operations

- [Product catalog](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/catalog/screens/CatalogScreen.tsx): `src/features/shopkeeper/catalog/screens/CatalogScreen.tsx`
- [Product management](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/products/hooks/useCreateProductForm.ts): `src/features/shopkeeper/products/hooks/useCreateProductForm.ts`
- [Category selection](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/components/CategoryModal.tsx): `src/features/shopkeeper/components/CategoryModal.tsx`
- [Order management](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/orders/screens/OrdersScreen.tsx): `src/features/shopkeeper/orders/screens/OrdersScreen.tsx`
- [Shop metrics](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/dashboard/screens/DashboardScreen.tsx): `src/features/shopkeeper/dashboard/screens/DashboardScreen.tsx`
- [Shop plans](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/features/shopkeeper/plans/screens/PlansScreen.tsx): `src/features/shopkeeper/plans/screens/PlansScreen.tsx`

### Shared platform

- [REST API client](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/services/api/api.ts): `src/services/api/api.ts`
- [Tourist auth state](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/stores/user/auth/authStore.ts): `src/stores/user/auth/authStore.ts`
- [Shopkeeper auth state](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/stores/shopkeeper/auth/shopkeeperAuthStore.ts): `src/stores/shopkeeper/auth/shopkeeperAuthStore.ts`
- [WebSocket client](https://github.com/passaaqui/passaaqui-mobile/blob/main/src/services/socket/stompClient.ts): `src/services/socket/stompClient.ts`

### Other components

- **Tourist**
- **Shopkeeper**

## Connections

- Tourist → Home and profile choice: opens app
- Shopkeeper → Home and profile choice: opens app
- Home and profile choice → Tourist authentication: enters tourist flow
- Home and profile choice → Shopkeeper authentication: enters shop flow
- Tourist → Map and navigation: explores map
- Map and navigation → Route session hooks: navigates
- Route session hooks → Routing service: calls route operations (evidence: `src/features/user/map/hooks/useRouteSession.ts`)
- Routing service → REST API client: sends REST requests (evidence: `src/services/routeService.ts`)
- Tourist → POIs and check-ins: checks in
- Map and navigation → Route event listener: receives route events
- Route event listener → WebSocket client: subscribes (evidence: `src/features/user/map/hooks/useRouteSocket.ts`)
- Route event listener → Routing service: normalizes check-in (evidence: `src/features/user/map/hooks/useRouteSocket.ts`)
- Tourist → Achievements: views achievements
- Tourist → Travel history: views visited cities
- Tourist → Product discovery: discovers products
- Product discovery → Product details and ratings: opens product
- Tourist → Checkout and Pix: redeems with Pix
- Checkout and Pix → Tourist order service: creates order
- Tourist → Purchased products: reviews purchases
- Purchased products → Product review: opens review
- Product review → Review media picker: selects media (evidence: `src/features/user/purchased/screens/ReviewProductScreen.tsx`)
- Product review → Review submission hook: submits review (evidence: `src/features/user/purchased/screens/ReviewProductScreen.tsx`)
- Review submission hook → Review service: creates review (evidence: `src/features/user/purchased/hooks/useCreateReview.ts`)
- Review service → REST API client: uploads review (evidence: `src/features/user/purchased/services/reviewService.ts`)
- Shopkeeper → Product catalog: manages catalog
- Product catalog → Product management: manages products
- Product management → Category selection: selects category (evidence: `src/features/shopkeeper/products/hooks/useCreateProductForm.ts`)
- Shopkeeper → Order management: manages orders
- Shopkeeper → Shop metrics: views metrics
- Shopkeeper → Shop plans: configures plans
- Tourist authentication → REST API client: authenticates via (evidence: `src/features/user/auth/services/authService.ts`)
- Shopkeeper authentication → REST API client: authenticates via (evidence: `src/features/shopkeeper/auth/services/shopkeeperAuthService.ts`)
- Tourist authentication → Tourist auth state: updates auth state (evidence: `src/features/user/auth/services/authService.ts`)
- Shopkeeper authentication → Shopkeeper auth state: updates auth state (evidence: `src/features/shopkeeper/auth/services/shopkeeperAuthService.ts`)
- REST API client → Tourist auth state: reads auth token (evidence: `src/services/api/api.ts`)
- REST API client → Shopkeeper auth state: reads auth token (evidence: `src/services/api/api.ts`)
