# sattuf/ma-rad-al-ashya architecture

> Architecture diagram of the GitHub repository sattuf/ma-rad-al-ashya, 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/sattuf/ma-rad-al-ashya
- Repository: https://github.com/sattuf/ma-rad-al-ashya

## Overview

Ma’rad is a C2C marketplace for browsing and publishing listings, communicating with sellers, and completing in-person transactions. Web and mobile clients enter through the API gateway; domain services cover accounts, listings, search, messaging, transactions, identity verification, fraud detection, moderation, and personalization. The graph also shows key internal calls visible in sampled code and the source index. Several cross-service links are documented only at the architecture level; unsampled integrations are not expanded into speculative call chains.

Main entry points: [`services/api-gateway/src/proxy/proxy.controller.ts`](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/api-gateway/src/proxy/proxy.controller.ts) (API gateway), [`services/search-service/src/search/search.service.ts`](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/search-service/src/search/search.service.ts) (Search), [`services/transactions-service/src/transactions/transactions.service.ts`](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/transactions-service/src/transactions/transactions.service.ts) (Transactions), [`services/transactions-service/src/reviews/reviews.service.ts`](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/transactions-service/src/reviews/reviews.service.ts) (Reviews and ratings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Client apps"]
  node_browser["Web client"]
  node_mobile["Mobile client"]
end

subgraph group_marketplace["Marketplace"]
  node_listings["Listings"]
  node_categories["Categories"]
  node_promotions["Listing promotions"]
  node_search["Search<br/>[search.service.ts]"]
  node_ranking["Search ranking<br/>[ranking.service.ts]"]
  node_transactions["Transactions"]
end

subgraph group_accounts["Accounts and trust"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_users["User profiles<br/>[users.service.ts]"]
  node_identity["Identity verification<br/>[kyc.service.ts]"]
  node_fraud["Fraud detection<br/>[admin.py]"]
  node_moderation["Reports and moderation<br/>[reports.service.ts]"]
end

subgraph group_engagement["Engagement"]
  node_messaging["Messaging"]
  node_reviews["Reviews and ratings<br/>[reviews.service.ts]"]
  node_personalization["Recommendations"]
  node_events["Engagement events<br/>[event_service.py]"]
end

subgraph group_platform["Platform services"]
  node_gateway["API gateway"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_elasticsearch[("Elasticsearch")]
end

node_browser -->|"requests API"| node_gateway
node_mobile -->|"requests API"| node_gateway
node_gateway -.->|"routes requests"| node_auth
node_gateway -.->|"routes requests"| node_listings
node_gateway -.->|"routes requests"| node_search
node_gateway -.->|"routes requests"| node_messaging
node_gateway -.->|"routes requests"| node_transactions
node_gateway -.->|"routes requests"| node_identity
node_gateway -.->|"routes requests"| node_fraud
node_gateway -.->|"routes requests"| node_moderation
node_auth -->|"uses account service"| node_users
node_listings -->|"indexes listings"| node_search
node_search -->|"gets ranking variant"| node_ranking
node_search -->|"reads and writes cache"| node_redis
node_search -->|"queries and indexes"| node_elasticsearch
node_search -->|"records click signals"| node_postgres
node_identity -.->|"persists verification"| node_postgres
node_transactions -.->|"persists transactions"| node_postgres
node_reviews -->|"checks transaction"| node_transactions
node_reviews -->|"stores reviews and ratings"| node_postgres
node_personalization -->|"uses event service"| node_events
node_fraud -->|"uses database"| node_postgres

click node_browser "https://github.com/sattuf/ma-rad-al-ashya/tree/main/apps/web/src/app"
click node_mobile "https://github.com/sattuf/ma-rad-al-ashya/tree/main/apps/mobile"
click node_gateway "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/api-gateway/src/proxy/proxy.controller.ts"
click node_auth "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/auth-service/src/auth/auth.service.ts"
click node_users "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/users-service/src/users/users.service.ts"
click node_identity "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/identity-service/src/services/kyc.service.ts"
click node_listings "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/listings-service/src/listings/listings.service.ts"
click node_categories "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/listings-service/src/categories/categories.service.ts"
click node_promotions "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/listings-service/src/promotions/promotions.service.ts"
click node_search "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/search-service/src/search/search.service.ts"
click node_ranking "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/search-service/src/ranking/ranking.service.ts"
click node_messaging "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/messaging-service/src/messaging/messaging.service.ts"
click node_transactions "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/transactions-service/src/transactions/transactions.service.ts"
click node_reviews "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/transactions-service/src/reviews/reviews.service.ts"
click node_personalization "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/personalization-service/app/services/recommendation_service.py"
click node_events "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/personalization-service/app/services/event_service.py"
click node_fraud "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/fraud-service/routers/admin.py"
click node_moderation "https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/moderation-service/src/reports/reports.service.ts"

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_browser,node_mobile toneBlue
class node_listings,node_categories,node_promotions,node_search,node_ranking,node_transactions toneAmber
class node_auth,node_users,node_identity,node_fraud,node_moderation toneMint
class node_messaging,node_reviews,node_personalization,node_events toneRose
class node_gateway,node_postgres,node_redis,node_elasticsearch toneIndigo
```

## Components

### Client apps

- [Web client](https://github.com/sattuf/ma-rad-al-ashya/tree/main/apps/web/src/app): `apps/web/src/app`
- [Mobile client](https://github.com/sattuf/ma-rad-al-ashya/tree/main/apps/mobile): `apps/mobile`

### Marketplace

- [Listings](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/listings-service/src/listings/listings.service.ts): `services/listings-service/src/listings/listings.service.ts`
- [Categories](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/listings-service/src/categories/categories.service.ts): `services/listings-service/src/categories/categories.service.ts`
- [Listing promotions](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/listings-service/src/promotions/promotions.service.ts): `services/listings-service/src/promotions/promotions.service.ts`
- [Search](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/search-service/src/search/search.service.ts): `services/search-service/src/search/search.service.ts`
- [Search ranking](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/search-service/src/ranking/ranking.service.ts): `services/search-service/src/ranking/ranking.service.ts`
- [Transactions](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/transactions-service/src/transactions/transactions.service.ts): `services/transactions-service/src/transactions/transactions.service.ts`

### Accounts and trust

- [Authentication](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/auth-service/src/auth/auth.service.ts): `services/auth-service/src/auth/auth.service.ts`
- [User profiles](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/users-service/src/users/users.service.ts): `services/users-service/src/users/users.service.ts`
- [Identity verification](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/identity-service/src/services/kyc.service.ts): `services/identity-service/src/services/kyc.service.ts`
- [Fraud detection](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/fraud-service/routers/admin.py): `services/fraud-service/routers/admin.py`
- [Reports and moderation](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/moderation-service/src/reports/reports.service.ts): `services/moderation-service/src/reports/reports.service.ts`

### Engagement

- [Messaging](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/messaging-service/src/messaging/messaging.service.ts): `services/messaging-service/src/messaging/messaging.service.ts`
- [Reviews and ratings](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/transactions-service/src/reviews/reviews.service.ts): `services/transactions-service/src/reviews/reviews.service.ts`
- [Recommendations](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/personalization-service/app/services/recommendation_service.py): `services/personalization-service/app/services/recommendation_service.py`
- [Engagement events](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/personalization-service/app/services/event_service.py): `services/personalization-service/app/services/event_service.py`

### Platform services

- [API gateway](https://github.com/sattuf/ma-rad-al-ashya/blob/main/services/api-gateway/src/proxy/proxy.controller.ts): `services/api-gateway/src/proxy/proxy.controller.ts`
- **PostgreSQL**
- **Redis**
- **Elasticsearch**

## Connections

- Web client → API gateway: requests API
- Mobile client → API gateway: requests API
- API gateway → Authentication: routes requests
- API gateway → Listings: routes requests
- API gateway → Search: routes requests
- API gateway → Messaging: routes requests
- API gateway → Transactions: routes requests
- API gateway → Identity verification: routes requests
- API gateway → Fraud detection: routes requests
- API gateway → Reports and moderation: routes requests
- Authentication → User profiles: uses account service (evidence: `services/auth-service/src/auth/auth.service.ts`)
- Listings → Search: indexes listings (evidence: `services/search-service/src/search/search.service.ts`)
- Search → Search ranking: gets ranking variant (evidence: `services/search-service/src/search/search.service.ts`)
- Search → Redis: reads and writes cache (evidence: `services/search-service/src/search/search.service.ts`)
- Search → Elasticsearch: queries and indexes (evidence: `services/search-service/src/search/search.service.ts`)
- Search → PostgreSQL: records click signals (evidence: `services/search-service/src/search/search.service.ts`)
- Identity verification → PostgreSQL: persists verification
- Transactions → PostgreSQL: persists transactions
- Reviews and ratings → Transactions: checks transaction (evidence: `services/transactions-service/src/reviews/reviews.service.ts`)
- Reviews and ratings → PostgreSQL: stores reviews and ratings (evidence: `services/transactions-service/src/reviews/reviews.service.ts`)
- Recommendations → Engagement events: uses event service (evidence: `services/personalization-service/app/services/recommendation_service.py`)
- Fraud detection → PostgreSQL: uses database