# glaybyonest/marketplace architecture

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

- Interactive diagram: https://gitdiagram.com/glaybyonest/marketplace
- Repository: https://github.com/glaybyonest/marketplace

## Overview

Marketplace is a full-stack platform for buyers, sellers, and administrators. Buyers browse and search products, manage favorites and a cart, then check out; accounts also cover profiles, delivery places, orders, sessions, and messaging. Seller and admin workflows manage storefronts, products, orders, and catalog categories. The React client calls a Go REST API backed by PostgreSQL. The backend also runs email and recommendation jobs, exposes health and metrics endpoints, and supports an optional OpenAI seller-product assistant. Some feature links rely on README documentation because their source was not sampled.

Main entry points: [`internal/app/app.go`](https://github.com/glaybyonest/marketplace/blob/main/internal/app/app.go) (App composition), [`internal/http/router.go`](https://github.com/glaybyonest/marketplace/blob/main/internal/http/router.go) (REST router), [`frontend/src/App.tsx`](https://github.com/glaybyonest/marketplace/blob/main/frontend/src/App.tsx) (Web app), [`internal/repository/postgres`](https://github.com/glaybyonest/marketplace/tree/main/internal/repository/postgres) (PostgreSQL repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Marketplace client"]
  node_web_app["Web app<br/>[App.tsx]"]
  node_web_routes["Client routes<br/>[AppRouter.tsx]"]
  node_client_services["API services"]
  node_product_client["Product service<br/>[productService.ts]"]
  node_web_state["Client state"]
end

subgraph group_api["HTTP API"]
  node_http_router["REST router<br/>[router.go]"]
  node_auth_handlers["Auth handlers<br/>[auth.go]"]
  node_feature_handlers["Feature handlers"]
  node_api_docs["OpenAPI docs<br/>[http.go]"]
end

subgraph group_business["Domain services"]
  node_auth_service["Authentication<br/>[auth.go]"]
  node_commerce_services["Commerce services"]
  node_seller_ai["Seller AI assistant<br/>[seller_ai.go]"]
  node_postgres_repos["PostgreSQL repositories"]
end

subgraph group_operations["Platform operations"]
  node_api_entry["API process<br/>[main.go]"]
  node_app_wiring["App composition<br/>[app.go]"]
  node_background_jobs["Background jobs<br/>[tasks.go]"]
  node_mailer["Queued mail sender<br/>[mailer.go]"]
  node_openai_client["OpenAI client<br/>[client.go]"]
  node_monitoring["Health and metrics"]
end

node_buyer(("Buyer"))
node_seller_user(("Seller"))
node_admin_user(("Administrator"))
node_postgres_db[("PostgreSQL")]

node_buyer -->|"uses"| node_web_app
node_seller_user -->|"uses"| node_web_app
node_admin_user -->|"uses"| node_web_app
node_web_app -->|"renders"| node_web_routes
node_web_routes -.->|"dispatches requests"| node_client_services
node_client_services -->|"calls REST API"| node_http_router
node_product_client -->|"calls REST API"| node_http_router
node_web_app -->|"dispatches actions"| node_web_state
node_api_entry -->|"starts"| node_app_wiring
node_app_wiring -->|"configures"| node_http_router
node_http_router -->|"routes auth"| node_auth_handlers
node_http_router -->|"routes features"| node_feature_handlers
node_auth_handlers -.->|"delegates to"| node_auth_service
node_feature_handlers -.->|"delegates to"| node_commerce_services
node_app_wiring -->|"constructs"| node_auth_service
node_app_wiring -->|"constructs"| node_commerce_services
node_app_wiring -->|"constructs"| node_seller_ai
node_commerce_services -.->|"uses"| node_postgres_repos
node_auth_service -.->|"uses"| node_postgres_repos
node_postgres_repos -.->|"reads and writes"| node_postgres_db
node_app_wiring -->|"starts"| node_background_jobs
node_background_jobs -->|"sends queued mail"| node_mailer
node_background_jobs -.->|"refreshes data"| node_postgres_repos
node_app_wiring -->|"configures optional provider"| node_openai_client
node_seller_ai -.->|"requests generation"| node_openai_client
node_app_wiring -.->|"configures"| node_monitoring
node_http_router -->|"exposes endpoints"| node_monitoring
node_http_router -->|"serves docs"| node_api_docs

click node_web_app "https://github.com/glaybyonest/marketplace/blob/main/frontend/src/App.tsx"
click node_web_routes "https://github.com/glaybyonest/marketplace/blob/main/frontend/src/routes/AppRouter.tsx"
click node_client_services "https://github.com/glaybyonest/marketplace/tree/main/frontend/src/services"
click node_product_client "https://github.com/glaybyonest/marketplace/blob/main/frontend/src/services/productService.ts"
click node_web_state "https://github.com/glaybyonest/marketplace/tree/main/frontend/src/store"
click node_api_entry "https://github.com/glaybyonest/marketplace/blob/main/cmd/api/main.go"
click node_app_wiring "https://github.com/glaybyonest/marketplace/blob/main/internal/app/app.go"
click node_http_router "https://github.com/glaybyonest/marketplace/blob/main/internal/http/router.go"
click node_auth_handlers "https://github.com/glaybyonest/marketplace/blob/main/internal/http/handlers/auth.go"
click node_feature_handlers "https://github.com/glaybyonest/marketplace/tree/main/internal/http/handlers"
click node_auth_service "https://github.com/glaybyonest/marketplace/blob/main/internal/usecase/auth.go"
click node_commerce_services "https://github.com/glaybyonest/marketplace/tree/main/internal/usecase"
click node_seller_ai "https://github.com/glaybyonest/marketplace/blob/main/internal/usecase/seller_ai.go"
click node_postgres_repos "https://github.com/glaybyonest/marketplace/tree/main/internal/repository/postgres"
click node_background_jobs "https://github.com/glaybyonest/marketplace/blob/main/internal/jobs/tasks.go"
click node_mailer "https://github.com/glaybyonest/marketplace/blob/main/internal/mailer/mailer.go"
click node_openai_client "https://github.com/glaybyonest/marketplace/blob/main/internal/integrations/openai/client.go"
click node_monitoring "https://github.com/glaybyonest/marketplace/tree/main/internal/observability"
click node_api_docs "https://github.com/glaybyonest/marketplace/blob/main/apidocs/http.go"

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_app,node_web_routes,node_client_services,node_product_client,node_web_state toneBlue
class node_http_router,node_auth_handlers,node_feature_handlers,node_api_docs,node_postgres_db toneAmber
class node_auth_service,node_commerce_services,node_seller_ai,node_postgres_repos toneMint
class node_api_entry,node_app_wiring,node_background_jobs,node_mailer,node_openai_client,node_monitoring toneRose
class node_buyer,node_seller_user,node_admin_user toneIndigo
```

## Components

### Marketplace client

- [Web app](https://github.com/glaybyonest/marketplace/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Client routes](https://github.com/glaybyonest/marketplace/blob/main/frontend/src/routes/AppRouter.tsx): `frontend/src/routes/AppRouter.tsx`
- [API services](https://github.com/glaybyonest/marketplace/tree/main/frontend/src/services): `frontend/src/services`
- [Product service](https://github.com/glaybyonest/marketplace/blob/main/frontend/src/services/productService.ts): `frontend/src/services/productService.ts`
- [Client state](https://github.com/glaybyonest/marketplace/tree/main/frontend/src/store): `frontend/src/store`

### HTTP API

- [REST router](https://github.com/glaybyonest/marketplace/blob/main/internal/http/router.go): `internal/http/router.go`
- [Auth handlers](https://github.com/glaybyonest/marketplace/blob/main/internal/http/handlers/auth.go): `internal/http/handlers/auth.go`
- [Feature handlers](https://github.com/glaybyonest/marketplace/tree/main/internal/http/handlers): `internal/http/handlers`
- [OpenAPI docs](https://github.com/glaybyonest/marketplace/blob/main/apidocs/http.go): `apidocs/http.go`

### Domain services

- [Authentication](https://github.com/glaybyonest/marketplace/blob/main/internal/usecase/auth.go): `internal/usecase/auth.go`
- [Commerce services](https://github.com/glaybyonest/marketplace/tree/main/internal/usecase): `internal/usecase`
- [Seller AI assistant](https://github.com/glaybyonest/marketplace/blob/main/internal/usecase/seller_ai.go): `internal/usecase/seller_ai.go`
- [PostgreSQL repositories](https://github.com/glaybyonest/marketplace/tree/main/internal/repository/postgres): `internal/repository/postgres`

### Platform operations

- [API process](https://github.com/glaybyonest/marketplace/blob/main/cmd/api/main.go): `cmd/api/main.go`
- [App composition](https://github.com/glaybyonest/marketplace/blob/main/internal/app/app.go): `internal/app/app.go`
- [Background jobs](https://github.com/glaybyonest/marketplace/blob/main/internal/jobs/tasks.go): `internal/jobs/tasks.go`
- [Queued mail sender](https://github.com/glaybyonest/marketplace/blob/main/internal/mailer/mailer.go): `internal/mailer/mailer.go`
- [OpenAI client](https://github.com/glaybyonest/marketplace/blob/main/internal/integrations/openai/client.go): `internal/integrations/openai/client.go`
- [Health and metrics](https://github.com/glaybyonest/marketplace/tree/main/internal/observability): `internal/observability`

### Other components

- **Buyer**
- **Seller**
- **Administrator**
- **PostgreSQL**

## Connections

- Buyer → Web app: uses (evidence: `README.md`)
- Seller → Web app: uses (evidence: `README.md`)
- Administrator → Web app: uses (evidence: `README.md`)
- Web app → Client routes: renders (evidence: `frontend/src/App.tsx`)
- Client routes → API services: dispatches requests
- API services → REST router: calls REST API (evidence: `README.md`)
- Product service → REST router: calls REST API (evidence: `README.md`)
- Web app → Client state: dispatches actions (evidence: `frontend/src/App.tsx`)
- API process → App composition: starts (evidence: `cmd/api/main.go`)
- App composition → REST router: configures (evidence: `internal/app/app.go`)
- REST router → Auth handlers: routes auth (evidence: `internal/http/router.go`)
- REST router → Feature handlers: routes features (evidence: `internal/http/router.go`)
- Auth handlers → Authentication: delegates to
- Feature handlers → Commerce services: delegates to
- App composition → Authentication: constructs (evidence: `internal/app/app.go`)
- App composition → Commerce services: constructs (evidence: `internal/app/app.go`)
- App composition → Seller AI assistant: constructs (evidence: `internal/app/app.go`)
- Commerce services → PostgreSQL repositories: uses
- Authentication → PostgreSQL repositories: uses
- PostgreSQL repositories → PostgreSQL: reads and writes
- App composition → Background jobs: starts (evidence: `internal/app/app.go`)
- Background jobs → Queued mail sender: sends queued mail (evidence: `internal/jobs/tasks.go`)
- Background jobs → PostgreSQL repositories: refreshes data
- App composition → OpenAI client: configures optional provider (evidence: `internal/app/app.go`)
- Seller AI assistant → OpenAI client: requests generation
- App composition → Health and metrics: configures
- REST router → Health and metrics: exposes endpoints (evidence: `internal/http/router.go`)
- REST router → OpenAPI docs: serves docs (evidence: `internal/http/router.go`)