# pi3-tcg/tcgmarket architecture

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

- Interactive diagram: https://gitdiagram.com/pi3-tcg/tcgmarket
- Repository: https://github.com/pi3-tcg/tcgmarket

## Overview

TCG Market is a trading-card platform for catalog discovery, personal collection management, profiles, administration, and user-to-user sales or trades. The user workflow begins in the React interface, reaches the REST API, and uses backend services to query the internal MongoDB catalog and manage user-owned records; purchase, trade, and review capabilities are also represented because they exist in the repository. The README documents catalog imports from external TCG sources. Only selected backend and frontend files were sampled, so unsampled subsystem links are marked unverified rather than presented as inspected call paths.

Main entry points: [`backend/src/main/java/com/pitcc/controller`](https://github.com/pi3-tcg/tcgmarket/tree/main/backend/src/main/java/com/pitcc/controller) (REST API controllers), [`backend/src/main/java/com/pitcc/service/AuthService.java`](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/AuthService.java) (Auth and JWT), [`backend/src/main/java/com/pitcc/service/CatalogSearchService.java`](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CatalogSearchService.java) (Catalog search), [`backend/src/main/java/com/pitcc/service/ReviewService.java`](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/ReviewService.java) (Transaction reviews)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["React application<br/>[App.tsx]"]
  node_routes["Page routing<br/>[router.tsx]"]
  node_api["REST API controllers"]
end

subgraph group_identity["Identity and profiles"]
  node_identity["Auth and JWT<br/>[AuthService.java]"]
  node_userstore[("User records")]
  node_profiles["Profiles and users"]
end

subgraph group_cards["Catalog and collection"]
  node_catalogsearch["Catalog search"]
  node_catalogstore[("Card catalog")]
  node_catalogimport["Catalog import"]
  node_tcgproviders["TCG data providers"]
  node_collection["Personal collection"]
  node_collectionstore[("Collection records")]
end

subgraph group_commerce["Trading and commerce"]
  node_adsmarket["Ads and marketplace"]
  node_checkout["Cart and checkout"]
  node_payments["Payment gateway"]
  node_trades["Trade proposals"]
  node_reviews["Transaction reviews<br/>[ReviewService.java]"]
  node_reviewstore[("Review records")]
end

subgraph group_operations["Administration"]
  node_admin["Admin tools"]
end

node_collector(("Player / collector"))
node_mongodb[("MongoDB")]
node_externalcatalogs["External card APIs"]
node_paymentprovider["Payment provider"]

node_collector -.->|"uses"| node_web
node_web -.->|"renders routes"| node_routes
node_routes -.->|"requests data"| node_api
node_api -.->|"delegates auth"| node_identity
node_identity -->|"reads users"| node_userstore
node_identity -.->|"persists users"| node_mongodb
node_api -->|"delegates collection"| node_collection
node_collection -.->|"searches records"| node_collectionstore
node_collectionstore -.->|"queries"| node_mongodb
node_api -.->|"serves catalog"| node_catalogsearch
node_catalogsearch -->|"reads cards"| node_catalogstore
node_catalogsearch -->|"queries cards"| node_mongodb
node_externalcatalogs -.->|"supplies card data"| node_tcgproviders
node_tcgproviders -.->|"provides imports"| node_catalogimport
node_catalogimport -.->|"imports cards"| node_catalogstore
node_catalogstore -.->|"stores cards"| node_mongodb
node_api -.->|"serves profiles"| node_profiles
node_api -.->|"serves listings"| node_adsmarket
node_api -.->|"delegates checkout"| node_checkout
node_checkout -.->|"requests payment"| node_payments
node_payments -.->|"charges through"| node_paymentprovider
node_api -.->|"serves trades"| node_trades
node_api -.->|"delegates reviews"| node_reviews
node_reviews -->|"saves and reads"| node_reviewstore
node_reviews -.->|"persists reviews"| node_mongodb
node_api -.->|"serves admin"| node_admin

click node_web "https://github.com/pi3-tcg/tcgmarket/blob/main/frontend/src/App.tsx"
click node_routes "https://github.com/pi3-tcg/tcgmarket/blob/main/frontend/src/router.tsx"
click node_api "https://github.com/pi3-tcg/tcgmarket/tree/main/backend/src/main/java/com/pitcc/controller"
click node_identity "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/AuthService.java"
click node_userstore "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/UserRepository.java"
click node_profiles "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/ProfileService.java"
click node_catalogsearch "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CatalogSearchService.java"
click node_catalogstore "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/CardRepository.java"
click node_catalogimport "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CatalogImportService.java"
click node_tcgproviders "https://github.com/pi3-tcg/tcgmarket/tree/main/backend/src/main/java/com/pitcc/integration/catalog"
click node_collection "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CollectionService.java"
click node_collectionstore "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/CollectionSearchRepository.java"
click node_adsmarket "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/MarketplaceService.java"
click node_checkout "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/PlaceOrderService.java"
click node_payments "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/integration/payment/PaymentGateway.java"
click node_trades "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CreateTradeProposalService.java"
click node_reviews "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/ReviewService.java"
click node_reviewstore "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/ReviewRepository.java"
click node_admin "https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/AdminDashboardService.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_web,node_routes,node_api toneBlue
class node_identity,node_userstore,node_profiles,node_mongodb toneAmber
class node_catalogsearch,node_catalogstore,node_catalogimport,node_tcgproviders,node_collection,node_collectionstore,node_externalcatalogs toneMint
class node_adsmarket,node_checkout,node_payments,node_trades,node_reviews,node_reviewstore toneRose
class node_admin,node_collector,node_paymentprovider toneIndigo
```

## Components

### Web experience

- [React application](https://github.com/pi3-tcg/tcgmarket/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Page routing](https://github.com/pi3-tcg/tcgmarket/blob/main/frontend/src/router.tsx): `frontend/src/router.tsx`
- [REST API controllers](https://github.com/pi3-tcg/tcgmarket/tree/main/backend/src/main/java/com/pitcc/controller): `backend/src/main/java/com/pitcc/controller`

### Identity and profiles

- [Auth and JWT](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/AuthService.java): `backend/src/main/java/com/pitcc/service/AuthService.java`
- [User records](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/UserRepository.java): `backend/src/main/java/com/pitcc/repository/UserRepository.java`
- [Profiles and users](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/ProfileService.java): `backend/src/main/java/com/pitcc/service/ProfileService.java`

### Catalog and collection

- [Catalog search](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CatalogSearchService.java): `backend/src/main/java/com/pitcc/service/CatalogSearchService.java`
- [Card catalog](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/CardRepository.java): `backend/src/main/java/com/pitcc/repository/CardRepository.java`
- [Catalog import](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CatalogImportService.java): `backend/src/main/java/com/pitcc/service/CatalogImportService.java`
- [TCG data providers](https://github.com/pi3-tcg/tcgmarket/tree/main/backend/src/main/java/com/pitcc/integration/catalog): `backend/src/main/java/com/pitcc/integration/catalog`
- [Personal collection](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CollectionService.java): `backend/src/main/java/com/pitcc/service/CollectionService.java`
- [Collection records](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/CollectionSearchRepository.java): `backend/src/main/java/com/pitcc/repository/CollectionSearchRepository.java`

### Trading and commerce

- [Ads and marketplace](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/MarketplaceService.java): `backend/src/main/java/com/pitcc/service/MarketplaceService.java`
- [Cart and checkout](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/PlaceOrderService.java): `backend/src/main/java/com/pitcc/service/PlaceOrderService.java`
- [Payment gateway](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/integration/payment/PaymentGateway.java): `backend/src/main/java/com/pitcc/integration/payment/PaymentGateway.java`
- [Trade proposals](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/CreateTradeProposalService.java): `backend/src/main/java/com/pitcc/service/CreateTradeProposalService.java`
- [Transaction reviews](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/ReviewService.java): `backend/src/main/java/com/pitcc/service/ReviewService.java`
- [Review records](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/repository/ReviewRepository.java): `backend/src/main/java/com/pitcc/repository/ReviewRepository.java`

### Administration

- [Admin tools](https://github.com/pi3-tcg/tcgmarket/blob/main/backend/src/main/java/com/pitcc/service/AdminDashboardService.java): `backend/src/main/java/com/pitcc/service/AdminDashboardService.java`

### Other components

- **Player / collector**
- **MongoDB**
- **External card APIs**
- **Payment provider**

## Connections

- Player / collector → React application: uses
- React application → Page routing: renders routes
- Page routing → REST API controllers: requests data
- REST API controllers → Auth and JWT: delegates auth
- Auth and JWT → User records: reads users (evidence: `backend/src/main/java/com/pitcc/service/AuthService.java`)
- Auth and JWT → MongoDB: persists users
- REST API controllers → Personal collection: delegates collection (evidence: `backend/src/main/java/com/pitcc/controller/CollectionController.java`)
- Personal collection → Collection records: searches records
- Collection records → MongoDB: queries
- REST API controllers → Catalog search: serves catalog
- Catalog search → Card catalog: reads cards (evidence: `backend/src/main/java/com/pitcc/service/CatalogSearchService.java`)
- Catalog search → MongoDB: queries cards (evidence: `backend/src/main/java/com/pitcc/service/CatalogSearchService.java`)
- External card APIs → TCG data providers: supplies card data
- TCG data providers → Catalog import: provides imports
- Catalog import → Card catalog: imports cards
- Card catalog → MongoDB: stores cards
- REST API controllers → Profiles and users: serves profiles
- REST API controllers → Ads and marketplace: serves listings
- REST API controllers → Cart and checkout: delegates checkout
- Cart and checkout → Payment gateway: requests payment
- Payment gateway → Payment provider: charges through
- REST API controllers → Trade proposals: serves trades
- REST API controllers → Transaction reviews: delegates reviews
- Transaction reviews → Review records: saves and reads (evidence: `backend/src/main/java/com/pitcc/service/ReviewService.java`)
- Transaction reviews → MongoDB: persists reviews
- REST API controllers → Admin tools: serves admin
