As the ConnectSouq platform, I want to generate and expose Trust Leaderboards using verified Trust Scores so that members can discover trusted professionals and view community rankings.

---

Business Background¶

The Trust Leaderboard is generated using each member's latest verified Trust Score and Trust Level. Rankings should update automatically whenever Trust Scores change and should only include eligible members. This supports visibility into the platform's reputation system while encouraging positive participation.

---

Functional Requirements¶

The system shall:

• Rank members by Trust Score.
• Display Trust Level and Badge.
• Support filtering by Country.
• Support filtering by Business Sector.
• Support member search.
• Return logged-in member's current rank.
• Exclude suspended or inactive members.
• Refresh rankings automatically after Trust Score updates.

---

Business Rules¶

1. Rankings are ordered by highest Trust Score.
2. Suspended or inactive members must not appear.
3. Members with identical Trust Scores are ordered by the earliest date they achieved that score.
4. Search results respect the same ranking logic.
5. Leaderboard is read-only.
6. Ranking updates automatically after Trust Score recalculation.

---

Database Changes¶

Table: Leaderboard_View (Materialized View or Optimized Query)¶

Field
Rank
MemberId
MemberName
TrustScore
TrustLevel
Badge
Country
BusinessSector
LastUpdated

---

API Endpoints¶

GET /api/leaderboard¶

Retrieve global Trust Leaderboard.

---

GET /api/leaderboard/me¶

Retrieve logged-in member's ranking.

---

GET /api/leaderboard/search¶

Search members in the leaderboard.

---

Validation Rules¶

• Member must be authenticated.
• Only active members returned.
• Ranking data must use latest Trust Scores.
• Filters must validate country and sector values.

---

Security¶

• JWT authentication
• Role-based authorization
• API rate limiting
• Audit logging

---

Audit Logs¶

Capture:

• Member ID requesting leaderboard
• Search criteria
• Applied filters
• Timestamp
• API response status

---

Acceptance Criteria¶

Scenario 1 – Retrieve Leaderboard¶

Given

Leaderboard data exists.

When

A member requests the leaderboard.

Then

• Members are returned in descending Trust Score order.
• Trust Level and Badge are included.
• Only eligible members appear.

---

Scenario 2 – Apply Filters¶

Given

Country and sector filters are provided.

When

The leaderboard is queried.

Then

Only matching members are returned while preserving ranking order.

---

Scenario 3 – View My Rank¶

Given

The member is authenticated.

When

The member requests their ranking.

Then

The API returns:

• Current rank
• Trust Score
• Trust Level
• Badge

even if the member is not listed in the current page of results.

---

In Scope (MVP)¶

• Global leaderboard
• Ranking calculation
• Country filtering
• Sector filtering
• Member search
• My Ranking API
• Automatic ranking refresh

---

Out of Scope¶

• Weekly/monthly leaderboards
• Franchise leaderboards
• Industry-specific awards
• Gamification rewards
• Public APIs for third parties
• Historical leaderboard snapshots

---

Definition of Done¶

• Leaderboard APIs implemented.
• Ranking algorithm validated.
• Search and filtering tested.
• Performance optimized for large datasets.
• Audit logging completed.
• Unit, integration, and QA testing passed.
• Product Owner approval received.