# gemstore/gemstore-api architecture

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

- Interactive diagram: https://gitdiagram.com/gemstore/gemstore-api
- Repository: https://github.com/gemstore/gemstore-api

## Overview

GemStore is a Spring Boot gemstone marketplace backend. Users authenticate, manage listings and profiles, interact through follows/favorites, message one another, and request price predictions; administrators moderate users and reports. The README documents PostgreSQL persistence, Kafka messaging, WebSocket notifications, and an external ML service. Source excerpts confirm selected service-to-repository and service-to-service calls; many controller and integration links are documented only at the product level, so those are cited to the README.

Main entry points: [`src/main/java/com/gemstore/backend/services/auth/AuthService.java`](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/auth/AuthService.java) (Authentication), [`src/main/java/com/gemstore/backend/services/listing/ListingService.java`](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/listing/ListingService.java) (Listing lifecycle), [`src/main/java/com/gemstore/backend/controllers/listing/ListingController.java`](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/listing/ListingController.java) (Listings API), [`src/main/java/com/gemstore/backend/services/message/MessageService.java`](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/message/MessageService.java) (Message workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity &amp; Access"]
  node_auth_api["Auth API"]
  node_auth_service["Authentication<br/>[AuthService.java]"]
  node_oauth["OAuth handlers"]
  node_jwt["JWT security<br/>[JwtFilter.java]"]
  node_user_service["User profiles<br/>[UserService.java]"]
end

subgraph group_market["Marketplace &amp; Social"]
  node_listing_api["Listings API"]
  node_listing_service["Listing lifecycle"]
  node_social_api["Social actions"]
  node_follow_service["Follow relationships<br/>[FollowService.java]"]
end

subgraph group_conversation["Messaging &amp; Alerts"]
  node_message_api["Messaging API"]
  node_message_service["Message workflow"]
  node_notification_service["Notification management"]
  node_websocket["WebSocket delivery"]
end

subgraph group_operations["Prediction &amp; Moderation"]
  node_prediction_api["Price prediction API"]
  node_prediction_service["Price estimation client"]
  node_report_api["Reports &amp; moderation API"]
  node_report_service["Report moderation<br/>[ReportService.java]"]
end

subgraph group_platform["Persistence &amp; Integrations"]
  node_listing_store[("Listing data")]
  node_kafka["Kafka topics"]
  node_ml_service["FastAPI ML service"]
  node_postgres[("PostgreSQL")]
  node_wso2["WSO2 API Manager"]
end

node_user(("Marketplace user"))
node_admin(("Administrator"))

node_user -->|"authenticates"| node_auth_api
node_auth_api -.->|"delegates to"| node_auth_service
node_auth_service -.->|"uses user mapping"| node_user_service
node_auth_service -->|"issues JWT"| node_jwt
node_oauth -->|"issues JWT"| node_jwt
node_user -->|"manages listings"| node_listing_api
node_listing_api -.->|"delegates to"| node_listing_service
node_listing_service -->|"queries listings"| node_listing_store
node_listing_service -.->|"uses seller data"| node_user_service
node_user -->|"follows users"| node_social_api
node_social_api -.->|"delegates to"| node_follow_service
node_follow_service -->|"notifies events"| node_notification_service
node_user -->|"sends messages"| node_message_api
node_message_api -.->|"delegates to"| node_message_service
node_message_service -->|"publishes events"| node_kafka
node_kafka -.->|"delivers events"| node_message_service
node_notification_service -->|"sends notification"| node_websocket
node_user -->|"requests estimate"| node_prediction_api
node_prediction_api -.->|"delegates to"| node_prediction_service
node_prediction_service -->|"requests prediction"| node_ml_service
node_admin -->|"moderates reports"| node_report_api
node_report_api -.->|"delegates to"| node_report_service
node_report_service -->|"checks listing reports"| node_listing_store
node_auth_service -.->|"persists users"| node_postgres
node_listing_service -->|"persists marketplace data"| node_postgres
node_user -->|"routes listings through"| node_wso2
node_wso2 -->|"forwards requests"| node_listing_api

click node_auth_api "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/auth/AuthController.java"
click node_auth_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/auth/AuthService.java"
click node_oauth "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/config/OAuth2SuccessHandler.java"
click node_jwt "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/config/JwtFilter.java"
click node_user_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/user/UserService.java"
click node_listing_api "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/listing/ListingController.java"
click node_listing_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/listing/ListingService.java"
click node_listing_store "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/repositories/listing/ListingRepository.java"
click node_social_api "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/user/FollowController.java"
click node_follow_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/user/FollowService.java"
click node_message_api "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/message/MessageController.java"
click node_message_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/message/MessageService.java"
click node_notification_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/notification/NotificationService.java"
click node_websocket "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/notification/NotificationWebSocketService.java"
click node_prediction_api "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/prediction/GemPriceController.java"
click node_prediction_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/prediction/GemPriceService.java"
click node_report_api "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/report/ReportController.java"
click node_report_service "https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/report/ReportService.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_auth_api,node_auth_service,node_oauth,node_jwt,node_user_service,node_user toneBlue
class node_listing_api,node_listing_service,node_social_api,node_follow_service toneAmber
class node_message_api,node_message_service,node_notification_service,node_websocket toneMint
class node_prediction_api,node_prediction_service,node_report_api,node_report_service toneRose
class node_listing_store,node_kafka,node_ml_service,node_postgres,node_wso2,node_admin toneIndigo
```

## Components

### Identity & Access

- [Auth API](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/auth/AuthController.java): `src/main/java/com/gemstore/backend/controllers/auth/AuthController.java`
- [Authentication](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/auth/AuthService.java): `src/main/java/com/gemstore/backend/services/auth/AuthService.java`
- [OAuth handlers](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/config/OAuth2SuccessHandler.java): `src/main/java/com/gemstore/backend/config/OAuth2SuccessHandler.java`
- [JWT security](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/config/JwtFilter.java): `src/main/java/com/gemstore/backend/config/JwtFilter.java`
- [User profiles](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/user/UserService.java): `src/main/java/com/gemstore/backend/services/user/UserService.java`

### Marketplace & Social

- [Listings API](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/listing/ListingController.java): `src/main/java/com/gemstore/backend/controllers/listing/ListingController.java`
- [Listing lifecycle](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/listing/ListingService.java): `src/main/java/com/gemstore/backend/services/listing/ListingService.java`
- [Social actions](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/user/FollowController.java): `src/main/java/com/gemstore/backend/controllers/user/FollowController.java`
- [Follow relationships](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/user/FollowService.java): `src/main/java/com/gemstore/backend/services/user/FollowService.java`

### Messaging & Alerts

- [Messaging API](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/message/MessageController.java): `src/main/java/com/gemstore/backend/controllers/message/MessageController.java`
- [Message workflow](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/message/MessageService.java): `src/main/java/com/gemstore/backend/services/message/MessageService.java`
- [Notification management](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/notification/NotificationService.java): `src/main/java/com/gemstore/backend/services/notification/NotificationService.java`
- [WebSocket delivery](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/notification/NotificationWebSocketService.java): `src/main/java/com/gemstore/backend/services/notification/NotificationWebSocketService.java`

### Prediction & Moderation

- [Price prediction API](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/prediction/GemPriceController.java): `src/main/java/com/gemstore/backend/controllers/prediction/GemPriceController.java`
- [Price estimation client](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/prediction/GemPriceService.java): `src/main/java/com/gemstore/backend/services/prediction/GemPriceService.java`
- [Reports & moderation API](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/controllers/report/ReportController.java): `src/main/java/com/gemstore/backend/controllers/report/ReportController.java`
- [Report moderation](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/services/report/ReportService.java): `src/main/java/com/gemstore/backend/services/report/ReportService.java`

### Persistence & Integrations

- [Listing data](https://github.com/gemstore/gemstore-api/blob/main/src/main/java/com/gemstore/backend/repositories/listing/ListingRepository.java): `src/main/java/com/gemstore/backend/repositories/listing/ListingRepository.java`
- **Kafka topics**
- **FastAPI ML service**
- **PostgreSQL**
- **WSO2 API Manager**

### Other components

- **Marketplace user**
- **Administrator**

## Connections

- Marketplace user → Auth API: authenticates (evidence: `README.md`)
- Auth API → Authentication: delegates to (evidence: `src/main/java/com/gemstore/backend/controllers/auth/AuthController.java`)
- Authentication → User profiles: uses user mapping
- Authentication → JWT security: issues JWT (evidence: `src/main/java/com/gemstore/backend/services/auth/AuthService.java`)
- OAuth handlers → JWT security: issues JWT (evidence: `src/main/java/com/gemstore/backend/config/OAuth2SuccessHandler.java`)
- Marketplace user → Listings API: manages listings (evidence: `README.md`)
- Listings API → Listing lifecycle: delegates to (evidence: `src/main/java/com/gemstore/backend/controllers/listing/ListingController.java`)
- Listing lifecycle → Listing data: queries listings (evidence: `src/main/java/com/gemstore/backend/services/listing/ListingService.java`)
- Listing lifecycle → User profiles: uses seller data
- Marketplace user → Social actions: follows users (evidence: `README.md`)
- Social actions → Follow relationships: delegates to (evidence: `src/main/java/com/gemstore/backend/controllers/user/FollowController.java`)
- Follow relationships → Notification management: notifies events (evidence: `src/main/java/com/gemstore/backend/services/user/FollowService.java`)
- Marketplace user → Messaging API: sends messages (evidence: `README.md`)
- Messaging API → Message workflow: delegates to (evidence: `src/main/java/com/gemstore/backend/controllers/message/MessageController.java`)
- Message workflow → Kafka topics: publishes events (evidence: `src/main/java/com/gemstore/backend/services/message/MessageService.java`)
- Kafka topics → Message workflow: delivers events
- Notification management → WebSocket delivery: sends notification (evidence: `src/main/java/com/gemstore/backend/services/notification/NotificationService.java`)
- Marketplace user → Price prediction API: requests estimate (evidence: `README.md`)
- Price prediction API → Price estimation client: delegates to (evidence: `src/main/java/com/gemstore/backend/controllers/prediction/GemPriceController.java`)
- Price estimation client → FastAPI ML service: requests prediction (evidence: `README.md`)
- Administrator → Reports & moderation API: moderates reports (evidence: `README.md`)
- Reports & moderation API → Report moderation: delegates to (evidence: `src/main/java/com/gemstore/backend/controllers/report/ReportController.java`)
- Report moderation → Listing data: checks listing reports (evidence: `src/main/java/com/gemstore/backend/services/report/ReportService.java`)
- Authentication → PostgreSQL: persists users
- Listing lifecycle → PostgreSQL: persists marketplace data (evidence: `README.md`)
- Marketplace user → WSO2 API Manager: routes listings through (evidence: `README.md`)
- WSO2 API Manager → Listings API: forwards requests (evidence: `README.md`)
