# bvbl1/masterhub architecture

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

- Interactive diagram: https://gitdiagram.com/bvbl1/masterhub
- Repository: https://github.com/bvbl1/masterhub

## Overview

MasterHub is a home-services marketplace: customers browse providers and services, then create orders or job requests, communicate with providers, pay, and leave reviews. The Next.js frontend reaches Go microservices through the REST gateway; chat also has a WebSocket path, and AI chat uses a frontend proxy. The graph preserves documented marketplace capabilities and sampled service wiring. README describes shared PostgreSQL schemas; unsampled service internals and gateway registrations limit confidence in some detailed links.

Main entry points: [`backend/gateway/cmd/main.go`](https://github.com/bvbl1/masterhub/blob/main/backend/gateway/cmd/main.go) (REST gateway), [`backend/order/internal/application/core/api/api.go`](https://github.com/bvbl1/masterhub/blob/main/backend/order/internal/application/core/api/api.go) (Orders and disputes), [`backend/notification/internal/application/core/api/api.go`](https://github.com/bvbl1/masterhub/blob/main/backend/notification/internal/application/core/api/api.go) (Notifications), [`backend/user/internal/application/core/api/api.go`](https://github.com/bvbl1/masterhub/blob/main/backend/user/internal/application/core/api/api.go) (Identity and profiles)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Customer experience"]
  node_frontend["Next.js marketplace"]
end

subgraph group_marketplace["Marketplace services"]
  node_user["Identity and profiles<br/>[api.go]"]
  node_service["Service listings<br/>[api.go]"]
  node_category["Categories<br/>[api.go]"]
  node_location["Locations<br/>[api.go]"]
  node_jobreq["Job requests<br/>[api.go]"]
end

subgraph group_transactions["Orders and payments"]
  node_order["Orders and disputes<br/>[api.go]"]
  node_payment["Payment processing<br/>[api.go]"]
end

subgraph group_engagement["Communication"]
  node_review["Reviews and ratings<br/>[api.go]"]
  node_chat["Real-time chat<br/>[api.go]"]
  node_notification["Notifications<br/>[api.go]"]
  node_telegram["Telegram bot<br/>[bot.go]"]
  node_email["Email delivery"]
end

subgraph group_edge["API and integrations"]
  node_gateway["REST gateway<br/>[main.go]"]
  node_media["Media uploads<br/>[api.go]"]
  node_ai["AI assistant<br/>[api.go]"]
  node_postgres[("PostgreSQL")]
  node_stripe["Stripe"]
  node_objectstore["S3 storage"]
  node_openrouter["OpenRouter"]
end

node_customer(("Customer or provider"))

node_customer -->|"uses"| node_frontend
node_frontend -->|"REST requests"| node_gateway
node_gateway -->|"gRPC proxy"| node_user
node_gateway -->|"gRPC proxy"| node_service
node_gateway -->|"gRPC proxy"| node_category
node_gateway -->|"gRPC proxy"| node_location
node_gateway -->|"gRPC proxy"| node_chat
node_gateway -->|"gRPC proxy"| node_notification
node_gateway -->|"gRPC proxy"| node_order
node_gateway -->|"gRPC proxy"| node_payment
node_gateway -->|"gRPC proxy"| node_review
node_gateway -->|"gRPC proxy"| node_media
node_gateway -->|"gRPC proxy"| node_jobreq
node_frontend -->|"WebSocket chat"| node_chat
node_frontend -->|"AI proxy"| node_ai
node_service -->|"calls adapter"| node_category
node_service -->|"calls adapter"| node_user
node_order -->|"calls adapter"| node_user
node_order -->|"calls adapter"| node_service
node_order -->|"calls adapter"| node_location
node_order -->|"calls adapter"| node_notification
node_order -->|"calls adapter"| node_payment
node_jobreq -->|"calls adapter"| node_user
node_jobreq -->|"calls adapter"| node_order
node_jobreq -->|"calls adapter"| node_notification
node_review -->|"calls adapter"| node_user
node_review -->|"calls adapter"| node_order
node_review -->|"calls adapter"| node_notification
node_payment -->|"calls adapter"| node_order
node_user -->|"reads and writes"| node_postgres
node_service -->|"reads and writes"| node_postgres
node_category -->|"reads and writes"| node_postgres
node_location -->|"reads and writes"| node_postgres
node_jobreq -->|"reads and writes"| node_postgres
node_order -->|"reads and writes"| node_postgres
node_payment -->|"reads and writes"| node_postgres
node_review -->|"reads and writes"| node_postgres
node_chat -->|"reads and writes"| node_postgres
node_notification -->|"reads and writes"| node_postgres
node_payment -->|"processes payments"| node_stripe
node_media -->|"stores media"| node_objectstore
node_ai -->|"requests AI"| node_openrouter
node_notification -->|"sends email"| node_email
node_telegram -.->|"AI adapter"| node_ai

click node_frontend "https://github.com/bvbl1/masterhub/tree/main/frontend/app"
click node_gateway "https://github.com/bvbl1/masterhub/blob/main/backend/gateway/cmd/main.go"
click node_user "https://github.com/bvbl1/masterhub/blob/main/backend/user/internal/application/core/api/api.go"
click node_service "https://github.com/bvbl1/masterhub/blob/main/backend/service/internal/application/core/api/api.go"
click node_category "https://github.com/bvbl1/masterhub/blob/main/backend/category/internal/application/core/api/api.go"
click node_location "https://github.com/bvbl1/masterhub/blob/main/backend/location/internal/application/core/api/api.go"
click node_jobreq "https://github.com/bvbl1/masterhub/blob/main/backend/job-request/internal/application/core/api/api.go"
click node_order "https://github.com/bvbl1/masterhub/blob/main/backend/order/internal/application/core/api/api.go"
click node_payment "https://github.com/bvbl1/masterhub/blob/main/backend/payment/internal/application/core/api/api.go"
click node_review "https://github.com/bvbl1/masterhub/blob/main/backend/review/internal/application/core/api/api.go"
click node_chat "https://github.com/bvbl1/masterhub/blob/main/backend/chat/internal/application/core/api/api.go"
click node_notification "https://github.com/bvbl1/masterhub/blob/main/backend/notification/internal/application/core/api/api.go"
click node_media "https://github.com/bvbl1/masterhub/blob/main/backend/media/internal/application/core/api/api.go"
click node_ai "https://github.com/bvbl1/masterhub/blob/main/backend/ai/internal/application/core/api/api.go"
click node_telegram "https://github.com/bvbl1/masterhub/blob/main/backend/telegram/internal/adapters/bot/bot.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_frontend toneBlue
class node_user,node_service,node_category,node_location,node_jobreq toneAmber
class node_order,node_payment toneMint
class node_review,node_chat,node_notification,node_telegram,node_email toneRose
class node_gateway,node_media,node_ai,node_postgres,node_stripe,node_objectstore,node_openrouter,node_customer toneIndigo
```

## Components

### Customer experience

- [Next.js marketplace](https://github.com/bvbl1/masterhub/tree/main/frontend/app): `frontend/app`

### Marketplace services

- [Identity and profiles](https://github.com/bvbl1/masterhub/blob/main/backend/user/internal/application/core/api/api.go): `backend/user/internal/application/core/api/api.go`
- [Service listings](https://github.com/bvbl1/masterhub/blob/main/backend/service/internal/application/core/api/api.go): `backend/service/internal/application/core/api/api.go`
- [Categories](https://github.com/bvbl1/masterhub/blob/main/backend/category/internal/application/core/api/api.go): `backend/category/internal/application/core/api/api.go`
- [Locations](https://github.com/bvbl1/masterhub/blob/main/backend/location/internal/application/core/api/api.go): `backend/location/internal/application/core/api/api.go`
- [Job requests](https://github.com/bvbl1/masterhub/blob/main/backend/job-request/internal/application/core/api/api.go): `backend/job-request/internal/application/core/api/api.go`

### Orders and payments

- [Orders and disputes](https://github.com/bvbl1/masterhub/blob/main/backend/order/internal/application/core/api/api.go): `backend/order/internal/application/core/api/api.go`
- [Payment processing](https://github.com/bvbl1/masterhub/blob/main/backend/payment/internal/application/core/api/api.go): `backend/payment/internal/application/core/api/api.go`

### Communication

- [Reviews and ratings](https://github.com/bvbl1/masterhub/blob/main/backend/review/internal/application/core/api/api.go): `backend/review/internal/application/core/api/api.go`
- [Real-time chat](https://github.com/bvbl1/masterhub/blob/main/backend/chat/internal/application/core/api/api.go): `backend/chat/internal/application/core/api/api.go`
- [Notifications](https://github.com/bvbl1/masterhub/blob/main/backend/notification/internal/application/core/api/api.go): `backend/notification/internal/application/core/api/api.go`
- [Telegram bot](https://github.com/bvbl1/masterhub/blob/main/backend/telegram/internal/adapters/bot/bot.go): `backend/telegram/internal/adapters/bot/bot.go`
- **Email delivery**

### API and integrations

- [REST gateway](https://github.com/bvbl1/masterhub/blob/main/backend/gateway/cmd/main.go): `backend/gateway/cmd/main.go`
- [Media uploads](https://github.com/bvbl1/masterhub/blob/main/backend/media/internal/application/core/api/api.go): `backend/media/internal/application/core/api/api.go`
- [AI assistant](https://github.com/bvbl1/masterhub/blob/main/backend/ai/internal/application/core/api/api.go): `backend/ai/internal/application/core/api/api.go`
- **PostgreSQL**
- **Stripe**
- **S3 storage**
- **OpenRouter**

### Other components

- **Customer or provider**

## Connections

- Customer or provider → Next.js marketplace: uses
- Next.js marketplace → REST gateway: REST requests
- REST gateway → Identity and profiles: gRPC proxy
- REST gateway → Service listings: gRPC proxy
- REST gateway → Categories: gRPC proxy
- REST gateway → Locations: gRPC proxy
- REST gateway → Real-time chat: gRPC proxy
- REST gateway → Notifications: gRPC proxy
- REST gateway → Orders and disputes: gRPC proxy
- REST gateway → Payment processing: gRPC proxy
- REST gateway → Reviews and ratings: gRPC proxy
- REST gateway → Media uploads: gRPC proxy
- REST gateway → Job requests: gRPC proxy
- Next.js marketplace → Real-time chat: WebSocket chat
- Next.js marketplace → AI assistant: AI proxy
- Service listings → Categories: calls adapter
- Service listings → Identity and profiles: calls adapter
- Orders and disputes → Identity and profiles: calls adapter
- Orders and disputes → Service listings: calls adapter
- Orders and disputes → Locations: calls adapter
- Orders and disputes → Notifications: calls adapter
- Orders and disputes → Payment processing: calls adapter
- Job requests → Identity and profiles: calls adapter
- Job requests → Orders and disputes: calls adapter
- Job requests → Notifications: calls adapter
- Reviews and ratings → Identity and profiles: calls adapter
- Reviews and ratings → Orders and disputes: calls adapter
- Reviews and ratings → Notifications: calls adapter
- Payment processing → Orders and disputes: calls adapter
- Identity and profiles → PostgreSQL: reads and writes
- Service listings → PostgreSQL: reads and writes
- Categories → PostgreSQL: reads and writes
- Locations → PostgreSQL: reads and writes
- Job requests → PostgreSQL: reads and writes
- Orders and disputes → PostgreSQL: reads and writes
- Payment processing → PostgreSQL: reads and writes
- Reviews and ratings → PostgreSQL: reads and writes
- Real-time chat → PostgreSQL: reads and writes
- Notifications → PostgreSQL: reads and writes
- Payment processing → Stripe: processes payments
- Media uploads → S3 storage: stores media
- AI assistant → OpenRouter: requests AI
- Notifications → Email delivery: sends email
- Telegram bot → AI assistant: AI adapter