# mahmoudadeli/jomla-backend architecture

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

- Interactive diagram: https://gitdiagram.com/mahmoudadeli/jomla-backend
- Repository: https://github.com/mahmoudadeli/jomla-backend

## Overview

Jomla is a B2B group-buying marketplace: buyers discover supplier offers and join quantity-based batches, or create and join group requests that suppliers can bid on. The README describes automated categorization, moderation, supplier matching, fulfillment, and multi-round AI negotiation backed by Qdrant. The tree supports these major subsystems, but sampled implementation is limited to selected query handlers; workflow links beyond the documented behavior are therefore kept at subsystem level. Persistence and external integration wiring are not fully sampled.

Main entry points: [`Jomla.Application/Features/GroupRequests`](https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/GroupRequests) (Group requests), [`Jomla.Infrastructure/Jobs/JobDispatcher/HangfireJobDispatcher.cs`](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Jobs/JobDispatcher/HangfireJobDispatcher.cs) (Background jobs), [`Jomla.Infrastructure/Persistance/AppDbContext.cs`](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Persistance/AppDbContext.cs) (Application database), [`Jomla.Infrastructure/Jobs/Matching/SupplierMatchingJob.cs`](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Jobs/Matching/SupplierMatchingJob.cs) (Supplier matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API access"]
  node_api_offers["Offer endpoints"]
  node_api_batches["Batch endpoints"]
  node_api_requests["Request endpoints"]
  node_api_request_offers["Request offer endpoints"]
  node_api_admin["Admin endpoints<br/>[AdminController.cs]"]
  node_api_auth["Authentication endpoints<br/>[AuthController.cs]"]
end

subgraph group_marketplace["Marketplace workflows"]
  node_offers["Supplier offers<br/>[Offers]"]
  node_batches["Batch purchasing<br/>[Batches]"]
  node_requests["Group requests<br/>[GroupRequests]"]
  node_categories["Categories<br/>[Categories]"]
  node_preferences["Supplier preferences"]
end

subgraph group_intelligence["Matching and AI"]
  node_moderation["AI moderation<br/>[ModerationAgent.cs]"]
  node_categorization["AI categorization<br/>[CategoryAgent.cs]"]
  node_matching["Supplier matching"]
  node_negotiation["AI negotiation"]
  node_round_index["Round indexing"]
end

subgraph group_platform["Platform services"]
  node_jobs["Background jobs"]
  node_notifications["Notifications and realtime<br/>[Notifications]"]
  node_realtime["Realtime delivery<br/>[RealtimeService.cs]"]
  node_auth["Identity and tokens<br/>[IdentityService.cs]"]
  node_database[("Application database<br/>[AppDbContext.cs]")]
end

node_buyers(("Buyers"))
node_suppliers(("Suppliers"))
node_admins(("Admins"))
node_qdrant[("Qdrant vector store")]
node_llm["Language model"]

node_buyers -->|"browse"| node_api_offers
node_buyers -->|"join batches"| node_api_batches
node_buyers -->|"create and join"| node_api_requests
node_buyers -->|"respond"| node_api_request_offers
node_suppliers -->|"manage offers"| node_api_offers
node_suppliers -->|"manage batches"| node_api_batches
node_suppliers -->|"view matches"| node_api_requests
node_suppliers -->|"place bids"| node_api_request_offers
node_admins -->|"review content"| node_api_admin
node_api_offers -->|"dispatches"| node_offers
node_api_batches -->|"dispatches"| node_batches
node_api_requests -->|"dispatches"| node_requests
node_api_request_offers -->|"dispatches"| node_requests
node_api_admin -->|"moderates"| node_offers
node_api_admin -->|"moderates"| node_requests
node_api_auth -->|"authenticates"| node_auth
node_offers -->|"reads and writes"| node_database
node_batches -->|"reads and writes"| node_database
node_requests -->|"reads and writes"| node_database
node_categories -->|"reads and writes"| node_database
node_preferences -->|"reads and writes"| node_database
node_offers -->|"submits for review"| node_moderation
node_requests -->|"detects category"| node_categorization
node_requests -->|"submits for review"| node_moderation
node_matching -->|"uses preferences"| node_preferences
node_matching -->|"finds requests"| node_requests
node_matching -->|"notifies suppliers"| node_notifications
node_jobs -->|"dispatches"| node_matching
node_jobs -->|"dispatches"| node_moderation
node_jobs -->|"dispatches expiry rounds"| node_negotiation
node_negotiation -.->|"requests pricing"| node_llm
node_negotiation -.->|"retrieves history"| node_qdrant
node_round_index -.->|"indexes rounds"| node_qdrant
node_requests -->|"schedules work"| node_jobs
node_batches -->|"schedules fulfillment"| node_jobs
node_notifications -->|"delivers updates"| node_realtime

click node_api_offers "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/OffersController.cs"
click node_api_batches "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/BatchesController.cs"
click node_api_requests "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/GroupRequestsController.cs"
click node_api_request_offers "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/GroupRequestOffersController.cs"
click node_api_admin "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/AdminController.cs"
click node_api_auth "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/AuthController.cs"
click node_offers "https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Offers"
click node_batches "https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Batches"
click node_requests "https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/GroupRequests"
click node_categories "https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Categories"
click node_preferences "https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/SupplierCategoryPreferences"
click node_moderation "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/ModerationAgent.cs"
click node_categorization "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/CategoryAgent.cs"
click node_matching "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Jobs/Matching/SupplierMatchingJob.cs"
click node_negotiation "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/NegotiationAgent.cs"
click node_round_index "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/NegotiationRoundIndexer.cs"
click node_jobs "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Jobs/JobDispatcher/HangfireJobDispatcher.cs"
click node_notifications "https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Notifications"
click node_realtime "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Services/RealtimeService.cs"
click node_auth "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Auth/IdentityService.cs"
click node_database "https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Persistance/AppDbContext.cs"

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_api_offers,node_api_batches,node_api_requests,node_api_request_offers,node_api_admin,node_api_auth toneBlue
class node_offers,node_batches,node_requests,node_categories,node_preferences,node_qdrant toneAmber
class node_moderation,node_categorization,node_matching,node_negotiation,node_round_index toneMint
class node_jobs,node_notifications,node_realtime,node_auth,node_database toneRose
class node_buyers,node_suppliers,node_admins,node_llm toneIndigo
```

## Components

### API access

- [Offer endpoints](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/OffersController.cs): `Jomla.API/Controllers/OffersController.cs`
- [Batch endpoints](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/BatchesController.cs): `Jomla.API/Controllers/BatchesController.cs`
- [Request endpoints](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/GroupRequestsController.cs): `Jomla.API/Controllers/GroupRequestsController.cs`
- [Request offer endpoints](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/GroupRequestOffersController.cs): `Jomla.API/Controllers/GroupRequestOffersController.cs`
- [Admin endpoints](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/AdminController.cs): `Jomla.API/Controllers/AdminController.cs`
- [Authentication endpoints](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Controllers/AuthController.cs): `Jomla.API/Controllers/AuthController.cs`

### Marketplace workflows

- [Supplier offers](https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Offers): `Jomla.Application/Features/Offers`
- [Batch purchasing](https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Batches): `Jomla.Application/Features/Batches`
- [Group requests](https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/GroupRequests): `Jomla.Application/Features/GroupRequests`
- [Categories](https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Categories): `Jomla.Application/Features/Categories`
- [Supplier preferences](https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/SupplierCategoryPreferences): `Jomla.Application/Features/SupplierCategoryPreferences`

### Matching and AI

- [AI moderation](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/ModerationAgent.cs): `Jomla.Infrastructure/AI/ModerationAgent.cs`
- [AI categorization](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/CategoryAgent.cs): `Jomla.Infrastructure/AI/CategoryAgent.cs`
- [Supplier matching](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Jobs/Matching/SupplierMatchingJob.cs): `Jomla.Infrastructure/Jobs/Matching/SupplierMatchingJob.cs`
- [AI negotiation](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/NegotiationAgent.cs): `Jomla.Infrastructure/AI/NegotiationAgent.cs`
- [Round indexing](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/AI/NegotiationRoundIndexer.cs): `Jomla.Infrastructure/AI/NegotiationRoundIndexer.cs`

### Platform services

- [Background jobs](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Jobs/JobDispatcher/HangfireJobDispatcher.cs): `Jomla.Infrastructure/Jobs/JobDispatcher/HangfireJobDispatcher.cs`
- [Notifications and realtime](https://github.com/mahmoudadeli/jomla-backend/tree/master/Jomla.Application/Features/Notifications): `Jomla.Application/Features/Notifications`
- [Realtime delivery](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.API/Services/RealtimeService.cs): `Jomla.API/Services/RealtimeService.cs`
- [Identity and tokens](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Auth/IdentityService.cs): `Jomla.Infrastructure/Auth/IdentityService.cs`
- [Application database](https://github.com/mahmoudadeli/jomla-backend/blob/master/Jomla.Infrastructure/Persistance/AppDbContext.cs): `Jomla.Infrastructure/Persistance/AppDbContext.cs`

### Other components

- **Buyers**
- **Suppliers**
- **Admins**
- **Qdrant vector store**
- **Language model**

## Connections

- Buyers → Offer endpoints: browse
- Buyers → Batch endpoints: join batches
- Buyers → Request endpoints: create and join
- Buyers → Request offer endpoints: respond
- Suppliers → Offer endpoints: manage offers
- Suppliers → Batch endpoints: manage batches
- Suppliers → Request endpoints: view matches
- Suppliers → Request offer endpoints: place bids
- Admins → Admin endpoints: review content
- Offer endpoints → Supplier offers: dispatches
- Batch endpoints → Batch purchasing: dispatches
- Request endpoints → Group requests: dispatches
- Request offer endpoints → Group requests: dispatches
- Admin endpoints → Supplier offers: moderates
- Admin endpoints → Group requests: moderates
- Authentication endpoints → Identity and tokens: authenticates
- Supplier offers → Application database: reads and writes
- Batch purchasing → Application database: reads and writes
- Group requests → Application database: reads and writes
- Categories → Application database: reads and writes
- Supplier preferences → Application database: reads and writes
- Supplier offers → AI moderation: submits for review
- Group requests → AI categorization: detects category
- Group requests → AI moderation: submits for review
- Supplier matching → Supplier preferences: uses preferences
- Supplier matching → Group requests: finds requests
- Supplier matching → Notifications and realtime: notifies suppliers
- Background jobs → Supplier matching: dispatches
- Background jobs → AI moderation: dispatches
- Background jobs → AI negotiation: dispatches expiry rounds
- AI negotiation → Language model: requests pricing
- AI negotiation → Qdrant vector store: retrieves history
- Round indexing → Qdrant vector store: indexes rounds
- Group requests → Background jobs: schedules work
- Batch purchasing → Background jobs: schedules fulfillment
- Notifications and realtime → Realtime delivery: delivers updates