As the ConnectSouq platform, I want to automatically calculate each member's Trust Score whenever a verified activity is completed so that Trust Scores remain accurate, transparent, and consistent across the platform.

---

Business Background¶

The Trust Score Engine is the core business service responsible for awarding points based on verified member activities. Every qualifying action—such as completing a profile, registering a business opportunity, introducing buyers and sellers, mentoring members, or receiving Trust Tokens—must update the member's score according to the approved Trust Framework. The engine also categorizes points into the four Trust Dimensions and determines the member's Trust Level.

---

Functional Requirements¶

The system shall:

• Capture verified platform events.
• Validate that the activity qualifies for scoring.
• Assign points based on configured scoring rules.
• Update the appropriate Trust Dimension.
• Recalculate the overall Trust Score.
• Recalculate the member's Trust Level.
• Store a complete audit history.
• Prevent duplicate point allocation for the same qualifying activity.

---

Business Rules¶

1. Only verified activities generate Trust Points.
2. Each qualifying activity can earn points only once unless explicitly configured otherwise.
3. Points are assigned from the configurable scoring matrix.
4. Total Trust Score equals the sum of all Trust Dimension scores.
5. Trust Level is determined using configured score thresholds.
6. Every score change must create an audit record.
7. Duplicate event processing must not award duplicate points.

---

Database Changes¶

Table: Trust_Score¶

Field
MemberId
TotalScore
BusinessImpact
CommunityImpact
LeadershipImpact
GrowthImpact
TrustLevel
LastCalculatedOn

---

Table: Trust_Score_Activity¶

Field
ActivityId
MemberId
ActivityType
Dimension
PointsAwarded
VerificationStatus
SourceModule
ActivityDate
CreatedBy

---

Table: Trust_Score_Audit¶

Field
AuditId
MemberId
PreviousScore
UpdatedScore
ActivityId
Timestamp

---

API Endpoints¶

GET /api/trust/activities¶

Retrieve member Trust Score activities.

---

POST /api/trust/recalculate¶

Recalculate Trust Score after a verified activity.

---

GET /api/trust/summary¶

Return Trust Score summary.

---

Validation Rules¶

• Member must exist.
• Activity must be verified.
• Activity must not have been processed previously.
• Invalid activities must be rejected.
• Duplicate requests must be ignored safely.

---

Error Handling¶

Error	Response
Member not found	404
Activity not eligible	400
Duplicate activity	409
Unauthorized	401
Internal Server Error	500

---

Security¶

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

---

Audit Logs¶

The system shall record:

• Member ID
• Activity ID
• Activity Type
• Points Awarded
• Previous Score
• Updated Score
• User/System initiating the update
• Timestamp

---

Acceptance Criteria¶

Scenario 1 – Award Points¶

Given

• A qualifying activity has been verified.

When

• The Trust Score Engine processes the activity.

Then

• The configured points are awarded.
• The correct Trust Dimension is updated.
• Total Trust Score is recalculated.
• Trust Level is recalculated if thresholds are crossed.
• An audit record is created.

---

Scenario 2 – Duplicate Activity¶

Given

• The activity has already been processed.

When

• The engine receives the same activity again.

Then

• No additional points are awarded.
• A duplicate processing event is logged.

---

Scenario 3 – Invalid Activity¶

Given

• An activity does not qualify for scoring.

When

• The engine evaluates it.

Then

• No Trust Points are awarded.
• The activity is rejected with the appropriate validation message.

---

In Scope (MVP)¶

• Rule-based score calculation
• Event processing
• Trust Dimension updates
• Trust Level calculation
• Activity history
• Audit logging
• Duplicate prevention

---

Out of Scope¶

• AI-driven scoring
• Machine learning recommendations
• Dynamic scoring formulas
• Manual score overrides
• Predictive trust analytics

---

Definition of Done¶

• Score calculation engine implemented.
• Configurable scoring rules supported.
• Duplicate prevention validated.
• APIs documented and tested.
• Audit logging completed.
• Unit, integration, and QA testing passed.
• Product Owner approval obtained.